lecodes-sdk 0.20.0 → 1.0.0

package/src/compile/index.ts

@@ -63,13 +63,17 @@ 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,
   sceneEditorEntries,
+  sceneImportsOf,
   SCENE_ENTRY_PATH,
   SCENE_HARNESS_DIR,
 } from "./sceneEditor"

package/src/compile/sceneEditor.ts

@@ -47,10 +47,44 @@ export const loadSceneHarness = (fallbackDir?: string): Record<string, string> =
  * the project's file list — `.editor.ts` entries are picked out of it. Compile with
  * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`, `editor: true`.
  */
+/** Resolve a relative import specifier against a project path ("./src/map.scene.ts" + "./map/x.scene"
+ *  → "./src/map/x.scene"). */
+const resolveRelative = (fromPath: string, spec: string): string => {
+  const segs = (p: string) => p.split("/").filter((s) => s !== "" && s !== ".")
+  const out = segs(fromPath).slice(0, -1)
+  for (const seg of segs(spec)) {
+    if (seg === "..") out.pop()
+    else out.push(seg)
+  }
+  return "./" + out.join("/")
+}
+
+/**
+ * The other scene files a scene file imports as prefabs (`import x from './x.scene'`), as project
+ * paths present in `projectPaths`. The edit bundle registers their handles BY PATH
+ * (`__lecodesSceneFiles`), so the editor can live-patch a `prefab:` node — add, duplicate, undo —
+ * without a compile: the doc sees `prefab: X` as an identifier, the host maps it through the
+ * file's import table to this path, and the harness resolves the path to the running handle.
+ */
+export const sceneImportsOf = (sceneText: string, scenePath: string, projectPaths: string[]): string[] => {
+  const known = new Set(projectPaths)
+  const out: string[] = []
+  const re = /^\s*import\s+[A-Za-z_$][\w$]*\s+from\s+["']([^"']+\.scene(?:\.ts)?)["']/gm
+  for (const m of sceneText.matchAll(re)) {
+    const spec = m[1]
+    if (!spec.startsWith(".")) continue
+    let p = resolveRelative(scenePath, spec)
+    if (!p.endsWith(".ts")) p += ".ts"
+    if (known.has(p) && !out.includes(p)) out.push(p)
+  }
+  return out
+}
+
 export const sceneEditorEntries = (
   scenePath: string,
   harness: Record<string, string>,
   projectPaths: string[] = [],
+  sceneImports: string[] = [],
 ): CompileEntry[] => {
   const entries: CompileEntry[] = Object.entries(harness).map(([ name, text ]) => ({
     path: `${SCENE_HARNESS_DIR}/${name}`,
@@ -74,15 +108,22 @@ export const sceneEditorEntries = (
   const materialImports = materialPaths.map((p, i) => `import __mat${i} from "${p}"\n`).join("")
   const materialRegister = materialPaths.length === 0 ? ""
     : `;(globalThis as any).__lecodesMaterials = { ${materialPaths.map((p, i) => `${JSON.stringify(p)}: __mat${i}`).join(", ")} }\n`
+  // The scene's prefab imports, registered by project path (see sceneImportsOf) — the same module
+  // instances the scene itself imported, so a live-patched prefab node is the same handle.
+  const sceneImportLines = sceneImports.map((p, i) => `import __scn${i} from "${p}"\n`).join("")
+  const sceneRegister = sceneImports.length === 0 ? ""
+    : `;(globalThis as any).__lecodesSceneFiles = { ${sceneImports.map((p, i) => `${JSON.stringify(p)}: __scn${i}`).join(", ")} }\n`
   entries.push({
     path: SCENE_ENTRY_PATH,
     type: "text",
     text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
       + materialImports
+      + sceneImportLines
       + `import "${scenePath}"\n`
       + editorImports
       + `import "${SCENE_HARNESS_DIR}/main.ts"\n`
-      + materialRegister,
+      + materialRegister
+      + sceneRegister,
   })
   return entries
 }

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) } }
@@ -214,7 +227,11 @@ let fixedFallbackAcc = 0
 // 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-physics' cphysFrameBegin.
-const fixedStep: PhaseFn = (dt) => { _phaseHooks.fixed?.(dt); fixedUpdaters.run("updateFixed", dt) }
+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/CameraPlace.ts

@@ -1,52 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
-   *  clicking it selects the node. Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}

package/src/gl/DecalSet.ts

@@ -0,0 +1,360 @@
+// 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
+  /** Opacity multipliers at the image's BOTTOM and TOP edge (−Y / +Y), interpolated along it — a
+   *  tire mark that darkens as the slide deepens. Default `[1, 1]`. */
+  gradient?: [number, number]
+  /** Tilt of the image's bottom and top edge, as a unit-space slope (Δy per Δx across the box):
+   *  the edge pivots on the corner of the side it keeps and cuts INTO the box on the other, so two
+   *  boxes can meet on one shared line — what `DecalTrail` uses to mitre its joints. `0` = square.
+   *  Default `[0, 0]`. */
+  caps?: [number, 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) — see `Mesh.renderPriority`. Default 3: a decal is
+   *  part of the surface it sits on, so it draws before every other blended thing (meshes 4,
+   *  particles 5) — the engine's depth sort compares object centres, and a set spread over the
+   *  level has no useful centre. */
+  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 = 27
+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)
+      this.renderPriority = options.renderPriority ?? 3
+    } 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)
+  }
+
+  /** @internal One decal's frame → record → host (`DecalTrail` writes its segments through here). */
+  _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!
+    const caps = o.caps ?? d.caps
+    r[23] = caps ? caps[0] : 0; r[24] = caps ? caps[1] : 0
+    const gradient = o.gradient ?? d.gradient
+    r[25] = gradient ? gradient[0] : 1; r[26] = gradient ? gradient[1] : 1
+    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
+  }
+}
+
+/** A `DecalTrail`'s look: the strip's width, and what every segment carries. */
+export type DecalTrailOptions = Omit<DecalOptions, "size" | "caps" | "gradient"> & {
+  /** Width of the strip on the surface, world units. */
+  width: number
+}
+
+// The mitre stops making sense past this turn between two segments (a sharp reversal would need a
+// box longer than the strip is wide); the trail breaks there and starts afresh.
+const TRAIL_MAX_SLOPE = 1.75   // tan 60°
+
+/**
+ * A continuous strip of decals along a path — a tire's skid mark, a dragged body, a tread track.
+ * Feed it points (`add`) as the thing moves; every new point becomes one box-decal SEGMENT from the
+ * previous point, its image's up along the travel, and the joints between segments are MITRED: each
+ * box is cut along the bisector it shares with its neighbour (`caps`), so the strip has no overlaps
+ * darkening the outside of a bend and no wedges of gap on the inside. The opacity given with each
+ * point is interpolated along the segment (`gradient`), so a mark can darken as a slide deepens and
+ * fade as it ends. Segments are the set's decals — same ring, same `max` budget: a set of 900 holds
+ * 900 segments across every trail drawn from it.
+ *
+ * The previous segment is REWRITTEN when the next point arrives (its far cap becomes the shared
+ * mitre), through `DecalSet.update`'s path — a recycled slot is simply left alone by the engine.
+ */
+export class DecalTrail {
+  private _prev: { point: Vec3, opacity: number } | null = null
+  private _seg: {
+    slot: number, start: Vec3, end: Vec3, dir: Vec3, right: Vec3, normal: Vec3,
+    slopeStart: number, a0: number, a1: number,
+  } | null = null
+
+  readonly set: DecalSet
+  readonly options: DecalTrailOptions
+
+  constructor(set: DecalSet, options: DecalTrailOptions) {
+    this.set = set
+    this.options = options
+  }
+
+  /** Extend the strip to `point` on a surface with `normal`, `opacity` (0..1) at that point. The
+   *  first call after a start / `end()` only anchors the strip. Returns the new segment's slot, or
+   *  −1 when nothing was drawn (the anchor, a point that did not move, no host support). */
+  add(point: Vec3Like, normal: Vec3Like, opacity = 1): number {
+    const p = new Vec3(point)
+    const n = new Vec3(normal).normalize()
+    const prev = this._prev
+    this._prev = { point: p, opacity }
+    if (!prev) return -1
+    // The segment, flattened onto the surface plane.
+    let d = p.sub(prev.point)
+    d = d.sub(n.scale(d.dot(n)))
+    const len = d.length()
+    if (len < 1e-3) { this._prev = prev; return -1 }   // not moved: wait for a real step
+    const dir = d.scale(1 / len)
+    const right = dir.cross(n)   // DecalSet.spawn's frame: right × up = normal, image unmirrored from the normal's side
+    const w = this.options.width
+
+    // Mitre with the previous segment: the joint's bisector is the sum of the two right normals,
+    // and each box takes it as a cap — the previous one at its END (rewritten now), this one at its
+    // START — with the slopes measured in each box's own frame. A trail's first segment, or one
+    // after a break, starts square.
+    let slopeStart = 0
+    const last = this._seg
+    if (last) {
+      const lastDir = last.dir.sub(n.scale(last.dir.dot(n))).normalize()
+      const lastRight = lastDir.cross(n)
+      const m = lastRight.add(right)
+      const denom = m.dot(right)
+      const slopeEnd = Math.abs(denom) > 1e-4 ? m.dot(lastDir) / denom : Infinity
+      if (Math.abs(slopeEnd) <= TRAIL_MAX_SLOPE) {
+        this._rewrite(last, slopeEnd)
+        slopeStart = -slopeEnd
+      } else {
+        this._rewrite(last, 0)   // too sharp to mitre: leave the last one square, start afresh
+      }
+    }
+    const seg = { slot: -1, start: prev.point, end: p, dir, right, normal: n, slopeStart, a0: prev.opacity, a1: opacity }
+    seg.slot = this._box(seg, 0, -1)
+    this._seg = seg
+    return seg.slot
+  }
+
+  /** Finish the strip. With a `point`, one last segment runs out to it at opacity 0 — a mark that
+   *  tapers away instead of stopping dead. The next `add` anchors a new strip. */
+  end(point?: Vec3Like, normal: Vec3Like = Vec3.up): this {
+    if (point && this._prev) this.add(point, normal, 0)
+    this._prev = null
+    this._seg = null
+    return this
+  }
+
+  private _rewrite(seg: NonNullable<DecalTrail["_seg"]>, slopeEnd: number): void {
+    if (seg.slot >= 0) this._box(seg, slopeEnd, seg.slot)
+  }
+
+  /** Write one segment's box: the strip between its joints, extended past each mitred joint by the
+   *  mitre's reach (w/2 · |slope|) so the tilted cap still passes through the joint's centre. */
+  private _box(seg: NonNullable<DecalTrail["_seg"]>, slopeEnd: number, slot: number): number {
+    const w = this.options.width
+    const L = seg.end.sub(seg.start).length()
+    const extStart = 0.5 * w * Math.abs(seg.slopeStart)
+    const extEnd = 0.5 * w * Math.abs(slopeEnd)
+    const boxLen = L + extStart + extEnd
+    const centre = seg.start.add(seg.dir.scale(0.5 * boxLen - extStart))
+    // World slopes → unit-space slopes: x is measured in widths, y in box lengths.
+    const caps: [number, number] = [ seg.slopeStart * (w / boxLen), slopeEnd * (w / boxLen) ]
+    const { width: _w, ...rest } = this.options
+    const s = this.set._write(slot < 0 ? NO_SLOT : slot, seg.right, seg.dir, seg.normal, centre,
+      { ...rest, size: [ w, boxLen ], caps, gradient: [ seg.a0, seg.a1 ] })
+    return slot < 0 ? s : slot
+  }
+}