A game that is more than one scene needs a way from one to the next, so the graph can load one (#39)

Load scene sets a flag on the World like Stop and Restart do; the swap
happens after the tick, and the last wish of a tick wins. Exactly one
thing crosses over: the SharedState, so global variables and global
machines keep what they know while everything local is built anew.
Loading the scene that is already running rebuilds it, which is what
"reset the level" means when the score must survive.

A run starts either from the start scene (a new project field, set from
the asset panel and marked with an arrow in the list) or from whatever
scene is open. The toggle next to Play says which question is asked and
remembers the answer in localStorage: it is a way of working, not part
of the game.

Sounds no longer end because a scene ends. A voice belongs to the
behavior that started it and stops right after On destroy, so the scene
swap is no longer a special case at all. For the enemy that plays its
explosion and destroys itself in the same breath there is now a
detached input on Play sound.

The scene selector stays usable while a run plays, because a double
click in the asset panel already did the same thing unguarded. It moves
what the editor looks at, not what the run plays.

src/core/graph/nodes/action/LoadScene.ts

@@ -0,0 +1,35 @@
+import type { NodeDef, PortDef } from '../../NodeRegistry';
+import { asString } from '../../values';
+import { exec } from '../shared';
+
+/**
+ * The `scene` input; unconnected it shows the scene picker, the way `soundPort` shows the sound
+ * one. A `Scene` literal is what feeds it through an edge.
+ */
+const scenePort = (): PortDef => ({
+  key: 'scene',
+  label: 'scene',
+  type: 'string',
+  field: { key: 'scene', label: 'Scene', kind: 'scene', default: '' },
+});
+
+export const LoadScene: NodeDef = {
+  type: 'LoadScene',
+  label: 'Load scene',
+  category: 'action',
+  description:
+    'Replaces the running scene with another one. Everything of the old scene is gone – its ' +
+    'objects, their behaviors and the sounds those behaviors were playing; what a Variables asset ' +
+    'holds and where a global state machine stands carry over, because those belong to the run and ' +
+    'not to the scene. Naming the scene that is already running rebuilds it, which is how a level ' +
+    'is reset without losing the score. The swap happens once the frame has finished, so the rest ' +
+    'of this graph still runs; asked twice in one frame, the last answer wins.',
+  inputs: [exec(), scenePort()],
+  outputs: [exec()],
+  params: [],
+  run: (ctx, inputs) => {
+    const scene = asString(inputs.scene);
+    if (scene) ctx.loadScene(scene);
+    return { next: 'exec' };
+  },
+};

src/core/graph/nodes/action/PlaySound.ts

@@ -1,5 +1,5 @@
 import type { NodeDef, PortDef } from '../../NodeRegistry';
-import { asNumber, asString, type Value } from '../../values';
+import { asBoolean, asNumber, asString, type Value } from '../../values';
 import { exec, num, soundPort, withDefault } from '../shared';
 
 /**
@@ -34,6 +34,19 @@ export function loopChoice(value: Value | undefined): boolean | undefined {
   return undefined;
 }
 
+/**
+ * The way out of the ownership rule, off by default. Needed for one shape that is common enough to
+ * deserve it: an object that plays its own death sound and destroys itself in the same flow – the
+ * voice would be cut off in the instant it started, because the behavior holding it is gone.
+ */
+const detachedPort = (): PortDef => ({
+  key: 'detached',
+  label: 'detached',
+  type: 'boolean',
+  default: false,
+  field: { key: 'detached', label: 'Detached (outlives this object)', kind: 'boolean', default: false },
+});
+
 export const PlaySound: NodeDef = {
   type: 'PlaySound',
   label: 'Play sound',
@@ -42,13 +55,15 @@ export const PlaySound: NodeDef = {
     'Plays a sound asset. "volume" multiplies the volume the asset itself carries and "loop" either ' +
     "leaves the asset's own setting alone or overrules it, so the asset says what the sound is and " +
     'the node only colours it. Each play is a voice of its own: firing this twice in a row is heard ' +
-    'twice, overlapping.',
-  inputs: [exec(), soundPort(), withDefault(num('volume'), 1), loopPort()],
+    'twice, overlapping. The sound belongs to this object and stops when the object is destroyed, ' +
+    'unless "detached" is on.',
+  inputs: [exec(), soundPort(), withDefault(num('volume'), 1), loopPort(), detachedPort()],
   outputs: [exec()],
   params: [],
   run: (ctx, inputs) => {
     const sound = asString(inputs.sound);
-    if (sound) ctx.playSound(sound, asNumber(inputs.volume), loopChoice(inputs.loop));
+    if (sound)
+      ctx.playSound(sound, asNumber(inputs.volume), loopChoice(inputs.loop), asBoolean(inputs.detached));
     return { next: 'exec' };
   },
 };

src/core/graph/nodes/data/literals.ts

@@ -40,6 +40,11 @@ export const SoundLiteral = literal(
   'sound',
   'A constant sound, for a "Play sound" or a "Stop sound" to work on.',
 );
+export const SceneLiteral = literal(
+  'Scene',
+  'scene',
+  'A constant scene, for a "Load scene" to work on.',
+);
 export const ListLiteral = literal(
   'List',
   'list',

src/core/graph/nodes/index.ts

@@ -1,6 +1,7 @@
 import { type NodeDef, registerNode } from '../NodeRegistry';
 import { Destroy } from './action/Destroy';
 import { Emit } from './action/Emit';
+import { LoadScene } from './action/LoadScene';
 import { Log } from './action/Log';
 import { Move } from './action/Move';
 import { PlaySound } from './action/PlaySound';
@@ -34,6 +35,7 @@ import {
   BooleanLiteral,
   ListLiteral,
   NumberLiteral,
+  SceneLiteral,
   SoundLiteral,
   StateMachineLiteral,
   StringLiteral,
@@ -150,6 +152,7 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   TextureLiteral,
   StateMachineLiteral,
   SoundLiteral,
+  SceneLiteral,
   Add,
   Subtract,
   Multiply,
@@ -201,6 +204,7 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   Emit,
   PlaySound,
   StopSound,
+  LoadScene,
   Log,
   StopGame,
   RestartGame,