lecodes-cli 0.1.7 → 0.2.0

package/runtime/sdk/g2/Node2D.ts

@@ -1,13 +1,19 @@
 // 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 is the sole writer (no 2D physics yet) so a local cache makes reads free.
+// 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 trigger /
-// logic objects you attach a .collider() to.
+// 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 { Emitter } from "../core/events"
+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 }
@@ -17,24 +23,19 @@ export type Node2DEvents = {
   loopReached: (clip: string) => void
   /** A non-looping animation clip finished. */
   completed: (clip: string) => void
-  /** A collider overlap began / ended (deferred — native 2D triggers are not built yet). */
+  /** 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 type ColliderOptions = {
-  /** Box half-extents (world units). Defaults to the sprite size when omitted. */
-  size?: Vec2Like
-  /** Center offset. */
-  offset?: Vec2Like
-  /** Report overlaps via 'enter'/'exit' instead of blocking (always true for now). */
-  trigger?: boolean
-}
-
-export class Node2D extends Emitter<Node2DEvents> {
+export class Node2D extends AspectHost<Node2DEvents> {
   /** Native entity handle. */
   readonly id: number
 
@@ -47,23 +48,34 @@ export class Node2D extends Emitter<Node2DEvents> {
   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 world; at zoom 1, units == pixels) ---
-  get x(): number { return this._x }
-  set x(v: number) { this._x = v; _creator2d.setPosition(this.id, v, this._y) }
-  get y(): number { return this._y }
-  set y(v: number) { this._y = v; _creator2d.setPosition(this.id, this._x, v) }
+  // --- 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 position(): Vec2 { return new Vec2(this._x, this._y) }
+  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 { return this._rotation }
+  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) }
@@ -85,20 +97,98 @@ export class Node2D extends Emitter<Node2DEvents> {
   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
+  }
+
   /**
-   * Attach a collider for overlap detection. DEFERRED: native 2D physics/triggers are not built yet,
-   * so this records intent and is a no-op until the engine lands — the 'enter'/'exit' events won't
-   * fire. The API is here so game code that uses it compiles and stays stable.
+   * 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).
    */
-  collider(_options: ColliderOptions = {}): this {
+  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
   }
 
-  /** @internal — overridden by Sprite to translate native clip ids into named animation events. */
+  /** 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

@@ -2,8 +2,11 @@
 // 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 type { Node2D } from "./Node2D"
+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. */
@@ -30,6 +33,10 @@ 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 = {}) {
     this.id = _creator2d.createScene()
     this.camera = new Camera2D(this.id)
@@ -46,6 +53,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,10 +1,9 @@
 // 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 { Node2D } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
 
@@ -12,7 +11,7 @@ export type SpriteOptions = {
   texture?: Texture2D
   /** 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 +22,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 +31,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
@@ -95,70 +76,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) }
+}