lecodes-cli 0.11.0 → 0.12.0

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "lecodes-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "dependencies": {
-    "@letary/chisel": "^0.6.0"
+    "@letary/chisel": "^0.6.0",
+    "jimp": "^1.6.1"
   },
   "devDependencies": {
     "lecodes-design": "workspace:*",
@@ -12,7 +13,7 @@
     "sdk": "workspace:*"
   },
   "peerDependencies": {
-    "lecodes-design": "^0.3.2",
+    "lecodes-design": "^0.4.0",
     "lecodes-renderer": "^0.7.1",
     "lecodes-3d-editor": "^0.1.0"
   },

package/runtime/sdk/g2/Node2D.ts

@@ -39,6 +39,9 @@ export class Node2D extends AspectHost<Node2DEvents> {
   /** Native entity handle. */
   readonly id: number
 
+  /** Optional debug/editor name (plain JS data — scene2d files stamp their node names here). */
+  name?: string
+
   protected _x = 0
   protected _y = 0
   protected _rotation = 0

package/runtime/sdk/g2/SpriteAnimation.ts

@@ -4,32 +4,55 @@
 //   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 overrides. */
-export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean }
+/** 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 {
-    this._define()
+    // 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] ?? "")
@@ -42,20 +65,16 @@ export class SpriteAnimation extends Aspect<"anim", Sprite> {
   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")
+    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 = 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 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 = (idx % cols) * fw
-        const py = Math.floor(idx / cols) * fh
+        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
@@ -65,26 +84,88 @@ export class SpriteAnimation extends Aspect<"anim", Sprite> {
       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). */
-  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
+  /**
+   * 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
-    _creator2d.stopAnimation(this.node.id)
+    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
+  }
 }

package/runtime/sdk/g2/SpriteSheet.ts

@@ -0,0 +1,166 @@
+// Sprite sheets as data: one `.sprite.ts` file per image, `export default defineSpriteSheet({...})`.
+// ONE model: every named entry is a region of the image (a rect), optionally SLICED into an
+// animation grid, optionally carrying named clips over that grid — so game code (and the scene
+// editor) reference frames by NAME and never hardcode rects:
+//
+//   import props from './props.sprite'
+//   import hero from './hero.sprite'
+//   scene.add(props.make('tree_orange', { position: [80, 144], layer: 1 }))
+//   scene.add(props.make('water', { position: [0, 0] }))            // sliced, loops on its own
+//   const player = hero.make('hero', { clip: 'idle', layer: 1 })
+//   player.anim.play('walk', inputVector)
+//
+// A sheet describes ART only — rects, slices, clips, anchors. World semantics (colliders, bodies)
+// are the SCENE's job: attach Shape2D / Physics2D / Trigger2D aspects to the placed node (a
+// `.scene2d.ts` `aspects:` list, or `.aspect(...)` in code). Each tool owns its own part.
+//
+// The texture loads lazily on the first make()/load(); sprites created before it resolves get their
+// texture/frame applied on arrival (the world size is known up front from the rect / slice cell, so
+// layout doesn't wait). The sprite editor reads and writes these files — hand edits are preserved
+// (see packages/scene-doc).
+
+import { type Vec2Like } from "../math/vec"
+import { Sprite } from "./Sprite"
+import { SpriteAnimation, type Clip } from "./SpriteAnimation"
+import { Texture2D } from "./Texture2D"
+
+/**
+ * A named region of the image. Just a rect is a static sprite; `slice` subdivides the rect into an
+ * animation grid ([cols, rows] — the cell is rect size / counts); `clips` names frame runs over
+ * that grid (local, row-major). A sliced entry with NO clips loops all of its cells in order.
+ */
+export type SheetSprite = {
+  /** Pixel rect [x, y, w, h] in the image. */
+  rect?: [number, number, number, number]
+  /** Subdivide the rect into an animation grid: [cols, rows]. */
+  slice?: [number, number]
+  /** Playback fps for this sprite's animation (defaults to the sheet fps, then 12). */
+  fps?: number
+  /** Named clips over the local grid (see SpriteAnimation). Omit to loop every cell. */
+  clips?: Record<string, Clip>
+  /** Facing names in local-row order for `perDirection` clips (compass tokens: S/SE/E/…). */
+  directions?: string[]
+  /** Overrides the sheet anchor. */
+  anchor?: Vec2Like
+}
+
+export type SpriteSheetDef = {
+  /** The image URL — write `asset('./sheet.png')`. */
+  image: string
+  /** Default pivot for every sprite made from this sheet ([0.5, 1] = feet, for Y-sorted worlds). */
+  anchor?: Vec2Like
+  /** Default fps for sliced sprites / clips that don't override it. */
+  fps?: number
+  /** The named sprites. */
+  sprites?: Record<string, SheetSprite>
+}
+
+export type SpriteMakeOptions = {
+  position?: Vec2Like
+  layer?: number
+  /** Overrides the sheet/sprite anchor. */
+  anchor?: Vec2Like
+  /** Start this clip immediately (sliced sprites with clips). */
+  clip?: string
+  /** Initial facing for `perDirection` clips. */
+  direction?: string
+}
+
+/** The name a sliced-but-clipless sprite's implicit everything-loop plays under. */
+const LOOP_ALL = "all"
+
+export class SpriteSheet {
+  private _def: SpriteSheetDef
+  private _tex: Texture2D | null = null
+  private _loading: Promise<Texture2D> | null = null
+
+  constructor(def: SpriteSheetDef) {
+    this._def = def
+  }
+
+  /** The sheet definition (read-only by convention — the editor owns the file). */
+  get def(): SpriteSheetDef { return this._def }
+
+  /** The loaded texture, or null before load() resolves. */
+  get texture(): Texture2D | null { return this._tex }
+
+  /** Load the sheet's texture (idempotent). make() starts this automatically. */
+  load(): Promise<Texture2D> {
+    if (!this._loading) {
+      this._loading = Texture2D.load(this._def.image).then((tex) => { this._tex = tex; return tex })
+    }
+    return this._loading
+  }
+
+  /** Names of the sheet's sprites. */
+  get spriteNames(): string[] { return Object.keys(this._def.sprites ?? {}) }
+
+  /** Build a named sprite; starting a clip hands back the animation handle. */
+  make(name: string, opts: SpriteMakeOptions & { clip: string }): Sprite & { anim: SpriteAnimation }
+  make(name: string, opts?: SpriteMakeOptions): Sprite
+  make(name: string, opts: SpriteMakeOptions = {}): Sprite {
+    const def = this._def
+    const named = def.sprites?.[name]
+    if (!named) {
+      throw new Error(`SpriteSheet.make(): unknown sprite "${name}" (have: ${this.spriteNames.join(", ") || "none"})`)
+    }
+    const rect = named.rect
+    const slice = named.slice
+
+    const sprite = new Sprite({
+      anchor: opts.anchor ?? named.anchor ?? def.anchor,
+      layer: opts.layer,
+      position: opts.position,
+    })
+
+    // The world size is known without the texture (the rect, or its slice cell) — set it up front
+    // so layout, Y-sort and colliders are correct even while the image is still loading.
+    if (rect) sprite.size = slice ? [ rect[2] / slice[0], rect[3] / slice[1] ] : [ rect[2], rect[3] ]
+
+    // sliced sprite: all animation flows through SpriteAnimation, anchored at the rect's origin.
+    // No clips declared = one implicit clip looping every cell (animated tiles).
+    if (rect && slice) {
+      const [ cols, rows ] = slice
+      const clips = named.clips && Object.keys(named.clips).length > 0
+        ? named.clips
+        : { [LOOP_ALL]: Array.from({ length: cols * rows }, (_, i) => i) }
+      const animOpts: Partial<SpriteAnimation> = {
+        size: [ rect[2] / cols, rect[3] / rows ],
+        cols,
+        origin: [ rect[0], rect[1] ],
+        clips,
+      }
+      const fps = named.fps ?? def.fps
+      if (fps !== undefined) animOpts.fps = fps
+      if (named.directions) animOpts.directions = named.directions
+      sprite.aspect(SpriteAnimation, animOpts)
+      const start = opts.clip ?? (named.clips ? undefined : LOOP_ALL)
+      if (start) (sprite as Sprite & { anim: SpriteAnimation }).anim.play(start, opts.direction)
+    }
+
+    // texture + frame: now if loaded, else on arrival
+    if (this._tex) this._applyTexture(sprite, named, this._tex)
+    else this.load().then((tex) => this._applyTexture(sprite, named, tex))
+    return sprite
+  }
+
+  /** The pixel rect [x, y, w, h] of a named sprite's REGION (the whole rect, sliced or not). */
+  rectOf(name: string): [number, number, number, number] | null {
+    const rect = this._def.sprites?.[name]?.rect
+    return rect ? [ ...rect ] : null
+  }
+
+  private _applyTexture(sprite: Sprite, named: SheetSprite, tex: Texture2D): void {
+    sprite.texture = tex // native resets UV/size; the Sprite setter re-applies our explicit size
+    const rect = named.rect
+    if (rect) {
+      const [ cw, ch ] = named.slice ? [ rect[2] / named.slice[0], rect[3] / named.slice[1] ] : [ rect[2], rect[3] ]
+      sprite.setFramePx(rect[0], rect[1], cw, ch) // cell 0 (or the whole static rect)
+    }
+    const anim = (sprite as Partial<{ anim: SpriteAnimation }>).anim
+    if (anim) anim.define()
+  }
+}
+
+/** Declare a sprite sheet (the default export of a `.sprite.ts` file). */
+export const defineSpriteSheet = (def: SpriteSheetDef): SpriteSheet => new SpriteSheet(def)

package/runtime/sdk/g2/Tileset.ts

@@ -0,0 +1,71 @@
+// Tilesets as data: one `.tiles.ts` file per atlas, `export default defineTileset({...})` — the
+// material vocabulary (autotile rules) for maps painted by material id. The pure model + deriver
+// live in ./autotile.ts; this file is the runtime handle plus the `Autotile2D` aspect that binds a
+// tilemap node to its tileset:
+//
+//   // world.tiles.ts
+//   export default defineTileset({
+//     image: asset('./TileSet.png'),
+//     tile: 32,
+//     materials: {
+//       grass: { id: 1, kind: 'patch', color: '#4a7c3a', fill: [261, [262, 0.1]],
+//                over: { '*': { edges: [197, 262, 325, 260], outer: [198, 326, 324, 196],
+//                               inner: [199, 327, 391, 263] } } },
+//       road:  { id: 2, kind: 'path', color: '#8a8578', straights: [520, 521], corners: [522, 523, 524, 525] },
+//     },
+//   })
+//
+//   // meadow.scene2d.ts
+//   import world from './world.tiles'
+//   ground: { tilemap: { texture: asset('./TileSet.png'), tile: 32, atlas: [64, 64],
+//                        cells: cells('…') },              // cells hold MATERIAL ids here
+//             aspects: [use(Autotile2D, { tileset: world, seed: 3 })] }
+//
+// The aspect flips the meaning of the same `cells('…')` payload from raw atlas indices to material
+// ids; the scene2d loader runs the deriver BEFORE the Tilemap is constructed (aspects are data on
+// the node def), so no post-construction data path exists and derived indices are never persisted.
+
+import { Aspect } from "../core/Aspect"
+import type { Node2D } from "./Node2D"
+import { deriveCells, type TilesetDef, type TileMaterial } from "./autotile"
+
+export class Tileset {
+  private _def: TilesetDef
+
+  constructor(def: TilesetDef) { this._def = def }
+
+  /** The tileset definition (read-only by convention — the editor owns the file). */
+  get def(): TilesetDef { return this._def }
+
+  /** Names of the declared materials, in file order. */
+  get materialNames(): string[] { return Object.keys(this._def.materials ?? {}) }
+
+  /** A material by name. */
+  material(name: string): TileMaterial | undefined { return this._def.materials?.[name] }
+
+  /** The cell value maps store for a named material (what you paint / pass in `data`). */
+  id(name: string): number | undefined { return this._def.materials?.[name]?.id }
+
+  /** Derive display atlas indices from a material-id grid (what Autotile2D does at load). */
+  derive(cols: number, rows: number, data: ArrayLike<number>, seed = 0): Int32Array {
+    return deriveCells(this._def, cols, rows, data, seed)
+  }
+}
+
+/** Declare a tileset (the default export of a `.tiles.ts` file). */
+export const defineTileset = (def: TilesetDef): Tileset => new Tileset(def)
+
+/**
+ * Marks a tilemap node's `cells` as MATERIAL ids of a tileset instead of raw atlas indices:
+ * `aspects: [use(Autotile2D, { tileset: world })]`. The scene2d loader derives the display
+ * indices (neighbor-mask autotile + seeded scatter, deterministic) before building the tilemap;
+ * the aspect itself holds no behavior. Change `seed` to reshuffle scatter variants.
+ */
+export class Autotile2D extends Aspect<"autotile", Node2D> {
+  static readonly aspect = "autotile"
+
+  /** The imported `.tiles.ts` handle. */
+  tileset: Tileset | null = null
+  /** Scatter seed — same seed, same map, same result on every platform. */
+  seed = 0
+}