lecodes-sdk 0.19.2 → 0.20.2

package/src/compile/__tests__/compile.test.ts

@@ -285,3 +285,15 @@ test("buildHeader / detectProjectKind signal the engine from bundled code", () =
   expect(detectProjectKind("const x = 1")).toBe("ui")
   expect(detectProjectKind("_creator.createARController()")).toBe("ar")
 })
+
+test("a .json project file is data — asset()/import gives the parsed value", async () => {
+  const js = await compileProject({
+    name: "Data", publicUrl: "https://le.codes", header: false,
+    entries: [
+      { path: "/main.ts", type: "text", text: 'toast(asset("./style.json").name)\n' },
+      { path: "/style.json", type: "text", text: '{ "name": "OSM Bright", "version": 8 }\n' },
+    ],
+  })
+  expect(js).toContain("OSM Bright")
+  expect(js).not.toContain('"./style.json"') // desugared to the import, not left as a string
+})

package/src/compile/compileProject.ts

@@ -69,21 +69,22 @@ export type CompileOptions = {
   serverUrl?: string
 }
 
-export const compileProject = async (opts: CompileOptions): Promise<string> => {
-  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
-  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
-  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
-  if (!entry) {
-    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
-  }
+/** The bundle + its map SEPARATELY (the platform deploy writes the map as a sibling `.js.map`; the
+ *  preview inlines it) plus the entrypoint the compile used. `code` carries the metadata header
+ *  unless `header: false`; `map` is already shifted past that header. */
+export type CompileResult = { code: string, map: string | null, entry: string }
 
+/** Turn compile entries into the bundler's module map — the per-kind rules of the deployable
+ *  bundle (resource → URL export, shader → per-backend URL template, .svg → SvgSource, .json →
+ *  data, code verbatim). Exported for callers that build a `libraries` map from entries. */
+export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: string, localAssets?: boolean }): Record<string, string> => {
   const files: Record<string, string> = {}
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // The host resolves the asset by name at runtime (reads the local file → systemId); the
         // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
-        const name = e.path.split(/[\\/]/).pop() ?? e.path
+        const name = e.path.split(/[\/]/).pop() ?? e.path
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
@@ -98,7 +99,7 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
         // desktop host reports "desktop" on Windows and "opengl" on Linux, iOS "metal".
         // Only entries the CLI actually compiled+staged carry `shadersLocal`; server artifacts
         // (URLs) and un-staged ones keep the URL forms below.
-        const name = shaders[0].src.split(/[\\/]/).pop() ?? ""
+        const name = shaders[0].src.split(/[\/]/).pop() ?? ""
         const [prefix, suffix = ".filamat"] = name.split("_opengl")
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`
       } else if (shaders.length > 0) {
@@ -108,20 +109,39 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
       }
     } else if (e.path.toLowerCase().endsWith(".svg")) {
       files[e.path] = `export default SvgSource(\`${e.text ?? ""}\`)`
+    } else if (e.path.toLowerCase().endsWith(".json")) {
+      // A .json project file is DATA, not code: `import data from "./x.json"` — and `asset("./x.json")`,
+      // which desugars to that import — yields the parsed value. The bundler would otherwise try to
+      // parse the file as JS. JSON is an expression, so a default export is the whole translation.
+      files[e.path] = `export default ${e.text?.trim() || "null"}`
     } else {
       files[e.path] = e.text ?? ""
     }
   }
+  return files
+}
 
+export const compileProjectWithMap = async (opts: CompileOptions): Promise<CompileResult> => {
+  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
+  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
+  if (!entry) {
+    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
+  }
+
+  const files = entriesToFiles(entries, opts)
   const { code, map } = await bundleProjectWithMap(
     entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true,
   )
-  if (opts.header === false) {
-    return map ? `${code}\n${inlineSourceMapComment(map)}` : code
-  }
+  if (opts.header === false) return { code, map, entry }
   const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader })
-  if (!map) return header + code
-  // Shift the map down past the header (prepended before the code); the inline comment lands last.
+  // Shift the map down past the header (prepended before the code).
   const headerLines = (header.match(/\n/g) ?? []).length
-  return `${header}${code}\n${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`
+  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry }
+}
+
+/** The bundle as ONE string, the map inlined at its end (the shipped/preview form). */
+export const compileProject = async (opts: CompileOptions): Promise<string> => {
+  const { code, map } = await compileProjectWithMap(opts)
+  return map ? `${code}\n${inlineSourceMapComment(map)}` : code
 }

package/src/compile/index.ts

@@ -63,9 +63,12 @@ export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
 export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
 export {
   compileProject,
+  compileProjectWithMap,
+  entriesToFiles,
   type CompileEntry,
   type CompileOptions,
   type CompileFileType,
+  type CompileResult,
 } from "./compileProject"
 export {
   loadSceneHarness,

package/src/core/Aspect.ts

@@ -96,14 +96,27 @@ type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
 type FixedInstaller = (fixed: PhaseFn) => boolean
 let frameInstaller: FrameInstaller | undefined
 let fixedInstaller: FixedInstaller | undefined
-/** @internal Install a render-synced frame source for aspect update(dt) (+ the fixed-step source). Called from an engine layer. */
-export const _installAspectFrames = (fn: FrameInstaller, fixed?: FixedInstaller): void => { frameInstaller = fn; fixedInstaller = fixed }
+/** @internal Install a render-synced frame source for aspect update(dt) (+ the fixed-step source). Called from an engine layer.
+ *  The FIRST engine layer wins: a 3D game that later builds a Scene2D for a UIImage minimap keeps its dispatch on the
+ *  3D engine (the one it presents); the 2D engine's phases stay unwired there, so nothing ticks twice. */
+export const _installAspectFrames = (fn: FrameInstaller, fixed?: FixedInstaller): void => {
+  if (frameInstaller) return
+  frameInstaller = fn; fixedInstaller = fixed
+}
 
 /** @internal Engine-level phase hooks (the Net system, sdk/src/net): FIRST in the early and fixed
  *  phases, LAST in the late one, ahead of / behind every game aspect regardless of ordering
  *  constraints. Single slot each; raw dt. */
 export const _phaseHooks: { early: PhaseFn | null; fixed: PhaseFn | null; late: PhaseFn | null } = { early: null, fixed: null, late: null }
 
+/** @internal Advances at the start of EVERY phase pass — early, each fixed step, late — on the
+ *  render-synced path and the setLoop fallback alike. The key for "read the engine once per phase"
+ *  caches (gl/Vehicle's state block): between two passes the engine rewrites state natively (the
+ *  physics steps, the transform sync), so a value cached under an older stamp is stale. Once per
+ *  FRAME is not enough — the early and late phases of one frame straddle the physics step, and a
+ *  value first read in `updateBefore` must not be what `update` sees. */
+export const _phaseStamp = { value: 0 }
+
 let attachSeq = 0
 const warned = new Set<string>()
 const warnOnce = (msg: string): void => { if (!warned.has(msg)) { warned.add(msg); console.warn(msg) } }
@@ -213,8 +226,12 @@ let fixedFallbackAcc = 0
 // The FIXED phase: dt = Time.fixedDt (1/60) every call, once per physics substep, on every host. The
 // engine drives it from inside its substep loop when it has the hook; otherwise (older wasm / Apple /
 // Android builds, the setLoop path) the SDK steps its own accumulator right after the early phase -
-// same step, same 4-substep cap, same drop-the-backlog rule as creator-gl's physics/world.cpp.
-const fixedStep: PhaseFn = (dt) => { _phaseHooks.fixed?.(dt); fixedUpdaters.run("updateFixed", dt) }
+// same step, same 4-substep cap, same drop-the-backlog rule as creator-physics' cphysFrameBegin.
+const fixedStep: PhaseFn = (dt) => {
+  _phaseStamp.value++   // a substep moved the bodies natively since the last pass
+  _phaseHooks.fixed?.(dt)
+  fixedUpdaters.run("updateFixed", dt)
+}
 const fixedFallback = (): void => {
   const step = Time.fixedDt
   fixedFallbackAcc += Time.dt   // scaled: paused -> no steps, slow-motion -> fewer steps, never a shorter dt
@@ -229,12 +246,17 @@ const ensureDispatch = (): void => {
   // Both phases scale their OWN raw dt (the engine hands the same value to both; a host or test that
   // drives them apart still gets each phase's dt right). The frame counter / clocks advance once, early.
   const early: PhaseFn = (dt) => {
+    _phaseStamp.value++
     Time._beginFrame(dt)
     _phaseHooks.early?.(dt)
     earlyUpdaters.run("updateBefore", Time.dt)
     if (fixedFallbackOn) fixedFallback()
   }
-  const late: PhaseFn = (dt) => { lateUpdaters.run("update", Time._phaseDt(dt)); _phaseHooks.late?.(dt) }
+  const late: PhaseFn = (dt) => {
+    _phaseStamp.value++   // the physics step + transform sync ran since the early pass
+    lateUpdaters.run("update", Time._phaseDt(dt))
+    _phaseHooks.late?.(dt)
+  }
   // render-synced source if an engine layer installed one; else one host loop (early then late).
   if (!(frameInstaller && frameInstaller(early, late))) {
     setLoop((dt) => { early(dt); late(dt) })
@@ -266,10 +288,13 @@ const registerUpdater = (inst: Aspect<any, any, any>): void => {
 }
 const unregisterUpdater = (inst: Aspect<any, any, any>): void => {
   const a = internals(inst)
-  if (a._phases === 0) return
-  earlyUpdaters.remove(a)
-  lateUpdaters.remove(a)
-  fixedUpdaters.remove(a)
+  const phases = a._phases
+  if (phases === 0) return
+  // `_phases` records which lists the aspect is in (1 early / 2 late / 4 fixed) — only those are
+  // scanned, so detaching a late-only aspect never walks the early or fixed lists.
+  if (phases & 1) earlyUpdaters.remove(a)
+  if (phases & 2) lateUpdaters.remove(a)
+  if (phases & 4) fixedUpdaters.remove(a)
   a._phases = 0
 }
 

package/src/g2/Scene2D.ts

@@ -167,6 +167,13 @@ export class Scene2D implements Presentable {
     return this
   }
 
+  /** @internal UIImage source marker (UIImage.toSrc): `UIImage(scene)` shows this scene live — the
+   *  host draws it into the image node's box every frame with the scene's own camera (a minimap, a
+   *  portrait, any 2D view inside the UI). Needs no open(); the scene keeps its aspects and animations. */
+  _imageSrc(): { scene2d: number } {
+    return { scene2d: this.id }
+  }
+
   /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
   _viewDesc(): object {
     return this._vd ??= { type: "scene2d", sceneId: this.id, _p: this }

package/src/gl/AudioSource.ts

@@ -0,0 +1,113 @@
+// A 3D sound emitter, as an aspect on a Node (docs/audio-plan.md §2). The engine follows the node's
+// world pose every frame (position, facing for the cone, velocity for doppler); voices played
+// through it are spatialized against the scene's listener (scene.audio.listener, the camera by
+// default). Parented, animated and physics-driven nodes just work.
+//
+//   const gun = new Node().aspect(AudioSource, { minDistance: 1, maxDistance: 40 })
+//   gun.audio.play(shot, { pitch: 0.95 + Math.random() * 0.1 })
+//   const hum = car.audio.play(engineLoop, { loop: true }); hum.pitch = 0.8 + rpm * 0.6
+//   speaker.aspect(AudioSource, { cone: { inner: 60, outer: 120, outerGain: 0.3 } })   // facing −Z
+//   enemy.aspect(AudioSource, { occlusion: true })   // a wall between it and the listener muffles it
+//
+// Without host audio the aspect is inert: `play` returns an inert Voice, nothing throws.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { audio, sourceParams, type PlaySoundOptions, type Rolloff } from "../audio/audio"
+import type { Sound } from "../audio/Sound"
+import { audioSupported } from "../audio/support"
+import type { Voice } from "../audio/Voice"
+import type { Node } from "./Node"
+
+export type AudioCone = {
+  /** Degrees of full volume around the node's −Z. */
+  inner: number
+  /** Degrees where the volume has fallen to `outerGain`. */
+  outer: number
+  /** Volume behind the source, 0 … 1. */
+  outerGain?: number
+}
+
+export class AudioSource extends Aspect<"audio", Node> {
+  static readonly aspect = "audio"
+
+  static fields: FieldMeta<AudioSource> = {
+    minDistance: { min: 0.05, max: 100, step: 0.05 },
+    maxDistance: { min: 0.5, max: 1000, step: 0.5 },
+    doppler: { min: 0, max: 1, step: 0.05 },
+    spread: { min: 0, max: 1, step: 0.05 },
+  }
+
+  private _minDistance = 1
+  private _maxDistance = 50
+  private _rolloff: Rolloff = "inverse"
+  private _cone: AudioCone | null = null
+  private _doppler = 0
+  private _spread = 0
+  private _occlusion = false
+  private _bus = "sfx"
+  /** @internal engine source id (0 = not attached / no audio). */
+  _id = 0
+
+  /** Metres of full volume around the node. Default 1. */
+  get minDistance(): number { return this._minDistance }
+  set minDistance(v: number) { this._minDistance = v; this._push() }
+  /** Metres beyond which the source no longer gets quieter. Default 50. */
+  get maxDistance(): number { return this._maxDistance }
+  set maxDistance(v: number) { this._maxDistance = v; this._push() }
+  /** `inverse` (default), `linear`, `exponential`, `none`. */
+  get rolloff(): Rolloff { return this._rolloff }
+  set rolloff(v: Rolloff) { this._rolloff = v; this._push() }
+  /** Directional source along the node's −Z; null = omnidirectional (default). */
+  get cone(): AudioCone | null { return this._cone }
+  set cone(v: AudioCone | null) { this._cone = v; this._push() }
+  /** Doppler amount 0 … 1 (0 = off, the default) — needs the node to actually move. */
+  get doppler(): number { return this._doppler }
+  set doppler(v: number) { this._doppler = v; this._push() }
+  /** 0 = pin-point panning (default) … 1 = the same on every speaker (a big, close source). */
+  get spread(): number { return this._spread }
+  set spread(v: number) { this._spread = v; this._push() }
+  /** The engine raycasts listener → source (against solid bodies) and muffles the voices when
+   *  something is in the way. Default false. */
+  get occlusion(): boolean { return this._occlusion }
+  set occlusion(v: boolean) { this._occlusion = v; this._push() }
+  /** Default bus for voices on this source. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  /** Live voices on this source. */
+  get voices(): number { return this._id && audioSupported ? _creatorAudio.sourceVoices(this._id) : 0 }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createSource()
+    if (!this._id) return
+    _creatorAudio.attachSource(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroySource(this._id)
+    this._id = 0
+  }
+
+  /** Play a clip from this node. */
+  play(sound: Sound, options: PlaySoundOptions = {}): Voice {
+    return audio._play(sound, this._id, options)
+  }
+
+  /** Stop every voice on this source (fade in seconds). */
+  stopAll(fade = 0): void {
+    if (this._id && audioSupported) _creatorAudio.stopSource(this._id, fade)
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    const cone = this._cone
+    _creatorAudio.setSourceParams(this._id, sourceParams({
+      minDistance: this._minDistance, maxDistance: this._maxDistance, rolloff: this._rolloff,
+      coneInner: cone ? cone.inner : 360, coneOuter: cone ? cone.outer : 360, coneOuterGain: cone ? cone.outerGain ?? 0.25 : 1,
+      doppler: this._doppler, spread: this._spread, occlusion: this._occlusion, bus: audio._busId(this._bus),
+    }))
+  }
+}

package/src/gl/AudioZone.ts

@@ -0,0 +1,75 @@
+// A reverb zone, as an aspect on a Node (docs/audio-plan.md §2): a box or sphere volume that
+// follows the node; while the listener is inside, the zone's reverb blends onto a bus (the bus's
+// own reverb outside it). Zones nest: the smallest one containing the listener wins. `blend` is
+// how many metres inside the border the crossfade takes — walking through a doorway is smooth.
+//
+//   new Node().aspect(AudioZone, { box: [6, 2.5, 6], reverb: 'hall', blend: 2 })
+//   corridor.aspect(Shape, { box: [1, 1.5, 8] }).aspect(AudioZone, { reverb: 'bathroom' })  // the Shape's box
+//
+// Sizes follow Shape's convention: `box` = HALF-extents, `sphere` = radius, in the node's local
+// units (the node's scale applies). Without host audio the aspect is inert.
+
+import { Aspect } from "../core/Aspect"
+import { reverbBlock, type ReverbParams, type ReverbPreset } from "../audio/Bus"
+import { audio } from "../audio/audio"
+import { audioSupported } from "../audio/support"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Node } from "./Node"
+import { Shape } from "./Shape"
+
+export class AudioZone extends Aspect<"audioZone", Node> {
+  static readonly aspect = "audioZone"
+
+  private _box: Vec3Like | null = null
+  private _sphere: number | null = null
+  private _reverb: ReverbPreset | ReverbParams = "room"
+  private _blend = 1
+  private _bus = "sfx"
+  /** @internal engine zone id. */
+  _id = 0
+  /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
+  get id(): number { return this._id }
+
+  /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
+  get box(): Vec3Like | null { return this._box }
+  set box(v: Vec3Like | null) { this._box = v; if (v) this._sphere = null; this._push() }
+  /** Radius; falls back to the node's Shape sphere. */
+  get sphere(): number | null { return this._sphere }
+  set sphere(v: number | null) { this._sphere = v; if (v !== null) this._box = null; this._push() }
+  /** A preset name or explicit params (see Bus.reverb). */
+  get reverb(): ReverbPreset | ReverbParams { return this._reverb }
+  set reverb(v: ReverbPreset | ReverbParams) { this._reverb = v; this._push() }
+  /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
+  get blend(): number { return this._blend }
+  set blend(v: number) { this._blend = v; this._push() }
+  /** The bus the zone's reverb rides on. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createZone()
+    if (!this._id) return
+    _creatorAudio.attachZone(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroyZone(this._id)
+    this._id = 0
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    let box = this._box, sphere = this._sphere
+    if (!box && sphere === null) {
+      const shape = this.node.get(Shape)
+      if (shape?.sphere !== undefined) sphere = shape.sphere
+      else if (shape?.box) box = shape.box
+    }
+    const dims = sphere !== null
+      ? new Float32Array([ sphere * 2, sphere * 2, sphere * 2 ])
+      : new Float32Array(box ? [ cx(box) * 2, cy(box) * 2, cz(box) * 2 ] : [ 2, 2, 2 ])
+    _creatorAudio.setZone(this._id, sphere !== null ? 1 : 0, dims, this._blend, audio._busId(this._bus), reverbBlock(this._reverb))
+  }
+}

package/src/gl/DecalSet.ts

@@ -0,0 +1,233 @@
+// Projected decals — bullet holes, footprints, dirt, blood. A DecalSet is one node that owns up to
+// `max` decals drawn as ONE native renderable: each decal is a box that projects its image onto the
+// opaque scene inside it (the engine reads the scene depth — creator-gl src/decals.cpp +
+// materials/src/decal.mat), so it wraps floor-wall corners, stairs and curved surfaces without any
+// geometry access. It lands on opaque surfaces only: never on particles, glass or other decals.
+//
+// Coordinates are in the SET's space: a set added at the scene root with no transform takes world
+// coordinates (the usual case); a set parented to a door rides with it and takes door-local ones.
+// Slots are a ring — a full set recycles its oldest decal, so `max` is the on-screen budget.
+
+import { Node } from "./Node"
+import { Material } from "./Material"
+import type { Texture } from "./Texture"
+import { Vec3, type Vec3Like } from "../math/vec"
+import { Quat, type QuatLike } from "../math/quat"
+import { Color, type ColorInput } from "../core/color"
+
+/** Per-decal look and life — defaults come from the set's options. */
+export type DecalOptions = {
+  /** Image width and height on the surface (world units); a number = square. Default 0.2. */
+  size?: number | [number, number]
+  /** Projection depth (world units): how far in front of and behind the hit point the decal still
+   *  lands. Default = the smaller of width / height. */
+  depth?: number
+  /** Atlas cell (row-major from the top-left) for a set with a `sheet`; `"random"` picks one.
+   *  Default 0. */
+  frame?: number | "random"
+  /** Tint multiplied into the image. Default white. */
+  tint?: ColorInput
+  /** 0..1 on top of the tint's alpha. Default 1. */
+  opacity?: number
+  /** Seconds until the decal is gone; 0 = stays until recycled. Default 0. */
+  life?: number
+  /** Seconds to fade in after spawning. Default 0. */
+  fadeIn?: number
+  /** Seconds of fade at the end of `life` (ignored with life 0). Default 0. */
+  fadeOut?: number
+}
+
+export type DecalSetOptions = DecalOptions & {
+  /** The material — `Material.decal({ map })` by default (`map` below is its shortcut). A custom
+   *  material must keep decal.mat's vertex contract. */
+  material?: Material
+  /** Atlas texture for the default material. */
+  map?: Texture
+  /** Tangent-space normal atlas (same cell grid) → a RELIEF decal that bends the surface's
+   *  lighting instead of painting a colour (`Material.decal` `normalMap`). Footprints and dents
+   *  need only this; a bullet hole gives `map` too and its colour multiplies in. */
+  normalMap?: Texture
+  /** Relief strength for `normalMap`. Default 1. Default material only. */
+  bump?: number
+  /** Atlas grid of the map: columns, or [columns, rows]. Default 1 (the whole texture). */
+  sheet?: number | [number, number]
+  /** Slot budget — the most decals alive at once. Default 256. */
+  max?: number
+  /** Soft fraction (0..1) of the box's half depth at both ends, so an oblique surface leaves the
+   *  box gently. Default 0.3. Default material only. */
+  edge?: number
+  /** Surfaces turned more than this away from the projection axis fade out — the cosine of the
+   *  angle (0.3 ≈ 72°) keeps a floor hit off the wall it meets; 0 = project onto anything.
+   *  Default 0.3. Default material only. */
+  angleFade?: number
+  /** HDR boost of the image (0 = none). Default material only. */
+  emissive?: number
+  name?: string
+  /** Coarse draw order, 0 (first) … 7 (last); default 4 — see `Mesh.renderPriority`. Decals are
+   *  blended and sort with the other blended draws of their priority. */
+  renderPriority?: number
+}
+
+/** `spawn` placement: where the image sits on the surface. */
+export type DecalSpawnOptions = DecalOptions & {
+  /** World direction the image's top points along the surface (projected onto it) — a footprint's
+   *  travel direction. Default: a random spin. */
+  up?: Vec3Like
+  /** Extra spin around the normal, radians. Default: random when `up` is not given, else 0. */
+  rotation?: number
+}
+
+/** `place` / `update` placement: a full frame, like a node looking INTO the surface (its −Z is the
+ *  projection direction, +Y the image's top). */
+export type DecalPlacement = DecalOptions & {
+  position: Vec3Like
+  /** A quaternion, or Euler degrees (YXZ) like `Node.eulerAngles`. Default identity = projecting
+   *  down −Z. */
+  rotation?: QuatLike | Vec3Like
+}
+
+const RECORD = 23
+const NO_SLOT = 0xFFFFFFFF
+
+export class DecalSet extends Node {
+  private _material: Material
+  private readonly _max: number
+  private readonly _cols: number
+  private readonly _rows: number
+  private readonly _defaults: DecalOptions
+  private readonly _rec = new Float32Array(RECORD)
+  private readonly _slots = new Map<number, DecalPlacement>()
+  private static _warned = false
+
+  constructor(options: DecalSetOptions = {}) {
+    super()
+    if (options.name) this.name = options.name
+    this._material = options.material ?? Material.decal({
+      map: options.map, normalMap: options.normalMap, bump: options.bump,
+      edge: options.edge, angleFade: options.angleFade, emissive: options.emissive,
+    })
+    this._max = Math.max(1, Math.round(options.max ?? 256))
+    const sheet = options.sheet ?? 1
+    this._cols = Math.max(1, Array.isArray(sheet) ? sheet[0] : sheet)
+    this._rows = Math.max(1, Array.isArray(sheet) ? sheet[1] : 1)
+    this._defaults = {
+      size: options.size ?? 0.2, depth: options.depth, frame: options.frame ?? 0, tint: options.tint,
+      opacity: options.opacity ?? 1, life: options.life ?? 0, fadeIn: options.fadeIn ?? 0, fadeOut: options.fadeOut ?? 0,
+    }
+    if (_creator.createDecalSet) {
+      _creator.createDecalSet(this.id, Material.idOf(this._material), this._max)
+      if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+    } else if (!DecalSet._warned) {
+      DecalSet._warned = true
+      console.warn("[decals] this host has no createDecalSet — decals are not drawn")
+    }
+  }
+
+  get material(): Material { return this._material }
+  /** Decals alive right now. */
+  get count(): number { return _creator.decalCount ? _creator.decalCount(this.id) : 0 }
+  /** The slot budget the set was created with. */
+  get max(): number { return this._max }
+
+  /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
+  set renderPriority(v: number) {
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+  }
+
+  /** Stamp a decal on a surface: `point` on it, `normal` out of it (a raycast hit, a foot plant
+   *  with `Vec3.up`). Returns the slot for `update` / `remove` (−1 when the host draws none). */
+  spawn(point: Vec3Like, normal: Vec3Like, options: DecalSpawnOptions = {}): number {
+    const n = new Vec3(normal).normalize()
+    // Image up on the surface: the hint projected onto the plane, or any perpendicular.
+    let up = options.up ? new Vec3(options.up) : null
+    if (up) { up = up.sub(n.scale(up.dot(n))); if (up.length() < 1e-4) up = null }
+    if (!up) {
+      const helper = Math.abs(n.y) < 0.99 ? Vec3.up : Vec3.right
+      up = helper.sub(n.scale(helper.dot(n)))
+    }
+    up = up.normalize()
+    // right = up × normal keeps the frame right-handed (right × up = normal), so the image reads
+    // unmirrored from the normal's side; then the spin around the normal.
+    let right = up.cross(n)
+    const spin = options.rotation ?? (options.up ? 0 : Math.random() * Math.PI * 2)
+    if (spin !== 0) {
+      const c = Math.cos(spin), s = Math.sin(spin)
+      const r2 = right.scale(c).add(up.scale(s))
+      up = up.scale(c).sub(right.scale(s))
+      right = r2
+    }
+    return this._write(NO_SLOT, right, up, n, new Vec3(point), options)
+  }
+
+  /** Place a decal by a full frame (an editor-placed stain, a moving marker). Returns the slot. */
+  place(placement: DecalPlacement): number {
+    const slot = this._writePlacement(NO_SLOT, placement)
+    if (slot >= 0) this._slots.set(slot, placement)
+    return slot
+  }
+
+  /** Move / restyle a placed decal; fields left out keep the values it was placed with. Its birth
+   *  time (the life clock) is kept. */
+  update(slot: number, placement: Partial<DecalPlacement>): this {
+    const prev = this._slots.get(slot)
+    if (!prev) return this
+    const next = { ...prev, ...placement }
+    this._slots.set(slot, next)
+    this._writePlacement(slot, next)
+    return this
+  }
+
+  remove(slot: number): this {
+    this._slots.delete(slot)
+    if (_creator.removeDecal && slot >= 0) _creator.removeDecal(this.id, slot)
+    return this
+  }
+
+  clear(): this {
+    this._slots.clear()
+    if (_creator.clearDecals) _creator.clearDecals(this.id)
+    return this
+  }
+
+  private _writePlacement(slot: number, p: DecalPlacement): number {
+    let q: Quat
+    if (p.rotation === undefined) q = Quat.identity
+    else if (p.rotation instanceof Quat || (p.rotation as any).w !== undefined || (p.rotation as any).length === 4) q = new Quat(p.rotation as QuatLike)
+    else { const e = new Vec3(p.rotation as Vec3Like); q = Quat.fromEuler(e.x, e.y, e.z) }
+    const right = q.rotateVec3(Vec3.right)
+    const up = q.rotateVec3(Vec3.up)
+    const normal = right.cross(up)   // +Z of the frame: the node's −Z looks into the surface
+    return this._write(slot, right, up, normal, new Vec3(p.position), p)
+  }
+
+  private _write(slot: number, right: Vec3, up: Vec3, normal: Vec3, centre: Vec3, o: DecalOptions): number {
+    const d = this._defaults
+    const size = o.size ?? d.size!
+    const w = typeof size === "number" ? size : size[0]
+    const h = typeof size === "number" ? size : size[1]
+    const depth = o.depth ?? d.depth ?? Math.min(w, h)
+    const r = this._rec
+    r[0] = right.x * w; r[1] = right.y * w; r[2] = right.z * w
+    r[3] = up.x * h; r[4] = up.y * h; r[5] = up.z * h
+    r[6] = normal.x * depth; r[7] = normal.y * depth; r[8] = normal.z * depth
+    r[9] = centre.x; r[10] = centre.y; r[11] = centre.z
+    // atlas cell → rect (v grows downward: v0 is the cell's top)
+    const cells = this._cols * this._rows
+    const frameOpt = o.frame ?? d.frame!
+    const frame = frameOpt === "random" ? Math.floor(Math.random() * cells) : ((Math.floor(frameOpt) % cells) + cells) % cells
+    const col = frame % this._cols, row = Math.floor(frame / this._cols)
+    r[12] = col / this._cols; r[13] = row / this._rows; r[14] = (col + 1) / this._cols; r[15] = (row + 1) / this._rows
+    const tint = o.tint ?? d.tint
+    const [tr, tg, tb, ta] = tint === undefined ? [1, 1, 1, 1] : Color.toRgba01(tint)
+    const opacity = o.opacity ?? d.opacity!
+    r[16] = tr; r[17] = tg; r[18] = tb; r[19] = ta * opacity
+    r[20] = o.life ?? d.life!; r[21] = o.fadeIn ?? d.fadeIn!; r[22] = o.fadeOut ?? d.fadeOut!
+    if (slot === NO_SLOT) {
+      if (!_creator.addDecal) return -1
+      const s = _creator.addDecal(this.id, r)
+      return s === NO_SLOT ? -1 : s
+    }
+    if (_creator.updateDecal) _creator.updateDecal(this.id, slot, r)
+    return slot
+  }
+}

package/src/gl/Geometry.ts

@@ -25,6 +25,11 @@ export class Geometry {
    *  tiles per face, which would fold every face onto the same texels); absent = the host reuses
    *  `uv`, which is right for a plane. */
   uv1?: Float32Array
+  /** Per-vertex COLOURS: 4 bytes (r, g, b, a) per vertex, 0..255. A material that declares
+   *  `requires: [color]` reads them through `getColor()` — one mesh, many colours, no material per
+   *  shade (a debug drawer, a gradient along a curve). Absent = every vertex white, which is what
+   *  the built-in materials expect. */
+  colors?: Uint8Array
   /** @internal native mesh-type enum (0 triangles / 1 edges / 2 vertices). */
   _meshKind = 0