lecodes-sdk 0.19.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "lecodes-sdk",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./compile": "./src/compile/index.ts",
+    "./compile/assetName": "./src/compile/assetName.ts",
+    "./compile/detectEntry": "./src/compile/detectEntry.ts",
+    "./compile/shaderSchema": "./src/compile/shaderSchema.ts",
+    "./compile/liteMaterial": "./src/compile/liteMaterial.ts",
+    "./inject": "./src/inject.ts",
+    "./server": "./src/server/host.ts",
+    "./prompts/select": "./prompts/select.ts",
+    "./global.d.ts": "./dist/global.d.ts",
+    "./host.d.ts": "./dist/host.d.ts",
+    "./types.json": "./dist/types.json"
+  },
+  "scripts": {
+    "build": "bun run build-types.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "docs:check": "node docs/check.mjs",
+    "prompts:build": "bun prompts/compose.ts",
+    "sync:marcidb": "bun scripts/sync-marcidb.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@letary/chisel": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.1",
+    "typescript": "~5.8.3",
+    "gl-matrix": "^3.4.4"
+  },
+  "version": "0.19.0",
+  "files": [
+    "src",
+    "dist",
+    "prompts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts/2d.md

@@ -0,0 +1,395 @@
+# 2D engine
+
+Scene2D + nodes (Sprite, Tilemap) + aspects (SpriteAnimation, Shape2D/Physics2D/Trigger2D/OneWay2D/CharacterController2D) + Canvas for baked text/vector graphics. All globals. `Scene2D` ≠ the 3D `Scene`; one scene active at a time. World units: 1 unit = 1 logical px at camera zoom 1. **Y-UP** (up = +y, gravity = negative y). Rotations in **degrees**, CCW. Game loop = setLoop(dt) from core. The UI kit renders ON TOP of the 2D canvas — build HUDs/menus/on-screen controls with UIScreen/UIWidget as usual (open the scene, then the HUD screen).
+
+// ===== SCENE & NODES =====
+
+new Scene2D(options?: {
+  background?: Color   // clear color (hex string or 0xRRGGBB); settable later via scene.background
+  filter?: 'nearest' | 'linear'  // texture sampling; default nearest (crisp pixel art), 'linear' for hi-res
+})   // art. filter is GLOBAL (one sampler for all textures), re-applied on open()
+
+scene.open(): this   // make active: starts the 2D engine, closes any other scene
+scene.close(): this / scene.destroy(): void;  Scene2D.active   // static: open Scene2D | null
+scene.camera   // the scene's Camera2D (readonly — never construct Camera2D yourself)
+scene.add(...nodes) / scene.remove(...nodes): this   // only ROOT nodes need add — children come with their parent
+
+// Layers & Y-sort: node.layer picks the layer (higher draws on top); within a layer node.z orders.
+scene.layer(1).ySort()   // top-down depth sorting: sprites lower on screen draw in front ("walk behind
+                         // trees"). Compares ANCHOR points → give nodes on that layer anchor [0.5, 1] (feet)
+
+scene.pick(worldPoint: Vec2Like): Node2D | null   // body-free hit-test: topmost visible sprite at the point
+
+// Scene-level pointer events — fire for EVERY tap; ev: { target: Node2D|null, worldX, worldY, clientX, clientY }
+scene.addEventListener('click', ev => {})   // pointer-up; target = hit physics-body node or null
+scene.addEventListener('touchstart', ev => {})   // pointer-down; ev.track({...}) for drags (see core) —
+                                                 //  onMove gives SCREEN px, camera.screenToWorld for world drags
+
+// --- Node2D — base node: an empty transform. Sprite/Tilemap extend it. ---
+// Bare Node2D: grouping parent, spawn marker, invisible collider/trigger. removeEventListener to detach.
+const node = new Node2D()
+node.x, node.y   // single-axis setters — use for per-axis writes
+node.position = [120, 64]   // Vec2Like; getter returns a copy — node.position.x = 3 written directly still works (compiled to node.x)
+node.rotation = 45   // degrees CCW
+node.scale = 2   // number or [sx, sy] — DRAW scale only (physics shapes ignore it)
+node.layer = 1; node.z = 5; node.visible = false
+
+node.add(...children): this   // attach (keeps world transform); node.remove(child) detaches → root
+node.setParent(parent | null, keepWorld = true): this;  node.parent / node.children
+node.worldPosition   // Vec2 — composes all ancestors (fresh copy)
+node.worldToLocal(p) / node.localToWorld(p): Vec2
+node.destroy(): void   // frees the native entity. CHILDREN ARE NOT DESTROYED — they reparent to root.
+
+// Node events (node.addEventListener(channel, cb)):
+//   'click' / 'touchstart' — pointer on this node's PHYSICS shape (needs Shape2D + Physics2D or Trigger2D)
+//   'enter' / 'exit'       — physics contact / sensor overlap began/ended; arg = the other Node2D
+//   'loopReached' / 'completed' — SpriteAnimation clip looped / non-looping clip finished; arg = clip NAME
+
+// --- Camera2D (scene.camera) ---
+camera.position = [x, y]   // world point at the CENTER of the screen (getter returns a copy)
+camera.zoom = 2   // magnification; default 1.  camera.rotation = 15 (degrees CCW)
+camera.screenToWorld(sx, sy): Vec2 / camera.worldToScreen(wx, wy): Vec2   // logical px ↔ world (handles the Y flip)
+// There is NO camera.follow() — lerp toward the target from setLoop, or better, use a LATE-phase aspect
+// that reads the final post-physics position (see ASPECTS: CameraFollow, and Example 1).
+
+// ===== SPRITES & TEXTURES =====
+
+const tex = await Texture2D.load(asset('./hero.png'))   // string url (asset() or https://) | FetchResponse | File
+tex.width, tex.height   // pixels (readonly);  tex.destroy() frees it (textures are shared: many sprites, one texture)
+
+new Sprite(options?: {
+  texture?: Texture2D | Canvas   // a Canvas bakes to a texture on assign (sprite then defaults to its LOGICAL size)
+  anchor?: Vec2Like   // pivot, Y-DOWN: [0,0] top-left … [1,1] bottom-right; default [0.5,0.5].
+                      // [0.5, 1] = bottom-center = "feet" — use on Y-sorted layers
+  size?: Vec2Like   // world size; default = texture pixel dims (1 texel = 1 world unit)
+  frame?: [u0, v0, u1, v1]   // normalized UV sub-rect
+  color?: Color   // tint MULTIPLIED with the texture; hex/packed only (default white = untinted)
+  opacity?: number   // 0..1
+  layer?: number
+  position?: Vec2Like
+})
+
+sprite.texture = tex; sprite.size = [w, h]
+sprite.setFramePx(x, y, w, h): this   // atlas sub-rect in TEXTURE PIXELS (image-editor coords) — chainable.
+                                      // Does NOT change size — set size to the frame's pixel dims yourself
+sprite.color = '#ff8800'; sprite.opacity = 0.5
+sprite.flipX = true; sprite.flipY = true   // mirror to face left/right — don't use negative scale
+
+// ===== ASPECTS — the composition system =====
+// Everything a node CAN DO attaches as an aspect — built-ins and your own game logic alike.
+node.aspect(Class, opts?)   // attach + configure; returns the node → chains. Re-calling merges opts
+node.get(Class)   // instance | undefined;  node.has(Class) — boolean + type guard
+node.removeAspect(Class)   // detach (runs onDetach)
+// Each aspect adds a NAMED ACCESSOR: hero.anim, hero.physics, hero.shape, hero.trigger, hero.controller —
+// for your own, the first generic param: Aspect<'camFollow', …> → node.camFollow.
+
+class CameraFollow extends Aspect<'camFollow', Node2D> {   // <accessor name, host node kind>
+  camera!: Camera2D   // class fields = configurable defaults, set via aspect() opts
+  smooth = 8
+  onAttach() {}   // node + opts are set here; onDetach() for cleanup. NEVER write a constructor —
+                  // the engine instantiates via node.aspect()
+  update(dt: number) {   // ticked every frame while attached; dt in SECONDS
+    this.camera.position = this.camera.position.lerp(this.node.worldPosition, this.smooth * dt)
+  }
+}
+hero.aspect(CameraFollow, { camera: scene.camera })
+// update() default phase = LATE (after the physics step — worldPosition is the final drawn position; right
+// for cameras/followers/readers). Aspects that WRITE velocity/forces/kinematic moves set the class field
+// `updateBeforePhysics = true` (same frame's step consumes them). `order = -10` sorts ticks within a phase.
+
+// ===== SPRITE ANIMATION =====
+// Sheet animation as an aspect on a Sprite — accessor node.anim. Playback advances natively.
+
+sprite.aspect(SpriteAnimation, {
+  size?: [w, h]   // ONE frame cell in texture px; default = full texture. Also sets sprite.size to the cell
+  fps?: number   // clip default; default 12
+  loop?: boolean   // clip default; default true
+  clips?: Record<string, number[] | { frames: number[], fps?, loop? }>
+})
+// Frame indices are ROW-MAJOR through the sheet grid: 0 = top-left cell, left-to-right then down.
+// The sprite MUST already have its texture when the aspect attaches (grid slices from it) — throws otherwise.
+
+sprite.anim.play('walk'): this   // throws on unknown clip. Re-playing the active clip is a NO-OP — safe every frame
+sprite.anim.stop(): this;  sprite.anim.speed = 2   // rate multiplier (write-only)
+sprite.anim.current   // playing clip name | null;  sprite.anim.frame — current index (readonly)
+
+// Events land on the NODE, arg = clip NAME ('loopReached' = looping clip wrapped):
+hero.addEventListener('completed', clip => { if (clip === 'die') hero.destroy() })  // non-looping clip finished
+
+// ===== TILEMAP =====
+// One node draws a whole level: atlas texture on a uniform grid, uploaded once, view-culled natively.
+
+new Tilemap(options: {
+  texture: Texture2D
+  cols: number, rows: number   // map size in tiles
+  tile: number | [w, h]   // cell size in world units (number = square)
+  atlas: [atlasCols, atlasRows]   // how the texture slices into tiles
+  data: number[] | Int32Array   // row-major atlas indices, length cols*rows; -1 = empty
+})
+// data row 0 = the TOP row of the map (reads like level text), even though world Y is up. Atlas indices
+// are row-major too: 0 = the atlas's top-left tile. node.position = the map's BOTTOM-LEFT corner.
+map.setTile(x, y, index): this   // grid coords as in data (row 0 = top); -1 clears. Cheap.
+// LIMITS — a static uniform grid. NO animated tiles (swap cells with setTile yourself), NO per-tile flip/
+// rotate (bake variants into the atlas), and NO collision: physics NEVER reads a tilemap, by design. Solid
+// geometry is scene objects — Node2Ds with Shape2D box/polygon/chain + a static Physics2D.
+
+// ===== 2D PHYSICS (Box2D) =====
+
+Physics2D.configure(config?: {
+  gravity?: Vec2Like   // world units/s², Y-up (down = negative Y); default [0, -980]. Top-down → [0, 0]
+  pixelsPerMeter?: number   // Box2D tolerance tuning (you still author in world units); default 64
+  subSteps?: number   // default 4
+})
+// OPTIONAL: the world builds itself on the first body. Calling it later changes gravity LIVE and leaves
+// every existing body alone. Fixed 60 Hz step (max 4 sub-steps/frame); rendered transforms interpolated.
+Physics2D.supported   // some builds ship without physics — the family then silently no-ops. Guard with it.
+
+// --- Shape2D — pure geometry (node.shape). Does nothing alone. Attach BEFORE the body. ---
+node.aspect(Shape2D, {
+  box?: [hw, hh]   // HALF-extents: box:[12,20] = a 24×40 box
+  circle?: number   // radius
+  capsule?: { from: Vec2Like, to: Vec2Like, radius: number } // between two node-local points
+  segment?: { from: Vec2Like, to: Vec2Like }   // one thin edge — STATIC only
+  polygon?: Vec2Like[]   // CONVEX, ≤ 8 local points (a concave outline is silently replaced by its hull)
+  chain?: Vec2Like[]   // polyline: long CONCAVE seam-free surfaces (terrain, cave walls). STATIC only.
+  loop?: boolean   // chain: close the contour.  flip?: put the solid side on the other side
+  origin?: Vec2Like   // the collider's centre relative to the node — applies to EVERY kind
+})
+// PREFER `{}`: it measures the rect the node actually DRAWS (sprite size × scale, positioned by anchor),
+// so a sprite anchored at its feet gets a collider around the art with no hand-computed numbers.
+// Re-configuring rebuilds the fixture IN PLACE (same body, same id, same velocity) — that is how a crouch
+// works. A chain is ONE-SIDED: solid on the RIGHT of the point order, so left-to-right ground needs flip.
+
+// --- Physics2D — rigid body (node.physics). Requires a Shape2D on the node (throws otherwise). ---
+node.aspect(Physics2D, {
+  motion?: 'static' | 'kinematic' | 'dynamic'   // default 'dynamic'
+  mass?: number   // omitted = from the collider's AREA (a big crate really is heavier)
+  friction?: number   // default 0.6; two bodies combine as sqrt(a*b) — the LOWER value wins
+  bounce?: number   // restitution 0..1, default 0; two bodies combine as MAX — the bouncier wins
+  fixedRotation?: boolean   // lock rotation; default false.  bullet?: continuous collision for fast movers
+  gravityScale?: number   // per-body multiplier, default 1.  linearDamping? / angularDamping?
+  group?: PhysicsGroup2D   // collision filtering, see below
+})
+// Everything above is LIVE: node.physics.motion = 'static' freezes a crate, .friction / .bounce / .mass /
+// .group / .enabled / .awake all apply immediately.
+node.physics.velocity = [vx, vy]      // world units/s (getter returns a fresh Vec2)
+node.physics.angularVelocity = 90     // degrees/s, rw
+node.physics.applyImpulse([x, y])     // at the centre of mass — NEVER spins the body
+node.physics.applyImpulseAt(v, worldPoint)   // …the lever arm becomes spin (a bullet's hit point)
+node.physics.applyForce([x, y])
+// PHYSICS OWNS THE TRANSFORM of dynamic/kinematic bodies. Never set node.position per frame on one —
+// drive dynamic with velocity/applyImpulse. A position/rotation WRITE is a teleport that reaches the
+// body (there is no moveTo any more); READING node.position is always correct. Keep bodies and sensors
+// on ROOT nodes — one parented to a moving node does not follow it.
+
+// --- Trigger2D — sensor zone (node.trigger). Fires enter/exit, blocks nothing. ---
+goal.aspect(Shape2D, { circle: 48 }).aspect(Trigger2D)   // { group? }
+goal.position = [x, y]        // the zone FOLLOWS the node (it is kinematic)
+goal.trigger.enabled = false  // switch it off instead of parking it off-screen
+goal.addEventListener('enter', (other, contact) => {})   // contact: { point, normal, speed }
+// enter/exit also fire for SOLID contacts, delivered to BOTH nodes; the normal points back at YOU, so
+// normal.y > 0.7 reads as "I landed on top of it". Adding the listener is what ENABLES contact events on
+// that body — without one nothing is reported and nothing is paid. Characters ARE detected by triggers.
+
+// --- OneWay2D — one-way surface (node.oneWay): the semisolid ledge of a platformer ---
+ledge.aspect(Shape2D, {}).aspect(Physics2D, { motion: 'static' }).aspect(OneWay2D)
+// { normal?: Vec2Like (which side is solid, default [0,1]), arc?: degrees (default 90), enabled? }
+// Jump up through it, stand on top. Works for characters AND ordinary bodies, no per-frame cost.
+
+// --- Collision groups: SUBTRACTIVE and SYMMETRIC ---
+const player  = Physics2D.addGroup()
+const bullets = Physics2D.addGroup().ignoreSelf().ignore(player)   // 30 groups max
+// A group collides with everything EXCEPT what it ignores, so adding a new group later can't silently
+// stop existing pairs colliding. ignore() is symmetric (name it once) and works after bodies exist.
+
+// --- CharacterController2D — KINEMATIC collide-and-slide mover (node.controller) ---
+node.aspect(CharacterController2D, { gravityScale?: 1, maxSlope?: 45, group?: PhysicsGroup2D })
+// Needs a CAPSULE Shape2D (derived from the sprite if absent). Does NOT use Physics2D. Zero JS per frame.
+c.move(x)             // HORIZONTAL command, world units/s — a VELOCITY, not a displacement (never * dt).
+                      // It EXPIRES each frame: no call = standing still, releasing keys needs no zero.
+c.move(x, y)          // FREE MODE (gravityScale 0): both axes. Top-down / swimming / a ladder.
+c.velocityY = 700     // LATCHED ballistic vertical. No ground check — do coyote time yourself.
+c.velocity            // read = what the SOLVER did (into a wall reads ~0); write = latch the whole vector
+c.grounded / c.groundState ('ground'|'slope'|'air') / c.groundNormal / c.groundNode
+c.collisions          // [{ node, normal }] from the last step — wall jumps, pushing crates
+c.dropThrough = platform   // ignore that node's OneWay2D surfaces; a plain latch, you clear it
+c.resizing            // a requested Shape2D resize didn't fit (standing up under a beam)
+// PLATFORMER vs TOP-DOWN is gravityScale, not two controllers. A kinematic platform carries the
+// character automatically. Crouch by re-configuring Shape2D with a shorter capsule; a refusal changes
+// nothing, so just call it again next frame. Solid contacts arrive in c.collisions, not as 'enter'.
+
+// Queries (static). q = { groups?: PhysicsGroup2D[], ignore?: Node2D | Node2D[] }
+Physics2D.raycast(from, to, q?)      // closest → { node, point, normal, fraction } | null
+Physics2D.raycastAll(from, to, q?)   // every hit, NEAREST FIRST (max 32)
+Physics2D.overlapPoint(p, q?)        // topmost by DRAW order (layer, then z)
+Physics2D.overlapCircle(centre, r, q?) / overlapBox(centre, half, q?) / overlapCapsule(from, to, r, q?)
+// `ignore` is the don't-hit-myself case. overlapCapsule is the DIRECTED shape (a beam with width, a sword
+// arc) and doubles as the SWEPT test for a moving circle — it can't tunnel through a thin wall.
+
+// Pointer picking: a node with Shape2D + (Physics2D | Trigger2D | CharacterController2D) is tappable —
+// it receives 'click'/'touchstart'. The scene ALSO gets every event (ev.target, ev.worldX/worldY).
+// Without physics: scene.pick(camera.screenToWorld(ev.clientX, ev.clientY)).
+
+// ===== CANVAS IN 2D =====
+// The Canvas drawing surface (see the CANVAS section above) is how TEXT and vector graphics get
+// into sprites — there is no Text2D node. Assign it wherever a texture goes; it bakes automatically:
+const label = new Sprite({ texture: c, layer: 2 })   // sprite world size = the canvas's LOGICAL size
+// Redraw + c.update() to refresh the sprite's pixels (see the drawing-pad example below).
+
+// ===== COMMON MISTAKES — DO NOT DO THESE =====
+
+// ❌ writing the transform of a dynamic body per frame — physics owns it and overwrites you
+setLoop(() => { hero.y += 2 })   // WRONG
+setLoop(() => { hero.physics.velocity = [0, 120] })   // ✅ drive the body (kinematic: moveTo)
+
+// ❌ expecting scale to resize the collider
+sprite.scale = 2   // draws 2×, physics box UNCHANGED — Shape2D never reads scale
+sprite.aspect(Shape2D, { box: [12, 20] })   // ✅ declare the extents you want (HALF-extents: this is 24×40)
+
+// ❌ Physics2D.configure() after bodies exist — resets the world, orphans every body
+// ✅ configure once at startup, before the first Shape2D/Physics2D/Trigger2D attach
+
+// node.position.x = 3 compiles to node.x = 3 (direct spelling only). ❌ const p = node.position; p.x = 3 — a stored copy, no-op
+
+// ❌ default [0.5,0.5] anchor on a Y-sorted layer — depth sorts wrong. ✅ anchor: [0.5, 1] (feet)
+
+// ❌ scene.camera.follow(hero)   — does not exist. ✅ lerp in setLoop, or a LATE-phase aspect (Example 1)
+
+// ❌ per-frame setFramePx to animate — poorly re-implements SpriteAnimation
+setLoop(() => sprite.setFramePx(...))   // WRONG
+sprite.aspect(SpriteAnimation, { size: [32, 48], clips: { walk: [0,1,2,3] } })   // ✅ then anim.play('walk')
+
+// ❌ CSS color strings on sprites — engine colors are hex/packed only (Canvas fillStyle is the exception)
+sprite.color = 'rgba(255,0,0,0.5)'   // WRONG
+sprite.color = '#ff0000'; sprite.opacity = 0.5   // ✅
+
+// ❌ attaching SpriteAnimation before the sprite has a texture — throws (the grid slices from it)
+// ❌ attaching Physics2D before Shape2D on the same node — throws (attach the shape first)
+// ❌ setting spawn position AFTER attaching Physics2D — the body already seeded from [0,0]; position first
+
+## Code examples
+
+// === EXAMPLE 1: top-down collector — tilemap, physics-driven hero, trigger pickups, camera follow, HUD ===
+<file name="main.ts">
+const TILE = 32, COLS = 24, ROWS = 18
+const W = COLS * TILE, H = ROWS * TILE
+const SPEED = 170
+
+// LATE-phase follow aspect: runs after the physics step, reads the hero's final drawn position — no lag.
+class CameraFollow extends Aspect<'camFollow', Node2D> {
+    camera!: Camera2D
+    smooth = 8
+    update(dt: number) {
+        this.camera.position = this.camera.position.lerp(this.node.worldPosition, this.smooth * dt)
+    }
+}
+
+async function main() {
+    const scene = new Scene2D({ background: '#2a3b24' })
+    scene.layer(1).ySort()   // actors/props sort by their feet
+    Physics2D.configure({ gravity: [0, 0] })   // top-down: no gravity. BEFORE any body is created.
+
+    const texTiles = await Texture2D.load(asset('./tiles.png'))   // 4x4 atlas of 32px tiles
+    const texHero = await Texture2D.load(asset('./hero.png'))   // sheet of 32x48 cells: idle + walk
+    const texCoin = await Texture2D.load(asset('./coin.png'))   // 6x1 sheet of 16x16 frames
+
+    // Ground: grass (atlas 0) with scattered detail (atlas 1). data row 0 = TOP row of the map.
+    const data = new Int32Array(COLS * ROWS)
+    for (let i = 0; i < data.length; i++) data[i] = Math.random() < 0.12 ? 1 : 0
+    scene.add(new Tilemap({ texture: texTiles, cols: COLS, rows: ROWS, tile: TILE, atlas: [4, 4], data }))
+
+    // Border walls: static segments (world coords — the nodes sit at [0,0]) keep the hero inside
+    const wall = (ax: number, ay: number, bx: number, by: number) => new Node2D()
+        .aspect(Shape2D, { segment: { from: [ax, ay], to: [bx, by] } })
+        .aspect(Physics2D, { motion: 'static' })
+    wall(0, 0, W, 0); wall(0, H, W, H); wall(0, 0, 0, H); wall(W, 0, W, H)
+
+    // Hero: feet anchor for Y-sort; feet-box collider offset up from the anchor; dynamic body driven
+    // by velocity (physics owns the transform). Position set BEFORE the body attaches.
+    const hero = new Sprite({ texture: texHero, anchor: [0.5, 1], layer: 1, position: [W / 2, H / 2] })
+        .aspect(SpriteAnimation, { size: [32, 48], fps: 10, clips: { idle: [0], walk: [1, 2, 3, 4] } })
+        .aspect(Shape2D, { box: [10, 6], offset: [0, 6] })
+        .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true, friction: 0 })
+        .aspect(CameraFollow, { camera: scene.camera })
+    hero.anim.play('idle')
+    scene.add(hero)
+
+    // HUD on top of the 2D canvas (UI kit)
+    let scoreText: UIText
+    const hud = UIScreen(
+        scoreText = UIText("Coins: 0").style({ color: "white", fontSize: 18, fontWeight: 700 }),
+    ).style({ p: 16, pt: "max(safe-top, 16px)" })
+    hud.open()
+
+    // Coin pickups: spinning sprite + a Trigger2D sensor — 'enter' fires on overlap, blocks nothing
+    let score = 0
+    const spawnCoin = (x: number, y: number) => {
+        const coin = new Sprite({ texture: texCoin, anchor: [0.5, 0.5], layer: 1, position: [x, y] })
+            .aspect(SpriteAnimation, { size: [16, 16], fps: 8, clips: { spin: [0, 1, 2, 3, 4, 5] } })
+            .aspect(Shape2D, { circle: 12 })
+            .aspect(Trigger2D)
+        coin.anim.play('spin')
+        coin.addEventListener('enter', other => {
+            if (other !== hero) return
+            scoreText.text = `Coins: ${++score}`
+            coin.destroy()
+        })
+        scene.add(coin)
+    }
+    for (let i = 0; i < 10; i++)
+        spawnCoin(48 + Math.random() * (W - 96), 48 + Math.random() * (H - 96))
+
+    scene.open()
+
+    // Input → velocity, every frame. (For touch, add an on-screen joystick UIWidget and merge its
+    // vector here — same velocity write.) Dynamic bodies keep momentum, so zero velocity when idle.
+    const body = hero.get(Physics2D)!
+    const held = (a: string, b: string) => Input.key(a) || Input.key(b) ? 1 : 0
+    setLoop(() => {
+        const dx = held('KeyD', 'ArrowRight') - held('KeyA', 'ArrowLeft')
+        const dy = held('KeyW', 'ArrowUp') - held('KeyS', 'ArrowDown')
+        const len = Math.hypot(dx, dy)
+        if (len > 0) {
+            body.velocity = [dx / len * SPEED, dy / len * SPEED]   // Y-up: W/up = +y
+            if (dx !== 0) hero.flipX = dx < 0
+            hero.anim.play('walk')   // re-playing the active clip is a no-op — safe every frame
+        } else {
+            body.velocity = [0, 0]
+            hero.anim.play('idle')
+        }
+    })
+}
+
+main()
+</file>
+
+// === EXAMPLE 2: drawing pad — Canvas sprite + scene gesture ===
+<file name="main.ts">
+const scene = new Scene2D({ background: '#ffffff', filter: 'linear' })
+const W = device.width, H = device.height
+const paper = new Canvas(W, H, { pixelRatio: device.pixelRatio })   // logical size; pixelRatio = crispness
+paper.strokeStyle = '#1a3aa8'; paper.lineWidth = 4; paper.lineCap = 'round'
+
+// Canvas-backed sprite takes the LOGICAL size; center the camera on it so world == screen area
+scene.add(new Sprite({ texture: paper, position: [W / 2, H / 2] }))
+scene.camera.position = [W / 2, H / 2]
+scene.open()
+
+// screen px → canvas coords (canvas is Y-down from its top-left; world is Y-up)
+const toCanvas = (sx: number, sy: number): [number, number] => {
+    const w = scene.camera.screenToWorld(sx, sy)
+    return [w.x, H - w.y]
+}
+
+scene.addEventListener('touchstart', ev => {
+    let [lx, ly] = toCanvas(ev.clientX, ev.clientY)
+    ev.track({
+        onMove({ clientX, clientY }) {   // logical SCREEN px
+            const [x, y] = toCanvas(clientX, clientY)
+            paper.beginPath().moveTo(lx, ly).lineTo(x, y).stroke()
+            paper.update()   // re-bake: push new pixels to the sprite
+            lx = x; ly = y
+        },
+    })
+})
+</file>

package/prompts/3d-scene-files.md

@@ -0,0 +1,113 @@
+## Scene files (.scene.ts)
+
+Projects may contain `*.scene.ts` files: declarative scenes that the platform's VISUAL scene
+editor reads and writes. The user may have built them by dragging models around — treat the file
+as their artwork. You may edit values and add nodes/aspects, but keep the `defineScene({...})`
+literal-object shape; an imperative rewrite (`new Scene()` + `scene.add(...)`) destroys their
+ability to keep editing it visually. `defineScene`, `use`, `ref` and `make` are globals.
+
+// ===== DEFINE SCENE =====
+
+// Default-export exactly one defineScene call per .scene.ts file.
+export default defineScene({
+  env?: SceneOptions,        // same options object as `new Scene(...)` above (skybox, ibl, bloom…)
+  nodes?: {
+    name: {                  // names are sibling-unique, no '/' or ':' in them
+      // -- source: AT MOST ONE of these per node; none = empty group node --
+      mesh?: { kind: 'box', size?: n | [x,y,z] } | { kind: 'sphere' | 'cylinder' | 'plane', ... },
+      model?: string,        // GLB via the asset macro: asset('./hero.glb')
+      light?: { kind: 'sun', direction?, intensity?, shadowsQuality? },  // 'sun' is the ONLY kind
+      camera?: { fov?, near?, far? },  // this node IS the scene camera (defaults 60 / 0.01 / 1000)
+      make?: make(factoryFn, { ...literalArgs }),  // code-built subtree from a user function
+      prefab?: SceneHandle,  // another .scene.ts's default export (import it)
+      // -- for a mesh source --
+      material?: { lit: { color?, metallic?, roughness? } } | { unlit: { color? } },
+      // -- transform / render --
+      position?: [x,y,z], eulerAngles?: [x,y,z], scale?: [x,y,z] | n,
+      visible?, castShadows?, receiveShadows?,
+      locked?: boolean,      // editor-only flag, zero runtime effect — leave it alone
+      // -- behavior / hierarchy --
+      aspects?: [ use(AspectClass, { ...props }) ],  // props may use ref('otherNode') for node refs
+      children?: { name: { ...same shape } },
+      // pose parts INSIDE a model/prefab, and attach a child node to such a part:
+      overrides?: { 'Bone/Path': { position?, eulerAngles?, scale?, visible? } },
+      mount?: 'Bone/Path',   // parents this node to that part of the PARENT node's asset
+    },
+  },
+})
+
+// ===== USING A SCENE FROM APP CODE =====
+
+import city from './city.scene'            // extension-less specifier; default export: SceneHandle
+
+const { scene, nodes, get } = await city.open()  // load (fetches GLBs) + become the active view
+// city.load() — instantiate without showing; both are idempotent (same instance every call)
+nodes.crate                          // typed by source: model → Model, mesh → Mesh, light → Light
+nodes['props/lamp']                  // keys are absolute '/'-joined paths; get(path) for dynamic
+nodes.crate.position = [1, 0.5, 2]   // plain SDK nodes — assign vectors, or scalar axes: node.y = 2
+nodes.hero.anim.play('walk')         // a model node is a Model: animations, parts — all there
+scene.close()                        // closing goes through the scene (there is NO handle.close())
+
+// ===== BEHAVIOR & INPUT =====
+
+// Put per-frame behavior in ASPECTS attached in the file — not in code that mutates the doc:
+//   aspects: [use(Spin, { speed: 40 })]
+// Built-in no-code aspects: MoveTo, FollowPath ({ path: ref('waypoints'), duration }), Spin,
+// LookAt, PlayAnimation. Custom ones are ~5 lines (see Aspects; update(dt) — dt in SECONDS):
+export class Spinner extends Aspect<'spinner'> {
+  speed = 30                                   // class fields = props settable from use(...)
+  update(dt: number) { this.node.eulerAngles = [0, this.node.eulerAngles.y + this.speed * dt, 0] }
+}
+// Clicks/taps: a node is pickable only with a Shape aspect — aspects: [use(Shape, {})] — then
+// nodes.crate.addEventListener('click', ev => ...). Catch-all with target (null on miss):
+// scene.addEventListener('click', ev => ev.target). Shape alone = static pick body; moving
+// clickables also need Physics.
+
+// ===== UI OVER AN OPEN SCENE =====
+
+// Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
+// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
+    .style({ top: 'max(safe-top, 16px)', left: 16 })
+hud.attachTo(scene).show()
+
+// ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
+
+// - Rebuilding a .scene.ts imperatively, or moving its content into main.ts. Edit the def in
+//   place; logic goes into aspect classes or app code around handle.open().
+// - scene.ref(...), handle.close(), onTap — none exist. It's nodes[path] / get(path),
+//   loaded.scene.close(), addEventListener('click').
+// - Two source keys on one node (e.g. mesh + model) — throws at load.
+// - Expecting clicks without use(Shape, {}) on the node.
+// - const p = node.position; p.x = 3 — NO-OP (a stored copy). node.position.x = 3 itself compiles to node.x = 3.
+// - env HDRI paths or light kinds other than 'sun' — not supported; ibl is just a boolean.
+
+## Scene file wiring example
+
+// A scene built in the visual editor, wired up with a click counter and a HUD.
+
+<file name="main.scene.ts">
+export default defineScene({
+  env: { skybox: '#a9b6c8' },
+  nodes: {
+    camera: { camera: {}, position: [0, 4, 9], eulerAngles: [-22, 0, 0] },
+    sun: { light: { kind: 'sun', shadowsQuality: 1 } },
+    ground: { mesh: { kind: 'box', size: [12, 0.4, 12] }, material: { lit: { color: '#3d4351' } },
+              position: [0, -0.2, 0], locked: true },
+    crate: { mesh: { kind: 'box' }, material: { lit: { color: '#8a8f98' } }, position: [0, 0.5, 0],
+             aspects: [use(Shape, {}), use(Spin, { speed: 25 })] },
+  },
+})
+</file>
+
+<file name="main.ts">
+import mainScene from './main.scene'
+
+const { scene, nodes } = await mainScene.open()
+
+let taps = 0
+const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
+UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+
+nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
+</file>