lecodes-sdk 0.19.0

package/src/g2/defineScene2d.ts

@@ -0,0 +1,381 @@
+// 2D scenes as data: the runtime behind `.scene2d.ts` files (docs/scene2d-editor-plan.md §4).
+// The 2D sibling of scene/defineScene.ts — same literal grammar (one default-exported
+// `defineScene2d({...})` call, nodes keyed by name, `use(...)` aspects, `make(...)` factories),
+// with the 2D source vocabulary: `sprite` (a named entry of an imported `.sprite.ts` sheet),
+// `tilemap` (texture + grid + a `cells('…')` payload), `camera`, `make`, or none = group.
+//
+//   // forest.scene2d.ts
+//   import props from './props.sprite'
+//   import hero from './hero.sprite'
+//   export default defineScene2d({
+//     env: { background: '#5a6b3b', pixelPerfect: true, gravity: [0, 0] },
+//     layers: { 1: { ySort: true } },
+//     nodes: {
+//       ground: { tilemap: { texture: asset('./TileSet.png'), tile: 64, atlas: [64, 64],
+//                            cells: cells('…') }, layer: 0 },
+//       tree1:  { sprite: { sheet: props, name: 'tree_orange' }, position: [160, 288], layer: 1 },
+//       player: { sprite: { sheet: hero, clip: 'idle' }, position: [800, 200], layer: 1,
+//                 aspects: [use(CameraFollow, { smooth: 0.12 })] },
+//     },
+//   })
+//
+//   // main.ts
+//   import forest from './forest.scene2d'
+//   const { scene, nodes } = await forest.open()
+//
+// Colliders and bodies are SCENE semantics (sheets are art only): give a node `aspects:
+// [use(Shape2D, {…}), use(Physics2D, {…})]`. Aspects attach normally in play mode; in edit mode
+// (`globalThis.__lecodesSceneEdit`) they are held as data, so nothing falls or fires while
+// editing — clip playback still runs (render-side).
+// Prefabs (scene-in-scene) are a later phase — not in this grammar yet.
+
+import type { ColorInput } from "../core/color"
+import type { Vec2Like } from "../math/vec"
+import {
+  EDIT_FLAG, isEditMode, resolveRefs, type AspectEntry, type MakeEntry as SharedMakeEntry,
+} from "../scene/grammar"
+import { Scene2D } from "./Scene2D"
+import { Node2D } from "./Node2D"
+import { Sprite } from "./Sprite"
+import { Tilemap } from "./Tilemap"
+import { Texture2D } from "./Texture2D"
+import { Physics2D } from "./Physics2D"
+import { SpriteSheet } from "./SpriteSheet"
+import { Tileset, Autotile2D } from "./Tileset"
+import type { SpriteAnimation } from "./SpriteAnimation"
+import type { CellsData } from "./cells"
+import type { With } from "../core/Aspect"
+
+// ---- the literal grammar (what the visual editor reads and writes) -----------
+
+export type Scene2dEnv = {
+  /** Background color — '#5a6b3b', 0x5a6b3b, or [r,g,b] in 0..1. */
+  background?: ColorInput
+  /** Texture sampling: 'nearest' (crisp pixel art, engine default) or 'linear'. */
+  filter?: "nearest" | "linear"
+  /** Pixel-art crispness: snap the camera to whole screen pixels (seeds CameraFollow's
+   *  `pixelSnap`, and the initial camera position lands on whole world units). */
+  pixelPerfect?: boolean
+  /** Physics world gravity (Y-up: down is negative). Presence configures the world before any
+   *  body is created — `[0, 0]` for top-down worlds. Omit to leave the world unconfigured. */
+  gravity?: Vec2Like
+}
+
+/** A sprite node: one named entry of an imported `.sprite.ts` sheet. The sheet is ART only —
+ *  colliders/bodies are scene semantics: put Shape2D / Physics2D / Trigger2D in `aspects`. */
+export type SpriteSourceDef = {
+  /** The imported sheet handle: `import props from './props.sprite'` … `sheet: props`. */
+  sheet: SpriteSheet
+  /** The entry name; omit when the sheet declares exactly one sprite. */
+  name?: string
+  /** Start this clip immediately (sliced entries with clips). */
+  clip?: string
+  /** Initial facing for `perDirection` clips. */
+  direction?: string
+}
+
+export type TilemapSourceDef = {
+  /** The tileset image — `asset('./TileSet.png')`. */
+  texture: string
+  /** On-screen cell size in world units — a number (square) or [w, h]. */
+  tile: number | [number, number]
+  /** Atlas grid: how the texture slices into tiles, [atlasCols, atlasRows]. */
+  atlas: [number, number]
+  /** The map: a `cells('…')` payload — or any `{ cols, rows, data }` of your own. */
+  cells: CellsData | { cols: number, rows: number, data: number[] | Int32Array }
+}
+
+/** A camera marker node: seeds the scene camera's starting position (+ zoom). To MOVE the camera
+ *  in play, attach `CameraFollow` to the node being followed — not aspects on this marker. */
+export type Camera2dNodeDef = { zoom?: number }
+
+export type Scene2dNodeDef = {
+  // -- source (at most one; none = plain group node) --
+  sprite?: SpriteSourceDef
+  tilemap?: TilemapSourceDef
+  camera?: Camera2dNodeDef
+  /** A code-built subtree — `make(factoryFn, { ...literal args })`, factory returns a Node2D. */
+  make?: SharedMakeEntry<any, Node2D>
+  // -- transform / render --
+  position?: Vec2Like
+  /** Degrees, CCW. */
+  rotation?: number
+  scale?: Vec2Like | number
+  /** Draw layer (int) — higher renders on top. */
+  layer?: number
+  /** Intra-layer depth for non-Y-sorted layers. */
+  z?: number
+  /** Sprite tint (sprite nodes only). */
+  color?: ColorInput
+  /** Sprite opacity 0..1 (sprite nodes only). */
+  opacity?: number
+  flipX?: boolean
+  flipY?: boolean
+  visible?: boolean
+  /** Editor-only: the move gizmo won't target this node (fields still edit). No runtime effect. */
+  locked?: boolean
+  // -- capabilities / hierarchy --
+  aspects?: readonly AspectEntry<any>[]
+  children?: Record<string, Scene2dNodeDef>
+}
+
+export type Scene2dCameraDef = {
+  position?: Vec2Like
+  zoom?: number
+}
+
+export type Scene2dDef = {
+  env?: Scene2dEnv
+  /** Per-layer config, keyed by layer number: `layers: { 1: { ySort: true } }`. */
+  layers?: Record<number | string, { ySort?: boolean }>
+  /** Starting camera when there's no camera NODE (a camera node wins). */
+  camera?: Scene2dCameraDef
+  nodes?: Record<string, Scene2dNodeDef>
+}
+
+// ---- typed handle -------------------------------------------------------------
+
+type SourceNodeOf<N extends Scene2dNodeDef> =
+  N extends { sprite: { clip: string } } ? Sprite & { anim: SpriteAnimation }
+  : N extends { sprite: SpriteSourceDef } ? Sprite
+  : N extends { tilemap: TilemapSourceDef } ? Tilemap
+  : Node2D
+
+type AspectsOf<N extends Scene2dNodeDef> =
+  N extends { aspects: readonly AspectEntry<infer A>[] } ? A : never
+
+type NodeOf<N extends Scene2dNodeDef> =
+  [AspectsOf<N>] extends [never] ? SourceNodeOf<N> : With<SourceNodeOf<N>, AspectsOf<N>>
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
+
+type ChildMapsOf<T extends Record<string, Scene2dNodeDef>> =
+  { [K in keyof T]: T[K] extends { children: infer C extends Record<string, Scene2dNodeDef> } ? NodesOf<C> : never }[keyof T]
+
+type NodesOf<T extends Record<string, Scene2dNodeDef>> =
+  { [K in keyof T]: NodeOf<T[K]> } &
+  ([ChildMapsOf<T>] extends [never] ? unknown : UnionToIntersection<ChildMapsOf<T>>)
+
+export type Scene2dNodes<D extends Scene2dDef> =
+  D["nodes"] extends Record<string, Scene2dNodeDef> ? NodesOf<D["nodes"]> : Record<string, Node2D>
+
+export type LoadedScene2d<D extends Scene2dDef> = {
+  scene: Scene2D
+  nodes: Scene2dNodes<D>
+}
+
+// ---- runtime -------------------------------------------------------------------
+
+const createSprite = (name: string, def: SpriteSourceDef): Sprite => {
+  const sheet = def.sheet
+  if (!(sheet instanceof SpriteSheet)) {
+    throw new Error(`Scene2d node "${name}": sprite.sheet is not a sheet handle (import the .sprite file's default export)`)
+  }
+  const entryName = def.name ?? (sheet.spriteNames.length === 1 ? sheet.spriteNames[0]! : undefined)
+  if (entryName === undefined) {
+    throw new Error(`Scene2d node "${name}": sprite.name is required — the sheet has ${sheet.spriteNames.length} sprites (${sheet.spriteNames.join(", ")})`)
+  }
+  return sheet.make(entryName, {
+    clip: def.clip,
+    direction: def.direction,
+  } as Parameters<SpriteSheet["make"]>[1])
+}
+
+const createTilemap = async (
+  name: string, def: TilemapSourceDef, aspects?: readonly AspectEntry<any>[],
+): Promise<Tilemap> => {
+  const grid = def.cells
+  if (!grid || typeof grid !== "object" || typeof (grid as CellsData).cols !== "number") {
+    throw new Error(`Scene2d node "${name}": tilemap.cells must be a cells('…') payload or a { cols, rows, data } value`)
+  }
+  // Autotile2D on the node flips `cells` from raw atlas indices to material ids — derive the
+  // display indices HERE, before the Tilemap exists (aspects are data on the def), so the native
+  // layer keeps receiving a dumb index grid and derived data is never persisted.
+  let data: number[] | Int32Array = grid.data
+  for (const entry of aspects ?? []) {
+    if ((entry.ctor as unknown) !== Autotile2D) continue
+    const props = entry.props as Partial<Autotile2D> | undefined
+    if (props?.tileset instanceof Tileset) {
+      data = props.tileset.derive(grid.cols, grid.rows, data, props.seed ?? 0)
+    } else {
+      console.error(`[scene2d] node "${name}": Autotile2D has no tileset handle — cells render as raw indices`)
+    }
+  }
+  const texture = await Texture2D.load(def.texture)
+  return new Tilemap({
+    texture, cols: grid.cols, rows: grid.rows,
+    tile: def.tile, atlas: def.atlas, data,
+  })
+}
+
+const createSource = (name: string, def: Scene2dNodeDef): Node2D | Promise<Node2D> => {
+  const sources = [ def.sprite, def.tilemap, def.camera, def.make ].filter((s) => s !== undefined).length
+  if (sources > 1) throw new Error(`Scene2d node "${name}" declares more than one source (sprite/tilemap/camera/make)`)
+  if (def.sprite !== undefined) return createSprite(name, def.sprite)
+  if (def.tilemap !== undefined) return createTilemap(name, def.tilemap, def.aspects)
+  // make/camera/group nodes are plain wrappers — make subtrees mount under them in phase 2
+  return new Node2D()
+}
+
+const applyNode = (node: Node2D, name: string, def: Scene2dNodeDef): void => {
+  node.name = name
+  if (def.position) node.position = def.position
+  if (def.rotation !== undefined) node.rotation = def.rotation
+  if (def.scale !== undefined) node.scale = def.scale
+  if (def.layer !== undefined) node.layer = def.layer
+  if (def.z !== undefined) node.z = def.z
+  if (def.visible !== undefined) node.visible = def.visible
+  if (def.locked !== undefined) (node as { _sceneLocked?: boolean })._sceneLocked = def.locked
+  if (def.camera !== undefined) (node as { _sceneCamera?: boolean })._sceneCamera = true
+  if (def.children) (node as { _sceneChildOrder?: string[] })._sceneChildOrder = Object.keys(def.children)
+  if (node instanceof Sprite) {
+    if (def.color !== undefined) node.color = def.color
+    if (def.opacity !== undefined) node.opacity = def.opacity
+    if (def.flipX !== undefined) node.flipX = def.flipX
+    if (def.flipY !== undefined) node.flipY = def.flipY
+  }
+}
+
+/** The first camera-source def in file order (depth-first), or null. */
+const findCamera = (defs?: Record<string, Scene2dNodeDef>): { name: string, def: Camera2dNodeDef } | null => {
+  for (const [ name, nd ] of Object.entries(defs ?? {})) {
+    if (nd.camera !== undefined) return { name, def: nd.camera }
+    const inner = findCamera(nd.children)
+    if (inner) return inner
+  }
+  return null
+}
+
+const attachAspects = (
+  node: Node2D, def: Scene2dNodeDef, nodes: Record<string, Node2D>, scene: Scene2D, env: Scene2dEnv,
+): void => {
+  if (isEditMode()) {
+    // Data-only (the future harness reads [ctor, props] from here) — no onAttach side effects
+    // (bodies, loops) while editing.
+    ;(node as unknown as { _sceneAspects: readonly AspectEntry<any>[] })._sceneAspects = def.aspects ?? []
+    return
+  }
+  for (const entry of def.aspects ?? []) {
+    let props = resolveRefs(entry.props as Record<string, unknown> | undefined, nodes)
+    // Aspects that declare `static wantsScene` (CameraFollow) get the scene wired in, and their
+    // pixel snapping defaults to env.pixelPerfect — explicit props always win.
+    if ((entry.ctor as { wantsScene?: boolean }).wantsScene) {
+      props = {
+        scene,
+        ...(env.pixelPerfect !== undefined ? { pixelSnap: env.pixelPerfect } : {}),
+        ...props,
+      }
+    }
+    ;(node as Node2D & { aspect(c: unknown, p?: unknown): unknown }).aspect(entry.ctor, props)
+  }
+}
+
+/** Run a def's make() factory (phase 2 — every node exists, so ref() args resolve). The subtree
+ *  mounts under the wrapper node; the wrapper's transform stays editor-owned. */
+const attachMake = (
+  node: Node2D, name: string, def: Scene2dNodeDef, nodes: Record<string, Node2D>, scene: Scene2D,
+): Promise<void> | undefined => {
+  const entry = def.make
+  if (!entry) return undefined
+  const args = resolveRefs({ ...(entry.args ?? {}) } as Record<string, unknown>, nodes) ?? {}
+  return Promise.resolve(entry.fn(args as never)).then((made) => {
+    if (made instanceof Node2D) {
+      node.add(made)
+      // membership is per-entity in creator-2d — add the whole made subtree to the draw set
+      const addAll = (n: Node2D): void => { scene.add(n); n.children.forEach(addAll) }
+      addAll(made)
+    }
+  }).catch((e) => { console.error(`[scene2d] make() factory failed on "${name}":`, e) })
+}
+
+/** Build one defs record into `scene` under `parent`, two-phase (all nodes first, then
+ *  aspects/make — so `ref()`s resolve regardless of declaration order). */
+const buildNodes = async (
+  defs: Record<string, Scene2dNodeDef>, parent: Node2D | null, scene: Scene2D,
+  nodes: Record<string, Node2D>, env: Scene2dEnv,
+): Promise<void> => {
+  const pending: { name: string, node: Node2D, def: Scene2dNodeDef }[] = []
+
+  const build = async (name: string, nd: Scene2dNodeDef, parentNode: Node2D | null): Promise<void> => {
+    const node = await createSource(name, nd)
+    if (parentNode) parentNode.add(node)
+    scene.add(node)
+    applyNode(node, name, nd)
+    pending.push({ name, node, def: nd })
+    nodes[name] = node
+    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node)))
+  }
+
+  await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent)))
+  const waits: Promise<void>[] = []
+  for (const p of pending) {
+    attachAspects(p.node, p.def, nodes, scene, env)
+    const wait = attachMake(p.node, p.name, p.def, nodes, scene)
+    if (wait) waits.push(wait)
+  }
+  if (waits.length > 0) await Promise.all(waits)
+}
+
+const instantiate = async (def: Scene2dDef): Promise<{ scene: Scene2D, nodes: Record<string, Node2D> }> => {
+  const env = def.env ?? {}
+  // configure() resets the physics world, so it must run before any body is created (aspects
+  // create bodies right after the node build). Edit mode holds physics as data — skip.
+  if (env.gravity !== undefined && !isEditMode()) Physics2D.configure({ gravity: env.gravity })
+
+  const scene = new Scene2D({ background: env.background, filter: env.filter })
+  for (const [ key, layer ] of Object.entries(def.layers ?? {})) {
+    if (layer?.ySort) scene.layer(Number(key)).ySort(true)
+  }
+
+  const nodes: Record<string, Node2D> = {}
+  await buildNodes(def.nodes ?? {}, null, scene, nodes, env)
+
+  // a camera NODE wins over the top-level `camera:` block; both only SEED the starting view —
+  // attach CameraFollow to the tracked node to move the camera in play
+  const cam = findCamera(def.nodes)
+  const camNode = cam ? nodes[cam.name] : undefined
+  if (cam && camNode) {
+    const p = camNode.worldPosition
+    scene.camera.position = env.pixelPerfect ? [ Math.round(p.x), Math.round(p.y) ] : p
+    if (cam.def.zoom !== undefined) scene.camera.zoom = cam.def.zoom
+  } else if (def.camera) {
+    if (def.camera.position) scene.camera.position = def.camera.position
+    if (def.camera.zoom !== undefined) scene.camera.zoom = def.camera.zoom
+  }
+
+  return { scene, nodes }
+}
+
+export class Scene2dHandle<D extends Scene2dDef = Scene2dDef> {
+  readonly def: D
+  private _loading?: Promise<LoadedScene2d<D>>
+
+  constructor(def: D) { this.def = def }
+
+  /** Instantiate the scene (idempotent — subsequent calls return the same instance). Does not open. */
+  load(): Promise<LoadedScene2d<D>> {
+    this._loading ??= instantiate(this.def).then((live) => live as LoadedScene2d<D>)
+    return this._loading
+  }
+
+  /** Load and make active (only the active 2D scene renders). */
+  async open(): Promise<LoadedScene2d<D>> {
+    const loaded = await this.load()
+    loaded.scene.open()
+    return loaded
+  }
+}
+
+/**
+ * Define a 2D scene as data — the default export of a `.scene2d.ts` file. Returns a typed handle:
+ * `const { scene, nodes } = await handle.open()` gives `nodes.<name>` typed by its source block
+ * (Sprite / Tilemap / Node2D) with its `use(...)`d aspects attached.
+ */
+export const defineScene2d = <const D extends Scene2dDef>(def: D): Scene2dHandle<D> => {
+  const handle = new Scene2dHandle(def)
+  const g = globalThis as unknown as { [EDIT_FLAG]?: boolean, __lecodesScenes2d?: Scene2dHandle[] }
+  // Editor hook: expose defined handles to a host that runs the bundle in edit mode.
+  if (g[EDIT_FLAG]) (g.__lecodesScenes2d ??= []).push(handle as Scene2dHandle)
+  return handle
+}

package/src/g2/groups2d.ts

@@ -0,0 +1,106 @@
+// Collision groups — which bodies are allowed to touch which. Called groups, not layers, because
+// `layer` already means DRAW order in 2D (`node.layer`, `scene2d.layer(n).ySort()`).
+//
+//   // game/groups.ts
+//   export const player  = Physics2D.addGroup()
+//   export const bullets = Physics2D.addGroup().ignoreSelf().ignore(player)
+//
+//   bullet.aspect(Physics2D, { motion: 'dynamic', group: bullets })
+//
+// Two decisions worth knowing, both deliberate:
+//
+// SUBTRACTIVE, not enumerative. A group collides with everything EXCEPT what it ignores, so adding a
+// new group later cannot silently stop existing pairs from colliding. The enumerative form —
+// "collides only with [ground, enemy]" — decays: introduce `crate` a month later and the bullets
+// start flying through it, with nothing to notice.
+//
+// SYMMETRIC. Box2D's filter is an AND of two masks, so declaring the relation on one side only is the
+// classic trap ("A allowed B but B didn't allow A" → they silently pass through). Both sides are set
+// from one undirected edge here, so naming it once is enough.
+//
+// Budget: 32 bits, because a category/mask must cross the bridge as a plain JS number and only 2^32 is
+// exactly representable there. One bit is the implicit default group, one is reserved for the
+// character's shadow body — 30 user groups.
+
+/** Collides with everything. */
+export const ALL_GROUPS = 0xffffffff
+
+/** @internal Bit 0 — every body that never names a group. */
+export const DEFAULT_BIT = 1 << 0
+/** @internal Bit 1 — the character's shadow body: solid shapes never see it, sensors always do. */
+export const CHARACTER_BIT = 1 << 1
+
+const MAX_USER_GROUPS = 30
+let nextBit = 2
+const all: PhysicsGroup2D[] = []
+
+// Bodies whose filter has to be re-pushed when the topology changes. Only bodies that actually named
+// a group register, so a project that never touches groups keeps an empty set.
+const listeners = new Set<() => void>()
+/** @internal */
+export const _watchGroupChanges = (fn: () => void): void => { listeners.add(fn) }
+/** @internal */
+export const _unwatchGroupChanges = (fn: () => void): void => { listeners.delete(fn) }
+
+export class PhysicsGroup2D {
+  /** The single category bit this group owns. */
+  readonly bit: number
+  /** Optional debug label, so an inspector says "bullets" rather than "group #3". */
+  readonly label: string
+
+  private _ignored = 0
+
+  /** @internal — use `Physics2D.addGroup()`. */
+  constructor(bit: number, label: string) {
+    this.bit = bit
+    this.label = label
+  }
+
+  /** @internal The Box2D pair for a shape in this group. */
+  get category(): number { return this.bit }
+  /** @internal */
+  get mask(): number { return (ALL_GROUPS & ~this._ignored) >>> 0 }
+
+  /**
+   * Stop colliding with these groups — symmetric, so naming it on one side is enough. Safe to call
+   * after bodies exist: their filters are re-pushed.
+   */
+  ignore(...groups: PhysicsGroup2D[]): this {
+    for (const g of groups) {
+      this._ignored |= g.bit
+      g._ignored |= this.bit
+    }
+    for (const fn of listeners) fn()
+    return this
+  }
+
+  /** Members of this group don't collide with EACH OTHER — bullets, debris, a ragdoll's own bones. */
+  ignoreSelf(): this {
+    this._ignored |= this.bit
+    for (const fn of listeners) fn()
+    return this
+  }
+}
+
+/** @internal The implicit group of every body that never names one. */
+export const defaultGroup = new PhysicsGroup2D(DEFAULT_BIT, "default")
+
+/** @internal Register a new group (see `Physics2D.addGroup`). */
+export const _addGroup = (label = ""): PhysicsGroup2D => {
+  if (nextBit >= 2 + MAX_USER_GROUPS) {
+    throw new Error(`Physics2D.addGroup: out of collision groups (${MAX_USER_GROUPS} max — a category has to cross the bridge as a 32-bit number, and two bits are reserved).`)
+  }
+  const g = new PhysicsGroup2D((1 << nextBit) >>> 0, label || `group${nextBit - 1}`)
+  nextBit++
+  all.push(g)
+  return g
+}
+
+/** @internal Sensors must always be visible to the character's shadow body, solids never. */
+export const sensorMask = (g: PhysicsGroup2D | undefined): number =>
+  (((g ?? defaultGroup).mask | CHARACTER_BIT) & ALL_GROUPS) >>> 0
+/** @internal */
+export const solidMask = (g: PhysicsGroup2D | undefined): number =>
+  (((g ?? defaultGroup).mask & ~CHARACTER_BIT) & ALL_GROUPS) >>> 0
+/** @internal */
+export const categoryOf = (g: PhysicsGroup2D | undefined): number => (g ?? defaultGroup).category

package/src/g2/loop.ts

@@ -0,0 +1,50 @@
+// Internal per-frame plumbing for the 2D engine. NOT user-facing — user game logic uses the host
+// `setLoop` global. `onUpdate` taps the engine's render-synced pre-frame hook (_creator2d.onUpdate),
+// for anything that must move in lockstep with the native render (no 1-frame lag).
+//
+// The animation-event registration is lazy (first use) so a 2D project that never animates a sprite
+// pulls none of this in.
+
+import { Vec2 } from "../math/vec"
+import { node2dRegistry } from "./Node2D"
+
+export const onUpdate = (callback: (dt: number) => void): void => _creator2d.onUpdate(callback)
+export const offUpdate = (callback: (dt: number) => void): void => _creator2d.offUpdate(callback)
+
+// Route native animation events (queued in C++, drained once per frame) to the owning node, which
+// translates the native clip id to a clip name and emits 'loopReached' / 'completed'.
+let animEventsRegistered = false
+export const ensureAnimEvents = (): void => {
+  if (animEventsRegistered) return
+  animEventsRegistered = true
+  _creator2d.setOnAnimEvent(({ entityId, clipId, type }) => {
+    node2dRegistry.get(entityId)?._dispatchAnimEvent(clipId, type)
+  })
+}
+
+// Route native physics contact/sensor events to the owning nodes' 'enter'/'exit' events. Each event
+// is delivered to BOTH nodes with the other as the argument. type: 0 contactBegin, 1 contactEnd,
+// 2 sensorBegin, 3 sensorEnd. Registered lazily by the first 'enter'/'exit' listener (Node2D) or the
+// first Trigger2D — it used to hang off Trigger2D alone, so solid-vs-solid contacts silently never
+// fired in a project without a single trigger.
+//
+// A contact BEGIN also carries the manifold, which the listener gets as a second argument: the world
+// point, the surface normal, and the approach speed. The normal points from A to B, so it is FLIPPED
+// for the second delivery — each side gets the normal pointing away from the thing it hit, which is
+// what "did I land on top or hit a wall" needs.
+let physicsEventsRegistered = false
+export const ensurePhysicsEvents = (): void => {
+  if (physicsEventsRegistered) return
+  physicsEventsRegistered = true
+  _creator2d.setOnPhysicsEvent((a, b, type, px, py, nx, ny, speed) => {
+    const na = node2dRegistry.get(a)
+    const nb = node2dRegistry.get(b)
+    if (!na || !nb) return
+    const channel = type === 1 || type === 3 ? "exit" : "enter"
+    // Box2D's manifold normal points from A TOWARD B. Each listener wants the normal of the surface
+    // it hit, pointing back at itself — so A gets it negated and B gets it as-is. Landing on a floor
+    // then reads normal.y ≈ +1 for the falling body, which is the test a game actually writes.
+    na._emitCollision(channel, nb, { point: new Vec2(px, py), normal: new Vec2(-nx, -ny), speed })
+    nb._emitCollision(channel, na, { point: new Vec2(px, py), normal: new Vec2(nx, ny), speed })
+  })
+}

package/src/g2/scenarios2d.ts

@@ -0,0 +1,69 @@
+// No-code 2D scenario aspects (the gl/scenarios.ts precedent): behaviors a scene builder attaches
+// in a `.scene2d.ts` file without writing aspect code. First resident: CameraFollow — the eased,
+// pixel-snapped follow camera every top-down/side-scroller needs (it absorbs the reference app's
+// ~50 lines of snap/follow plumbing).
+//
+// Conventions: update() runs in the LATE phase (after physics, render-synced when the engine
+// provides the hooks), so followers read final, drawn-this-frame positions.
+
+import { Aspect } from "../core/Aspect"
+import type { Camera2D } from "./Camera2D"
+import type { Node2D } from "./Node2D"
+import type { Scene2D } from "./Scene2D"
+
+// SCREEN pixels per world unit, MEASURED from the native projection (zoom + world→screen mapping
+// are applied natively, so "1 world unit = 1 px" can't be assumed — and worldToScreen is affine,
+// so the per-unit delta is position-independent). Re-measured only when zoom changes.
+type PixelGrid = { sx: number, sy: number, zoomAt: number }
+
+const snapToGrid = (cam: Camera2D, grid: PixelGrid, x: number, y: number): [number, number] => {
+  if (grid.sx === 0 || cam.zoom !== grid.zoomAt) {
+    const o = cam.worldToScreen(0, 0)
+    grid.sx = Math.abs(cam.worldToScreen(1, 0).x - o.x) || 1
+    grid.sy = Math.abs(cam.worldToScreen(0, 1).y - o.y) || 1
+    grid.zoomAt = cam.zoom
+  }
+  return [ Math.round(x * grid.sx) / grid.sx, Math.round(y * grid.sy) / grid.sy ]
+}
+
+/**
+ * Ease the scene camera toward this node every frame (attach it to the player). In a `.scene2d.ts`
+ * file the loader wires `scene` automatically; from hand-written code pass it yourself:
+ * `hero.aspect(CameraFollow, { scene })`.
+ *
+ * The eased position accumulates at full precision and only the value PUSHED to the camera is
+ * snapped — reading the snapped camera back as the ease-from value would let tiny sub-pixel steps
+ * round to zero near settle (the follow would stall a few px off-centre, then jump).
+ */
+export class CameraFollow extends Aspect<"cameraFollow", Node2D> {
+  static readonly aspect = "cameraFollow"
+  /** The scene2d loader injects the scene into aspects that declare this. */
+  static readonly wantsScene = true
+
+  /** The scene whose camera follows (wired by the scene file loader). */
+  scene: Scene2D | null = null
+  /** Exponential time constant in seconds; smaller = snappier, 0 = pin the node to centre. */
+  smooth = 0.12
+  /** Camera offset from the node, in world units. */
+  offset: [number, number] = [ 0, 0 ]
+  /** Quantize the camera to whole screen pixels so eased motion never shimmers pixel art.
+   *  Defaults to the scene's `env.pixelPerfect` (true when unset). */
+  pixelSnap = true
+
+  private _x = NaN
+  private _y = NaN
+  private readonly _grid: PixelGrid = { sx: 0, sy: 0, zoomAt: NaN }
+
+  update(dt: number): void {
+    const scene = this.scene
+    if (!scene) return
+    const cam = scene.camera
+    const p = this.node.worldPosition
+    const tx = p.x + this.offset[0], ty = p.y + this.offset[1]
+    if (Number.isNaN(this._x)) { const c = cam.position; this._x = c.x; this._y = c.y } // seed from the camera's pose
+    const k = this.smooth > 0 ? 1 - Math.exp(-dt / this.smooth) : 1
+    this._x += (tx - this._x) * k
+    this._y += (ty - this._y) * k
+    cam.position = this.pixelSnap ? snapToGrid(cam, this._grid, this._x, this._y) : [ this._x, this._y ]
+  }
+}