lecodes-cli 0.18.0 → 0.18.1

package/runtime/sdk/gl/Light.ts

@@ -1,4 +1,5 @@
-// Lights. Currently a directional sun (the engine's primary light). Add it to a scene like any node.
+// Lights. A directional sun (the engine's primary light) and punctual point lights. Add one to a
+// scene like any node; `intensity` and `color` stay writable so a light can be animated.
 
 import { Color, type ColorInput } from "../core/color"
 import type { Vec3Like } from "../math/vec"
@@ -21,17 +22,78 @@ export type SunOptions = {
   shadowsQuality?: 0 | 1 | 2 | 3
 }
 
+export type PointOptions = {
+  /**
+   * Luminous POWER in lumens — the same physical scale as the sun's lux and `environmentIntensity`,
+   * so a light keeps its look when the scene's exposure changes. A candle is ~12 lm, a bare 60 W
+   * bulb ~800, a car headlight ~1500, a fireball millions. Default 1000.
+   */
+  intensity?: number
+  color?: ColorInput
+  /**
+   * Metres of influence — past it the light contributes nothing. This is the performance knob:
+   * overlapping point lights are the expensive case, so keep it as small as the look allows.
+   * Default 10.
+   */
+  range?: number
+  /** Point-light shadows are a cubemap render per light; off by default. */
+  castShadows?: boolean
+}
+
 export class Light extends Node {
+  private _intensity = 0
+  /** @internal sun direction as created (the engine keeps it; Lightmap.load reads it back). */
+  _direction: [number, number, number] = [ 0, -1, 0 ]
+  /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
+  static lastSun: Light | null = null
+
   /** A directional sun light. */
   static sun(options: SunOptions = {}): Light {
     const light = new Light()
     const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
+    light._direction = [ dx, dy, dz ]
+    light._intensity = options.intensity ?? 100000
+    Light.lastSun = light
     _creator.createSunLight(
       light.id, dx, dy, dz,
-      options.intensity ?? 100000,
+      light._intensity,
       Color.toPackedRgb(options.color ?? 0xffffff),
       options.shadowsQuality ?? 1,
     )
     return light
   }
+
+  /**
+   * A point light — a lamp, a muzzle flash, a fireball. Position it like any node.
+   *
+   * Feature-detected: hosts that predate it create the node and light nothing, which keeps a scene
+   * that adds atmosphere on top of its sun renderable everywhere. Check `Light.supportsPoint`
+   * before making one carry the scene.
+   */
+  static point(options: PointOptions = {}): Light {
+    const light = new Light()
+    light._intensity = options.intensity ?? 1000
+    _creator.createPointLight?.(
+      light.id,
+      light._intensity,
+      Color.toPackedRgb(options.color ?? 0xffffff),
+      options.range ?? 10,
+      options.castShadows ?? false,
+    )
+    return light
+  }
+
+  /** Whether this host can create point lights at all. */
+  static get supportsPoint(): boolean { return _creator.createPointLight !== undefined }
+
+  /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
+  get intensity(): number { return this._intensity }
+  set intensity(value: number) {
+    this._intensity = value
+    _creator.setLightIntensity?.(this.id, value)
+  }
+
+  set color(value: ColorInput) {
+    _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
+  }
 }

package/runtime/sdk/gl/Lightmap.ts

@@ -0,0 +1,179 @@
+// Baked shadows for static 3D geometry (docs/lightmap-plan.md). A scene FILE does all of this by
+// itself: `env: { lightmap: { data, texture } }` marks the level as baked, every model/mesh node
+// that no Physics aspect moves is a static (keys = node paths, `lightmap: true|false` overrides),
+// and the runtime applies the bake when the level finishes loading (scene/defineScene.ts).
+// Hand-built scenes register what never moves with `Lightmap.add`, bake once with
+// `lecodes lightmap bake` (the desktop host traces the live scene and writes lightmap.ktx2 +
+// lightmap.bake), and `Lightmap.load` applies the atlas at runtime:
+//
+//   const crate = await Model.load(asset('./assets/props/crate.glb'), { lightmap: true })
+//   Lightmap.add(holder)                    // a Model, a Mesh, or a node holding them
+//   Lightmap.add(ground)                    // Mesh.plane works too
+//   ...
+//   await Lightmap.load(scene, { data: asset('./assets/lightmap/lightmap.bake'),
+//                                texture: asset('./assets/lightmap/lightmap.ktx2') })
+//
+// Both files are asset() handles because the compiler stages exactly the files it sees (the data
+// file is JSON with a .bake extension — a .json would be scanned as a code module). `load` is a
+// no-op when the bake is missing or the host predates the feature, so the project stays runnable —
+// and in BAKE mode (`lecodes lightmap bake`) it is where the bake fires: the same call marks "the
+// scene is complete". Atlas channels: R = sun visibility, G = ambient occlusion; the shader keeps
+// the real-time sun for dynamic casters and multiplies the baked mask in with an ambient floor.
+
+import { fetch } from "../runtime/fetch"
+import { Texture } from "./Texture"
+import { Material } from "./Material"
+import { Mesh } from "./Mesh"
+import { Model } from "./Model"
+import { Node } from "./Node"
+import type { Scene } from "./Scene"
+
+export type LightmapLoadOptions = {
+  /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
+  sunStrength?: number
+  /** Multiplier on the ambient (IBL) share in the shadow math — how bright a fully shadowed texel
+   *  stays. 1 reproduces filament's own real-time shadow darkness (the shader reads the scene's sun
+   *  and IBL from filament's per-frame uniforms); raise it for lighter shadows, lower for deeper. Default 1. */
+  ambientScale?: number
+}
+
+export type LightmapInfo = {
+  size: number
+  texel: number
+  /** keys applied / keys in the file / registered statics without a rect */
+  applied: number
+  total: number
+  missing: string[]
+}
+
+type Entry = { key: string, model?: Model, mesh?: Mesh }
+
+type BakeConfig = {
+  outDir: string, size?: number, texel?: number, sunRays?: number, aoRays?: number,
+  aoDistance?: number, bias?: number, sunAngle?: number,
+}
+
+const bakeConfig = (): BakeConfig | null => {
+  const g = (globalThis as unknown as { __lecodesLightmap?: BakeConfig }).__lecodesLightmap
+  return g && typeof g.outDir === "string" ? g : null
+}
+
+/** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
+const hex8 = (c: unknown): string => {
+  if (typeof c !== "string") return "#ffffffff"
+  if (c.length === 7) return c + "ff"
+  if (c.length === 4) return "#" + c[1] + c[1] + c[2] + c[2] + c[3] + c[3] + "ff"
+  return c
+}
+
+export class Lightmap {
+  /** True while `lecodes lightmap bake` runs the app — skip menus and build the scene straight away. */
+  static get baking(): boolean { return bakeConfig() !== null }
+
+  private static entries: Entry[] = []
+  private static ordinals = new Map<string, number>()
+  private static warned = false
+
+  /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
+   *  both receivers and occluders in the bake. `key` names the entry in lightmap.bake (default:
+   *  the node's name + a running number, `container#3`); pass one when names are not stable. */
+  static add(node: Node, key?: string): Node {
+    const base = key ?? `${node.name || "node"}#${Lightmap.next(node.name || "node")}`
+    const found: Entry[] = []
+    const walk = (n: Node): void => {
+      if (n instanceof Model) { found.push({ key: base, model: n }); return }
+      if (n instanceof Mesh) { found.push({ key: base, mesh: n }); return }
+      for (const c of n.children) walk(c)
+    }
+    walk(node)
+    if (found.length === 0) { console.warn(`Lightmap.add: ${base} holds no Model or Mesh`); return node }
+    if (found.length > 1) found.forEach((e, i) => { e.key = `${base}/${i}` })
+    Lightmap.entries.push(...found)
+    return node
+  }
+
+  /** @internal Scene-file runtime: one model/mesh node under its path key (no subtree walk). */
+  static _register(node: Model | Mesh, key: string): void {
+    Lightmap.entries.push(node instanceof Model ? { key, model: node } : { key, mesh: node })
+  }
+
+  private static next(name: string): number {
+    const n = Lightmap.ordinals.get(name) ?? 0
+    Lightmap.ordinals.set(name, n + 1)
+    return n
+  }
+
+  /** Forget every registration (a scene rebuild). */
+  static clear(): void {
+    Lightmap.entries = []
+    Lightmap.ordinals.clear()
+  }
+
+  /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
+   *  applied (no bake yet, a host without the feature, bake mode). */
+  static async load(scene: Scene, files: { data: string, texture: string }, options: LightmapLoadOptions = {}): Promise<LightmapInfo | null> {
+    const bake = bakeConfig()
+    if (bake) { Lightmap.bake(bake); return null }
+    if (!_creator.lightmapApply) {
+      if (!Lightmap.warned) { Lightmap.warned = true; console.warn("Lightmap: this host has no lightmap support — rendering without the bake") }
+      return null
+    }
+    let data: { size: number, texel: number, sun?: number[] | null, instances: { key: string, receiver: boolean, st?: number[] }[] }
+    try {
+      const resp = await fetch(files.data, { useOnce: true })
+      if (resp.status >= 400) { console.warn(`Lightmap: no bake at ${files.data} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
+      data = resp.json()
+      resp.dispose()
+    } catch (e) {
+      console.warn(`Lightmap: could not read ${files.data}: ${String(e)}`)
+      return null
+    }
+    const texture = await Texture.load(files.texture)
+    const ambientScale = options.ambientScale ?? 1
+    const strength = options.sunStrength ?? 1
+    const rects = new Map<string, number[]>()
+    for (const inst of data.instances) if (inst.receiver && inst.st) rects.set(inst.key, inst.st)
+    let applied = 0
+    const missing: string[] = []
+    for (const e of Lightmap.entries) {
+      const st = rects.get(e.key)
+      if (!st) { missing.push(e.key); continue }
+      if (e.model) {
+        const n = _creator.lightmapApply(e.model.id, texture._id, st[0], st[1], st[2], st[3], ambientScale, strength)
+        if (n === 0) { console.warn(`Lightmap: ${e.key} was not loaded with { lightmap: true } — skipped`); continue }
+        _creator.setGlbShadows?.(e.model.id, false, true)
+      } else if (e.mesh) {
+        Lightmap.swapMeshMaterial(e.mesh, texture, st, ambientScale, strength)
+        e.mesh.castShadows = false
+      }
+      applied++
+    }
+    if (missing.length) console.warn(`Lightmap: ${missing.length} static(s) have no rect in the bake (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "…" : ""}) — rebake`)
+    return { size: data.size, texel: data.texel, applied, total: rects.size, missing }
+  }
+
+  /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
+  private static swapMeshMaterial(mesh: Mesh, texture: Texture, st: number[], ambientScale: number, strength: number): void {
+    const src = mesh.material
+    const u = src?.uniforms ?? {}
+    const m = Material.lightmap()
+    m.set("baseColorFactor", hex8(u.baseColor))
+    if (u.baseColorMap instanceof Texture) m.set("baseColorMap", u.baseColorMap)
+    if (typeof u.roughness === "number") m.set("roughnessFactor", u.roughness)
+    if (typeof u.metallic === "number") m.set("metallicFactor", u.metallic)
+    m.set("lightmap", texture)
+    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
+    m.set("ambientScale", ambientScale)
+    m.set("sunStrength", strength)
+    mesh.setMaterial(m)
+  }
+
+  private static bake(cfg: BakeConfig): void {
+    if (!_creator.lightmapBake) { console.error("[lightmap] error: this host has no bake module (build the desktop host with CREATOR_GL_LIGHTMAP, or update lecodes desktop)"); return }
+    const ids = Uint32Array.from(Lightmap.entries.map((e) => (e.model ?? e.mesh)!.id))
+    const keys = Lightmap.entries.map((e) => e.key).join("\n")
+    if (ids.length === 0) { console.error("[lightmap] error: nothing registered — call Lightmap.add on the static props before Lightmap.load"); return }
+    _creator.lightmapBake(cfg.outDir, ids, keys, cfg.size ?? 4096, cfg.texel ?? 0.02, cfg.sunRays ?? 32, cfg.aoRays ?? 64,
+      cfg.aoDistance ?? 2, cfg.bias ?? 0.02, cfg.sunAngle ?? 0.5)
+  }
+}

package/runtime/sdk/gl/Material.ts

@@ -58,6 +58,12 @@ export type ParticlesMaterialOptions = {
   blend?: "alpha" | "add"
   /** Soft radial falloff toward the sprite edge. Defaults to true without a map, false with one. */
   soft?: boolean
+  /** Soft particles: fade each sprite out over this many metres as it cuts into the scene geometry
+   *  behind it (Unity's "Soft Particles Factor"), so smoke and dust no longer slice through the
+   *  ground and walls with a hard edge. 0 = off (default). Reads the scene's depth buffer, which the
+   *  engine keeps bound while any soft system is on screen — the extra depth pass is only paid then.
+   *  Filament hosts (desktop / web / Android / Apple); web-lite draws such sprites unfaded. */
+  depthFade?: number
   /** How each particle is drawn: `'point'` (default — GPU point sprites, cheapest), `'quad'`
    *  (real camera-facing quads — no driver size cap, geometric rotation), or `'stretch'`
    *  (quads stretched along velocity — sparks, rain, speed streaks). `'ribbon'` is what `Trail`
@@ -169,6 +175,7 @@ export class Material {
     m.uniforms.emissive = options.emissive ?? 0
     m.uniforms.additive = options.blend === "add" ? 1 : 0
     m.uniforms.softness = (options.soft ?? !options.map) ? 1 : 0
+    m.uniforms.depthFade = options.depthFade ?? 0
     if (quad) {
       m.uniforms.mode = options.render === "ribbon" ? 2 : options.render === "stretch" ? 1 : 0
       m.uniforms.stretch = options.stretch ?? (options.render === "stretch" ? 0.05 : 0)
@@ -188,6 +195,24 @@ export class Material {
     return m
   }
 
+  /** The lightmap material (docs/lightmap-plan.md): PBR base colour × a baked shadow/AO atlas on UV1.
+   *  Models take it through `Model.load(…, { lightmap: true })`; `Lightmap.load` builds one per static
+   *  Mesh. Parameters use gltfio's names (`baseColorFactor`, `baseColorMap`, `roughnessFactor`,
+   *  `metallicFactor`) plus `lightmap`, `lightmapST`, `ambientScale`, `sunStrength` (the sun / IBL terms come from
+   *  filament's per-frame uniforms inside the shader). */
+  static lightmap(): Material {
+    // Inline literal: the compiler's preload header captures the shader name from it.
+    const m = new Material({ _id: _creatorUtils.fetchLocal("lightmap.filamat") } as any)
+    m.set("baseColorFactor", "#ffffffff").set("roughnessFactor", 1).set("metallicFactor", 0)
+    m.set("lightmapST", [ 1, 1, 0, 0 ]).set("ambientScale", 1).set("sunStrength", 1).set("hasNormalMap", 0)
+    return m
+  }
+
+  /** @internal the shared template instance `Model.load({ lightmap })` hands the engine (its MATERIAL is what
+   *  the GLB provider instantiates; the template itself never draws). */
+  static _lightmapTemplate(): Material { return (Material._lmTemplate ??= Material.lightmap()) }
+  private static _lmTemplate: Material | undefined
+
   /** Shadow-catcher material (transparent except where shadows fall). */
   static shadow(color: ColorInput = "#000000aa"): Material {
     const m = new Material({ _id: _creatorUtils.fetchLocal("shadow.filamat") } as any)

package/runtime/sdk/gl/Mesh.ts

@@ -24,7 +24,6 @@ export type MeshOptions = {
 
 export class Mesh extends Node {
   private _geometry?: Geometry
-  private _materials: Material[] = []
 
   constructor(geometry?: Geometry, material?: Material) {
     super()
@@ -32,29 +31,15 @@ export class Mesh extends Node {
       const mat = material ?? Material.unlit()
       this._geometry = geometry
       this._materials = [ mat ]
-      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind)
+      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1)
     }
   }
 
   override get geometry(): Geometry | undefined { return this._geometry }
 
-  get material(): Material { return this._materials[0] }
-  set material(m: Material) { this.setMaterial(m, 0) }
-
-  setMaterial(material: Material, index = 0): this {
-    this._materials[index] = material
-    _creator.setMaterial(this.id, Material.idOf(material), index)
-    return this
-  }
-  getMaterial(index = 0): Material | null {
-    const existing = this._materials[index]
-    if (existing) return existing
-    const id = _creator.getMaterial(this.id, index)
-    if (id === 0) return null
-    const mat = new Material(id)
-    this._materials[index] = mat
-    return mat
-  }
+  /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
+  override get material(): Material { return this._materials![0]! }
+  override set material(m: Material) { this.setMaterial(m, 0) }
 
   set culling(v: boolean) { _creator.setCulling(this.id, v) }
   set castShadows(v: boolean) { _creator.setCastShadows(this.id, v) }
@@ -63,10 +48,8 @@ export class Mesh extends Node {
   // --- factories ---
 
   static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    const geo = Geometry.box()
-    const [ sx, sy, sz ] = sizeToVec(options.size ?? 1)
-    if (sx !== 1 || sy !== 1 || sz !== 1) geo.scale(sx, sy, sz)
-    return apply(new Mesh(geo, options.material), options)
+    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
+    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
   }
 
   static sphere(options: MeshOptions & SphereOptions = {}): Mesh {

package/runtime/sdk/gl/Model.ts

@@ -7,11 +7,14 @@
 import { fetch, type FetchResponse } from "../runtime/fetch"
 import { Node } from "./Node"
 import { Animator } from "./animation/Animator"
+import { Material } from "./Material"
 
 export class Model extends Node {
   /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
    *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
   declare readonly anim: Animator
+  /** @internal loaded through the lightmap material (docs/lightmap-plan.md); clones inherit it. */
+  _lightmapped = false
 
   constructor(internalId: number) {
     super(internalId)
@@ -24,13 +27,21 @@ export class Model extends Node {
   clone(): Model {
     const id = _creator.cloneEntity(this.id)
     _creator.setGlbCulling(id, false)
-    return new Model(id)
+    const m = new Model(id)
+    m._lightmapped = this._lightmapped
+    return m
   }
 
   /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
   static load(
     source: string | FetchResponse,
-    options: { culling?: boolean, onProgress?: (p: { loaded: number, total?: number }) => void } = {},
+    options: {
+      culling?: boolean
+      onProgress?: (p: { loaded: number, total?: number }) => void
+      /** Load through the lightmap material so `Lightmap.load` can bind a baked atlas (the GLB needs
+       *  TEXCOORD_1 — `lecodes assets doctor --lightmap-uv`). Hosts without lightmap support ignore it. */
+      lightmap?: boolean
+    } = {},
   ): Promise<Model> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
@@ -39,9 +50,12 @@ export class Model extends Node {
       })
     }
     return new Promise<Model>((resolve, reject) => {
+      const lightmapped = !!options.lightmap && !!_creator.setNextGlbLightmapped
+      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()))
       _creator.createGlb((source as unknown as { _id: number })._id, (entityId: number) => {
         if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
         const model = new Model(entityId)
+        model._lightmapped = lightmapped
         if (options.culling !== true) _creator.setGlbCulling(entityId, false)
         resolve(model)
       }, reject)

package/runtime/sdk/gl/Node.ts

@@ -13,7 +13,8 @@ import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 import { ensurePhysicsEvents } from "./physicsEvents"
-import { glState } from "./state"
+import { Material } from "./Material"
+import type { CompAxis, CompWriter } from "../core/compWrite"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
@@ -49,7 +50,10 @@ const findNodeByWalk = (rootId: number, name: string): number => {
   return exact || loose
 }
 
-export class Node extends AspectHost<NodeEvents> {
+// Scratch for the world-position read-back in _setOwnedPosition (one per module, never handed out).
+const worldScratch = new Float32Array(3)
+
+export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** Native entity handle. */
   readonly id: number
 
@@ -58,11 +62,10 @@ export class Node extends AspectHost<NodeEvents> {
   isTracked = false
 
   private _matrix?: Float32Array
-  private _lastSync = 0
-  private _syncFrame = -1
   private _worldMatrix?: Float32Array
-  private _scaleCache?: [number, number, number]
   private _boneCache?: Map<string, Node | null>
+  /** Materials assigned through setMaterial, by primitive slot (a Mesh fills slot 0 itself). */
+  protected _materials?: Material[]
 
   constructor(internalId?: number) {
     super()
@@ -80,29 +83,31 @@ export class Node extends AspectHost<NodeEvents> {
   set visible(value: boolean) { _creator.setVisible(this.id, value) }
 
   // --- local transform ---
-  // Native owns the authoritative matrix; we keep a Float32Array cache (re-synced lazily because physics
-  // can rewrite it each frame). The PUBLIC `matrix` getter hands back a fresh Mat4 *copy* (value
-  // semantics — mutating it never touches the node until you assign it back). `_sync()` is the internal
-  // hot path that returns the cache directly for cheap component reads.
+  // Native owns the authoritative matrix. `_sync()` reads it into a per-node scratch buffer on EVERY
+  // call: a bridge read is ~40 ns on QuickJS — what the Date.now() of a staleness check cost — so a
+  // cache bought nothing and needed invalidation hooks (physics / controllers / animation rewrite
+  // transforms natively between frames). The PUBLIC `matrix` getter hands back a fresh Mat4 *copy*
+  // (value semantics — mutating it never touches the node until you assign it back); `_sync()` is
+  // the internal hot path for component reads.
   private _sync(): Float32Array {
-    if (!this._matrix) this._matrix = new Float32Array(16)
-    // stale once per render frame (glState.frame — physics/controllers/animation rewrite transforms
-    // between frames), or after 10 ms of wall time when no scene loop is running
-    if (this._lastSync === 0 || this._syncFrame !== glState.frame || Date.now() - this._lastSync > 10) {
-      _creator.getMatrix(this.id, this._matrix)
-      this._scaleCache = undefined
-      this._lastSync = Date.now()
-      this._syncFrame = glState.frame
-    }
-    return this._matrix
+    const m = this._matrix ?? (this._matrix = new Float32Array(16))
+    _creator.getMatrix(this.id, m)
+    return m
   }
 
   get matrix(): Mat4 { return new Mat4(this._sync()) }
   set matrix(m: Mat4Like) {
-    if (!this._matrix) this._matrix = new Float32Array(16)
-    this._matrix.set(matArr(m))
-    this._lastSync = Date.now()
-    _creator.setMatrix(this.id, this._matrix)
+    const buf = this._matrix ?? (this._matrix = new Float32Array(16))
+    buf.set(matArr(m))
+    _creator.setMatrix(this.id, buf)
+    // A matrix write on a physics-owned node must move the engine object too, or it is silently
+    // overwritten by the next sync. Position always; rotation only for a BODY (see _setOwnedRotation).
+    // Scale is never routed — a Jolt shape is built at a fixed size, that is `Shape`'s job.
+    // `worldMatrix` composes into this setter, so it is covered here too.
+    if (this._xf) {
+      this._setOwnedPosition(buf[12], buf[13], buf[14])
+      this._setOwnedRotation()
+    }
   }
 
   get worldMatrix(): Mat4 {
@@ -120,39 +125,86 @@ export class Node extends AspectHost<NodeEvents> {
     this.matrix = p.worldMatrix.invert().mul(m)
   }
 
+  /** @internal The engine object that mirrors this node's transform, if any — a physics body or a
+   *  character (0 = none). `position` writes are routed to it as well, because the engine is the
+   *  authority: on a dynamic body a plain setPosition is overwritten by the next sync, and on a
+   *  static / pick / trigger body it would leave the COLLIDER behind while the node moved. Set by
+   *  Shape (bodies) and CharacterController. */
+  _xf = 0
+  /** @internal What `_xf` is: 1 = character, 2 = physics body. */
+  _xfKind = 0
+
+  // Route a position write to the engine object that owns this node. Kept out of the setters' hot path
+  // (they only pay one truthiness check). `position` stays a LOCAL coordinate like on every node, while
+  // physics works in world space — so the node is written first and the world point read back natively
+  // (one bridge call for any parent depth, no allocation; the native transform manager updates the
+  // world matrix synchronously).
+  private _setOwnedPosition(x: number, y: number, z: number): void {
+    _creator.setPosition(this.id, x, y, z)   // keep the node itself right, so a read-back is immediate
+    _creator.getWorldPosition(this.id, worldScratch)
+    if (this._xfKind === 1) _creator.characterSetPosition(this._xf, worldScratch[0], worldScratch[1], worldScratch[2])
+    else _creator.physicsSetBodyPosition(this._xf, worldScratch[0], worldScratch[1], worldScratch[2])
+  }
+
+  // The rotation half of the same routing. BODIES ONLY: a character's rotation is node-owned by design
+  // (the engine writes its position and nothing else — a capsule is symmetric about its up axis, so its
+  // yaw is physically meaningless), and pushing one into Jolt would invent an authority that isn't there.
+  // The node has already been written by the caller, so the world rotation is read back from it — that
+  // way the engine's own euler convention decides, instead of this file re-deriving it.
+  private _setOwnedRotation(): void {
+    if (this._xfKind !== 2 || !_creator.physicsSetBodyRotation) return
+    const q = this.worldMatrix.rotation
+    _creator.physicsSetBodyRotation(this._xf, q.x, q.y, q.z, q.w)
+  }
+
   get position(): Vec3 { const m = this._sync(); return new Vec3(m[12], m[13], m[14]) }
-  set position(v: Vec3Like) { this._lastSync = 0; _creator.setPosition(this.id, cx(v), cy(v), cz(v)) }
+  set position(v: Vec3Like) {
+    if (this._xf) this._setOwnedPosition(cx(v), cy(v), cz(v))
+    else _creator.setPosition(this.id, cx(v), cy(v), cz(v))
+  }
 
-  // Scalar position accessors — the loud, correct way to nudge one axis (`node.x = 3`), so nobody reaches
-  // for `node.position.x = 3` (a no-op: the getter returns a fresh copy).
+  // Scalar position accessors — one axis without touching the others (`node.x = 3`). The direct spelling
+  // `node.position.x = 3` compiles to the same thing (chisel's comp_write pass routes it through
+  // `_writeComp` below); only a STORED copy of `position` is still a copy.
   get x(): number { return this._sync()[12] }
-  set x(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, v, m[13], m[14]) }
+  set x(v: number) { const m = this._sync(); if (this._xf) this._setOwnedPosition(v, m[13], m[14]); else _creator.setPosition(this.id, v, m[13], m[14]) }
   get y(): number { return this._sync()[13] }
-  set y(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, m[12], v, m[14]) }
+  set y(v: number) { const m = this._sync(); if (this._xf) this._setOwnedPosition(m[12], v, m[14]); else _creator.setPosition(this.id, m[12], v, m[14]) }
   get z(): number { return this._sync()[14] }
-  set z(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, m[12], m[13], v) }
+  set z(v: number) { const m = this._sync(); if (this._xf) this._setOwnedPosition(m[12], m[13], v); else _creator.setPosition(this.id, m[12], m[13], v) }
+
+  /** @internal chisel `comp_write` (see core/compWrite.ts): `node.position.<axis> = v` is compiled to a
+   *  call here; the scalar setters already carry the physics routing. The list is compile-time data. */
+  static _comps = [ "position" ]
+  _writeComp(_prop: string, axis: CompAxis, v: number): void {
+    if (axis === "x") this.x = v
+    else if (axis === "y") this.y = v
+    else if (axis === "z") this.z = v
+  }
 
   get scale(): Vec3 {
-    if (this._lastSync === 0 || !this._scaleCache) {
-      const m = this._sync()
-      this._scaleCache = [ Math.hypot(m[0], m[1], m[2]), Math.hypot(m[4], m[5], m[6]), Math.hypot(m[8], m[9], m[10]) ]
-    }
-    return new Vec3(this._scaleCache)
+    const m = this._sync()
+    return new Vec3(Math.hypot(m[0], m[1], m[2]), Math.hypot(m[4], m[5], m[6]), Math.hypot(m[8], m[9], m[10]))
   }
   set scale(v: Vec3Like | number) {
-    this._lastSync = 0
     if (typeof v === "number") _creator.setScale(this.id, v, v, v)
     else _creator.setScale(this.id, cx(v), cy(v), cz(v))
   }
 
   get quaternion(): Quat { return new Mat4(this._sync()).rotation }
-  set quaternion(v: QuatLike) { this._lastSync = 0; _creator.setQuaternion(this.id, cx(v), cy(v), cz(v), cw(v)) }
+  set quaternion(v: QuatLike) {
+    _creator.setQuaternion(this.id, cx(v), cy(v), cz(v), cw(v))
+    if (this._xf) this._setOwnedRotation()
+  }
 
   get eulerAngles(): Vec3 { return new Mat4(this._sync()).eulerAngles }
   // order 1 = YXZ — the SDK's euler convention (math/quat.ts); the getter also extracts YXZ, so
   // the pair round-trips. (Historically this passed 0/XYZ AND the engine stored the euler matrix
   // transposed — the setter applied the INVERSE rotation. Both fixed 2026-07-10.)
-  set eulerAngles(v: Vec3Like) { this._lastSync = 0; _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 1) }
+  set eulerAngles(v: Vec3Like) {
+    _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 1)
+    if (this._xf) this._setOwnedRotation()
+  }
 
   // --- world-space reads ---
   get forward(): Vec3 {
@@ -190,13 +242,29 @@ export class Node extends AspectHost<NodeEvents> {
   setParent(parent: Node | null, worldPositionStays = false): this {
     if (parent === null) _creator.setParentNull(this.id, worldPositionStays)
     else _creator.setParent(this.id, parent.id, worldPositionStays)
-    if (worldPositionStays) this._lastSync = 0
     return this
   }
   traverse(callback: (node: Node) => void): void {
     callback(this)
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
   }
+  // --- materials (any renderable: a Mesh, or an internal node of a loaded Model) ---
+  /** The material assigned to slot 0 through this API (null before one is set — a GLB part's own
+   *  glTF material stays native-side). */
+  get material(): Material | null { return this.getMaterial(0) }
+  set material(m: Material) { this.setMaterial(m, 0) }
+  /** Replace the material of one primitive slot (`index` = the primitive's order in the glTF
+   *  mesh; a primitive-shape Mesh has one slot). */
+  setMaterial(material: Material, index = 0): this {
+    (this._materials ??= [])[index] = material
+    _creator.setMaterial(this.id, Material.idOf(material), index)
+    return this
+  }
+  /** The material previously assigned to `index` (null when none was — see Mesh for the probe). */
+  getMaterial(index = 0): Material | null {
+    return this._materials?.[index] ?? null
+  }
+
   /** Find a descendant by name — bones of a loaded Model included (`hero.bone('RightHand').add(sword)`).
    *  Same rule the Animator binds clips with: exact name first, then the part after the last `:` / `|`
    *  (Mixamo `mixamorig:Hips` matches `Hips`); a skinned joint beats a plain node of the same name.
@@ -260,8 +328,20 @@ export class Node extends AspectHost<NodeEvents> {
   _emitCollision(channel: "enter" | "exit", other: Node): void { this.dispatch(channel, other) }
 
 
+  /** Destroy this node and its whole subtree. Every aspect in the subtree is detached first (its
+   *  `onDetach` runs: physics bodies released, updaters unregistered, listeners dropped) — native
+   *  `destroyEntity` frees the entity tree but knows nothing about JS-side aspects, and a destroyed
+   *  node's `update()` must not keep ticking. Deepest nodes go first, then this one. */
   destroy(): void {
-    nodeRegistry.delete(this.id)
+    const subtree: Node[] = [this]
+    _creator.traverse(this.id, (id) => { const n = nodeRegistry.get(id); if (n) subtree.push(n) })
+    for (let i = subtree.length - 1; i >= 0; i--) {
+      const n = subtree[i]
+      n._detachAll()
+      n._xf = 0
+      n._xfKind = 0
+      nodeRegistry.delete(n.id)
+    }
     _creator.destroyEntity(this.id)
   }
 }