lecodes-cli 0.1.7 → 0.3.0

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

@@ -2,8 +2,28 @@
 // 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 { _installAspectFrames } from "../core/Aspect"
+import { cx, cy, type Vec2Like } from "../math/vec"
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
-import type { Node2D } from "./Node2D"
+import { node2dRegistry, type Node2D } from "./Node2D"
+import { ensurePointerEvents } from "./touch"
+
+// Route aspect update(dt) through the render-synced native phases (c2dRender early = before physics,
+// late = after animations / before draw), so followers/cameras are in lockstep with the draw. Done from
+// the 2D layer (not core) so a 3D-only bundle never pulls in the 2D bridge. Installed once, lazily on
+// the first Scene2D. On an older wasm without the hooks the installer returns false → setLoop fallback.
+let framesInstalled = false
+const installRenderSyncedFrames = (): void => {
+  if (framesInstalled) return
+  framesInstalled = true
+  _installAspectFrames((early, late) => {
+    if (typeof _creator2d.setEarlyUpdate !== "function") return false
+    _creator2d.setEarlyUpdate(early)
+    _creator2d.setLateUpdate(late)
+    return true
+  })
+}
 
 export type Scene2DOptions = {
   /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
@@ -30,7 +50,12 @@ export class Scene2D {
   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 = {}) {
+    installRenderSyncedFrames()
     this.id = _creator2d.createScene()
     this.camera = new Camera2D(this.id)
     if (options.background !== undefined) this.background = options.background
@@ -46,6 +71,27 @@ export class Scene2D {
     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

package/runtime/sdk/g2/Shape.ts

@@ -0,0 +1,63 @@
+// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape does not by itself
+// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger (sensor), both
+// of which require a Shape and turn its geometry into a Box2D fixture. The shape is also what pointer
+// picking hits, so a node is clickable once it has a Shape + Physics2D/Trigger (a body to query).
+//
+//   wall.aspect(Shape, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
+//   goal.aspect(Shape, { circle: 20 }).aspect(Trigger)
+//   hero.aspect(Shape, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
+//
+// With no geometry set, Shape derives a box from the node's sprite size ("auto").
+
+import { Aspect } from "../core/Aspect"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { Node2D } from "./Node2D"
+
+export class Shape extends Aspect<"shape", Node2D> {
+  static readonly aspect = "shape"
+
+  /** Box half-extents [hw, hh] (world units). */
+  box?: Vec2Like
+  /** Circle radius. */
+  circle?: number
+  /** Capsule between two local points, with a radius. */
+  capsule?: { from: Vec2Like, to: Vec2Like, radius: number }
+  /** Thin segment (an edge — for static ground/walls/slopes) between two local points. */
+  segment?: { from: Vec2Like, to: Vec2Like }
+  /** Convex polygon, up to 8 local points (a convex hull is computed). */
+  polygon?: Vec2Like[]
+  /** Local offset of the shape from the node origin. */
+  offset?: Vec2Like
+
+  /**
+   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger).
+   * `sensor` selects a sensor (trigger) vs solid fixture; density/friction/restitution are the
+   * material (ignored for sensors / segments only use friction+restitution).
+   */
+  _addTo(handle: number, sensor: boolean, density: number, friction: number, restitution: number): void {
+    const ox = this.offset ? cx(this.offset) : 0
+    const oy = this.offset ? cy(this.offset) : 0
+    if (this.circle !== undefined) {
+      _creator2d.physicsAddCircle(handle, this.circle, ox, oy, density, friction, restitution, sensor)
+    } else if (this.capsule) {
+      const { from, to, radius } = this.capsule
+      _creator2d.physicsAddCapsule(handle, cx(from), cy(from), cx(to), cy(to), radius, density, friction, restitution, sensor)
+    } else if (this.segment) {
+      _creator2d.physicsAddSegment(handle, cx(this.segment.from), cy(this.segment.from), cx(this.segment.to), cy(this.segment.to), friction, restitution)
+    } else if (this.polygon) {
+      const pts = new Float32Array(this.polygon.length * 2)
+      this.polygon.forEach((p, i) => { pts[i * 2] = cx(p); pts[i * 2 + 1] = cy(p) })
+      _creator2d.physicsAddPolygon(handle, pts, this.polygon.length, density, friction, restitution, sensor)
+    } else {
+      // box: explicit half-extents, or "auto" from the node's sprite size (fallback 8×8).
+      let hw = 8, hh = 8
+      if (this.box) {
+        hw = cx(this.box); hh = cy(this.box)
+      } else {
+        const size = (this.node as { size?: Vec2 }).size
+        if (size) { hw = size.x * 0.5; hh = size.y * 0.5 }
+      }
+      _creator2d.physicsAddBox(handle, hw, hh, ox, oy, density, friction, restitution, sensor)
+    }
+  }
+}

package/runtime/sdk/g2/Sprite.ts

@@ -1,18 +1,21 @@
 // A textured 2D node. Cheap setters proxy straight to the native sprite; the data lives in
-// creator-2d. Sprite-sheet animation is built in as chainable methods (no separate component):
-//   new Sprite({ texture }).clips({ size: [32, 48], idle: [0,1,2,3], walk: [4,5,6,7] }).play('idle')
+// creator-2d. Sprite-sheet animation is no longer built in — attach the SpriteAnimation aspect:
+//   new Sprite({ texture }).aspect(SpriteAnimation, { size: [32, 48], idle: [0,1,2,3] }).anim.play('idle')
 
 import { Color, type ColorInput } from "../core/color"
 import { Vec2, type Vec2Like } from "../math/vec"
-import { ensureAnimEvents } from "./loop"
+import { Canvas, isCanvas } from "../canvas/Canvas"
 import { Node2D } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
 
+/** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
+export type TextureSource = Texture2D | Canvas
+
 export type SpriteOptions = {
-  texture?: Texture2D
+  texture?: TextureSource
   /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
   anchor?: Vec2Like
-  /** World size; defaults to the texture's pixel dimensions (or the clip frame size once set). */
+  /** World size; defaults to the texture's pixel dimensions. */
   size?: Vec2Like
   /** Normalized UV sub-rect [u0,v0,u1,v1]. */
   frame?: [number, number, number, number]
@@ -23,20 +26,6 @@ export type SpriteOptions = {
   position?: Vec2Like
 }
 
-/** Per-clip frame list, or an object for per-clip fps/loop overrides. */
-export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean }
-
-/** Animation definition: the grid frame size + named clips (+ optional shared fps/loop defaults). */
-export type SpriteClips = {
-  /** Grid cell size in texture pixels. */
-  size: [number, number]
-  /** Default fps for clips that don't override it (default 12). */
-  fps?: number
-  /** Default loop for clips that don't override it (default true). */
-  loop?: boolean
-  [clip: string]: Clip | [number, number] | number | boolean | undefined
-}
-
 export class Sprite extends Node2D {
   private _texture?: Texture2D
   private _anchor = new Vec2(0.5, 0.5)
@@ -46,10 +35,6 @@ export class Sprite extends Node2D {
   private _flipY = false
   private _size: Vec2 | null = null
 
-  private _clipIds: Record<string, number> = {}
-  private _clipNames: Record<number, string> = {}
-  private _current: string | null = null
-
   constructor(options: SpriteOptions = {}) {
     super()
     if (options.texture) this.texture = options.texture
@@ -63,10 +48,11 @@ export class Sprite extends Node2D {
   }
 
   get texture(): Texture2D | undefined { return this._texture }
-  set texture(t: Texture2D | undefined) {
-    this._texture = t
-    if (!t) return
-    _creator2d.setSprite(this.id, t.id) // native resets UV + size to the full texture
+  set texture(t: TextureSource | undefined) {
+    const tex = isCanvas(t) ? t.texture() : t   // a Canvas bakes to a texture on assign
+    this._texture = tex
+    if (!tex) return
+    _creator2d.setSprite(this.id, tex.id) // native resets UV + size to the full texture
     if (this._size) _creator2d.setSpriteSize(this.id, this._size.x, this._size.y)
   }
 
@@ -95,70 +81,4 @@ export class Sprite extends Node2D {
   set flipX(v: boolean) { this._flipX = v; _creator2d.setSpriteFlip(this.id, v, this._flipY) }
   get flipY(): boolean { return this._flipY }
   set flipY(v: boolean) { this._flipY = v; _creator2d.setSpriteFlip(this.id, this._flipX, v) }
-
-  // --- animation (chainable) ---
-
-  /**
-   * Define named sprite-sheet clips from a uniform grid. Frame indices are row-major into the grid.
-   * Sets the sprite's display size to one cell. Once defined, clips advance entirely in native code.
-   */
-  clips(def: SpriteClips): this {
-    const tex = this._texture
-    if (!tex) throw new Error("Sprite.clips(): set a texture before defining clips")
-    const [ fw, fh ] = def.size
-    const defFps = typeof def.fps === "number" ? def.fps : 12
-    const defLoop = typeof def.loop === "boolean" ? def.loop : true
-    const cols = Math.max(1, Math.floor(tex.width / fw))
-
-    for (const name of Object.keys(def)) {
-      if (name === "size" || name === "fps" || name === "loop") continue
-      const value = def[name] as Clip
-      const indices = Array.isArray(value) ? value : value.frames
-      const fps = Array.isArray(value) ? defFps : (value.fps ?? defFps)
-      const loop = Array.isArray(value) ? defLoop : (value.loop ?? defLoop)
-
-      const frames = new Float32Array(indices.length * 4)
-      indices.forEach((idx, i) => {
-        const cx = (idx % cols) * fw
-        const cy = Math.floor(idx / cols) * fh
-        frames[i * 4 + 0] = cx / tex.width
-        frames[i * 4 + 1] = cy / tex.height
-        frames[i * 4 + 2] = (cx + fw) / tex.width
-        frames[i * 4 + 3] = (cy + fh) / tex.height
-      })
-      const clipId = _creator2d.defineAnimation(this.id, frames, fps, loop)
-      this._clipIds[name] = clipId
-      this._clipNames[clipId] = name
-    }
-
-    if (!this._size) _creator2d.setSpriteSize(this.id, fw, fh)
-    ensureAnimEvents()
-    return this
-  }
-
-  /** Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly). */
-  play(name: string): this {
-    const id = this._clipIds[name]
-    if (id === undefined) throw new Error(`Sprite.play(): unknown clip "${name}"`)
-    if (this._current === name) return this
-    this._current = name
-    _creator2d.playAnimation(this.id, id)
-    return this
-  }
-
-  stop(): this {
-    this._current = null
-    _creator2d.stopAnimation(this.id)
-    return this
-  }
-
-  set animationSpeed(value: number) { _creator2d.setAnimationSpeed(this.id, value) }
-  get currentClip(): string | null { return this._current }
-  get animationFrame(): number { return _creator2d.getAnimationFrame(this.id) }
-
-  /** @internal — translate a native clip id back to its name and emit the animation event. */
-  override _dispatchAnimEvent(clipId: number, type: number): void {
-    const name = this._clipNames[clipId] ?? ""
-    this.dispatch(type === 1 ? "completed" : "loopReached", name)
-  }
 }

package/runtime/sdk/g2/SpriteAnimation.ts

@@ -0,0 +1,90 @@
+// Sprite-sheet animation as an aspect on a Sprite. Configured as DATA (frame size + named clips) in
+// the attach call, then driven by name:
+//   sprite.aspect(SpriteAnimation, { size: [32, 48], fps: 10, clips: { idle: [0,1], walk: [4,5,6,7] } })
+//   sprite.anim.play('walk')
+// Once defined, clips advance entirely in native code; the aspect just translates clip ids back to
+// names for the node's 'loopReached' / 'completed' events.
+
+import { Aspect } from "../core/Aspect"
+import { ensureAnimEvents } from "./loop"
+import type { Sprite } from "./Sprite"
+
+/** Per-clip frame list, or an object for per-clip fps/loop overrides. */
+export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean }
+
+export class SpriteAnimation extends Aspect<"anim", Sprite> {
+  static readonly aspect = "anim"
+
+  /** Grid cell size in texture pixels (defaults to the full texture). */
+  size?: [number, number]
+  /** Default fps for clips that don't override it. */
+  fps = 12
+  /** Default loop for clips that don't override it. */
+  loop = true
+  /** Named clips; frame indices are row-major into the grid. Set via the attach opts. */
+  clips: Record<string, Clip> = {}
+
+  private _clipIds: Record<string, number> = {}
+  private _clipNames: Record<number, string> = {}
+  private _current: string | null = null
+
+  onAttach(): void {
+    this._define()
+    // route native animation events for this entity to named 'loopReached'/'completed' events.
+    ;(this.node as { _dispatchAnimEvent: (clipId: number, type: number) => void })._dispatchAnimEvent =
+      (clipId, type) => this.node._emitAnim(type === 1 ? "completed" : "loopReached", this._clipNames[clipId] ?? "")
+    ensureAnimEvents()
+  }
+
+  /** (Re)build native clips from `this.clips`. Called on attach; call again after changing clips. */
+  define(): this { this._define(); return this }
+
+  private _define(): void {
+    const node = this.node
+    const tex = node.texture
+    if (!tex) throw new Error("SpriteAnimation: set a texture on the Sprite before adding the aspect")
+    const [ fw, fh ] = this.size ?? [ tex.width, tex.height ]
+    const cols = Math.max(1, Math.floor(tex.width / fw))
+
+    for (const name of Object.keys(this.clips)) {
+      const value = this.clips[name]
+      const indices = Array.isArray(value) ? value : value.frames
+      const fps = Array.isArray(value) ? this.fps : (value.fps ?? this.fps)
+      const loop = Array.isArray(value) ? this.loop : (value.loop ?? this.loop)
+
+      const frames = new Float32Array(indices.length * 4)
+      indices.forEach((idx, i) => {
+        const px = (idx % cols) * fw
+        const py = Math.floor(idx / cols) * fh
+        frames[i * 4 + 0] = px / tex.width
+        frames[i * 4 + 1] = py / tex.height
+        frames[i * 4 + 2] = (px + fw) / tex.width
+        frames[i * 4 + 3] = (py + fh) / tex.height
+      })
+      const clipId = _creator2d.defineAnimation(node.id, frames, fps, loop)
+      this._clipIds[name] = clipId
+      this._clipNames[clipId] = name
+    }
+    if (this.size) _creator2d.setSpriteSize(node.id, fw, fh)
+  }
+
+  /** Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly). */
+  play(name: string): this {
+    const id = this._clipIds[name]
+    if (id === undefined) throw new Error(`SpriteAnimation.play(): unknown clip "${name}"`)
+    if (this._current === name) return this
+    this._current = name
+    _creator2d.playAnimation(this.node.id, id)
+    return this
+  }
+
+  stop(): this {
+    this._current = null
+    _creator2d.stopAnimation(this.node.id)
+    return this
+  }
+
+  set speed(value: number) { _creator2d.setAnimationSpeed(this.node.id, value) }
+  get current(): string | null { return this._current }
+  get frame(): number { return _creator2d.getAnimationFrame(this.node.id) }
+}

package/runtime/sdk/g2/Texture2D.ts

@@ -17,6 +17,14 @@ export class Texture2D {
     this.height = height
   }
 
+  // Wrap a Canvas's baked surface as a texture (RGBA8, already rasterized → synchronous, no decode).
+  // Structural type avoids a Canvas import cycle (Canvas imports Texture2D).
+  static fromCanvas(canvas: { _bakeSurface(): number, width: number, height: number, pixelRatio: number }): Texture2D {
+    const surfaceId = canvas._bakeSurface()
+    const texId = _creator2d.createTextureFromCanvas(surfaceId)
+    return new Texture2D(texId, Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio))
+  }
+
   static load(source: string | FetchResponse): Promise<Texture2D> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {

package/runtime/sdk/g2/Trigger.ts

@@ -0,0 +1,47 @@
+// A trigger zone, as an aspect on a Node2D. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement.
+//
+//   const goal = new Node2D({ ... })
+//     .aspect(Shape, { box: [32, 64] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => ...)
+//
+// (A trigger is still pointer-pickable — clicks hit sensor shapes too.)
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, type Vec2Like } from "../math/vec"
+import { ensurePhysicsEvents } from "./loop"
+import { Shape } from "./Shape"
+import type { Node2D } from "./Node2D"
+
+export class Trigger extends Aspect<"trigger", Node2D> {
+  static readonly aspect = "trigger"
+
+  private _h = 0
+  /** Native body handle (0 if 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("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    this._h = _creator2d.physicsCreateBody(this.node.id, 0 /* static */)
+    if (!this._h) return
+    shape._addTo(this._h, true /* sensor */, 1, 0, 0)
+    ensurePhysicsEvents()   // routes contact/sensor events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._h) { _creator2d.physicsRemoveBody(this._h); this._h = 0 }
+  }
+
+  /** Reposition the trigger zone to a world point. */
+  moveTo(p: Vec2Like): this {
+    if (this._h) _creator2d.physicsSetTransform(this._h, cx(p), cy(p), 0)
+    return this
+  }
+}

package/runtime/sdk/g2/loop.ts

@@ -1,9 +1,9 @@
 // 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),
-// used by camera.follow so the camera moves in lockstep with the native render (no 1-frame lag).
+// for anything that must move in lockstep with the native render (no 1-frame lag).
 //
-// Both registrations are lazy (first use) so a 2D project that never follows a camera or animates a
-// sprite pulls none of this in.
+// The animation-event registration is lazy (first use) so a 2D project that never animates a sprite
+// pulls none of this in.
 
 import { node2dRegistry } from "./Node2D"
 
@@ -20,3 +20,20 @@ export const ensureAnimEvents = (): void => {
     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 on the first physics body.
+let physicsEventsRegistered = false
+export const ensurePhysicsEvents = (): void => {
+  if (physicsEventsRegistered) return
+  physicsEventsRegistered = true
+  _creator2d.setOnPhysicsEvent((a, b, type) => {
+    const na = node2dRegistry.get(a)
+    const nb = node2dRegistry.get(b)
+    if (!na || !nb) return
+    const channel = type === 1 || type === 3 ? "exit" : "enter"
+    na._emitCollision(channel, nb)
+    nb._emitCollision(channel, na)
+  })
+}