lecodes-sdk 0.20.0 → 1.0.0

package/src/scene/defineScene.ts

@@ -46,13 +46,14 @@ import { CameraPlace } from "../gl/CameraPlace"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
-import { Physics } from "../gl/Physics"
+import { Physics } from "../gl/physics/Physics"
+import { CharacterController } from "../gl/physics/CharacterController"
 import { Lightmap } from "../gl/Lightmap"
-import { NavMesh } from "../gl/NavMesh"
-import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/Terrain"
+import { NavMesh } from "../gl/nav/NavMesh"
+import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
 import { Light, type SunOptions } from "../gl/Light"
 import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
-import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
+import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
 import { GizmoBuffer, Gizmos, withGizmoScope, type GizmoBatch } from "./gizmos"
 
 // ---- the literal grammar (what the visual editor reads and writes) -----------
@@ -61,6 +62,7 @@ export type MeshDef =
   | { kind: "box", size?: Vec3Like | number }
   | ({ kind: "sphere" } & SphereOptions)
   | ({ kind: "cylinder" } & CylinderOptions)
+  | ({ kind: "capsule" } & CapsuleOptions)
   | ({ kind: "plane" } & PlaneOptions)
 
 export type LightDef = { kind: "sun" } & SunOptions
@@ -230,6 +232,10 @@ export type SceneLightmapDef = {
    *  ambient cube (2026-08-31) movers shade like the statics and the default is right; it stays as a
    *  trim. See `LightmapLoadOptions.volumeBoost`. */
   volumeBoost?: number
+  /** Occluder-only statics (props without lightmap UVs): `"baked"` (default) = their shadow is in the
+   *  atlas, they stop casting in real time and the shadow pass draws only the movers; `"realtime"` =
+   *  they keep casting (their shadow on other non-receiver props). See `LightmapLoadOptions.occluderShadows`. */
+  occluderShadows?: "baked" | "realtime"
 }
 
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
@@ -402,6 +408,7 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
     case "box": mesh = Mesh.box({ size: def.size, material: mat }); break
     case "sphere": { const { kind: _k, ...opts } = def; mesh = Mesh.sphere({ ...opts, material: mat }); break }
     case "cylinder": { const { kind: _k, ...opts } = def; mesh = Mesh.cylinder({ ...opts, material: mat }); break }
+    case "capsule": { const { kind: _k, ...opts } = def; mesh = Mesh.capsule({ ...opts, material: mat }); break }
     case "plane": { const { kind: _k, ...opts } = def; mesh = Mesh.plane({ ...opts, material: mat }); break }
   }
   if (material instanceof MaterialHandle) material._users.add({ node: mesh, slot: 0 })
@@ -417,11 +424,15 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
 
 type LightmapCtx = { prefix: string, volume: boolean, dynamicOnly?: boolean }
 
+// A CharacterController moves its node as surely as a dynamic body does (2026-09-11: the hero's
+// capsule was read as static, so its sword baked a shadow into the terrain at the spawn point).
 const movesByPhysics = (def: SceneNodeDef): boolean =>
   (def.aspects ?? []).some((e) =>
-    (e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+    ((e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+    || (e.ctor as unknown) === CharacterController)
 
-/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
+/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule).
+ *  Children of a mover are movers too — buildNodes carries that down, this is the node's own verdict. */
 export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap ?? !movesByPhysics(def)
 
 // `lightmap` undefined = Model.load's own default ('dynamic' while a level with a light volume runs —
@@ -860,7 +871,9 @@ const buildNodes = async (
 ): Promise<void> => {
   const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
 
-  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string): Promise<void> => {
+  // `parentMoves`: a child of a mover moves with it (the body under the hero's capsule) — it never
+  // bakes, whatever its own def says short of an explicit `lightmap: true`
+  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string, parentMoves = false): Promise<void> => {
     // names are path segments — '/' would fork the path, ':' would ambiguate editor card keys
     if (name === "" || name.includes("/") || name.includes(":")) {
       throw new Error(`Scene node name "${name}" is invalid — names are non-empty and contain no '/' or ':'`)
@@ -868,7 +881,7 @@ const buildNodes = async (
     // the path is derived from def keys BEFORE any await, so it is deterministic even though
     // Promise.all makes build completion (and record insertion) order nondeterministic
     const path = parentPath === "" ? name : `${parentPath}/${name}`
-    const lmStatic = lm !== null && !lm.dynamicOnly && isLightmapStatic(nd)
+    const lmStatic = lm !== null && !lm.dynamicOnly && (nd.lightmap ?? (!parentMoves && isLightmapStatic(nd)))
     // a mover in a level with a light volume reads the volume (models: the engine binds it; meshes: registered below)
     const lmDynamic = lm !== null && !lmStatic && lm.volume
     const node = await createSource(path, nd, lmStatic ? true : lmDynamic ? "dynamic" : undefined)
@@ -886,7 +899,7 @@ const buildNodes = async (
     if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/`, volume: lm!.volume } : lm && lm.volume ? { prefix: `${lm.prefix}${path}/`, volume: true, dynamicOnly: true } : null)
     pending.push({ path, node, def: nd })
     nodes[path] = node
-    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path)))
+    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path, parentMoves || (lm !== null && !lmStatic))))
   }
 
   await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent, "")))
@@ -983,7 +996,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   if (lm && lightmap) {
     await Lightmap.load(scene, { data: lightmap.data, texture: lightmap.texture, light: lightmap.light, volume: lightmap.volume },
       { sunStrength: lightmap.sunStrength, ambientScale: lightmap.ambientScale, aoStrength: lightmap.aoStrength,
-        lightBoost: lightmap.lightBoost, volumeBoost: lightmap.volumeBoost })
+        lightBoost: lightmap.lightBoost, volumeBoost: lightmap.volumeBoost, occluderShadows: lightmap.occluderShadows })
   }
   // navigation: load the baked mesh — or, under `lecodes navmesh bake`, dump the level's collision
   // geometry for it (the static bodies exist by now; edit mode never loads it — v1)
@@ -1117,6 +1130,9 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       scene.add(node)
       applyNode(node, p.slice(p.lastIndexOf("/") + 1), d)
       if (isEditMode()) addEditorMarker(node, d)
+      // a prefab wrapper instantiates its file's nodes (same path as buildNodes; no lightmap
+      // context — a patched node is an edit-mode rebuild, baked lighting is the level's business)
+      if (d.prefab !== undefined) await attachPrefab(node, p, d, scene, new Set([ this.def ]), null)
       attachAspects(node, p, d, nodes, scene, this._editorRuns)
       nodes[p] = node
       await Promise.all(Object.entries(d.children ?? {}).map(([ cn, cd ]) => build(`${p}/${cn}`, cd, node)))

package/src/scene/gizmos.ts

@@ -1,148 +1,148 @@
-// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
-// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
-// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
-// currently executing (an ambient scope the scene loader opens around each synchronous call), and
-// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
-// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
-//
-//   rebuild() {
-//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
-//     for (const p of points) Gizmos.cross(p, 0.07)
-//   }
-//
-// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
-// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
-// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
-//
-// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
-// follows the node live — through a gizmo drag, not only after it — with the node's scale
-// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
-// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
-// accent while selected. World-space calls (path lines) are never pickable.
-
-import { Mat4, type Mat4Like } from "../math/mat4"
-import type { Vec3Like } from "../math/vec"
-
-/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
-export type GizmoAnchor = { readonly id: number }
-
-export type GizmoStyle = {
-  /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
-  color?: string
-  /** 0..1, default 1. */
-  alpha?: number
-  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
-   *  live, are pickable (a click selects the node) and turn the selection accent when it is
-   *  selected. Omit for world-space lines (not pickable). */
-  node?: GizmoAnchor | null
-}
-
-/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
- *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
-export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
-
-const DEFAULT_COLOR = "#cfd4dd"
-
-/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
- *  hundred same-colored segments cost one draw. */
-export class GizmoBuffer {
-  batches: GizmoBatch[] = []
-  private _byStyle = new Map<string, GizmoBatch>()
-
-  clear(): void {
-    this.batches = []
-    this._byStyle.clear()
-  }
-
-  segments(style: GizmoStyle | undefined): number[] {
-    const color = style?.color ?? DEFAULT_COLOR
-    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
-    const entityId = style?.node?.id
-    const key = `${color}@${alpha}@${entityId ?? ""}`
-    let b = this._byStyle.get(key)
-    if (!b) {
-      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
-      this._byStyle.set(key, b)
-      this.batches.push(b)
-    }
-    return b.segments
-  }
-}
-
-let current: GizmoBuffer | null = null
-let warnedOutOfScope = false
-
-const xyz = (p: Vec3Like): [number, number, number] =>
-  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
-
-const target = (style: GizmoStyle | undefined): number[] | null => {
-  if (current) return current.segments(style)
-  if (!warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
-    warnedOutOfScope = true
-    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
-  }
-  return null
-}
-
-/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
- *  restore the outer one. */
-export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
-  const prev = current
-  buffer.clear()
-  current = buffer
-  try { return fn() } finally { current = prev }
-}
-
-/**
- * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
- * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
- * off — a path through a wall is still a path); invisible everywhere else.
- */
-export const Gizmos = {
-  /** One segment from `a` to `b`. */
-  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
-    const out = target(style)
-    if (!out) return
-    out.push(...xyz(a), ...xyz(b))
-  },
-
-  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
-  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
-    if (points.length < 2) return
-    const out = target(style)
-    if (!out) return
-    const n = points.length
-    const last = style?.closed ? n : n - 1
-    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
-  },
-
-  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
-   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
-   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
-   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
-  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
-    const out = target(style)
-    if (!out) return
-    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
-    const m = style?.matrix ? new Mat4(style.matrix) : null
-    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
-    const P = (x: number, y: number, zz: number): [number, number, number] => {
-      if (!m) return [ x, y, zz ]
-      const v = m.transformPoint([ x, y, zz ])
-      return [ v.x, v.y, v.z ]
-    }
-    const o = P(0, 0, 0)
-    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
-    for (const q of c) out.push(...o, ...q)
-    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
-    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
-  },
-
-  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
-  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
-    const out = target(style)
-    if (!out) return
-    const [ x, y, z ] = xyz(p)
-    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
-  },
-}
+// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
+// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
+// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
+// currently executing (an ambient scope the scene loader opens around each synchronous call), and
+// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
+// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
+//
+//   rebuild() {
+//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
+//     for (const p of points) Gizmos.cross(p, 0.07)
+//   }
+//
+// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
+// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
+// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
+//
+// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
+// follows the node live — through a gizmo drag, not only after it — with the node's scale
+// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
+// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
+// accent while selected. World-space calls (path lines) are never pickable.
+
+import { Mat4, type Mat4Like } from "../math/mat4"
+import type { Vec3Like } from "../math/vec"
+
+/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
+export type GizmoAnchor = { readonly id: number }
+
+export type GizmoStyle = {
+  /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
+  color?: string
+  /** 0..1, default 1. */
+  alpha?: number
+  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
+   *  live, are pickable (a click selects the node) and turn the selection accent when it is
+   *  selected. Omit for world-space lines (not pickable). */
+  node?: GizmoAnchor | null
+}
+
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
+ *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
+export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
+
+const DEFAULT_COLOR = "#cfd4dd"
+
+/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
+ *  hundred same-colored segments cost one draw. */
+export class GizmoBuffer {
+  batches: GizmoBatch[] = []
+  private _byStyle = new Map<string, GizmoBatch>()
+
+  clear(): void {
+    this.batches = []
+    this._byStyle.clear()
+  }
+
+  segments(style: GizmoStyle | undefined): number[] {
+    const color = style?.color ?? DEFAULT_COLOR
+    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
+    const entityId = style?.node?.id
+    const key = `${color}@${alpha}@${entityId ?? ""}`
+    let b = this._byStyle.get(key)
+    if (!b) {
+      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
+      this._byStyle.set(key, b)
+      this.batches.push(b)
+    }
+    return b.segments
+  }
+}
+
+let current: GizmoBuffer | null = null
+let warnedOutOfScope = false
+
+const xyz = (p: Vec3Like): [number, number, number] =>
+  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
+
+const target = (style: GizmoStyle | undefined): number[] | null => {
+  if (current) return current.segments(style)
+  if (!warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
+    warnedOutOfScope = true
+    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
+  }
+  return null
+}
+
+/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
+ *  restore the outer one. */
+export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
+  const prev = current
+  buffer.clear()
+  current = buffer
+  try { return fn() } finally { current = prev }
+}
+
+/**
+ * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
+ * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
+ * off — a path through a wall is still a path); invisible everywhere else.
+ */
+export const Gizmos = {
+  /** One segment from `a` to `b`. */
+  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    out.push(...xyz(a), ...xyz(b))
+  },
+
+  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
+  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
+    if (points.length < 2) return
+    const out = target(style)
+    if (!out) return
+    const n = points.length
+    const last = style?.closed ? n : n - 1
+    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
+  },
+
+  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
+   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
+   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
+   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
+  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
+    const out = target(style)
+    if (!out) return
+    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
+    const m = style?.matrix ? new Mat4(style.matrix) : null
+    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
+    const P = (x: number, y: number, zz: number): [number, number, number] => {
+      if (!m) return [ x, y, zz ]
+      const v = m.transformPoint([ x, y, zz ])
+      return [ v.x, v.y, v.z ]
+    }
+    const o = P(0, 0, 0)
+    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
+    for (const q of c) out.push(...o, ...q)
+    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
+    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
+  },
+
+  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
+  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    const [ x, y, z ] = xyz(p)
+    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
+  },
+}

package/src/scene/level.ts

@@ -14,8 +14,8 @@
 
 import { Node } from "../gl/Node"
 import { Model } from "../gl/Model"
-import { Shape } from "../gl/Shape"
-import { Physics } from "../gl/Physics"
+import { Shape } from "../gl/physics/Shape"
+import { Physics } from "../gl/physics/Physics"
 import { cx, cy, cz, type Vec3Like } from "../math/vec"
 
 /** One placement handed to a `build` function (all coordinates local to the group). */

package/src/ui/UIImage.ts

@@ -2,6 +2,7 @@ import type { FetchResponse } from "../runtime/fetch"
 import type { SvgSourceValue as SvgSource } from "../runtime/misc"
 import type { File } from "../runtime/fetch"
 import { Canvas, isCanvas } from "../canvas/Canvas"
+import type { Scene2D } from "../g2/Scene2D"
 import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
@@ -10,19 +11,32 @@ export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "
  *  docs/canvas-contract.md ("Pending"). */
 export type CanvasImageSource = { canvasSurface: number }
 
-/** Accepted image sources. A Canvas is baked to a surface marker on assign. */
-export type ImageSource = string | FetchResponse | File | SvgSource | Canvas
+/** A live 2D scene as an image source: the host draws the scene into the node's box every frame
+ *  (the scene's camera, projected into the box). No intrinsic size — give the node a width and
+ *  height. */
+export type Scene2DImageSource = { scene2d: number }
 
-const toSrc = (src: ImageSource): string | FetchResponse | File | SvgSource | CanvasImageSource =>
+/** Accepted image sources. A Canvas is baked to a surface marker on assign; a Scene2D becomes a
+ *  live-scene marker. */
+export type ImageSource = string | FetchResponse | File | SvgSource | Canvas | Scene2D
+
+// An engine object that knows how to present itself as an image source (Scene2D._imageSrc). Duck-typed
+// so the UI layer never imports an engine class — a UI-only bundle carries no engine bridge.
+const hasImageSrc = (v: unknown): v is { _imageSrc(): Scene2DImageSource } =>
+  typeof v === "object" && v !== null && typeof (v as { _imageSrc?: unknown })._imageSrc === "function"
+
+const toSrc = (src: ImageSource): ResolvedImageSource =>
   // _bakeSurfaceForUI (not _bakeSurface) also flags the canvas UI-bound, so canvas.update() later
   // refreshes this image node in place — that's what makes an animated UIImage(canvas) update.
-  isCanvas(src) ? { canvasSurface: src._bakeSurfaceForUI() } : src
+  isCanvas(src) ? { canvasSurface: src._bakeSurfaceForUI() } : hasImageSrc(src) ? src._imageSrc() : src
 
-/** The stored/resolved image source (a Canvas is resolved to a surface marker). */
-export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource
+/** The stored/resolved image source (a Canvas is resolved to a surface marker, a Scene2D to a
+ *  live-scene marker). */
+export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource | Scene2DImageSource
 
 /** An image element. Sources: URL / `asset(...)`, fetch response / File, an SVG source
- *  (`assetIcon`), or a live Canvas (`canvas.update()` refreshes the node in place). */
+ *  (`assetIcon`), a live Canvas (`canvas.update()` refreshes the node in place), or a live Scene2D
+ *  (drawn into the box every frame — a minimap). */
 export interface UIImage extends UIElementBase<UIImageStyle> {
   readonly type: "image",
   /** The image source — writable to swap the picture in place. */

package/dist/types/gl/Gearbox.d.ts

@@ -1,86 +0,0 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import type { Node } from "./Node";
-import type { Vehicle } from "./Vehicle";
-export declare class Gearbox extends Aspect<"gearbox", Node> {
-    static readonly aspect = "gearbox";
-    /** Forward gear ratios, first gear first. Engine RPM = wheel speed × ratio × the differential. */
-    ratios: number[];
-    /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
-    reverse: number;
-    /** Shift up when the engine passes this fraction of its redline. */
-    shiftUp: number;
-    /** Shift down when it falls below this fraction. */
-    shiftDown: number;
-    /** How long a shift takes, in seconds — the clutch is out for this long. */
-    shiftTime: number;
-    /** How long the clutch takes to re-engage afterwards. */
-    clutchTime: number;
-    /** How long to wait after a shift before another is allowed — without it a car sitting on a
-     *  threshold hunts between two gears. */
-    latency: number;
-    /** How far the clutch bites the instant drive is asked for from rest, 0..1. It only has to COUPLE
-     *  the shafts — how much torque that passes is the engine's business, so a feathered throttle
-     *  still pulls away gently at the same bite point. */
-    bite: number;
-    static fields: FieldMeta<Gearbox>;
-    /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
-    gear: number;
-    /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
-    get shifting(): boolean;
-    private _shiftLeft;
-    private _engageLeft;
-    private _waitLeft;
-    private _take;
-    /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
-    updateBefore(dt: number): void;
-    /**
-     * The driver's left foot: where the clutch pedal is, ignoring shifts. Returns the new engagement.
-     *
-     * A driver does not compute anything. They watch the tacho: **revs sinking to idle means the
-     * wheels are about to drag the engine under, and that is when you push the clutch in.** That
-     * single test replaces every ratio and threshold — the crossover it finds is the exact speed where
-     * engine braking stops and the engine would start PUSHING instead, and it finds it per gear
-     * without being told the gear.
-     *
-     * The pedal comes back UP only for the throttle. Healthy revs are not on their own a reason to
-     * engage: a car standing still shows healthy revs too — the wheels simply are not turning to say
-     * otherwise — and a clutch dropped on that evidence lurches the car off with no throttle at all.
-     *
-     * Three things fall out of it for free:
-     *
-     * - **A braked car stops.** The engine cannot stall, so a clutch left in at 0 km/h feeds idle
-     *   torque to the wheels forever and the car creeps against its own brakes. Here the revs pin at
-     *   idle, so the pedal goes down and the brakes have nothing to fight.
-     * - **Reverse is not a special case.** No ratio takes part, so it needs no separate number — which
-     *   is exactly why a fixed road-speed threshold got reverse wrong.
-     * - **Hill starts judder instead of stalling.** Let the pedal out, the load pulls the revs down,
-     *   the rule pushes it straight back in, and the clutch sits slipping at the bite point until the
-     *   car moves. So the test deliberately ignores the throttle — gating it on "no throttle" would
-     *   stall the car under load. Throttle only holds the floor at `bite`.
-     *
-     * The cost is honest and small: once the pedal is down the revs sit at idle and cannot rise on
-     * their own, so **coasting downhill gives no engine braking until you touch the throttle** — which
-     * is precisely what a car with the clutch in does. Slipping it permanently to keep listening would
-     * bring the creep straight back.
-     */
-    protected takeUp(v: Vehicle, dt: number): number;
-    /**
-     * Which gear the car should be in. The default is an ordinary automatic: pull away from neutral in
-     * the direction of the throttle, shift up past `shiftUp` of the redline and down below `shiftDown`,
-     * and refuse to shift again for `latency` seconds. Override this and nothing else.
-     */
-    select(v: Vehicle): number;
-    /** Change gear now, with the clutch envelope. Safe to call from `select()` or from game code
-     *  (a sequential manual is `if (Input.key('KeyE')) car.gearbox.shift(car.gearbox.gear + 1)`). */
-    shift(gear: number): void;
-    /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
-    get ratio(): number;
-    /**
-     * The clutch scalar 0..1 the engine is given: the SHIFT envelope (out during a shift, ramping back
-     * over `clutchTime`) times the driver's pedal (`takeUp`). Two independent reasons for the clutch
-     * to be out, so they multiply: mid-shift is out however healthy the revs are, and an engine being
-     * dragged to idle is out whatever gear it just picked.
-     */
-    get clutch(): number;
-}