lecodes-sdk 2.4.10 → 2.5.0

package/src/gl/Statics.ts

@@ -0,0 +1,301 @@
+// THE STATIC LEVEL CACHE — the SDK half of creator-gl/src/statics.cpp (the file format: ./staticsFormat.ts).
+//
+// A level's STATICS (the nodes that never move once loaded: what the bake sees) are built the slow way exactly
+// once — a JS node per placement, a clone per node, a bake record bound per primitive — and then SNAPSHOTTED
+// into one binary beside the level's `.bake` (`<level>.static`, written by `lecodes level build`). The next
+// `load()` of the same level fetches that file, checks its digests against the ones it derives from the scene's
+// defs and the bake, and rebuilds the statics natively: the JS loads ONE template per kind and the engine clones
+// it at every placement, binds the records and creates the static bodies — no node, no aspect, no path string
+// per placement in JS. The dynamic nodes of the level (the spawn, the lamps with behaviour, the terrain) build
+// as they always did, beside the one JS node each covered root keeps.
+//
+// WHAT IS COVERED. `coveredRoots` picks the maximal subtrees whose every node is static data: a `model` or a
+// plain node, a `prefab` whose file is all such nodes, with nothing but `Shape` / `Physics { motion: 'static' }`
+// aspects, no `make`, no `mesh`, no `terrain`, no `light`, no model `overrides`, no foliage fade. `static: false`
+// anywhere keeps the node — and the subtree above it — out. The search descends through `children` and through
+// a prefab's own nodes (an imported scene is one prefab holding its terrain beside the groups of placements: the
+// groups are the roots), so a level has as many roots as it has such subtrees; the cache keeps them all, in order.
+//
+// THE DIGESTS: `defs` (two 32-bit hashes over a canonical JSON of the covered defs — a placement moved, a kind
+// swapped) and `bake` (the bake's identity — a rebake). Either mismatch declines the cache with a log line and the
+// level loads the slow way until `lecodes level build` runs again. Assets' CONTENTS are not in them (a GLB
+// re-exported under the same name): that is the compiler's digest, a later step. Kinds are keyed by their STABLE
+// asset name (runtime/fetch.ts assetNameOf): an "id:" url is this run's only.
+
+import { fetch, assetNameOf, assetUrlOf, type FetchResponse } from "../runtime/fetch"
+import { Model, foliageKindOf, type FoliageKind } from "./Model"
+import { Node } from "./Node"
+import { Scene } from "./Scene"
+import { Physics } from "./physics/Physics"
+import { Shape } from "./physics/Shape"
+import { CharacterController } from "./physics/CharacterController"
+import type { SceneDef, SceneNodeDef } from "../scene/defineScene"
+import type { AspectEntry } from "../scene/grammar"
+import type { BakeData } from "./Lightmap"
+import { ShapeKind, NONE, bakeDigest, decode, encode, hash64, readHeader, recordsByPath, type Digest, type StaticKind, type StaticPlacement, type StaticRecord } from "./staticsFormat"
+
+export { bakeDigest, type Digest } from "./staticsFormat"
+
+/** `lecodes level build` runs the app with this on `globalThis.__lecodesStatic`: the project root the snapshot is written under. */
+export type StaticsConfig = { root: string }
+export const staticsConfig = (): StaticsConfig | null => {
+  const g = (globalThis as unknown as { __lecodesStatic?: StaticsConfig }).__lecodesStatic
+  return g && typeof g.root === "string" ? g : null
+}
+/** True under any of the CLI's tool runs that must see the level the slow, complete way (the bakes, the snapshot). */
+export const toolRun = (): boolean => {
+  const g = globalThis as unknown as Record<string, unknown>
+  return !!g.__lecodesLightmap || !!g.__lecodesNavmesh || !!g.__lecodesStatic
+}
+
+export type CoveredRoot = { path: string, def: SceneNodeDef }
+
+// ---- the rule ---------------------------------------------------------------------------------------------
+
+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) === CharacterController)
+
+const dataAspect = (e: AspectEntry<any>): boolean => {
+  const c = e.ctor as unknown
+  if (c === Shape) return true
+  if (c === Physics) return ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") === "static"
+  return false
+}
+
+const cacheable = (def: SceneNodeDef, stack: Set<SceneDef>): boolean => {
+  if (def.static !== undefined ? !def.static : movesByPhysics(def)) return false
+  if (def.mesh !== undefined || def.terrain !== undefined || def.light !== undefined || def.camera !== undefined || def.make !== undefined) return false
+  if (def.overrides !== undefined) return false
+  if (typeof def.foliage === "object") return false
+  if ((def.aspects ?? []).some((e) => !dataAspect(e))) return false
+  if (def.prefab !== undefined) {
+    const pdef = (def.prefab as { def?: SceneDef }).def
+    if (!pdef || typeof pdef !== "object" || stack.has(pdef)) return false
+    const inner = new Set(stack).add(pdef)
+    for (const nd of Object.values(pdef.nodes ?? {})) if (!cacheable(nd, inner)) return false
+  }
+  for (const nd of Object.values(def.children ?? {})) if (!cacheable(nd, stack)) return false
+  return true
+}
+
+/** The maximal cacheable subtrees among `defs`, depth first: through `children`, and through a prefab's nodes
+ *  (paths run through the prefab's path, as the bake's keys do). */
+export const coveredRoots = (defs: Record<string, SceneNodeDef> | undefined, scene: SceneDef): CoveredRoot[] => {
+  const out: CoveredRoot[] = []
+  const walk = (ds: Record<string, SceneNodeDef> | undefined, prefix: string, stack: Set<SceneDef>): void => {
+    for (const [ name, nd ] of Object.entries(ds ?? {})) {
+      const path = prefix === "" ? name : `${prefix}/${name}`
+      if (cacheable(nd, stack)) { out.push({ path, def: nd }); continue }
+      const pdef = nd.prefab !== undefined ? (nd.prefab as { def?: SceneDef }).def : undefined
+      if (pdef && !stack.has(pdef)) walk(pdef.nodes, path, new Set(stack).add(pdef))
+      walk(nd.children, path, stack)
+    }
+  }
+  walk(defs, "", new Set<SceneDef>([ scene ]))
+  return out
+}
+
+type ModelPartRow = { path: string, node: Node }
+
+/** The live node at a full path: a top-level entry of the record, or a prefab internal reached through its
+ *  wrapper's part rows (the record only keys the top level; internals live in the wrapper's `_prefabParts`). */
+export const findNode = (nodes: Record<string, Node>, path: string): Node | null => {
+  const direct = nodes[path]
+  if (direct) return direct
+  for (let cut = path.lastIndexOf("/"); cut > 0; cut = path.lastIndexOf("/", cut - 1)) {
+    const wrapper = nodes[path.slice(0, cut)]
+    if (!wrapper) continue
+    const rows = (wrapper as { _prefabParts?: ModelPartRow[] })._prefabParts
+    if (!rows) return null
+    const rel = path.slice(cut + 1)
+    const row = rows.find((r) => r.path === rel)
+    return row ? row.node : null
+  }
+  return null
+}
+
+// ---- the defs digest --------------------------------------------------------------------------------------
+
+const canonical = (def: SceneNodeDef, stack: Set<SceneDef>): unknown => {
+  const o: Record<string, unknown> = {}
+  if (def.model !== undefined) o.m = assetNameOf(String(def.model))   // the staged name: an "id:" url is this run's only
+  if (def.position !== undefined) o.p = def.position
+  if (def.eulerAngles !== undefined) o.e = def.eulerAngles
+  if (def.scale !== undefined) o.s = def.scale
+  if (def.visible !== undefined) o.v = def.visible
+  if (def.castShadows !== undefined) o.c = def.castShadows
+  if (def.receiveShadows !== undefined) o.r = def.receiveShadows
+  if (def.foliage !== undefined) o.f = def.foliage
+  if (def.lightmap !== undefined) o.l = def.lightmap
+  if (def.static !== undefined) o.st = def.static
+  if (def.aspects?.length) o.a = def.aspects.map((e) => [ (e.ctor as { name?: string }).name ?? "?", e.props ?? null ])
+  if (def.prefab !== undefined) {
+    const pdef = (def.prefab as { def?: SceneDef }).def
+    if (pdef && !stack.has(pdef)) {
+      const inner = new Set(stack).add(pdef)
+      o.pf = Object.fromEntries(Object.entries(pdef.nodes ?? {}).map(([ k, v ]) => [ k, canonical(v, inner) ]))
+    }
+  }
+  if (def.children) o.ch = Object.fromEntries(Object.entries(def.children).map(([ k, v ]) => [ k, canonical(v, stack) ]))
+  return o
+}
+
+/** The digest of the covered defs — what a snapshot's placements were made from. */
+export const defsDigest = (roots: CoveredRoot[], scene: SceneDef): Digest => {
+  const stack = new Set<SceneDef>([ scene ])
+  return hash64(JSON.stringify(roots.map((r) => [ r.path, canonical(r.def, stack) ])))
+}
+
+// ---- the snapshot -----------------------------------------------------------------------------------------
+
+/** Every def node under a covered root with its live node: `children` and prefab internals alike (the wrapper's
+ *  `_prefabParts` rows carry the internals' nodes; their defs come from the prefab's file, by the same path). */
+const collect = (root: CoveredRoot, rootNode: Node, scene: SceneDef, out: { path: string, def: SceneNodeDef, node: Node }[]): void => {
+  const defsOf = (defs: Record<string, SceneNodeDef> | undefined, prefix: string, stack: Set<SceneDef>, into: Map<string, SceneNodeDef>): void => {
+    for (const [ name, nd ] of Object.entries(defs ?? {})) {
+      const path = prefix === "" ? name : `${prefix}/${name}`
+      into.set(path, nd)
+      defsOf(nd.children, path, stack, into)
+      const pdef = nd.prefab !== undefined ? (nd.prefab as { def?: SceneDef }).def : undefined
+      if (pdef && !stack.has(pdef)) defsOf(pdef.nodes, path, new Set(stack).add(pdef), into)
+    }
+  }
+  const walk = (path: string, def: SceneNodeDef, node: Node, stack: Set<SceneDef>): void => {
+    out.push({ path, def, node })
+    if (def.prefab !== undefined) {
+      const rows = (node as { _prefabParts?: ModelPartRow[] })._prefabParts ?? []
+      const pdef = (def.prefab as { def?: SceneDef }).def
+      const defs = new Map<string, SceneNodeDef>()
+      if (pdef) defsOf(pdef.nodes, "", new Set(stack).add(pdef), defs)
+      for (const r of rows) {
+        const d = defs.get(r.path)
+        if (d) out.push({ path: `${path}/${r.path}`, def: d, node: r.node })   // a GLB's internal parts have no def: skipped
+      }
+      return
+    }
+    // the live children by name ONCE per parent: `node.children` and `.name` are bridge calls each, and a root of
+    // two thousand placements looked each child up by scanning them all (Chernobyl's snapshot: 9 minutes, 2026-11-03)
+    const byName = new Map<string, Node>()
+    for (const c of node.children) byName.set(c.name, c)
+    for (const [ name, nd ] of Object.entries(def.children ?? {})) {
+      const child = byName.get(name)
+      if (child) walk(`${path}/${name}`, nd, child, stack)
+    }
+  }
+  walk(root.path, root.def, rootNode, new Set([ scene ]))
+}
+
+const shapeOf = (def: SceneNodeDef): { kind: ShapeKind, params: number[] } => {
+  let shape: AspectEntry<any> | undefined, body: AspectEntry<any> | undefined
+  for (const e of def.aspects ?? []) {
+    if ((e.ctor as unknown) === Shape) shape = e
+    else if ((e.ctor as unknown) === Physics) body = e
+  }
+  if (!shape || !body) return { kind: ShapeKind.None, params: [] }
+  const p = (shape.props ?? {}) as { mesh?: boolean | "convex", box?: number[], sphere?: number, cylinder?: { halfHeight: number, radius: number }, capsule?: { halfHeight: number, radius: number }, heightfield?: boolean, origin?: number[] }
+  if (p.heightfield) return { kind: ShapeKind.None, params: [] }
+  const origin = p.origin ?? [ 0, 0, 0 ]
+  if (p.mesh === "convex") return { kind: ShapeKind.Convex, params: [ ...origin ] }
+  if (p.mesh) return { kind: ShapeKind.Mesh, params: [ ...origin ] }
+  if (p.sphere !== undefined) return { kind: ShapeKind.Sphere, params: [ p.sphere, ...origin ] }
+  if (p.cylinder) return { kind: ShapeKind.Cylinder, params: [ p.cylinder.halfHeight, p.cylinder.radius, ...origin ] }
+  if (p.capsule) return { kind: ShapeKind.Capsule, params: [ p.capsule.halfHeight, p.capsule.radius, ...origin ] }
+  if (p.box) return { kind: ShapeKind.Box, params: [ p.box[0], p.box[1], p.box[2], ...origin ] }
+  return { kind: ShapeKind.AutoBox, params: [ ...origin ] }
+}
+
+/** The snapshot of the covered roots' subtrees as they stand: the bytes `lecodes level build` writes. `bake` = the
+ *  data the level is bound to (its records go in, joined by path), null = an unbaked level (placements and bodies
+ *  only; the CLI stitches the records in after the bake). */
+export const snapshot = (roots: { root: CoveredRoot, node: Node }[], scene: SceneDef, bake: BakeData | null, defs: Digest): { bytes: Uint8Array, kinds: number, placements: number, records: number } => {
+  const byPath = bake ? recordsByPath(bake.instances) : new Map<string, StaticRecord[]>()
+  const kinds: StaticKind[] = []
+  const kindIndex = new Map<string, number>()
+  const placements: StaticPlacement[] = []
+  roots.forEach(({ root, node }, rootIndex) => {
+    const entries: { path: string, def: SceneNodeDef, node: Node }[] = []
+    collect(root, node, scene, entries)
+    const rootInv = node.worldMatrix.invert()
+    for (const e of entries) {
+      const def = e.def   // the root itself is a placement too when it carries a model (at identity under its JS node)
+      let kind = NONE
+      if (def.model !== undefined) {
+        const name = assetNameOf(String(def.model))
+        const foliage = foliageKindOf(def.foliage)   // a covered model is a lightmap static unless it is foliage (the foliage tier)
+        const key = `${foliage || "l"}|${name}`
+        let k = kindIndex.get(key)
+        if (k === undefined) { k = kinds.length; kinds.push({ name, lightmap: !foliage, foliage }); kindIndex.set(key, k) }
+        kind = k
+      }
+      const sh = shapeOf(def)
+      if (kind === NONE && sh.kind === ShapeKind.None) continue   // a bare wrapper: nothing to rebuild
+      const { position, rotation, scale } = rootInv.mul(e.node.worldMatrix).decompose()
+      placements.push({
+        kind, path: e.path, root: rootIndex,
+        pos: [ position.x, position.y, position.z ], quat: [ rotation.x, rotation.y, rotation.z, rotation.w ], scale: [ scale.x, scale.y, scale.z ],
+        castShadows: def.castShadows ?? true, receiveShadows: def.receiveShadows ?? true,
+        shape: sh.kind, params: sh.params,
+        records: byPath.get(e.path) ?? [],
+      })
+    }
+  })
+  const bytes = encode({ defs, bake: bakeDigest(bake), kinds, placements })
+  return { bytes, kinds: kinds.length, placements: placements.length, records: placements.reduce((n, p) => n + p.records.length, 0) }
+}
+
+// ---- the cached load --------------------------------------------------------------------------------------
+
+export type OpenedCache = { resp: FetchResponse, kinds: { url: string, lightmap: boolean, foliage: FoliageKind }[], placements: number, roots: number }
+
+/** Fetch the level's cache and check it against the digests; null = absent, not a cache, or stale (the why logged). */
+export const open = async (url: string, defs: Digest, bake: Digest): Promise<OpenedCache | null> => {
+  if (!_creator.staticsBegin) return null
+  let resp: FetchResponse
+  try {
+    resp = await fetch(url, { useOnce: true })
+  } catch (e) {
+    console.warn(`[static] could not read ${url}: ${String(e)} — building the level the slow way`)
+    return null
+  }
+  if (resp.status >= 400) { console.log(`[static] no cache at ${url} (HTTP ${resp.status}) — building the level the slow way; \`lecodes level build\` writes one`); return null }
+  const bytes = resp.bytes()
+  const h = readHeader(bytes)
+  if (!h) { console.warn(`[static] ${url} is not a level cache (or an older one) — building the level the slow way; rerun \`lecodes level build\``); return null }
+  if (h.defs[0] !== defs[0] || h.defs[1] !== defs[1]) {
+    console.log(`[static] ${url} is stale (the scene's statics changed since \`lecodes level build\`) — building the level the slow way`)
+    return null
+  }
+  if (h.bake[0] !== bake[0] || h.bake[1] !== bake[1]) {
+    console.log(`[static] ${url} is stale (the bake changed since \`lecodes level build\`) — building the level the slow way`)
+    return null
+  }
+  const file = decode(bytes)
+  if (!file) { console.warn(`[static] ${url} is cut short — building the level the slow way; rerun \`lecodes level build\``); return null }
+  let roots = 0
+  for (const p of file.placements) roots = Math.max(roots, p.root + 1)
+  return { resp, kinds: file.kinds.map((k) => ({ url: assetUrlOf(k.name), lightmap: k.lightmap, foliage: k.foliage })), placements: file.placements.length, roots }
+}
+
+/** The kinds' templates, kept for the level's life (a template is the asset every clone shares). */
+const templates: Model[] = []
+
+/** Build the opened cache under `roots` (the covered roots' JS nodes, in the snapshot's order) in `scene`: the
+ *  templates load through `template` (one per kind, as the level's slow path would load them), the engine clones
+ *  each at its placements as it resolves. `pages` = the bake's light/aux texture ids interleaved (empty = no bake
+ *  bound). Resolves to the placements made. */
+export const build = async (
+  opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array,
+  template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>,
+): Promise<number> => {
+  const sceneId = (scene as unknown as { _id: number })._id
+  const kinds = _creator.staticsBegin!(sceneId, Uint32Array.from(roots.map((r) => r.id)), (opened.resp as unknown as { _h: { id: number } })._h.id)
+  if (kinds !== opened.kinds.length) { console.warn(`[static] the engine declined the cache (${kinds} of ${opened.kinds.length} kinds)`); _creator.staticsEnd!(); return 0 }
+  await Promise.all(opened.kinds.map(async (k, i) => {
+    const t = await template(k.url, k.lightmap, k.foliage)
+    templates.push(t)
+    _creator.staticsBuildKind!(i, t.id, pages)
+  }))
+  return _creator.staticsEnd!()   // every placement: the kinds' clones and the body-only ones staticsBegin built
+}

package/src/gl/nav/NavMesh.ts

@@ -19,6 +19,7 @@
 // fixed step for every agent in the scene (`NavCrowd`, a system the mesh attaches to its scene).
 
 import { fetch } from "../../runtime/fetch"
+import { assetNameOf } from "../../runtime/fetch"
 import { System } from "../../core/Aspect"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
 import { Geometry } from "../Geometry"
@@ -390,7 +391,9 @@ export class NavMesh {
     if (n === 0) { console.error("[navmesh] error: no static collision geometry — agents walk on STATIC Physics bodies (Shape + Physics { motion: 'static' })"); return }
     const agent = { radius: opts.agent?.radius ?? 0.4, height: opts.agent?.height ?? 1.8, climb: opts.agent?.climb ?? 0.4, slope: opts.agent?.slope ?? 50 }
     console.log(`[navmesh] geometry ${n} triangles → ${path}`)
-    console.log(`[navmesh] config ${JSON.stringify({ agent, areas: areaIds, costs: opts.areas ?? {}, data: opts.data })}`)
+    // `data` by its STABLE name (runtime/fetch.ts): an "id:" url is this run's; `lecodes level build` writes the mesh where the
+    // scene's own file is
+    console.log(`[navmesh] config ${JSON.stringify({ agent, areas: areaIds, costs: opts.areas ?? {}, data: opts.data ? assetNameOf(opts.data) : undefined })}`)
     console.log("[navmesh] done")
   }
 }

package/src/gl/staticsFormat.ts

@@ -0,0 +1,240 @@
+// THE STATIC LEVEL CACHE'S FILE FORMAT — pure data, no runtime: the SDK writes and reads it in the app (gl/Statics.ts),
+// the CLI reads and rewrites it in Bun (`lecodes level build` stitches a fresh bake's records in without a host run).
+// creator-gl/src/statics.cpp is the third reader; its header comment is the same spec.
+//
+//   header      magic 'LCST', version 2, defs digest lo/hi, bake digest lo/hi, kinds, placements, records, floats,
+//               string bytes                                                                    (11 words)
+//   kinds       [nameStr, flags, 0, 0]                           flags: bit0 lightmapped, bit1 foliage, bit2 grass (the
+//                                                                 foliage kind: ground cover; else a crown)
+//   placements  [kind | NONE, pathStr, pos xyz, quat xyzw, scale xyz, flags, shapeKind, shapeOff, recFirst, recCount,
+//                root, 0, 0]                                     flags: bit0 castShadows, bit1 receiveShadows
+//   records     [ordinal, page | OBJECT, st0, st1, st2, st3]     OBJECT: st0 = floats offset, st1 = float count
+//   floats      shape parameters (by shapeKind, then origin xyz), object-light slabs
+//   strings     NUL-terminated UTF-8, indexed by byte offset
+//
+// Every word is 32 bits, floats bit-cast, little-endian. The two digests are what makes the file safe to trust:
+// `defs` covers the scene's covered defs (a placement moved, a kind swapped), `bake` the bake the records came from
+// (a rebake); the app compares both with what it derives and declines a mismatch. The CLI restamps `bake` when it
+// stitches records, and leaves `defs` alone: a snapshot's placements are only ever written by the app.
+
+import type { FoliageKind } from "./Model"
+
+export const MAGIC = 0x5453434C, VERSION = 2, NONE = 0xFFFFFFFF
+export const HEADER = 11, KIND = 4, PLACEMENT = 20, RECORD = 6
+export const ShapeKind = { None: 0, Mesh: 1, Convex: 2, Box: 3, Sphere: 4, Cylinder: 5, Capsule: 6, AutoBox: 7 } as const
+export type ShapeKind = number
+
+export type Digest = [number, number]
+export type StaticKind = { name: string, lightmap: boolean, foliage: FoliageKind }
+/** A record: a rect (`page` + `st`) or an object light (`page === NONE`, `slabs` = the floats lightmapObjectApply takes). */
+export type StaticRecord = { ordinal: number, page: number, st?: number[], slabs?: number[] }
+export type StaticPlacement = {
+  kind: number, path: string, root: number
+  pos: number[], quat: number[], scale: number[]
+  castShadows: boolean, receiveShadows: boolean
+  shape: ShapeKind, params: number[]
+  records: StaticRecord[]
+}
+export type StaticsFile = { defs: Digest, bake: Digest, kinds: StaticKind[], placements: StaticPlacement[] }
+
+/** Two independent 32-bit hashes over `s` (FNV-1a and a multiplicative xor mix), chained from `seed`: 64 bits of
+ *  "did this change", which is all a header needs. */
+export const hash64 = (s: string, seed: Digest = [ 0x811c9dc5, 0x9747b28c ]): Digest => {
+  let a = seed[0] >>> 0, b = seed[1] >>> 0
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    a = Math.imul(a ^ c, 0x01000193) >>> 0
+    b = (Math.imul(b, 0x5bd1e995) ^ c ^ (b >>> 13)) >>> 0
+  }
+  return [ a, b ]
+}
+export const NO_BAKE: Digest = hash64("none")
+
+/** The bake's identity as the cache keys it: what a rebake changes. `bake` is the `.bake` JSON. */
+export const bakeDigest = (bake: { size: number, pages: number, texel: number, texels?: number, instances: unknown[], uv1?: string | null } | null): Digest =>
+  bake ? hash64(`${bake.size}|${bake.pages}|${bake.texel}|${bake.texels ?? 0}|${bake.instances.length}|${bake.uv1 ?? ""}`) : NO_BAKE
+
+// ---- the bake's records for a placement ------------------------------------------------------------------
+
+/** What a `.bake` instance carries that the cache keeps (the SDK's BakeInstance, structurally). */
+export type BakeRecordSource = {
+  key: string, receiver: boolean, small?: boolean, page?: number, st?: number[]
+  light?: { axis: number, from: number, to: number, cubes: number[][][], probes: number[] }
+}
+
+const probeId = (k: number): number => k === -2 ? 65534 : k < 0 ? 65535 : k
+
+/** The records of every bake instance keyed by node PATH (`<path>@<ordinal>` and whole-node `<path>` alike), in the
+ *  shape the cache stores — the same join the runtime makes when it binds a bake the slow way. */
+export const recordsByPath = (instances: BakeRecordSource[]): Map<string, StaticRecord[]> => {
+  const out = new Map<string, StaticRecord[]>()
+  for (const inst of instances) {
+    const m = /^(.*)@(\d+)$/.exec(inst.key)
+    const path = m ? m[1] : inst.key
+    const ordinal = m ? Number(m[2]) : -1
+    let rec: StaticRecord | null = null
+    if (inst.receiver && inst.st && inst.page !== undefined) rec = { ordinal, page: inst.page, st: inst.st.slice(0, 4) }
+    else if (inst.small && inst.light && Array.isArray(inst.light.cubes)) {
+      const l = inst.light
+      rec = { ordinal, page: NONE, slabs: [ l.axis, l.from, l.to, l.cubes.length, ...l.cubes.flat(2), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ] }
+    }
+    if (!rec) continue
+    let g = out.get(path)
+    if (!g) { g = []; out.set(path, g) }
+    g.push(rec)
+  }
+  return out
+}
+
+// ---- encode / decode ------------------------------------------------------------------------------------
+
+const utf8Length = (s: string): number => {
+  let n = 0
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    n += c < 0x80 ? 1 : c < 0x800 ? 2 : (c >= 0xd800 && c < 0xdc00) ? (i++, 4) : 3
+  }
+  return n
+}
+const utf8Write = (b: Uint8Array, at: number, s: string): number => {
+  const start = at
+  for (let i = 0; i < s.length; i++) {
+    let c = s.charCodeAt(i)
+    if (c >= 0xd800 && c < 0xdc00 && i + 1 < s.length) c = 0x10000 + ((c - 0xd800) << 10) + (s.charCodeAt(++i) - 0xdc00)
+    if (c < 0x80) b[at++] = c
+    else if (c < 0x800) { b[at++] = 0xc0 | (c >> 6); b[at++] = 0x80 | (c & 63) }
+    else if (c < 0x10000) { b[at++] = 0xe0 | (c >> 12); b[at++] = 0x80 | ((c >> 6) & 63); b[at++] = 0x80 | (c & 63) }
+    else { b[at++] = 0xf0 | (c >> 18); b[at++] = 0x80 | ((c >> 12) & 63); b[at++] = 0x80 | ((c >> 6) & 63); b[at++] = 0x80 | (c & 63) }
+  }
+  return at - start
+}
+const utf8Read = (b: Uint8Array, from: number, to: number): string => {
+  let s = ""
+  for (let i = from; i < to;) {
+    const c = b[i++]
+    if (c < 0x80) s += String.fromCharCode(c)
+    else if (c < 0xe0) s += String.fromCharCode(((c & 31) << 6) | (b[i++] & 63))
+    else if (c < 0xf0) s += String.fromCharCode(((c & 15) << 12) | ((b[i++] & 63) << 6) | (b[i++] & 63))
+    else { const cp = ((c & 7) << 18) | ((b[i++] & 63) << 12) | ((b[i++] & 63) << 6) | (b[i++] & 63); s += String.fromCodePoint(cp) }
+  }
+  return s
+}
+
+/** The file's bytes for `f`. */
+export const encode = (f: StaticsFile): Uint8Array => {
+  // the strings, interned BEFORE the buffer is sized (the header carries their byte count)
+  const offsets = new Map<string, number>()
+  const strings: string[] = []
+  let stringBytes = 0
+  const intern = (s: string): number => {
+    let off = offsets.get(s)
+    if (off === undefined) { off = stringBytes; offsets.set(s, off); strings.push(s); stringBytes += utf8Length(s) + 1 }
+    return off
+  }
+  for (const k of f.kinds) intern(k.name)
+  for (const p of f.placements) intern(p.path)
+  // the floats: per placement its shape parameters, then its object-light slabs
+  const floats: number[] = []
+  const shapeOff: number[] = []
+  const slabOff = new Map<StaticRecord, number>()
+  for (const p of f.placements) {
+    shapeOff.push(floats.length)
+    floats.push(...p.params)
+    for (const r of p.records) if (r.page === NONE && r.slabs) { slabOff.set(r, floats.length); floats.push(...r.slabs) }
+  }
+  const recordCount = f.placements.reduce((n, p) => n + p.records.length, 0)
+  const stringWords = (stringBytes + 3) >> 2
+  const words = HEADER + f.kinds.length * KIND + f.placements.length * PLACEMENT + recordCount * RECORD + floats.length + stringWords
+  const buf = new ArrayBuffer(words * 4)
+  const u = new Uint32Array(buf), fl = new Float32Array(buf), b = new Uint8Array(buf)
+  u[0] = MAGIC; u[1] = VERSION; u[2] = f.defs[0]; u[3] = f.defs[1]; u[4] = f.bake[0]; u[5] = f.bake[1]
+  u[6] = f.kinds.length; u[7] = f.placements.length; u[8] = recordCount; u[9] = floats.length; u[10] = stringBytes
+  let w = HEADER
+  for (const k of f.kinds) { u[w] = intern(k.name); u[w + 1] = (k.lightmap ? 1 : 0) | (k.foliage ? 2 : 0) | (k.foliage === "grass" ? 4 : 0); u[w + 2] = 0; u[w + 3] = 0; w += KIND }
+  const recBase = HEADER + f.kinds.length * KIND + f.placements.length * PLACEMENT
+  let rec = 0
+  f.placements.forEach((p, i) => {
+    u[w] = p.kind; u[w + 1] = intern(p.path)
+    fl[w + 2] = p.pos[0]; fl[w + 3] = p.pos[1]; fl[w + 4] = p.pos[2]
+    fl[w + 5] = p.quat[0]; fl[w + 6] = p.quat[1]; fl[w + 7] = p.quat[2]; fl[w + 8] = p.quat[3]
+    fl[w + 9] = p.scale[0]; fl[w + 10] = p.scale[1]; fl[w + 11] = p.scale[2]
+    u[w + 12] = (p.castShadows ? 1 : 0) | (p.receiveShadows ? 2 : 0); u[w + 13] = p.shape; u[w + 14] = shapeOff[i]
+    u[w + 15] = rec; u[w + 16] = p.records.length; u[w + 17] = p.root; u[w + 18] = 0; u[w + 19] = 0
+    for (const r of p.records) {
+      const at = recBase + rec * RECORD
+      u[at] = r.ordinal >>> 0; u[at + 1] = r.page >>> 0
+      if (r.page === NONE) { u[at + 2] = slabOff.get(r) ?? 0; u[at + 3] = r.slabs?.length ?? 0; u[at + 4] = 0; u[at + 5] = 0 }
+      else { const st = r.st ?? [ 0, 0, 0, 0 ]; fl[at + 2] = st[0]; fl[at + 3] = st[1]; fl[at + 4] = st[2]; fl[at + 5] = st[3] }
+      rec++
+    }
+    w += PLACEMENT
+  })
+  const floatBase = recBase + recordCount * RECORD
+  for (let i = 0; i < floats.length; i++) fl[floatBase + i] = floats[i]
+  let at = (floatBase + floats.length) * 4
+  for (const s of strings) { at += utf8Write(b, at, s); b[at++] = 0 }
+  return b
+}
+
+/** The header alone: null when `bytes` is not a cache of this version. */
+export const readHeader = (bytes: Uint8Array): { defs: Digest, bake: Digest, kinds: number, placements: number, records: number, floats: number, stringBytes: number } | null => {
+  if (bytes.length < HEADER * 4 || (bytes.byteOffset & 3) !== 0) return null
+  const u = new Uint32Array(bytes.buffer, bytes.byteOffset, HEADER)
+  if (u[0] !== MAGIC || u[1] !== VERSION) return null
+  return { defs: [ u[2], u[3] ], bake: [ u[4], u[5] ], kinds: u[6], placements: u[7], records: u[8], floats: u[9], stringBytes: u[10] }
+}
+
+const shapeParamCount = (kind: ShapeKind): number =>
+  kind === ShapeKind.Box ? 6 : kind === ShapeKind.Sphere ? 4 : kind === ShapeKind.Cylinder || kind === ShapeKind.Capsule ? 5 : kind === ShapeKind.None ? 0 : 3
+
+/** The whole file as data: null when it is not one. */
+export const decode = (bytes: Uint8Array): StaticsFile | null => {
+  const h = readHeader(bytes)
+  if (!h) return null
+  const words = HEADER + h.kinds * KIND + h.placements * PLACEMENT + h.records * RECORD + h.floats + ((h.stringBytes + 3) >> 2)
+  if (bytes.length < words * 4) return null
+  const u = new Uint32Array(bytes.buffer, bytes.byteOffset, words), fl = new Float32Array(bytes.buffer, bytes.byteOffset, words)
+  const stringBase = (HEADER + h.kinds * KIND + h.placements * PLACEMENT + h.records * RECORD + h.floats) * 4
+  const str = (off: number): string => {
+    let end = stringBase + off
+    while (end < bytes.length && bytes[end] !== 0) end++
+    return utf8Read(bytes, stringBase + off, end)
+  }
+  const floatBase = HEADER + h.kinds * KIND + h.placements * PLACEMENT + h.records * RECORD
+  const kinds: StaticKind[] = []
+  for (let k = 0; k < h.kinds; k++) {
+    const at = HEADER + k * KIND
+    kinds.push({ name: str(u[at]), lightmap: (u[at + 1] & 1) !== 0, foliage: (u[at + 1] & 2) === 0 ? false : (u[at + 1] & 4) !== 0 ? "grass" : "tree" })
+  }
+  const recBase = HEADER + h.kinds * KIND + h.placements * PLACEMENT
+  const placements: StaticPlacement[] = []
+  for (let i = 0; i < h.placements; i++) {
+    const w = HEADER + h.kinds * KIND + i * PLACEMENT
+    const shape = u[w + 13]
+    const records: StaticRecord[] = []
+    for (let r = u[w + 15], end = u[w + 15] + u[w + 16]; r < end; r++) {
+      const at = recBase + r * RECORD
+      const ordinal = u[at] | 0, page = u[at + 1]
+      if (page === NONE) records.push({ ordinal, page, slabs: Array.from(fl.subarray(floatBase + u[at + 2], floatBase + u[at + 2] + u[at + 3])) })
+      else records.push({ ordinal, page, st: [ fl[at + 2], fl[at + 3], fl[at + 4], fl[at + 5] ] })
+    }
+    placements.push({
+      kind: u[w], path: str(u[w + 1]), root: u[w + 17],
+      pos: [ fl[w + 2], fl[w + 3], fl[w + 4] ], quat: [ fl[w + 5], fl[w + 6], fl[w + 7], fl[w + 8] ], scale: [ fl[w + 9], fl[w + 10], fl[w + 11] ],
+      castShadows: (u[w + 12] & 1) !== 0, receiveShadows: (u[w + 12] & 2) !== 0,
+      shape, params: Array.from(fl.subarray(floatBase + u[w + 14], floatBase + u[w + 14] + shapeParamCount(shape))),
+      records,
+    })
+  }
+  return { defs: h.defs, bake: h.bake, kinds, placements }
+}
+
+/** `f` with its records replaced by `bake`'s (joined by placement path) and its bake digest restamped — what
+ *  `lecodes level build` does after a bake, with no host run. `null` bake = no records, NO_BAKE. */
+export const stitch = (f: StaticsFile, bake: { size: number, pages: number, texel: number, texels?: number, instances: BakeRecordSource[], uv1?: string | null } | null): StaticsFile => {
+  const byPath = bake ? recordsByPath(bake.instances) : new Map<string, StaticRecord[]>()
+  return {
+    defs: f.defs, bake: bakeDigest(bake), kinds: f.kinds,
+    placements: f.placements.map((p) => ({ ...p, records: byPath.get(p.path) ?? [] })),
+  }
+}

package/src/inject.ts

@@ -31,10 +31,11 @@ export { Canvas, Bitmap } from "./canvas/Canvas"
 // ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
 export { toast, openURL, SvgSource } from "./runtime/misc"
 export { app, type AppState, type OrientationLock } from "./runtime/app"
+export { env } from "./runtime/env"
 export { clipboard } from "./runtime/clipboard"
 export { permissions, type PermissionKind, type PermissionState } from "./runtime/permissions"
 export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
-export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
+export { fetch, fetchLocal, FormData, File, __localAsset, type FetchResponse } from "./runtime/fetch"
 export { localStorage } from "./runtime/storage"
 export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
 export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
@@ -44,6 +45,8 @@ export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, t
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
 // only ever imports its server functions (docs/backend-plan.md §4).
 export { __rpc, __channel, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc"
+// The font() compile macro's generated `.__fonts.ts` modules call this per face (UI tree + Font2D).
+export { __registerFont } from "./ui/fonts"
 // What a screen asks of the server, as reactive state: a request a screen follows, an action with its own busy / error.
 export { resource, action, dataOf, failureOf, type Loaded, type Failure, type Resource, type Action } from "./runtime/resource"
 export type { ChannelSubscription } from "./server/channel"
@@ -73,7 +76,17 @@ export { CharacterController2D } from "./g2/CharacterController2D"
 export { OneWay2D } from "./g2/OneWay2D"
 export { PhysicsGroup2D } from "./g2/groups2d"
 export { Tilemap } from "./g2/Tilemap"
+export { Path2D, type Path2DOptions, type Stroke2D, type StrokeJoin2D, type StrokeCap2D } from "./g2/Path2D"
+export { Material2D, type Material2DOptions, type Blend2D, type Filter2D, type Wrap2D } from "./g2/Material2D"
 export { Texture2D } from "./g2/Texture2D"
+// SDF text in the sprite batch (see src/g2/Text2D.ts)
+export { Font2D, type Font2DOptions } from "./g2/Font2D"
+export { Text2D, type Text2DOptions, type TextAlign2D, type TextOutline2D } from "./g2/Text2D"
+// particles in the sprite batch — the 3D node's simulation and vocabulary (see src/g2/Particles2D.ts)
+export {
+  Particles2D, type Particles2DOptions, type ParticleMode2D, type ParticleShape2D, type VelocityValue2D,
+  type VelocityOverLife2D,
+} from "./g2/Particles2D"
 // sprite sheets as data (.sprite.ts files — see src/g2/SpriteSheet.ts)
 export { SpriteSheet, defineSpriteSheet } from "./g2/SpriteSheet"
 export type { SpriteSheetDef, SheetSprite, SpriteMakeOptions } from "./g2/SpriteSheet"
@@ -87,7 +100,7 @@ export type {
 } from "./g2/autotile"
 // 2D scenes as data (.scene2d.ts files — see src/g2/defineScene2d.ts) + the cells('…') payload
 export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d"
-export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
+export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, PathSourceDef, TextSourceDef, Particles2DSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
 export { cells, encodeCells, type CellsData } from "./g2/cells"
 // no-code 2D scenario aspects (attachable in scene files — see src/g2/scenarios2d.ts)
 export { CameraFollow } from "./g2/scenarios2d"
@@ -260,6 +273,8 @@ export type { ReflectionProbeOptions } from "./gl/ReflectionProbe"
 export { Ray } from "./gl/Ray"
 export { Plane } from "./gl/Plane"
 export { Noise } from "./gl/Noise"
-export { Particles, Trail, curve, colorCurve } from "./gl/Particles"
+export { Particles, Trail } from "./gl/Particles"
+// the particle curves — one vocabulary for Particles, Trail and Particles2D (src/core/particlesConfig.ts)
+export { curve, colorCurve } from "./core/particlesConfig"
 export { DecalSet, DecalTrail } from "./gl/DecalSet"
 export type { DecalOptions, DecalSetOptions, DecalSpawnOptions, DecalPlacement, DecalTrailOptions } from "./gl/DecalSet"

package/src/runtime/env.ts

@@ -0,0 +1,13 @@
+/**
+ * `env` in the APP — the project's `PUBLIC_*` keys (src/core/env.ts says what `env` is): a maps key
+ * restricted to the app's id, an analytics id, a Sentry DSN. The values are baked into the bundle at
+ * compile time (./envValues.ts, replaced by the compile), so they are there offline and without a
+ * backend. Any other key is a secret: the compile refuses `env.STRIPE_KEY` in app code — read it in a
+ * `*.server.ts` file and call an endpoint.
+ */
+
+import { makeEnv, type Env } from "../core/env"
+import { values } from "./envValues"
+
+/** The app's public keys. A `PUBLIC_*` key that is not set throws `EnvError` on read. */
+export const env: Env = makeEnv(() => values)

package/src/runtime/envValues.ts

@@ -0,0 +1,8 @@
+/**
+ * The app's keys — the `PUBLIC_*` subset of the project's keys, baked into the bundle.
+ *
+ * This module is a placeholder the COMPILER REPLACES: `compileProjectWithMap({ env })` puts a module
+ * with the real values at this same path in chisel's file map (project files win over SDK files),
+ * the way `server/auth/appConfig.ts` carries app.json. Outside a compiled bundle it is empty.
+ */
+export const values: Record<string, string> = {}