lecodes-cli 0.1.6 → 0.1.7

package/runtime/sdk/animate/easings.ts

@@ -0,0 +1,126 @@
+export type Easing = (v: number) => number
+export type EasingModifier = (easing: Easing) => Easing
+
+const DEFAULT_OVERSHOOT_STRENGTH = 1.525
+const BOUNCE_FIRST_THRESHOLD = 4.0 / 11.0
+const BOUNCE_SECOND_THRESHOLD = 8.0 / 11.0
+const BOUNCE_THIRD_THRESHOLD = 9.0 / 10.0
+
+// helper constants
+const ca = 4356.0 / 361.0
+const cb = 35442.0 / 1805.0
+const cc = 16061.0 / 1805.0
+
+export function linear(p: number): number {
+  return p
+}
+
+export function bounceOut(p: number): number {
+  if (p === 1 || p === 0) return p
+  const p2 = p * p
+
+  return p < BOUNCE_FIRST_THRESHOLD
+    ? 7.5625 * p2
+    : p < BOUNCE_SECOND_THRESHOLD
+      ? 9.075 * p2 - 9.9 * p + 3.4
+      : p < BOUNCE_THIRD_THRESHOLD
+        ? ca * p2 - cb * p + cc
+        : 10.8 * p * p - 20.52 * p + 10.72
+}
+
+export function bounceInOut(p: number): number {
+  return p < 0.5
+    ? 0.5 * (1.0 - bounceOut(1.0 - p * 2.0))
+    : 0.5 * bounceOut(p * 2.0 - 1.0) + 0.5
+}
+
+// Accepts an easing function and returns a new one that outputs reversed values.
+// Turns easeIn into easeOut.
+export function reverseEasing(easing: Easing): Easing {
+  return p => 1 - easing(1 - p)
+}
+
+// Accepts an easing function and returns a new one that outputs mirrored values for
+// the second half of the animation. Turns easeIn into easeInOut.
+export function mirrorEasing(easing: Easing): Easing {
+  return p => (p <= 0.5 ? easing(2 * p) / 2 : (2 - easing(2 * (1 - p))) / 2)
+}
+
+// Creates an easing function that is based on the exponent of the provided `power`.
+// The higher the `power`, the stronger the easing.
+export function createExpoIn(power: number): Easing {
+  return p => p ** power
+}
+
+// Creates an easing function that has a stronger overshoot the higher the provided `power`.
+export function createBackIn(power: number): Easing {
+  return p => p * p * ((power + 1) * p - power)
+}
+
+// Creates an easing function that pulls back a little before moving, and then
+// has a `createBackIn`-based overshoot
+export function createAnticipate(power: number): Easing {
+  const backEasing = createBackIn(power)
+
+  return p =>
+    (p *= 2) < 1
+      ? 0.5 * backEasing(p)
+      : 0.5 * (2 - Math.pow(2, -10 * (p - 1)))
+}
+
+export function bounceIn(p: number): number {
+  return 1 - bounceOut(1 - p)
+}
+
+export function easeIn(p: number): number {
+  return p * p
+}
+
+export function easeOut(p: number): number {
+  return 1 - easeIn(1 - p)
+}
+
+export function easeInOut(p: number): number {
+  return p <= 0.5
+    ? easeIn(2 * p) / 2
+    : (2 - easeIn(2 * (1 - p))) / 2
+}
+
+export function circIn(p: number): number {
+  return 1 - Math.sin(Math.acos(p))
+}
+
+export function circOut(p: number): number {
+  return 1 - circIn(1 - p)
+}
+
+export function circInOut(p: number): number {
+  return p <= 0.5
+    ? circOut(2 * p) / 2
+    : (2 - circOut(2 * (1 - p))) / 2
+}
+
+export function backIn(p: number): number {
+  const power = DEFAULT_OVERSHOOT_STRENGTH
+  return p * p * ((power + 1) * p - power)
+}
+
+export function backOut(p: number): number {
+  return 1 - backIn(1 - p)
+}
+
+export function backInOut(p: number): number {
+  return p <= 0.5
+    ? backIn(2 * p) / 2
+    : (2 - backIn(2 * (1 - p))) / 2
+}
+
+export function anticipate(p: number): number {
+  const doubled = p * 2
+
+  if (doubled < 1) {
+    return 0.5 * backIn(doubled)
+  }
+
+  return 0.5 * (2 - Math.pow(2, -10 * (doubled - 1)))
+}

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,73 @@
+// Orthographic camera for a Scene2D. Position/zoom/rotation live natively; `follow` adds a
+// render-synced per-frame update that tracks a node.
+
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { Node2D } from "./Node2D"
+import { offUpdate, onUpdate } from "./loop"
+
+export type FollowOptions = {
+  /** World-space offset added to the target's position. */
+  offset?: Vec2Like
+  /** 0 = snap (default). >0 = exponential smoothing time constant in seconds (smaller = snappier). */
+  smooth?: number
+}
+
+export class Camera2D {
+  private _x = 0
+  private _y = 0
+  private _zoom = 1
+  private _rotation = 0
+
+  private _followTarget: Node2D | null = null
+  private _followOpts: FollowOptions = {}
+  private _followCb: ((dt: number) => void) | null = null
+
+  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])
+  }
+
+  /** Track a node each frame (snaps by default; pass `smooth` for eased follow). */
+  follow(node: Node2D, options: FollowOptions = {}): this {
+    this._followTarget = node
+    this._followOpts = options
+    if (this._followCb) return this
+    this._followCb = (dt: number) => {
+      const t = this._followTarget
+      if (!t) return
+      const [ ox, oy ] = this._followOpts.offset ?? [ 0, 0 ]
+      const tx = t.x + ox
+      const ty = t.y + oy
+      const s = this._followOpts.smooth ?? 0
+      if (s > 0) {
+        const k = 1 - Math.exp(-dt / s)
+        this.position = [ this._x + (tx - this._x) * k, this._y + (ty - this._y) * k ]
+      } else {
+        this.position = [ tx, ty ]
+      }
+    }
+    onUpdate(this._followCb)
+    return this
+  }
+
+  unfollow(): void {
+    this._followTarget = null
+    if (this._followCb) { offUpdate(this._followCb); this._followCb = null }
+  }
+}

package/runtime/sdk/g2/Node2D.ts

@@ -0,0 +1,104 @@
+// 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.
+//
+// Empty Node2Ds are useful as: grouping parents, world-space markers/spawn points, and trigger /
+// logic objects you attach a .collider() to.
+
+import { Emitter } from "../core/events"
+import { Registry } from "../core/registry"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+
+// 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 collider overlap began / ended (deferred — native 2D triggers are not built yet). */
+  enter: (other: Node2D) => void
+  exit: (other: Node2D) => 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> {
+  /** 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
+
+  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) }
+
+  get position(): Vec2 { 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 }
+  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) }
+
+  /**
+   * 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.
+   */
+  collider(_options: ColliderOptions = {}): this {
+    return this
+  }
+
+  /** @internal — overridden by Sprite to translate native clip ids into named animation events. */
+  _dispatchAnimEvent(_clipId: number, _type: number): void {}
+
+  destroy(): void {
+    node2dRegistry.delete(this.id)
+    _creator2d.destroyEntity(this.id)
+  }
+}

package/runtime/sdk/g2/Scene2D.ts

@@ -0,0 +1,73 @@
+// 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 { Camera2D } from "./Camera2D"
+import type { Node2D } from "./Node2D"
+
+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 }
+
+  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)
+  }
+
+  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)
+  }
+}

package/runtime/sdk/g2/Sprite.ts

@@ -0,0 +1,164 @@
+// 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')
+
+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"
+
+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). */
+  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
+}
+
+/** 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)
+  private _color: ColorInput = 0xffffff
+  private _opacity = 1
+  private _flipX = false
+  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
+    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: Texture2D | undefined) {
+    this._texture = t
+    if (!t) return
+    _creator2d.setSprite(this.id, t.id) // native resets UV + size to the full texture
+    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. */
+  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) }
+
+  // --- 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)
+  }
+}