lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/core/Aspect.ts

@@ -11,23 +11,29 @@
 //   class Health extends Aspect<'health', Sprite> { hp = 100; hurt(n: number) { this.hp -= n } }
 //   sprite.aspect(Health, { hp: 80 }).health.hurt(10)
 //
+// SYSTEMS are the same thing attached to a SCENE instead of a node — game logic that has no single
+// node to live on (input mapping, FX pools, the HUD, the game mode): `scene.system(Fx)` → `scene.fx`.
+// They share the lifecycle, the update phases, the ordering and the events of aspects (see System).
+//
 // The accessor name lives in the generic (Aspect<'name', Node>). The `chisel` bundler extracts it at
 // compile time and injects the runtime `static aspect` on user aspects + the virtual type accessor;
 // the SDK's own built-in aspects declare `static readonly aspect` directly (see SpriteAnimation etc.).
 
+import type { Scene } from "../gl/Scene"
 import { Emitter, type EventMap } from "./events"
 import type { InspectorUI } from "./InspectorUI"
 import type { Node } from "../gl/Node"
+import { Time, _registerTimeScaleSink } from "./time"
 
 // ---- type helpers -----------------------------------------------------------
 /** The class object of an aspect — accepted even when its constructor is protected/abstract. */
-export type AspectCtor<A extends Aspect<any, any>> = abstract new () => A
+export type AspectCtor<A extends Aspect<any, any, any>> = abstract new () => A
 /** The accessor name carried in the aspect's generic. */
-export type KeyOf<A> = A extends Aspect<infer K, any> ? K : never
-/** The node kind an aspect targets. */
-export type TargetOf<A> = A extends Aspect<any, infer P> ? P : never
+export type KeyOf<A> = A extends Aspect<infer K, any, any> ? K : never
+/** The node kind an aspect targets (the scene kind for a System). */
+export type TargetOf<A> = A extends Aspect<any, infer P, any> ? P : never
 /** `{ name: Aspect }` — the field an aspect contributes to its node. */
-export type FieldOf<A extends Aspect<any, any>> = { [P in KeyOf<A>]: A }
+export type FieldOf<A extends Aspect<any, any, any>> = { [P in KeyOf<A>]: A }
 
 type UnionToIntersection<U> =
   (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
@@ -37,73 +43,247 @@ type UnionToIntersection<U> =
  * English and mirrors the runtime guard `node.has(Health)`:
  *   let boss: With<Sprite, Health | Physics>
  */
-export type With<N, A extends Aspect<any, any>> =
+export type With<N, A extends Aspect<any, any, any>> =
   N & UnionToIntersection<A extends any ? FieldOf<A> : never>
 
 // ---- per-frame update dispatch (two phases) ---------------------------------
-// Aspects that define update(dt) are ticked every frame in ONE of two phases, chosen by the aspect's
-// `updateBeforePhysics` field:
-//   • LATE (default): after the physics step + transform sync, right before the frame draws. Reads of
-//     node.worldPosition are the FINAL drawn position — cameras/followers land exactly, no 1-frame lag.
-//   • EARLY (updateBeforePhysics = true): before the physics step, so writing velocity/force/kinematic
-//     transforms is consumed by the SAME frame's step (zero input latency).
+// Aspects tick every frame in one of two render-synced phases, chosen by WHICH METHOD they define:
+//   • `update(dt)` — LATE: after the physics step + transform sync + animators, right before the frame
+//     draws. Reads of node.worldPosition are the FINAL drawn position — cameras/followers land exactly,
+//     what you write to a plain node is what this frame shows. The default home for game logic.
+//   • `updateBefore(dt)` — EARLY: before the physics step, so writes of velocity / move commands /
+//     kinematic transforms are consumed by the SAME frame's step (zero input latency).
+// An aspect rarely needs both; when a behaviour does (feed the sim, then pose something after the
+// animators), it is two aspects on the same node — not one class in two phases.
+//
 // The FRAME SOURCE is pluggable so core never names a specific engine bridge (a 3D-only bundle must not
-// pull in the 2D one): the 2D layer installs a render-synced source via _installAspectFrames (the native
-// c2dRender early/late hooks), so dispatch is in lockstep with the draw. With none installed (3D-only,
-// or a runtime without the hooks) it falls back to a single host setLoop, early-then-late — no true
-// post-physics slot. Both lists stay sorted by the aspect's `order` field (default 0; ties keep
-// insertion order). Lazy: the first update-bearing aspect installs the dispatch; a project with none
-// starts nothing. No visibility culling yet — every registered aspect ticks regardless of on-screen state.
-type Updatable = Aspect<any, any>
+// pull in the 2D one): each engine layer installs a render-synced source via _installAspectFrames (the
+// native early/late hooks), so dispatch is in lockstep with the draw. With none installed (a runtime
+// without the hooks) it falls back to a single host setLoop, early-then-late — no true post-physics slot.
+//
+// ORDER within a phase: declared constraints first (`static after = [Controls]` / `static before`),
+// then the numeric `updateOrder` (ascending, default 0), then attach order. Constraints are edges between
+// classes: an aspect ranks after everything it names in `after` and after everything that names it in
+// `before`; a class with no constraints has rank 0. `updateOrder` only breaks ties inside a rank — so a
+// declared dependency always wins over a number.
+//
+// `dt` is GAME time (core/time.ts): scaled by Time.scale, 0 while Time.paused — and a paused frame skips
+// every updater except those with `updateWhilePaused = true`. Lazy: the first update-bearing aspect installs
+// the dispatch; a project with none starts nothing. No visibility culling yet.
+// The dispatcher's view of an instance: the lifecycle members are `protected` on Aspect (the engine calls
+// them, game code never does), so core reaches them through this structural type.
+interface Updatable {
+  _phaseSeq: number
+  _phases: number
+  updateOrder: number
+  updateWhilePaused: boolean
+  update?(dt: number): void
+  updateBefore?(dt: number): void
+  onAttach?(): void
+  onDetach?(): void
+  onReconfigure?(): void
+}
+const internals = (a: Aspect<any, any, any>): Updatable => a as unknown as Updatable
 type PhaseFn = (dt: number) => void
-const earlyUpdaters: Updatable[] = []
-const lateUpdaters: Updatable[] = []
-let dispatchInstalled = false
+type Ctor = Function & { after?: Function[], before?: Function[], aspect?: string }
 
 // A render-synced frame source: given the two phase runners, wire them to the engine and return true;
-// return false if unavailable (→ setLoop fallback). Installed by the 2D layer (see Scene2D) so core
-// never references a concrete engine bridge — that keeps the 2D bridge out of a 3D-only bundle.
+// return false if unavailable (→ setLoop fallback). Installed by the engine layers (Scene / Scene2D).
 type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
 let frameInstaller: FrameInstaller | undefined
-/** @internal Install a render-synced frame source for aspect update(dt). Called from the 2D layer. */
+/** @internal Install a render-synced frame source for aspect update(dt). Called from an engine layer. */
 export const _installAspectFrames = (fn: FrameInstaller): void => { frameInstaller = fn }
 
-const policyOf = (a: Updatable): { early: boolean; order: number } =>
-  ({ early: a.updateBeforePhysics === true, order: a.order ?? 0 })
+let attachSeq = 0
+const warned = new Set<string>()
+const warnOnce = (msg: string): void => { if (!warned.has(msg)) { warned.add(msg); console.warn(msg) } }
+
+/** One phase's updater list. Iterated LIVE (no per-frame copy): removals during a pass null the slot
+ *  and compact afterwards; additions land past the pass's end and tick from the next frame. Sorting
+ *  is lazy — re-ranked before the next pass after any add. */
+class PhaseList {
+  readonly items: (Updatable | null)[] = []
+  private iterating = false
+  private dirty = false
+  private holes = false
 
-// Stable insert by ascending order: place after the last element whose order is <= this one's.
-const addSorted = (list: Updatable[], a: Updatable, order: number): void => {
-  let i = list.length
-  while (i > 0 && list[i - 1].order > order) i--
-  list.splice(i, 0, a)
+  add(a: Updatable, phase: "update" | "updateBefore"): void {
+    a._phaseSeq = ++attachSeq
+    this.items.push(a)
+    this.dirty = true
+    a._phases |= phase === "update" ? 2 : 1
+  }
+  remove(a: Updatable): boolean {
+    const i = this.items.indexOf(a)
+    if (i < 0) return false
+    if (this.iterating) { this.items[i] = null; this.holes = true }
+    else this.items.splice(i, 1)
+    return true
+  }
+  run(method: "update" | "updateBefore", dt: number): void {
+    if (this.dirty) this.sort()
+    const items = this.items
+    const n = items.length   // appended during the pass → next frame (attach-order snapshot semantics)
+    const paused = Time.paused
+    this.iterating = true
+    for (let i = 0; i < n; i++) {
+      const a = items[i]
+      if (a === null || (paused && !a.updateWhilePaused)) continue
+      a[method]!(dt)
+    }
+    this.iterating = false
+    if (this.holes) {
+      this.holes = false
+      let w = 0
+      for (let r = 0; r < items.length; r++) { const a = items[r]; if (a !== null) items[w++] = a }
+      items.length = w
+    }
+  }
+  /** Stable sort by (constraint rank, updateOrder, attach sequence). */
+  private sort(): void {
+    this.dirty = false
+    const ranks = rankConstraints(this.items)
+    this.items.sort((x, y) => {
+      if (x === null || y === null) return x === null ? (y === null ? 0 : 1) : -1
+      const rx = ranks.get(x.constructor) ?? 0, ry = ranks.get(y.constructor) ?? 0
+      if (rx !== ry) return rx - ry
+      if (x.updateOrder !== y.updateOrder) return x.updateOrder - y.updateOrder
+      return x._phaseSeq - y._phaseSeq
+    })
+  }
 }
 
-const runPhase = (list: Updatable[], dt: number): void => {
-  // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
-  for (const a of list.slice()) a.update?.(dt)
+// Constraint rank per class among the classes present in one phase list: rank = 0 with no incoming
+// edge, else 1 + max(rank of predecessors). Edges: C after D (from C.after or D.before). A cycle is
+// warned once and its closing edge ignored; a constraint naming a class not present in this phase is
+// simply unconstrained here (early always precedes late anyway).
+const rankConstraints = (items: (Updatable | null)[]): Map<Function, number> => {
+  const present = new Set<Function>()
+  for (const a of items) if (a) present.add(a.constructor)
+  const preds = new Map<Function, Set<Function>>()
+  const edge = (before: Function, after: Function): void => {
+    if (!present.has(before) || !present.has(after) || before === after) return
+    let s = preds.get(after)
+    if (!s) preds.set(after, (s = new Set()))
+    s.add(before)
+  }
+  for (const c of present) {
+    for (const d of (c as Ctor).after ?? []) edge(d, c)
+    for (const d of (c as Ctor).before ?? []) edge(c, d)
+  }
+  if (preds.size === 0) return new Map()
+  const rank = new Map<Function, number>()
+  const visiting = new Set<Function>()
+  const rankOf = (c: Function): number => {
+    const known = rank.get(c)
+    if (known !== undefined) return known
+    if (visiting.has(c)) {
+      warnOnce(`[aspects] ordering cycle through ${c.name || "?"} — its constraint is ignored`)
+      return 0
+    }
+    visiting.add(c)
+    let r = 0
+    for (const p of preds.get(c) ?? []) r = Math.max(r, rankOf(p) + 1)
+    visiting.delete(c)
+    rank.set(c, r)
+    return r
+  }
+  for (const c of present) rankOf(c)
+  return rank
 }
 
+const earlyUpdaters = new PhaseList()
+const lateUpdaters = new PhaseList()
+let dispatchInstalled = false
+
 const ensureDispatch = (): void => {
   if (dispatchInstalled) return
   dispatchInstalled = true
-  const early: PhaseFn = (dt) => runPhase(earlyUpdaters, dt)
-  const late: PhaseFn = (dt) => runPhase(lateUpdaters, dt)
-  // render-synced source if the engine layer installed one; else one host loop (early then late).
+  // Both phases scale their OWN raw dt (the engine hands the same value to both; a host or test that
+  // drives them apart still gets each phase's dt right). The frame counter / clocks advance once, early.
+  const early: PhaseFn = (dt) => { Time._beginFrame(dt); earlyUpdaters.run("updateBefore", Time.dt) }
+  const late: PhaseFn = (dt) => lateUpdaters.run("update", Time._phaseDt(dt))
+  // render-synced source if an engine layer installed one; else one host loop (early then late).
   if (!(frameInstaller && frameInstaller(early, late))) {
     setLoop((dt) => { early(dt); late(dt) })
   }
 }
 
-const registerUpdater = (a: Updatable): void => {
-  const { early, order } = policyOf(a)
-  addSorted(early ? earlyUpdaters : lateUpdaters, a, order)
+const registerUpdater = (inst: Aspect<any, any, any>): void => {
+  const a = internals(inst)
+  const hasBefore = typeof a.updateBefore === "function"
+  const hasUpdate = typeof a.update === "function"
+  if (!hasBefore && !hasUpdate) return
+  if (hasBefore) earlyUpdaters.add(a, "updateBefore")
+  if (hasUpdate) lateUpdaters.add(a, "update")
   ensureDispatch()
 }
-const unregisterUpdater = (a: Updatable): void => {
-  let i = earlyUpdaters.indexOf(a)
-  if (i >= 0) { earlyUpdaters.splice(i, 1); return }
-  i = lateUpdaters.indexOf(a)
-  if (i >= 0) lateUpdaters.splice(i, 1)
+const unregisterUpdater = (inst: Aspect<any, any, any>): void => {
+  const a = internals(inst)
+  if (a._phases === 0) return
+  earlyUpdaters.remove(a)
+  lateUpdaters.remove(a)
+  a._phases = 0
+}
+
+// ---- per-class instance registry (`Aspect.all(Ctor)`) -----------------------
+const instances = new Map<Function, Aspect<any, any, any>[]>()
+const trackInstance = (a: Aspect<any, any, any>): void => {
+  let list = instances.get(a.constructor)
+  if (!list) instances.set(a.constructor, (list = []))
+  list.push(a)
+}
+const untrackInstance = (a: Aspect<any, any, any>): void => {
+  const list = instances.get(a.constructor)
+  if (!list) return
+  const i = list.indexOf(a)
+  if (i >= 0) list.splice(i, 1)
+}
+
+// ---- shared attach / detach (nodes AND scenes) ------------------------------
+// `host` receives the named accessor and becomes `inst.node`; `store` is the class → instance map
+// (a node's `_aspects`, a scene's `_systems`).
+type Store = Map<Function, Aspect<any, any, any>>
+
+const attachTo = <Self, A extends Aspect<any, any, any>>(
+  host: Self, store: Store, ctor: AspectCtor<A>, opts: Partial<A> | undefined, scene: unknown,
+): Self & FieldOf<A> => {
+  let inst = store.get(ctor) as A | undefined
+  const fresh = inst === undefined
+  if (!inst) {
+    inst = new (ctor as unknown as new () => A)()
+    ;(inst as { node: unknown }).node = host
+    if (scene !== undefined) (inst as { scene: unknown }).scene = scene
+    store.set(ctor, inst)
+    const name = (ctor as Ctor).aspect
+    if (name) (host as unknown as Record<string, unknown>)[name] = inst
+  }
+  if (opts) Object.assign(inst, opts)
+  if (fresh) {
+    trackInstance(inst)
+    internals(inst).onAttach?.()
+    registerUpdater(inst)
+  } else if (opts) internals(inst).onReconfigure?.()
+  return host as Self & FieldOf<A>
+}
+
+const detachFrom = (host: unknown, store: Store, ctor: Function): void => {
+  const inst = store.get(ctor)
+  if (!inst) return
+  internals(inst).onDetach?.()
+  unregisterUpdater(inst)
+  untrackInstance(inst)
+  inst._clearEvents()
+  store.delete(ctor)
+  const name = (ctor as Ctor).aspect
+  if (name) delete (host as Record<string, unknown>)[name]
+}
+
+/** Detach every aspect of a store, last-attached first (a Physics attached after its Shape releases
+ *  its body before the Shape goes). */
+const detachAllFrom = (host: unknown, store: Store): void => {
+  const ctors = [...store.keys()]
+  for (let i = ctors.length - 1; i >= 0; i--) detachFrom(host, store, ctors[i])
 }
 
 // ---- the host: mixed into every node kind (Node2D, Node) --------------------
@@ -114,66 +294,68 @@ const unregisterUpdater = (a: Updatable): void => {
  */
 export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<E> {
   /** @internal class → instance, the authoritative store (named accessors mirror this). */
-  readonly _aspects = new Map<Function, Aspect<any, any>>()
+  readonly _aspects = new Map<Function, Aspect<any, any, any>>()
 
   /** Attach (and configure) an aspect, or reconfigure it if already present. Returns the node typed
    *  as now-having that aspect (so no guard/`?.` is needed afterwards). Rejects a wrong target node. */
-  aspect<Self extends TargetOf<A>, A extends Aspect<any, any>>(
+  aspect<Self extends TargetOf<A>, A extends Aspect<any, any, any>>(
     this: Self,
     ctor: AspectCtor<A>,
     opts?: Partial<A>,
   ): Self & FieldOf<A> {
-    const host = this as unknown as AspectHost
-    let inst = host._aspects.get(ctor) as A | undefined
-    const fresh = inst === undefined
-    if (!inst) {
-      inst = new (ctor as unknown as new () => A)()
-      ;(inst as { node: unknown }).node = this
-      host._aspects.set(ctor, inst)
-      const name = (ctor as { aspect?: string }).aspect
-      if (name) (host as unknown as Record<string, unknown>)[name] = inst
-    }
-    if (opts) Object.assign(inst, opts)
-    if (fresh) {
-      inst.onAttach?.()
-      if (typeof inst.update === "function") registerUpdater(inst)
-    }
-    return this as Self & FieldOf<A>
+    return attachTo(this, (this as unknown as AspectHost)._aspects, ctor, opts, undefined)
   }
 
   /** Safe access — undefined if the aspect isn't attached. */
-  get<A extends Aspect<any, any>>(ctor: AspectCtor<A>): A | undefined {
+  get<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): A | undefined {
     return this._aspects.get(ctor) as A | undefined
   }
 
   /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
-  has<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
+  has<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
     return this._aspects.has(ctor)
   }
 
   /** Detach an aspect (runs its onDetach). Named `removeAspect` so it never collides with the
    *  child-management `add`/`remove` semantics some node kinds expose. */
-  removeAspect<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this {
-    const inst = this._aspects.get(ctor)
-    if (inst) {
-      inst.onDetach?.()
-      unregisterUpdater(inst)
-      this._aspects.delete(ctor)
-      const name = (ctor as { aspect?: string }).aspect
-      if (name) delete (this as unknown as Record<string, unknown>)[name]
-    }
+  removeAspect<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this {
+    detachFrom(this, this._aspects, ctor)
     return this
   }
+
+  /** @internal Detach every aspect (node teardown): onDetach, updaters, events, registries. */
+  _detachAll(): void {
+    detachAllFrom(this, this._aspects)
+    this.clearListeners()
+  }
 }
 
+// ---- systems: aspects of a scene --------------------------------------------
+/** @internal What a scene needs to carry systems. Scene / Scene2D implement it over these helpers. */
+export type SystemHost = { readonly _systems: Map<Function, Aspect<any, any, any>> }
+
+/** @internal `scene.system(Ctor, opts)`. */
+export const _attachSystem = <Self extends SystemHost, A extends Aspect<any, any, any>>(
+  scene: Self, ctor: AspectCtor<A>, opts?: Partial<A>,
+): Self & FieldOf<A> => attachTo(scene, scene._systems, ctor, opts, scene)
+/** @internal `scene.removeSystem(Ctor)`. */
+export const _detachSystem = (scene: SystemHost, ctor: Function): void => detachFrom(scene, scene._systems, ctor)
+/** @internal Scene teardown: every system, last-attached first. */
+export const _detachAllSystems = (scene: SystemHost): void => detachAllFrom(scene, scene._systems)
+
+/** @internal Engine layers call this once with their bridge's clock hook (feature-detected). */
+export const _installTimeScale = (sink: (scale: number) => void): void => _registerTimeScaleSink(sink)
+
 // ---- the aspect base --------------------------------------------------------
 /**
  * Base for everything you attach. `K` = accessor name (extracted by chisel for the runtime). `P` =
  * the target node kind: `this.node` is typed to it, AND attaching to a wrong node is a compile error.
+ * `E` = the events this aspect emits (`{ explode: (b: Barrel) => void }`): `this.emit('explode', …)`
+ * inside, `node.barrel.on('explode', fn)` outside.
  * Initialize in `onAttach` (the node is set by then) — not a constructor; aspects are created by the
  * engine via `node.aspect()`, never `new`.
  */
-export abstract class Aspect<K extends string, P = Node> {
+export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}> {
   /**
    * Opt this aspect class into EDITOR-RUN mode (generators): while a scene is edited, the scene
    * loader constructs the instance (refs resolved, `node`/`generated` set — never `onAttach`) and
@@ -195,12 +377,25 @@ export abstract class Aspect<K extends string, P = Node> {
    */
   static inspector?: (ui: InspectorUI, aspect: any) => void
 
+  /** Tick AFTER these classes within the same phase (`static after = [Controls]`). A constraint
+   *  always beats the numeric `updateOrder`. Classes absent from the phase are ignored. */
+  static after?: Function[]
+  /** Tick BEFORE these classes within the same phase (`static before = [Camera]`). */
+  static before?: Function[]
+
+  /** Every live instance of an aspect/system class, in attach order — the registry a game used to
+   *  hand-roll as `static all[]`. Live, read-only: copy it (`[...Aspect.all(Barrel)]`) before a loop
+   *  that detaches. Empty in the scene editor (aspects are inert data there). */
+  static all<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): readonly A[] {
+    return (instances.get(ctor) ?? []) as unknown as readonly A[]
+  }
+
   // NOTE: P has no `extends AspectHost` constraint on purpose — Emitter<E>'s generic
   // addEventListener makes a specific-event node (AspectHost<NodeEvents>) not assignable to
   // AspectHost<any>, which would reject every real node. P only types `this.node`; target
   // enforcement happens in aspect() via `this: Self extends TargetOf<A>`. Defaults to Node
   // (3D is the default engine) — a 2D aspect declares its own P, e.g. Aspect<'x', Sprite>.
-  /** The node this aspect is attached to (set at attach time). */
+  /** The node this aspect is attached to (set at attach time). For a System: the scene. */
   readonly node!: P
   /**
    * GENERATOR aspects (`static editor = { rebuild: true }`, attached through a scene file): a
@@ -209,11 +404,36 @@ export abstract class Aspect<K extends string, P = Node> {
    * the scene's draw set automatically (membership is separate from parenting). Undefined for
    * aspects attached by hand outside scene files. See docs/3d/scene-files.md.
    */
-  readonly generated!: Node & { clear(): void }
-  /** @internal phantom — lets the type system recover the accessor name `K`. Never read at runtime. */
+  readonly generated!: Node & { clear(): void, readonly version: number }
+  /**
+   * GENERATOR aspects attached through a scene file: the `Scene` the host node was built into —
+   * what `handle.instantiate({ scene })` / `scene.add()` need inside `rebuild()`. Set by the scene
+   * loader (edit AND play mode); undefined for aspects attached by hand. 3D only (2D aspects own
+   * their `scene` field). For a System: always set — the scene it is attached to.
+   */
+  readonly scene!: P extends Node ? Scene : P extends SystemHost ? P : unknown
+  // Phantom fields — they let the type system recover `K` (the accessor name) and `E` from an
+  // instance type (`KeyOf<A>`), never read at runtime. Deliberately NOT marked as internal-only:
+  // build-types emits with `stripInternal` (which matches that tag in ANY leading comment, `//`
+  // included), and without these in the public .d.ts `infer K` collapses to `string`, which turned
+  // every `node.<accessor>` / `scene.<accessor>` into an untyped index signature in projects.
   declare protected readonly __key__?: K
-  onAttach?(): void
-  onDetach?(): void
+  declare protected readonly __events__?: E
+  /** @internal attach sequence within the phase lists (tie-breaker). */
+  _phaseSeq = 0
+  /** @internal bit 1 = registered early, bit 2 = registered late. */
+  _phases = 0
+  private _listeners?: Map<string, Function[]>
+
+  // ---- lifecycle: the engine calls these, game code never does (hence `protected`; a subclass may
+  // still widen one to public when a method doubles as an explicit action). ----
+  /** The node (or scene) is set — initialize here, not in a constructor. */
+  protected onAttach?(): void
+  /** Release what onAttach acquired. */
+  protected onDetach?(): void
+  /** Called after `node.aspect(Ctor, opts)` re-assigns options on an ALREADY attached aspect (a
+   *  pre-attached one like `model.anim`): rebuild whatever was derived from the options at attach. */
+  protected onReconfigure?(): void
   /**
    * GENERATOR aspects: (re)build the derived output under `this.generated` — must be idempotent
    * (clear, then create). Call it from `onAttach()` for play mode; a class opting in with
@@ -222,23 +442,71 @@ export abstract class Aspect<K extends string, P = Node> {
    */
   rebuild?(): void
   /**
-   * Called every frame while attached (dt = seconds since the last frame). Render-synced: runs in the
-   * LATE phase by default — after the physics step + transform sync, right before the frame draws — so
-   * reads of `node.worldPosition` are the final drawn position (cameras/followers have no 1-frame lag).
-   * Set `updateBeforePhysics = true` (an instance field) to run in the EARLY phase (before the step)
-   * instead — for aspects that WRITE velocity/force/kinematic transforms and want the same frame's
-   * step to consume them. Cameras/followers READ, so they stay in the default LATE phase.
+   * LATE phase — every frame while attached, after the physics step + transform sync + animators,
+   * right before the frame draws: reads of `node.worldPosition` are the final drawn position
+   * (cameras/followers have no 1-frame lag) and what you write to a plain node is what this frame
+   * shows. The default home for game logic. `dt` = GAME seconds since the last frame (`Time.scale`
+   * applied; 0 while paused — see `updateWhilePaused`).
    */
-  update?(dt: number): void
+  protected update?(dt: number): void
+  /**
+   * EARLY phase — every frame BEFORE the physics step, so what you feed the simulation (velocity,
+   * `controller.move()`, forces, kinematic transforms) is consumed by this same frame's step: zero
+   * input latency. Use it only when you FEED the simulation. Reads here see last frame's settled
+   * state. A class rarely needs both phases — that is two aspects on one node.
+   */
+  protected updateBefore?(dt: number): void
 
-  /** Run update(dt) in the EARLY phase (before the physics step) rather than the default LATE phase.
-   *  An instance field (like `updateWhenVisible`) — set it as a class field: `updateBeforePhysics = true`.
-   *  Use only when you FEED the simulation (velocity/force/kinematic transform). Read once, at attach. */
-  updateBeforePhysics = false
-  /** Tick order within a phase — ascending; default 0, ties keep attach order. Read once, at attach. */
-  order = 0
+  /** Tick order within a phase and rank — ascending; default 0, ties keep attach order. A declared
+   *  `static after` / `static before` constraint always beats this number. Read once, at attach —
+   *  set it as a class field. */
+  protected updateOrder = 0
+  /** Keep ticking while `Time.paused` (a HUD fade, the pause menu). `dt` is still 0 then — read
+   *  `Time.unscaledDt` for wall-clock motion. Checked every frame; may be toggled at any time. */
+  protected updateWhilePaused = false
 
   /** Opt-in: only run update(dt) while the node is on-screen. NOOP for now — visibility culling isn't
    *  wired yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
-  updateWhenVisible = false
+  protected updateWhenVisible = false
+
+  // ---- events: what this aspect tells the world (`E` in the generic) ----
+  /** Listen to one of this aspect's events. Chainable. Cleared on detach. */
+  on<C extends keyof E & string>(channel: C, callback: E[C]): this {
+    const map = (this._listeners ??= new Map())
+    const list = map.get(channel)
+    if (list) list.push(callback)
+    else map.set(channel, [callback])
+    return this
+  }
+  /** Remove a listener added with `on` (same function reference). */
+  off<C extends keyof E & string>(channel: C, callback: E[C]): this {
+    const list = this._listeners?.get(channel)
+    if (list) { const i = list.indexOf(callback); if (i >= 0) list.splice(i, 1) }
+    return this
+  }
+  /** Fire one of this aspect's events. Protected: only the aspect itself emits. */
+  protected emit<C extends keyof E & string>(channel: C, ...args: Parameters<E[C]>): void {
+    const list = this._listeners?.get(channel)
+    if (!list || list.length === 0) return
+    for (const fn of list.slice()) fn(...args)
+  }
+  /** @internal */
+  _clearEvents(): void { this._listeners = undefined }
+}
+
+/**
+ * An aspect of a SCENE: game logic with no single node to live on — input mapping, the FX pools, the
+ * HUD, the game mode. Same lifecycle (`onAttach`/`onDetach`), same two phases (`updateBefore` /
+ * `update`), same ordering (`updateOrder`, `static after`) and events as a node aspect; `this.scene` is the
+ * scene it was attached to. `S` = the scene kind (`Scene` by default, `Scene2D` for 2D games).
+ *
+ *   class Hud extends System<'hud'> {
+ *     static after = [Player]
+ *     update(dt: number) { … }
+ *   }
+ *   scene.system(Hud)      // attach
+ *   scene.hud              // the typed accessor
+ */
+export abstract class System<K extends string, S extends SystemHost = Scene, E extends EventMap = {}> extends Aspect<K, S, E> {
+  // `this.scene` (and `this.node`) are typed S by the base class's conditional — nothing to add.
 }

package/runtime/sdk/core/compWrite.ts

@@ -0,0 +1,42 @@
+// Component writes on SDK-owned vectors — the runtime half of chisel's `comp_write` pass.
+//
+//   hero.controller.velocity.y = 7     →  __compWrite(hero.controller, "velocity", "y", 7)
+//   hero.controller.velocity.y += 3    →  __compOp(hero.controller, "velocity", "y", 0, 3)
+//
+// A getter like `velocity` hands out a fresh Vec3, so the literal spelling would write to a copy and
+// silently do nothing. chisel rewrites the exact `<owner>.<prop>.<x|y|z|w> = v` shape into these
+// helpers, which ask the OWNER to apply the component write (no getter call, no allocation) and
+// fall back to the plain write on anything else, so a user record `{ velocity: { x, y } }` behaves
+// exactly as written. Only the direct spelling is covered: `const v = c.velocity; v.y = 7` is still
+// a write to a copy.
+//
+// Owners today: Node / Node2D / Camera2D (`position` → the scalar setters, physics routing included),
+// Physics (`velocity`, `angularVelocity`), CharacterController / CharacterController2D (`velocity`).
+//
+// An owner declares WHICH getters qualify as compile-time data and answers them at runtime:
+//
+//   static _comps = ["velocity"]                 // chisel reads the list, then strips it (0 bytes shipped)
+//   _writeComp(prop, axis, value) { … }          // called for listed props only; a hook without the
+//                                                // list is a build diagnostic and routes nothing
+
+export type CompAxis = "x" | "y" | "z" | "w"
+
+/** Implemented by a class whose vector getters accept component writes (see above). The class also
+ *  carries `static _comps: string[]` naming those getters — compile-time data, absent at runtime. */
+export interface CompWriter {
+  _writeComp(prop: string, axis: CompAxis, value: number): void
+}
+
+/** `<o>.<prop>.<axis> = value`, routed to the owner when it has the hook. Returns the value. */
+export const __compWrite = (o: any, prop: string, axis: CompAxis, value: number): number => {
+  if (o._writeComp !== undefined) o._writeComp(prop, axis, value)   // a direct call, not .call — cheaper on QuickJS
+  else o[prop][axis] = value
+  return value
+}
+
+/** `<o>.<prop>.<axis> op= v` — `op`: 0 `+=`, 1 `-=`, 2 `*=`, 3 `/=`. The current component is read
+ *  through the normal getter (one fresh vector), the result written like `__compWrite`. */
+export const __compOp = (o: any, prop: string, axis: CompAxis, op: number, v: number): number => {
+  const cur = o[prop][axis] as number
+  return __compWrite(o, prop, axis, op === 0 ? cur + v : op === 1 ? cur - v : op === 2 ? cur * v : cur / v)
+}

package/runtime/sdk/core/fields.ts

@@ -62,7 +62,7 @@ export type AspectClassInfo = {
 
 // Instance fields every aspect inherits from the Aspect base — configuration plumbing, not content.
 // `generated` is declare-only in TS, but the bundler lowers it to a real (undefined) class field.
-const BASE_FIELDS = new Set([ "node", "generated", "updateBeforePhysics", "order", "updateWhenVisible" ])
+const BASE_FIELDS = new Set([ "node", "generated", "updateOrder", "updateWhilePaused", "updateWhenVisible" ])
 
 /** Infer the editor widget from a default value's shape. */
 export const inferFieldEditor = (value: unknown): FieldEditor | undefined => {