Behavior lifecycle: On enable, On disable and On destroy events (#42)

Order per instance: On start -> On enable -> On update ... -> On disable
-> On destroy. On enable fires right after On start and whenever the
behavior comes back on (itself and its parents); On disable in the frame
it goes off, the instance stays frozen. On destroy fires when the entity
leaves the world (Destroy node, child of a destroyed object) and when the
world is torn down on stop/restart, preceded by On disable if still on.
A new On start node added while playing still does not fire for a
running instance (kept as is, documented in the wiki).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/core/graph/nodes/events/OnDestroy.ts

@@ -0,0 +1,12 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { exec } from '../shared';
+
+export const OnDestroy: NodeDef = {
+  type: 'OnDestroy',
+  label: 'On destroy',
+  category: 'event',
+  description: 'Runs once when the object is destroyed – also when the game stops or restarts.',
+  inputs: [],
+  outputs: [exec()],
+  params: [],
+};

src/core/graph/nodes/events/OnDisable.ts

@@ -0,0 +1,12 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { exec } from '../shared';
+
+export const OnDisable: NodeDef = {
+  type: 'OnDisable',
+  label: 'On disable',
+  category: 'event',
+  description: 'Runs when the behavior is switched off (itself or a parent), and before On destroy.',
+  inputs: [],
+  outputs: [exec()],
+  params: [],
+};

src/core/graph/nodes/events/OnEnable.ts

@@ -0,0 +1,12 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { exec } from '../shared';
+
+export const OnEnable: NodeDef = {
+  type: 'OnEnable',
+  label: 'On enable',
+  category: 'event',
+  description: 'Runs right after On start, and again each time the behavior is switched back on.',
+  inputs: [],
+  outputs: [exec()],
+  params: [],
+};

src/core/graph/nodes/index.ts

@@ -71,6 +71,9 @@ import { OnClick } from './events/OnClick';
 import { OnCollisionEnter } from './events/OnCollisionEnter';
 import { OnCollisionExit } from './events/OnCollisionExit';
 import { OnCollisionStay } from './events/OnCollisionStay';
+import { OnDestroy } from './events/OnDestroy';
+import { OnDisable } from './events/OnDisable';
+import { OnEnable } from './events/OnEnable';
 import { OnKeyDown } from './events/OnKeyDown';
 import { OnKeyHeld } from './events/OnKeyHeld';
 import { OnKeyUp } from './events/OnKeyUp';
@@ -94,7 +97,10 @@ import { Variables } from './variable/Variables';
  */
 export const BUILT_IN_NODES: readonly NodeDef[] = [
   OnStart,
+  OnEnable,
   OnUpdate,
+  OnDisable,
+  OnDestroy,
   OnKeyDown,
   OnKeyUp,
   OnKeyHeld,

src/runtime/systems/BehaviorSystem.ts

@@ -43,6 +43,8 @@ interface Instance {
   values: Map<Graph, Map<string, Produced>>;
   /** Current state per state machine – this instance's alone, like its variables. */
   states: Record<string, string>;
+  /** Whether the behavior was effectively on when last looked at; a change fires On enable/On disable. */
+  active: boolean;
 }
 
 /**
@@ -104,7 +106,9 @@ export class BehaviorSystem implements System {
     this.syncInstances(world);
   }
 
+  /** Tearing the world down (stop, restart) destroys every object, so each instance hears it. */
   stop(): void {
+    for (const instance of this.instances) this.finish(instance);
     this.instances = [];
     this.world = null;
   }
@@ -114,7 +118,7 @@ export class BehaviorSystem implements System {
    * switched on, which is what lets a hidden screen wake up when shown.
    */
   private syncInstances(world: World): void {
-    this.instances = this.instances.filter((i) => world.entities.includes(i.entity));
+    this.reap(world);
     for (const entity of world.entities) {
       if (
         entity.type !== 'behavior' ||
@@ -137,19 +141,58 @@ export class BehaviorSystem implements System {
           byNode.set(id, { time: world.time, values: produced });
         },
       } satisfies TraceListener;
-      const instance: Instance = { entity, interpreter, trace, values, states: {} };
+      const instance: Instance = { entity, interpreter, trace, values, states: {}, active: true };
       this.instances.push(instance);
-      this.run(instance, (i, ctx) => i.fire('OnStart', ctx), 0);
+      this.run(
+        instance,
+        (i, ctx) => {
+          i.fire('OnStart', ctx);
+          i.fire('OnEnable', ctx);
+        },
+        0,
+      );
     }
   }
 
+  /** Instances whose entity left the world get their last events and are dropped. */
+  private reap(world: World): void {
+    const gone = this.instances.filter((i) => !world.entities.includes(i.entity));
+    if (gone.length === 0) return;
+    this.instances = this.instances.filter((i) => !gone.includes(i));
+    for (const instance of gone) this.finish(instance);
+  }
+
+  private finish(instance: Instance): void {
+    this.run(
+      instance,
+      (i, ctx) => {
+        if (instance.active) i.fire('OnDisable', ctx);
+        instance.active = false;
+        i.fire('OnDestroy', ctx);
+      },
+      0,
+    );
+  }
+
+  /**
+   * Follows the effective switch – off when the behavior or a parent is off, or when "run in editor"
+   * was taken back while running – and fires the edge it just crossed.
+   */
+  private switched(instance: Instance): boolean {
+    const on = isHandleEnabled(instance.entity) && this.shouldRun(instance.entity);
+    if (on !== instance.active) {
+      instance.active = on;
+      this.run(instance, (i, ctx) => i.fire(on ? 'OnEnable' : 'OnDisable', ctx), 0);
+    }
+    return on;
+  }
+
   update(world: World, dt: number): void {
     this.syncInstances(world);
     const keyOf = (node: { params: PropertyBag }) => textOf(node.params.key ?? '');
     for (const instance of this.instances) {
-      if (!world.entities.includes(instance.entity)) continue; // destroyed during play
-      if (!isHandleEnabled(instance.entity)) continue; // switched off (itself or a parent)
-      if (!this.shouldRun(instance.entity)) continue; // "run in editor" taken back while running
+      if (!world.entities.includes(instance.entity)) continue; // destroyed this frame, reaped below
+      if (!this.switched(instance)) continue;
       this.run(
         instance,
         (i, ctx) => {
@@ -180,6 +223,7 @@ export class BehaviorSystem implements System {
         dt,
       );
     }
+    this.reap(world);
   }
 
   /**