lecodes-cli 0.18.2 → 0.19.2

package/runtime/sdk/g2/defineScene2d.ts

@@ -1,381 +0,0 @@
-// 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/runtime/sdk/g2/groups2d.ts

@@ -1,106 +0,0 @@
-// 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/runtime/sdk/g2/loop.ts

@@ -1,50 +0,0 @@
-// 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/runtime/sdk/g2/scenarios2d.ts

@@ -1,69 +0,0 @@
-// 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 ]
-  }
-}