lecodes-cli 0.19.0 → 0.20.0

package/runtime/sdk/g2/Shape2D.ts

@@ -1,259 +0,0 @@
-// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape2D does not by itself
-// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger2D (sensor), both
-// of which require a Shape2D 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 Shape2D + Physics2D/Trigger2D (a body to query).
-//
-//   wall.aspect(Shape2D, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
-//   goal.aspect(Shape2D, { circle: 20 }).aspect(Trigger2D)
-//   hero.aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
-//
-// With no geometry set, Shape2D derives a box from WHAT THE NODE DRAWS — the sprite's size scaled by
-// the node, positioned by its anchor. So `aspect(Shape2D, {})` on a sprite anchored at its feet gives
-// a collider that wraps the art instead of one centred on the pivot (half of it underground), which
-// is why every character used to carry a hand-computed offset.
-//
-// RE-CONFIGURING REBUILDS IT IN PLACE: `node.aspect(Shape2D, { capsule: … })` on a live node swaps the
-// fixture while the body keeps its id, its velocity and its place in the world. That is what makes a
-// crouch (and a live editor edit) possible.
-
-import { Aspect } from "../core/Aspect"
-import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
-import { ALL_GROUPS } from "./groups2d"
-import type { Node2D } from "./Node2D"
-
-/** @internal How an owner (Physics2D / Trigger2D) wants the geometry realised. */
-export type ShapeFixture2D = {
-  sensor: boolean
-  friction: number
-  bounce: number
-  category?: number
-  mask?: number
-  /** Chains carry no mass, so Box2D only accepts them on a static body. */
-  staticBody?: boolean
-}
-
-export class Shape2D 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) between two local points. */
-  segment?: { from: Vec2Like, to: Vec2Like }
-  /** Convex polygon, up to 8 local points (a convex hull is computed — a CONCAVE outline silently
-   *  becomes its hull; use `chain` for those). */
-  polygon?: Vec2Like[]
-  /**
-   * A polyline of connected segments — the one shape that expresses a long CONCAVE surface (rolling
-   * terrain, a cave wall) in one piece, seam-free. Pass only the points that should be solid; the
-   * tangent points Box2D needs at the ends are synthesised here.
-   *
-   * STATIC bodies only (a polyline has no area, so no mass), at least 2 points (4 with `loop`), and it
-   * must not self-intersect. It is ONE-SIDED: solid on the right of the point order — walk the points
-   * so that the solid material is on your right, or set `flip`.
-   */
-  chain?: Vec2Like[]
-  /** `chain`: close the contour (an island / a room boundary). Needs at least 4 points. */
-  loop?: boolean
-  /** `chain`: put the solid side on the other side of the line. */
-  flip?: boolean
-  /** The collider's centre relative to the node, in world units. Applies to EVERY kind — it
-   *  translates a capsule's / segment's / polygon's / chain's points too, unlike the old `offset`. */
-  origin?: Vec2Like
-
-  /** @internal Geometry as of the last build — an unchanged signature means nothing to rebuild. */
-  private _sig = ""
-  /** @internal The last resize the CHARACTER refused (backs `controller.resizing`). */
-  _resizeRefused = false
-  /** @internal How the owner asked for it, so a rebuild can replay the same fixture. */
-  private _fx: ShapeFixture2D | null = null
-  private _handle = 0
-
-  /** @internal — the character claimed this shape; record the geometry so a later re-configure is
-   *  compared against it. */
-  _claimedByCharacter(): void { this._sig = this._signature(); this._resizeRefused = false }
-
-  /** @internal — realise this geometry as a fixture on `handle` (a body from Physics2D/Trigger2D). */
-  _addTo(handle: number, fx: ShapeFixture2D): void {
-    this._handle = handle
-    this._fx = fx
-    this._sig = this._signature()
-    this._create()
-  }
-
-  /** @internal — the owner's material changed live; keep it for the next rebuild. */
-  _setMaterial(friction: number, bounce: number): void {
-    if (this._fx) { this._fx.friction = friction; this._fx.bounce = bounce }
-  }
-
-  /** @internal — the owner's filter changed live. */
-  _setFilter(category: number, mask: number): void {
-    if (this._fx) { this._fx.category = category; this._fx.mask = mask }
-  }
-
-  onDetach(): void { this._handle = 0; this._fx = null; this._sig = ""; this._resizeRefused = false }
-
-  /**
-   * Re-configuring the aspect swaps the fixture in place — same body, same id, same velocity, same
-   * position. Nothing happens when the geometry is unchanged, so re-applying the same options in a
-   * loop is free.
-   */
-  onReconfigure(): void {
-    const sig = this._signature()
-    if (sig === this._sig) return
-
-    // A CharacterController2D owns this shape instead of a body: resizing goes to the mover, which
-    // VALIDATES it (you cannot stand up under a low pipe) and can refuse.
-    if (this.node._xfKind === 1) {
-      const cap = this._capsule()
-      const ok = _creator2d.characterSetCapsule(this.node._xf, cap.x1, cap.y1, cap.x2, cap.y2, cap.radius)
-      // On refusal NOTHING changed — so DON'T commit the signature. The next identical
-      // `aspect(Shape2D, …)` then still sees a difference and retries; committing here would swallow
-      // every retry for good, which is the whole trap in this design.
-      this._resizeRefused = !ok
-      if (ok) this._sig = sig
-      return
-    }
-
-    if (!this._handle || !this._fx) return
-    this._sig = sig
-    _creator2d.physicsClearShapes(this._handle)
-    this._create()
-  }
-
-  /**
-   * @internal — this geometry as a CAPSULE, for CharacterController2D (the mover takes nothing else).
-   * An explicit capsule is used as given; anything else is derived from the drawn rect, so
-   * `aspect(Shape2D, {})` on a sprite gives a capsule that wraps the art.
-   */
-  _capsule(): { x1: number, y1: number, x2: number, y2: number, radius: number } {
-    const ox = this.origin ? cx(this.origin) : 0
-    const oy = this.origin ? cy(this.origin) : 0
-    if (this.capsule) {
-      const { from, to, radius } = this.capsule
-      return { x1: cx(from) + ox, y1: cy(from) + oy, x2: cx(to) + ox, y2: cy(to) + oy, radius }
-    }
-    if (this.circle !== undefined) return { x1: ox, y1: oy, x2: ox, y2: oy, radius: this.circle }
-    let hw = 8, hh = 8, bx = ox, by = oy
-    if (this.box) { hw = cx(this.box); hh = cy(this.box) }
-    else {
-      const a = this._autoBox()
-      hw = a.hw; hh = a.hh
-      if (!this.origin) { bx = a.x; by = a.y }
-    }
-    const radius = Math.min(hw, hh)
-    const half = Math.max(0, hh - radius)
-    return { x1: bx, y1: by - half, x2: bx, y2: by + half, radius }
-  }
-
-  // ---- internals ---------------------------------------------------------------------------------
-
-  private _create(): void {
-    const fx = this._fx!
-    const handle = this._handle
-    const category = fx.category ?? ALL_GROUPS
-    const mask = fx.mask ?? ALL_GROUPS
-    const ox = this.origin ? cx(this.origin) : 0
-    const oy = this.origin ? cy(this.origin) : 0
-
-    if (this.chain) {
-      this._createChain(handle, fx, category, mask, ox, oy)
-    } else if (this.circle !== undefined) {
-      _creator2d.physicsAddCircle(handle, this.circle, ox, oy, fx.friction, fx.bounce, fx.sensor, category, mask)
-    } else if (this.capsule) {
-      const { from, to, radius } = this.capsule
-      _creator2d.physicsAddCapsule(handle, cx(from) + ox, cy(from) + oy, cx(to) + ox, cy(to) + oy, radius,
-                                   fx.friction, fx.bounce, fx.sensor, category, mask)
-    } else if (this.segment) {
-      const { from, to } = this.segment
-      _creator2d.physicsAddSegment(handle, cx(from) + ox, cy(from) + oy, cx(to) + ox, cy(to) + oy,
-                                   fx.friction, fx.bounce, category, mask)
-    } else if (this.polygon) {
-      const pts = new Float32Array(this.polygon.length * 2)
-      this.polygon.forEach((p, i) => { pts[i * 2] = cx(p) + ox; pts[i * 2 + 1] = cy(p) + oy })
-      _creator2d.physicsAddPolygon(handle, pts, this.polygon.length, fx.friction, fx.bounce, fx.sensor, category, mask)
-    } else {
-      // box: explicit half-extents, or "auto" — the rect the node actually draws.
-      let hw = 8, hh = 8, bx = ox, by = oy
-      if (this.box) {
-        hw = cx(this.box); hh = cy(this.box)
-      } else {
-        const auto = this._autoBox()
-        hw = auto.hw; hh = auto.hh
-        if (!this.origin) { bx = auto.x; by = auto.y }   // an explicit origin still wins
-      }
-      _creator2d.physicsAddBox(handle, hw, hh, bx, by, fx.friction, fx.bounce, fx.sensor, category, mask)
-    }
-  }
-
-  /**
-   * Box2D's chain wants the two TANGENT points as extra entries and does not collide on its first or
-   * last edge — pass it your outline verbatim and you lose both end segments (four points give ONE).
-   * So the caller passes only the solid points and the ends are extrapolated here: `p0 + (p0 - p1)`.
-   * A loop needs none of that (every point is interior) but does need 4 of them.
-   */
-  private _createChain(handle: number, fx: ShapeFixture2D, category: number, mask: number, ox: number, oy: number): void {
-    const src = this.chain!
-    const loop = this.loop === true
-    if (src.length < (loop ? 4 : 2)) {
-      throw new Error(`Shape2D chain needs at least ${loop ? 4 : 2} points (got ${src.length})${loop ? " — a closed contour of 3 is a polygon" : ""}`)
-    }
-    if (fx.staticBody === false) {
-      throw new Error("Shape2D { chain } works on a STATIC body only — a polyline has no area, so no mass. Use polygon/box for a dynamic body.")
-    }
-    const order = this.flip === true ? [ ...src ].reverse() : src
-    const p: number[] = []
-    if (!loop) {
-      // leading ghost: mirror the first point across the second
-      p.push(2 * cx(order[0]) - cx(order[1]) + ox, 2 * cy(order[0]) - cy(order[1]) + oy)
-    }
-    for (const v of order) p.push(cx(v) + ox, cy(v) + oy)
-    if (!loop) {
-      const n = order.length
-      p.push(2 * cx(order[n - 1]) - cx(order[n - 2]) + ox, 2 * cy(order[n - 1]) - cy(order[n - 2]) + oy)
-    }
-    _creator2d.physicsAddChain(handle, new Float32Array(p), p.length / 2, loop, fx.friction, fx.bounce, category, mask)
-  }
-
-  // Everything that changes the GEOMETRY, so a re-configure that only touches the material is free.
-  private _signature(): string {
-    const o = this.origin ? `${cx(this.origin)},${cy(this.origin)}` : ""
-    if (this.chain) return `chain:${this.chain.map(v => `${cx(v)},${cy(v)}`).join(";")}|${this.loop}|${this.flip}|${o}`
-    if (this.circle !== undefined) return `circle:${this.circle}|${o}`
-    if (this.capsule) {
-      const { from, to, radius } = this.capsule
-      return `cap:${cx(from)},${cy(from)},${cx(to)},${cy(to)},${radius}|${o}`
-    }
-    if (this.segment) {
-      const { from, to } = this.segment
-      return `seg:${cx(from)},${cy(from)},${cx(to)},${cy(to)}|${o}`
-    }
-    if (this.polygon) return `poly:${this.polygon.map(v => `${cx(v)},${cy(v)}`).join(";")}|${o}`
-    if (this.box) return `box:${cx(this.box)},${cy(this.box)}|${o}`
-    const a = this._autoBox()
-    return `auto:${a.hw},${a.hh},${a.x},${a.y}|${o}`
-  }
-
-  /**
-   * @internal — half-extents and centre of the rect this node DRAWS, in the node's own frame.
-   *
-   * Sprite anchor space is Y-DOWN while the world is Y-up (see docs/conventions.md), so `anchor: [.5, 1]`
-   * ("feet") puts the art ABOVE the origin: its centre sits at +h/2. A node with no sprite falls back
-   * to 8x8 at the origin. This is a SNAPSHOT taken when the fixture is built — growing the sprite later
-   * does not resize the collider; re-configure the aspect to re-measure.
-   */
-  private _autoBox(): { hw: number, hh: number, x: number, y: number } {
-    const n = this.node as { size?: Vec2, anchor?: Vec2, scale?: Vec2 }
-    const size = n.size
-    if (!size || !(size.x > 0) || !(size.y > 0)) return { hw: 8, hh: 8, x: 0, y: 0 }
-    const sx = n.scale ? Math.abs(n.scale.x) : 1
-    const sy = n.scale ? Math.abs(n.scale.y) : 1
-    const w = size.x * sx, h = size.y * sy
-    const ax = n.anchor ? n.anchor.x : 0.5
-    const ay = n.anchor ? n.anchor.y : 0.5
-    return { hw: w * 0.5, hh: h * 0.5, x: (0.5 - ax) * w, y: (ay - 0.5) * h }
-  }
-}

package/runtime/sdk/g2/Sprite.ts

@@ -1,89 +0,0 @@
-// A textured 2D node. Cheap setters proxy straight to the native sprite; the data lives in
-// 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 { 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?: 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. */
-  size?: Vec2Like
-  /** Normalized UV sub-rect [u0,v0,u1,v1]. */
-  frame?: [number, number, number, number]
-  /** Tint multiplied with the texture. */
-  color?: ColorInput
-  opacity?: number
-  layer?: number
-  position?: Vec2Like
-}
-
-export class Sprite extends Node2D {
-  private _texture?: Texture2D
-  private _anchor = new Vec2(0.5, 0.5)
-  private _color: ColorInput = 0xffffff
-  private _opacity = 1
-  private _flipX = false
-  private _flipY = false
-  private _size: Vec2 | null = null
-
-  constructor(options: SpriteOptions = {}) {
-    super()
-    if (options.texture) this.texture = options.texture
-    if (options.size) this.size = options.size
-    if (options.anchor) this.anchor = options.anchor
-    if (options.frame) this.frame = options.frame
-    if (options.color !== undefined) this.color = options.color
-    if (options.opacity !== undefined) this.opacity = options.opacity
-    if (options.layer !== undefined) this.layer = options.layer
-    if (options.position) this.position = options.position
-  }
-
-  get texture(): Texture2D | undefined { return this._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 (pixel) texture
-    // A Canvas is authored in LOGICAL units but baked at logical × pixelRatio, so default the sprite's
-    // WORLD size to the canvas's LOGICAL size — pixelRatio then only affects crispness, not on-screen
-    // size. (A plain texture keeps the native default: the texture's pixel dimensions.)
-    if (!this._size && isCanvas(t)) this._size = new Vec2(t.width, t.height)
-    if (this._size) _creator2d.setSpriteSize(this.id, this._size.x, this._size.y)
-  }
-
-  /** Current world size: explicit override if set, else the texture's pixel dimensions (a Canvas-backed
-   *  sprite defaults to the canvas's LOGICAL size, so pixelRatio is crispness only, not size). */
-  get size(): Vec2 { return this._size ?? (this._texture ? new Vec2(this._texture.width, this._texture.height) : new Vec2(0, 0)) }
-  set size(v: Vec2Like) { this._size = new Vec2(v); _creator2d.setSpriteSize(this.id, this._size.x, this._size.y) }
-
-  get anchor(): Vec2 { return this._anchor.clone() }
-  set anchor(v: Vec2Like) { this._anchor = new Vec2(v); _creator2d.setSpriteAnchor(this.id, this._anchor.x, this._anchor.y) }
-
-  /** Set the UV sub-rect (normalized). */
-  set frame(uv: [number, number, number, number]) { _creator2d.setSpriteFrame(this.id, uv[0], uv[1], uv[2], uv[3]) }
-  /** Set the sub-rect in texture pixels. */
-  setFramePx(px: number, py: number, pw: number, ph: number): this {
-    _creator2d.setSpriteFramePx(this.id, px, py, pw, ph)
-    return this
-  }
-
-  get color(): ColorInput { return this._color }
-  set color(c: ColorInput) { this._color = c; const [ r, g, b ] = Color.toRgb01(c); _creator2d.setSpriteColor(this.id, r, g, b) }
-
-  get opacity(): number { return this._opacity }
-  set opacity(a: number) { this._opacity = a; _creator2d.setSpriteOpacity(this.id, a) }
-
-  get flipX(): boolean { return this._flipX }
-  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) }
-}

package/runtime/sdk/g2/SpriteAnimation.ts

@@ -1,171 +0,0 @@
-// 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.
-//
-// Directional sheets (one texture row per facing): set `directions` in row order and mark clips
-// `perDirection` — each expands to `name_DIR` with the frames offset by that row. Then
-// `play('walk', 'SE')` or `play('walk', moveVector)` picks the row (compass tokens: E/NE/N/NW/W/SW/S/SE),
-// and the last direction sticks, so a later `play('idle')` keeps facing.
-//
-// The native clips need the texture's dimensions, so when the Sprite has no texture yet (SpriteSheet's
-// deferred load), the define is postponed: play() calls queue by name and start once define() runs.
-
-import { Aspect } from "../core/Aspect"
-import { cx, cy, type Vec2Like } from "../math/vec"
-import { ensureAnimEvents } from "./loop"
-import type { Sprite } from "./Sprite"
-
-/** Per-clip frame list, or an object for per-clip fps/loop/direction overrides. */
-export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean, perDirection?: boolean }
-
-// Compass angles in Y-up world degrees (E = +x, N = +y) for vector → direction resolution.
-const COMPASS: Record<string, number> = { E: 0, NE: 45, N: 90, NW: 135, W: 180, SW: 225, S: 270, SE: 315 }
-
-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]
-  /** Grid columns override — for sheets with padding; defaults to floor(texWidth / cellWidth). */
-  cols?: number
-  /** Pixel origin of the grid in the texture — cells index from here (a SpriteSheet region). */
-  origin?: [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> = {}
-  /** Facing names in texture-row order (row i = directions[i]) for `perDirection` clips. */
-  directions?: string[]
-
-  private _clipIds: Record<string, number> = {}
-  private _clipNames: Record<number, string> = {}
-  private _current: string | null = null
-  private _defined = false
-  private _queued: string | null = null
-  private _dir: string | null = null
-
-  onAttach(): void {
-    // No texture yet (deferred sheet load): postpone the native define — SpriteSheet (or the user)
-    // calls define() after assigning the texture; play() calls queue until then.
-    if (this.node.texture) 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 defining clips")
-    const [ fw, fh ] = this.size ?? [ tex.width, tex.height ]
-    const cols = this.cols ?? Math.max(1, Math.floor(tex.width / fw))
-    const [ ox, oy ] = this.origin ?? [ 0, 0 ]
-
-    const defineOne = (name: string, indices: number[], fps: number, loop: boolean): void => {
-      const frames = new Float32Array(indices.length * 4)
-      indices.forEach((idx, i) => {
-        const px = ox + (idx % cols) * fw
-        const py = oy + 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
-    }
-
-    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 dirs = !Array.isArray(value) && value.perDirection ? this.directions : undefined
-
-      if (dirs && dirs.length > 0) {
-        // one clip per facing: row i's frames are the base (row-0) frames shifted down i rows.
-        dirs.forEach((dir, row) => defineOne(`${name}_${dir}`, indices.map((f) => f + row * cols), fps, loop))
-      } else {
-        defineOne(name, indices, fps, loop)
-      }
-    }
-    if (this.size) _creator2d.setSpriteSize(node.id, fw, fh)
-    this._defined = true
-
-    if (this._queued) {
-      const queued = this._queued
-      this._queued = null
-      const id = this._clipIds[queued]
-      if (id === undefined) throw new Error(`SpriteAnimation.play(): unknown clip "${queued}"`)
-      _creator2d.playAnimation(node.id, id)
-    }
-  }
-
-  /**
-   * Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly).
-   * For a `perDirection` clip, `dir` picks the facing — a direction name or a movement vector
-   * (nearest compass row wins); omitted, the last direction (or the first row) is kept.
-   */
-  play(name: string, dir?: string | Vec2Like): this {
-    let target = name
-    const clip = this.clips[name]
-    if (clip && !Array.isArray(clip) && clip.perDirection && this.directions?.length) {
-      const resolved = this._resolveDir(dir)
-      if (resolved) { this._dir = resolved; target = `${name}_${resolved}` }
-    }
-    if (this._current === target) return this
-    this._current = target
-    if (!this._defined) { this._queued = target; return this }
-    const id = this._clipIds[target]
-    if (id === undefined) throw new Error(`SpriteAnimation.play(): unknown clip "${target}"`)
-    _creator2d.playAnimation(this.node.id, id)
-    return this
-  }
-
-  stop(): this {
-    this._current = null
-    this._queued = null
-    if (this._defined) _creator2d.stopAnimation(this.node.id)
-    return this
-  }
-
-  /** Current facing (last direction resolved by play()), or null before the first directional play. */
-  get direction(): string | null { return this._dir }
-
-  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) }
-
-  // A direction name passes through; a vector resolves to the nearest compass row this sheet has.
-  // A zero vector (standing still) keeps the current facing.
-  private _resolveDir(dir?: string | Vec2Like): string | null {
-    const dirs = this.directions!
-    if (typeof dir === "string") return dir
-    if (dir !== undefined) {
-      const x = cx(dir), y = cy(dir)
-      if (x !== 0 || y !== 0) {
-        const angle = (Math.atan2(y, x) * 180 / Math.PI + 360) % 360
-        let best: string | null = null
-        let bestDist = Infinity
-        for (const d of dirs) {
-          const a = COMPASS[d]
-          if (a === undefined) continue
-          const dist = Math.min(Math.abs(a - angle), 360 - Math.abs(a - angle))
-          if (dist < bestDist) { bestDist = dist; best = d }
-        }
-        if (best) return best
-      }
-    }
-    return this._dir ?? dirs[0] ?? null
-  }
-}