lecodes-cli 0.1.6 → 0.2.0

package/runtime/sdk/core/color.ts

@@ -0,0 +1,66 @@
+// Shared color parsing for both engines. Users pass colors the natural ways — a CSS-ish hex string
+// ('#10131a', '#abc', '#rrggbbaa'), a packed number (0xff0000), or normalized components
+// ([r,g,b] / [r,g,b,a] in 0..1). The engines want different forms (2D wants 0..1 floats, 3D wants a
+// packed int), so this module is the single place that converts.
+
+export type ColorInput =
+  | string
+  | number
+  | readonly [number, number, number]
+  | readonly [number, number, number, number]
+
+const parseHexString = (input: string): [number, number, number, number] => {
+  let s = input.trim()
+  if (s[0] === "#") s = s.slice(1)
+  // #rgb / #rgba shorthand → double each nibble
+  if (s.length === 3 || s.length === 4) s = s.split("").map((c) => c + c).join("")
+  const int = parseInt(s, 16)
+  if (s.length === 8) return [ (int >>> 24) & 255, (int >> 16) & 255, (int >> 8) & 255, int & 255 ]
+  // default 6-digit (rrggbb); anything malformed falls back to opaque black
+  if (s.length === 6) return [ (int >> 16) & 255, (int >> 8) & 255, int & 255, 255 ]
+  return [ 0, 0, 0, 255 ]
+}
+
+/** Normalize any ColorInput to four 0..1 float components (array inputs pass through losslessly). */
+const toFloats = (c: ColorInput): [number, number, number, number] => {
+  if (typeof c === "number") return [ ((c >> 16) & 255) / 255, ((c >> 8) & 255) / 255, (c & 255) / 255, 1 ]
+  if (typeof c === "string") {
+    const b = parseHexString(c)
+    return [ b[0] / 255, b[1] / 255, b[2] / 255, b[3] / 255 ]
+  }
+  return [ c[0], c[1], c[2], (c as readonly number[])[3] ?? 1 ]
+}
+
+const toBytes = (c: ColorInput): [number, number, number, number] => {
+  const f = toFloats(c)
+  return [ Math.round(f[0] * 255), Math.round(f[1] * 255), Math.round(f[2] * 255), Math.round(f[3] * 255) ]
+}
+
+export const Color = {
+  /** [r,g,b] in 0..1 — for the 2D engine's float color setters. */
+  toRgb01(c: ColorInput): [number, number, number] {
+    const f = toFloats(c)
+    return [ f[0], f[1], f[2] ]
+  },
+  /** [r,g,b,a] in 0..1. */
+  toRgba01(c: ColorInput): [number, number, number, number] {
+    return toFloats(c)
+  },
+  /** 0xRRGGBB packed int — for the 3D engine's color uniforms / skybox. */
+  toPackedRgb(c: ColorInput): number {
+    const b = toBytes(c)
+    return (b[0] << 16) | (b[1] << 8) | b[2]
+  },
+  /** 0xRRGGBBAA packed int (unsigned). */
+  toPackedRgba(c: ColorInput): number {
+    const b = toBytes(c)
+    return ((b[0] << 24) | (b[1] << 16) | (b[2] << 8) | b[3]) >>> 0
+  },
+  /** '#rrggbb' (or '#rrggbbaa' when alpha < 1) — for the 3D material color uniforms. */
+  toHexString(c: ColorInput): string {
+    const b = toBytes(c)
+    const hex = (n: number) => n.toString(16).padStart(2, "0")
+    const base = `#${hex(b[0])}${hex(b[1])}${hex(b[2])}`
+    return b[3] >= 255 ? base : base + hex(b[3])
+  },
+}

package/runtime/sdk/core/events.ts

@@ -0,0 +1,38 @@
+// Tiny typed event dispatcher shared by media players, sockets, and (later) nodes. Keeps the
+// addEventListener / removeEventListener / dispatch boilerplate in one place.
+
+export type EventMap = Record<string, (...args: any[]) => void>
+
+export class Emitter<E extends EventMap> {
+  private _listeners: { [K in keyof E]?: E[K][] } = {}
+
+  addEventListener<K extends keyof E>(channel: K, callback: E[K]): void {
+    const list = this._listeners[channel]
+    if (list) list.push(callback)
+    else this._listeners[channel] = [ callback ]
+  }
+
+  removeEventListener<K extends keyof E>(channel: K, callback: E[K]): void {
+    const list = this._listeners[channel]
+    if (!list) return
+    const i = list.indexOf(callback)
+    if (i >= 0) list.splice(i, 1)
+  }
+
+  /** Fire all listeners on a channel. Protected: only the owning class emits. */
+  protected dispatch<K extends keyof E>(channel: K, ...args: Parameters<E[K]>): void {
+    const list = this._listeners[channel]
+    if (!list) return
+    for (const fn of list.slice()) fn(...args)
+  }
+
+  protected hasListeners<K extends keyof E>(channel: K): boolean {
+    const list = this._listeners[channel]
+    return !!list && list.length > 0
+  }
+
+  /** Drop every listener on every channel (used when the owning object is disposed). */
+  protected clearListeners(): void {
+    this._listeners = {}
+  }
+}

package/runtime/sdk/core/registry.ts

@@ -0,0 +1,23 @@
+// Maps a native handle (the integer id the engine returns) back to its JS wrapper, so callbacks
+// the host fires by id (animation events, touch hits, media events) can be routed to the owning
+// object. Each engine/domain keeps its own Registry instance.
+
+export class Registry<T> {
+  private map = new Map<number, T>()
+
+  set(id: number, value: T): void {
+    this.map.set(id, value)
+  }
+
+  get(id: number): T | undefined {
+    return this.map.get(id)
+  }
+
+  delete(id: number): void {
+    this.map.delete(id)
+  }
+
+  has(id: number): boolean {
+    return this.map.has(id)
+  }
+}

package/runtime/sdk/g2/Camera2D.ts

@@ -0,0 +1,33 @@
+// Orthographic camera for a Scene2D. Position / zoom / rotation live natively. To make the camera
+// track a node, attach a small update(dt) aspect that eases camera.position toward the node — there's
+// no built-in follow() (and so nothing to dispose).
+
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+
+export class Camera2D {
+  private _x = 0
+  private _y = 0
+  private _zoom = 1
+  private _rotation = 0
+
+  private readonly sceneId: number
+  constructor(sceneId: number) { this.sceneId = sceneId }
+
+  get position(): Vec2 { return new Vec2(this._x, this._y) }
+  set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.cameraSetPosition(this.sceneId, this._x, this._y) }
+
+  get zoom(): number { return this._zoom }
+  set zoom(z: number) { this._zoom = z; _creator2d.cameraSetZoom(this.sceneId, z) }
+
+  get rotation(): number { return this._rotation }
+  set rotation(deg: number) { this._rotation = deg; _creator2d.cameraSetRotation(this.sceneId, deg) }
+
+  screenToWorld(screenX: number, screenY: number): Vec2 {
+    const o = _creator2d.cameraScreenToWorld(this.sceneId, screenX, screenY)
+    return new Vec2(o[0], o[1])
+  }
+  worldToScreen(worldX: number, worldY: number): Vec2 {
+    const o = _creator2d.cameraWorldToScreen(this.sceneId, worldX, worldY)
+    return new Vec2(o[0], o[1])
+  }
+}

package/runtime/sdk/g2/CharacterController2D.ts

@@ -0,0 +1,75 @@
+// A platformer-friendly character controller, as an aspect on a Node2D. Built on a fixed-rotation
+// dynamic Physics2D body: you drive horizontal intent + jump, and Box2D handles gravity, falling, and
+// wall/floor collision response; a short downward ray reports `grounded`.
+//
+//   const hero = new Sprite({ texture, anchor: [0.5, 1] })
+//     .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true, shape: { type: 'capsule', from:[0,6], to:[0,26], radius:6 } })
+//     .aspect(CharacterController2D, { speed: 200, jumpSpeed: 520 })
+//   Input.on('left',  d => hero.controller.move(d ? -1 : 0))
+//   Input.on('jump',  () => hero.controller.jump())
+//
+// Velocity-control (set velocity each frame) is the standard, robust approach for platformers and
+// reuses the physics solver. For pixel-tight movement without any solver bounce/seam quirks, a
+// kinematic move-and-slide controller can be added later (see creator-2d PLAN.md, Phase G).
+
+import { Aspect } from "../core/Aspect"
+import { Vec2 } from "../math/vec"
+import { Physics2D } from "./Physics2D"
+import { Shape } from "./Shape"
+import type { Node2D } from "./Node2D"
+
+export class CharacterController2D extends Aspect<"controller", Node2D> {
+  static readonly aspect = "controller"
+
+  /** Horizontal move speed (world units/s). */
+  speed = 200
+  /** Jump take-off speed (world units/s). */
+  jumpSpeed = 500
+  /** Extra probe distance below the body's feet used for the grounded check (world units). */
+  groundProbe = 6
+  /** Distance from the node origin down to the feet. Defaults to half the sprite height. */
+  footOffset?: number
+
+  private _moveX = 0
+  private _jumpQueued = false
+  private _grounded = false
+
+  /** Horizontal intent in [-1, 1] (e.g. from input). Sticky — set 0 to stop. Applied next frame. */
+  move(dir: number): void { this._moveX = dir < -1 ? -1 : dir > 1 ? 1 : dir }
+  /** Queue a jump; consumed on the next frame if grounded. */
+  jump(): void { this._jumpQueued = true }
+  /** True while standing on something (updated each frame). */
+  get grounded(): boolean { return this._grounded }
+
+  private get phys(): Physics2D | undefined { return this.node.get(Physics2D) }
+
+  onAttach(): void {
+    // Ensure a Shape (auto box from the sprite) + a dynamic, fixed-rotation body if not already set up.
+    if (!this.node.has(Shape)) this.node.aspect(Shape, {})
+    if (!this.node.has(Physics2D)) this.node.aspect(Physics2D, { motion: "dynamic", fixedRotation: true })
+  }
+
+  update(_dt: number): void {
+    const phys = this.phys
+    if (!phys) return
+
+    // Grounded probe: a short ray straight down from the feet. The ray originates inside the body,
+    // so Box2D won't report the body's own shape; we exclude self defensively too.
+    const pos = this.node.worldPosition
+    const foot = this.footOffset ?? this._spriteHalfHeight()
+    const hit = Physics2D.raycast([pos.x, pos.y - foot * 0.5], [pos.x, pos.y - foot - this.groundProbe])
+    this._grounded = !!hit && hit.node !== this.node
+
+    let vy = phys.velocity.y
+    if (this._jumpQueued && this._grounded) { vy = this.jumpSpeed; this._grounded = false }
+    this._jumpQueued = false
+
+    // Drive horizontal velocity directly; let the sim own vertical (gravity / jump / landing).
+    phys.velocity = new Vec2(this._moveX * this.speed, vy)
+  }
+
+  private _spriteHalfHeight(): number {
+    const size = (this.node as { size?: Vec2 }).size
+    return size ? size.y * 0.5 : 8
+  }
+}

package/runtime/sdk/g2/Node2D.ts

@@ -0,0 +1,194 @@
+// Base 2D scene node — an empty transform. Sprite and Tilemap extend it, so every node operation
+// (position, layer, visibility, events) works on them. Native (creator-2d) owns the authoritative
+// transform. JS caches it for free reads (JS is normally the sole writer); the exception is a node
+// driven by a dynamic/kinematic Physics2D body — there the native physics step also writes the
+// transform, so such nodes are flagged `_physicsDriven` and their transform getters sync the cache
+// from native first (lazy: only on read, only for moving bodies). So node.position stays correct
+// under physics without any per-frame bookkeeping.
+//
+// Empty Node2Ds are useful as: grouping parents, world-space markers/spawn points, and physics /
+// trigger objects — attach a Shape (geometry) plus a Physics2D (rigid body) or Trigger (sensor).
+
+import { AspectHost } from "../core/Aspect"
+import { Registry } from "../core/registry"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+import { ensurePointerEvents } from "./touch"
+
+// re-exported so existing `import { Vec2 } from "./Node2D"` sites keep working; the canonical home is math/.
+export { Vec2, type Vec2Like }
+
+export type Node2DEvents = {
+  /** A looping animation clip wrapped around (fires each loop). */
+  loopReached: (clip: string) => void
+  /** A non-looping animation clip finished. */
+  completed: (clip: string) => void
+  /** A physics contact / sensor overlap began / ended (the other node). */
+  enter: (other: Node2D) => void
+  exit: (other: Node2D) => void
+  /** Pointer up over this node's Physics2D shape (a tap/click). */
+  click: (ev: ClickEvent<Node2D | null>) => void
+  /** Pointer down on this node's Physics2D shape. Call ev.track(...) to capture the drag. */
+  touchstart: (ev: TouchStartEvent<Node2D | null>) => void
+}
+
+/** id → Node2D, so host callbacks (animation events) route back to the owning JS object. */
+export const node2dRegistry = new Registry<Node2D>()
+
+export class Node2D extends AspectHost<Node2DEvents> {
+  /** Native entity handle. */
+  readonly id: number
+
+  protected _x = 0
+  protected _y = 0
+  protected _rotation = 0
+  protected _sx = 1
+  protected _sy = 1
+  protected _layer = 0
+  protected _z = 0
+  protected _visible = true
+
+  /** @internal — set by Physics2D for a dynamic/kinematic body: the native step owns this node's
+   *  transform, so the transform getters re-sync the cache from native before returning. */
+  _physicsDriven = false
+
+  private _parent: Node2D | null = null
+  private _children: Node2D[] = []
+
+  constructor(internalId?: number) {
+    super()
+    this.id = internalId ?? _creator2d.createEntity()
+    node2dRegistry.set(this.id, this)
+  }
+
+  // --- transform (Y-up, LOCAL to the parent; at zoom 1, units == logical pixels) ---
+  // Pull the native transform into the cache iff physics owns it. No-op for the common case (plain
+  // nodes keep free reads); one native read for a moving body, and only when actually read.
+  private _pull(): void { if (this._physicsDriven) this._syncLocalFromNative() }
+
+  get x(): number { this._pull(); return this._x }
+  set x(v: number) { this._pull(); this._x = v; _creator2d.setPosition(this.id, v, this._y) }
+  get y(): number { this._pull(); return this._y }
+  set y(v: number) { this._pull(); this._y = v; _creator2d.setPosition(this.id, this._x, v) }
+
+  get position(): Vec2 { this._pull(); return new Vec2(this._x, this._y) }
+  set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.setPosition(this.id, this._x, this._y) }
+
+  /** Rotation in degrees (CCW). */
+  get rotation(): number { this._pull(); return this._rotation }
+  set rotation(deg: number) { this._rotation = deg; _creator2d.setRotation(this.id, deg) }
+
+  get scale(): Vec2 { return new Vec2(this._sx, this._sy) }
+  set scale(v: Vec2Like | number) {
+    const sx = typeof v === "number" ? v : cx(v)
+    const sy = typeof v === "number" ? v : cy(v)
+    this._sx = sx; this._sy = sy
+    _creator2d.setScale(this.id, sx, sy)
+  }
+
+  /** Draw layer (int). Higher layers render on top. */
+  get layer(): number { return this._layer }
+  set layer(v: number) { this._layer = v; _creator2d.setLayer(this.id, v) }
+
+  /** Intra-layer depth for non-Y-sorted layers (higher z = on top). */
+  get z(): number { return this._z }
+  set z(v: number) { this._z = v; _creator2d.setZ(this.id, v) }
+
+  get visible(): boolean { return this._visible }
+  set visible(v: boolean) { this._visible = v; _creator2d.setVisible(this.id, v) }
+
+  // --- hierarchy (parent/child; transforms above are LOCAL to the parent) ---
+  get parent(): Node2D | null { return this._parent }
+  set parent(p: Node2D | null) { this.setParent(p) }
+
+  get children(): readonly Node2D[] { return this._children }
+
+  /** Attach children to this node (each keeps its current world transform). Returns this. */
+  add(...children: Node2D[]): this {
+    for (const c of children) c.setParent(this)
+    return this
+  }
+
+  /** Detach a direct child (reparents it to root, keeping its world transform). Returns this. */
+  remove(child: Node2D): this {
+    if (child._parent === this) child.setParent(null)
+    return this
+  }
+
+  /**
+   * Reparent this node. `keepWorld` (default true) recomputes the local transform so the on-screen
+   * position/rotation/scale is unchanged; pass false to keep the local transform and move with the
+   * new parent. Self/descendant parents are rejected natively (no cycles).
+   */
+  setParent(parent: Node2D | null, keepWorld = true): this {
+    if (parent === this) return this
+    if (this._parent) {
+      const arr = this._parent._children
+      const i = arr.indexOf(this)
+      if (i >= 0) arr.splice(i, 1)
+    }
+    this._parent = parent
+    if (parent) parent._children.push(this)
+    _creator2d.setParent(this.id, parent?.id ?? 0, keepWorld)
+    if (keepWorld) this._syncLocalFromNative()   // native recomputed our local transform
+    return this
+  }
+
+  /** World-space position (composes all ancestors). */
+  get worldPosition(): Vec2 {
+    const o = _creator2d.getWorldPosition(this.id)
+    return new Vec2(o[0], o[1])
+  }
+
+  /** Convert a world-space point into this node's local space (and back). */
+  worldToLocal(p: Vec2Like): Vec2 {
+    const o = _creator2d.worldToLocal(this.id, cx(p), cy(p))
+    return new Vec2(o[0], o[1])
+  }
+  localToWorld(p: Vec2Like): Vec2 {
+    const o = _creator2d.localToWorld(this.id, cx(p), cy(p))
+    return new Vec2(o[0], o[1])
+  }
+
+  private _syncLocalFromNative(): void {
+    const t = _creator2d.getLocalTransform(this.id)   // [x, y, rotDeg, sx, sy]
+    this._x = t[0]; this._y = t[1]; this._rotation = t[2]; this._sx = t[3]; this._sy = t[4]
+  }
+
+  /** @internal — host animation events route here by id; the SpriteAnimation aspect installs an
+   *  instance override that translates clip ids to names and emits 'loopReached' / 'completed'. */
+  _dispatchAnimEvent(_clipId: number, _type: number): void {}
+
+  /** @internal — emit a translated animation event (the SpriteAnimation aspect can't reach the
+   *  protected dispatch directly). */
+  _emitAnim(channel: "loopReached" | "completed", clip: string): void { this.dispatch(channel, clip) }
+
+  /** @internal — physics contact/sensor events route here (loop.ts) → the node's 'enter'/'exit'. */
+  _emitCollision(channel: "enter" | "exit", other: Node2D): void { this.dispatch(channel, other) }
+
+  // Lazily register the host pointer callback when the first click/touchstart listener is added.
+  override addEventListener<K extends keyof Node2DEvents>(channel: K, callback: Node2DEvents[K]): void {
+    if (channel === "click" || channel === "touchstart") ensurePointerEvents()
+    super.addEventListener(channel, callback)
+  }
+
+  /** @internal — the pointer system (g2/touch.ts) fires click/touchstart here. */
+  _dispatchEvent<K extends keyof Node2DEvents>(channel: K, ...args: Parameters<Node2DEvents[K]>): void {
+    this.dispatch(channel, ...args)
+  }
+
+  destroy(): void {
+    // Detach from parent; native reparents our children to root (keepWorld), so resync their caches.
+    if (this._parent) {
+      const arr = this._parent._children
+      const i = arr.indexOf(this)
+      if (i >= 0) arr.splice(i, 1)
+      this._parent = null
+    }
+    const orphans = this._children.slice()
+    this._children.length = 0
+    node2dRegistry.delete(this.id)
+    _creator2d.destroyEntity(this.id)
+    for (const c of orphans) { c._parent = null; c._syncLocalFromNative() }
+  }
+}

package/runtime/sdk/g2/Physics2D.ts

@@ -0,0 +1,126 @@
+// A rigid body, as an aspect on a Node2D, backed by Box2D v3 in creator-2d. Mirrors the 3D Physics
+// aspect. Requires a Shape aspect on the same node (its geometry becomes the body's solid fixture).
+//
+//   Physics2D.configure({ gravity: [0, -980] })          // once, before creating bodies
+//   ground.aspect(Shape, { segment: { from: [-500,0], to: [500,0] } }).aspect(Physics2D, { motion: 'static' })
+//   hero.aspect(Shape, { box: [12, 20] }).aspect(Physics2D, { motion: 'dynamic', fixedRotation: true })
+//   hero.physics.applyImpulse([0, 400])                   // jump
+//   hero.addEventListener('enter', other => …)            // contact / sensor overlap began
+//
+// For a `dynamic` body, physics OWNS the transform — don't set node.position per frame; drive it via
+// velocity / applyImpulse. Reading node.position works: the node is flagged _physicsDriven and lazily
+// syncs its cache from native on read. Kinematic bodies are driven with moveTo. Best practice: keep
+// bodies on root nodes (see creator-2d PLAN.md).
+
+import { Aspect } from "../core/Aspect"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import { node2dRegistry, type Node2D } from "./Node2D"
+import { Shape } from "./Shape"
+
+export type MotionType = "static" | "kinematic" | "dynamic"
+const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
+
+export interface PhysicsConfig {
+  /** Gravity in world units/s² (Y-up: down is negative). Default [0, -980]. */
+  gravity?: Vec2Like
+  /** Pixels per meter — tunes Box2D's internal tolerances; you still author in world units. Default 64. */
+  pixelsPerMeter?: number
+  /** Solver sub-steps per fixed step. Default 4. */
+  subSteps?: number
+}
+
+/** Closest raycast hit. */
+export interface RayHit {
+  node: Node2D | null
+  point: Vec2
+  normal: Vec2
+  fraction: number
+}
+
+// Resolve a native entity id to its Node2D (0 = none).
+const node2dById = (id: number): Node2D | null => (id ? node2dRegistry.get(id) ?? null : null)
+
+export class Physics2D extends Aspect<"physics", Node2D> {
+  static readonly aspect = "physics"
+
+  /** Default "dynamic". */
+  motion: MotionType = "dynamic"
+  density = 1
+  friction = 0.3
+  restitution = 0
+  /** Lock rotation (essential for platformer characters). */
+  fixedRotation = false
+  gravityScale = 1
+  /** Continuous collision for fast-moving bodies (projectiles). */
+  bullet = false
+
+  private _h = 0   // native body handle (0 = none / no physics support)
+
+  /** Native body handle. 0 until attached, or if the build has no physics support. */
+  get handle(): number { return this._h }
+
+  onAttach(): void {
+    if (!_creator2d.physicsHasSupport || !_creator2d.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Physics2D requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics2D, {…})")
+    }
+    this._h = _creator2d.physicsCreateBody(this.node.id, MOTION[this.motion])
+    if (!this._h) return
+    shape._addTo(this._h, false /* solid */, this.density, this.friction, this.restitution)
+    // dynamic/kinematic bodies are moved by the native step → the node must re-sync its transform
+    // cache from native on read. Static bodies never move, so they keep the free cache.
+    if (this.motion !== "static") this.node._physicsDriven = true
+    if (this.fixedRotation) _creator2d.physicsSetFixedRotation(this._h, true)
+    if (this.gravityScale !== 1) _creator2d.physicsSetGravityScale(this._h, this.gravityScale)
+    if (this.bullet) _creator2d.physicsSetBullet(this._h, true)
+  }
+
+  onDetach(): void {
+    if (this._h) { _creator2d.physicsRemoveBody(this._h); this._h = 0 }
+    this.node._physicsDriven = false
+  }
+
+  /** Linear velocity in world units/second (fresh Vec2 on read). */
+  get velocity(): Vec2 {
+    const o = this._h ? _creator2d.physicsGetLinearVelocity(this._h) : null
+    return o ? new Vec2(o[0], o[1]) : new Vec2(0, 0)
+  }
+  set velocity(v: Vec2Like) { if (this._h) _creator2d.physicsSetLinearVelocity(this._h, cx(v), cy(v)) }
+
+  /** Angular velocity in degrees/second. */
+  set angularVelocity(degPerSec: number) { if (this._h) _creator2d.physicsSetAngularVelocity(this._h, degPerSec) }
+
+  set gravityFactor(scale: number) { this.gravityScale = scale; if (this._h) _creator2d.physicsSetGravityScale(this._h, scale) }
+  set linearDamping(d: number) { if (this._h) _creator2d.physicsSetLinearDamping(this._h, d) }
+  set enabled(v: boolean) { if (this._h) _creator2d.physicsSetEnabled(this._h, v) }
+
+  /** Apply an instantaneous impulse (world units) and wake the body. */
+  applyImpulse(v: Vec2Like): this { if (this._h) _creator2d.physicsApplyLinearImpulse(this._h, cx(v), cy(v)); return this }
+  /** Apply a continuous force (world units) and wake the body. */
+  applyForce(v: Vec2Like): this { if (this._h) _creator2d.physicsApplyForce(this._h, cx(v), cy(v)); return this }
+  /** Teleport / drive a kinematic (or dynamic) body to a world position (+ optional rotation degrees). */
+  moveTo(p: Vec2Like, deg = 0): this { if (this._h) _creator2d.physicsSetTransform(this._h, cx(p), cy(p), deg); return this }
+
+  // --- world (static) -------------------------------------------------------------------------
+  /** Create / reset the physics world. Call once before creating bodies. */
+  static configure(config: PhysicsConfig = {}): void {
+    const g = config.gravity ?? [0, -980]
+    _creator2d.physicsConfigure(cx(g), cy(g), config.pixelsPerMeter ?? 64, config.subSteps ?? 4)
+  }
+
+  /** Whether this build has physics support (CREATOR_2D_PHYSICS). */
+  static get supported(): boolean { return !!_creator2d.physicsHasSupport && _creator2d.physicsHasSupport() }
+
+  /** Closest body hit by the segment from→to, or null. `node` resolves the hit entity. */
+  static raycast(from: Vec2Like, to: Vec2Like): RayHit | null {
+    const o = _creator2d.physicsRaycastClosest(cx(from), cy(from), cx(to), cy(to))
+    if (o[0] < 0.5) return null
+    return { node: node2dById(o[1]), point: new Vec2(o[2], o[3]), normal: new Vec2(o[4], o[5]), fraction: o[6] }
+  }
+
+  /** Topmost body (solid or sensor) whose shape contains the world point, or null. */
+  static overlapPoint(p: Vec2Like): Node2D | null {
+    return node2dById(_creator2d.physicsOverlapPoint(cx(p), cy(p)))
+  }
+}

package/runtime/sdk/g2/Scene2D.ts

@@ -0,0 +1,101 @@
+// A 2D scene: a draw set + an orthographic Camera2D. Opening a scene asks the host to bring up the
+// 2D engine and starts its RAF loop; only the active scene renders. Grown from the Phase 0 seed.
+
+import { Color, type ColorInput } from "../core/color"
+import { cx, cy, type Vec2Like } from "../math/vec"
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+import { Camera2D } from "./Camera2D"
+import { node2dRegistry, type Node2D } from "./Node2D"
+import { ensurePointerEvents } from "./touch"
+
+export type Scene2DOptions = {
+  /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
+  background?: ColorInput
+}
+
+/** Returned by scene2d.layer(n); chain .ySort() to enable top-down depth sorting for that layer. */
+class LayerHandle {
+  private readonly sceneId: number
+  private readonly layer: number
+  constructor(sceneId: number, layer: number) { this.sceneId = sceneId; this.layer = layer }
+  /** In this layer, lower-on-screen sprites overlap higher ones (top-down feet sorting). */
+  ySort(enabled = true): this {
+    _creator2d.setLayerYSort(this.sceneId, this.layer, enabled)
+    return this
+  }
+}
+
+export class Scene2D {
+  /** Native scene handle. */
+  readonly id: number
+  readonly camera: Camera2D
+
+  private static _active: Scene2D | null = null
+  static get active(): Scene2D | null { return Scene2D._active }
+
+  /** @internal — scene-level pointer listeners (the catch-all; target = hit node or null). */
+  readonly _clickListeners: Array<(ev: ClickEvent<Node2D | null>) => void> = []
+  readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void> = []
+
+  constructor(options: Scene2DOptions = {}) {
+    this.id = _creator2d.createScene()
+    this.camera = new Camera2D(this.id)
+    if (options.background !== undefined) this.background = options.background
+  }
+
+  set background(color: ColorInput) {
+    const [ r, g, b, a ] = Color.toRgba01(color)
+    _creator2d.sceneSetClearColor(this.id, r, g, b, a)
+  }
+
+  /** Address a draw layer to configure it, e.g. scene2d.layer(1).ySort(). */
+  layer(n: number): LayerHandle {
+    return new LayerHandle(this.id, n)
+  }
+
+  /** Topmost visible sprite whose world bounds contain the world point, or null. Body-free
+   *  hit-test for tap/click picking — pair with camera.screenToWorld(). */
+  pick(worldPoint: Vec2Like): Node2D | null {
+    const id = _creator2d.pickSprite(this.id, cx(worldPoint), cy(worldPoint))
+    return id ? node2dRegistry.get(id) ?? null : null
+  }
+
+  /** Scene-level pointer events. The handler fires for every tap/press in the scene, with
+   *  `ev.target` = the hit Physics2D node (or null). On 'touchstart' you can ev.track(...) a drag. */
+  addEventListener(channel: "click", callback: (ev: ClickEvent<Node2D | null>) => void): void
+  addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<Node2D | null>) => void): void
+  addEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void {
+    const list = channel === "click" ? this._clickListeners : this._touchStartListeners
+    if (!list.includes(callback)) { list.push(callback); ensurePointerEvents() }
+  }
+  removeEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void {
+    const list = channel === "click" ? this._clickListeners : this._touchStartListeners
+    const i = list.indexOf(callback)
+    if (i >= 0) list.splice(i, 1)
+  }
+
+  add(...nodes: Node2D[]): this {
+    for (const n of nodes) _creator2d.addEntityToScene(this.id, n.id)
+    return this
+  }
+  remove(...nodes: Node2D[]): this {
+    for (const n of nodes) _creator2d.removeEntityFromScene(this.id, n.id)
+    return this
+  }
+
+  /** Make this the active scene (brings up the 2D engine on the canvas; closes any other). */
+  open(): this {
+    _creator2d.openScene(this.id)
+    Scene2D._active = this
+    return this
+  }
+  close(): this {
+    _creator2d.closeScene()
+    if (Scene2D._active === this) Scene2D._active = null
+    return this
+  }
+  destroy(): void {
+    this.close()
+    _creator2d.destroyScene(this.id)
+  }
+}