lecodes-sdk 1.1.0 → 2.0.0

package/src/gl/Model.ts

@@ -1,167 +1,172 @@
-// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
-// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
-// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
-//   const hero = await Model.load(asset('./hero.glb'))
-//   hero.anim.play('Run', { loop: true })
-
-import { fetch, type FetchResponse } from "../runtime/fetch"
-import { Node } from "./Node"
-import { Animator, _pushLod, type LodMode } from "./animation/Animator"
-import { Material } from "./Material"
-
-/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
- *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
- *  `world` its skinned position this frame. */
-export interface TrianglePick {
-  /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
-  entity: number
-  node: number
-  nodeName: string
-  mesh: string
-  primitive: number
-  material: string
-  /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
-  triangle: number
-  backface: boolean
-  distance: number
-  point: [number, number, number]
-  bary: [number, number, number]
-  skin: string
-  vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
-}
-
-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 (a baked static); clones inherit it. */
-  _lightmapped = false
-  /** @internal loaded through the foliage tier (`Foliage`); clones inherit it. */
-  _foliage = false
-  /** @internal the shadow pair, mirrored here because the bridge writes both at once. */
-  _castShadows = true
-  /** @internal */
-  _receiveShadows = true
-  /** @internal */
-  _culling = true
-  /** @internal -1 = auto (see `lod`) */
-  _lodMesh = -1
-
-  constructor(internalId: number) {
-    super(internalId)
-    this.aspect(Animator)
-  }
-
-  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
-   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
-   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
-   *  is never wanted. */
-  get castShadows(): boolean { return this._castShadows }
-  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
-
-  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
-  get receiveShadows(): boolean { return this._receiveShadows }
-  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
-
-  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
-   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
-   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
-   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
-   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
-   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
-  get culling(): boolean { return this._culling }
-  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
-  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
-   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
-   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
-   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
-   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
-  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
-  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
-
-  /** @internal the default for a fresh instance (load / clone), decided once per host. */
-  static _cullingDefault(): boolean {
-    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
-    return Model._cullDefault
-  }
-  private static _cullDefault: boolean | undefined
-
-  /** @internal both flags travel together — the bridge walks the instance once. */
-  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
-
-  /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
-   *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
-   *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
-   *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
-   *  only. null = miss, or a host without the pick (desktop today). */
-  pickTriangle(screenX: number, screenY: number): TrianglePick | null {
-    const json = _creator.pickTriangle?.(this.id, screenX, screenY)
-    return json ? JSON.parse(json) as TrianglePick : null
-  }
-
-  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
-   *  the same parent and scene and sharing this model's current transform. The clone has its own
-   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
-  clone(): Model {
-    const id = _creator.cloneEntity(this.id)
-    const m = new Model(id)
-    m._lightmapped = this._lightmapped
-    m._foliage = this._foliage
-    if (!this._culling) { m._culling = false; _creator.setGlbCulling(id, false) }   // the engine default is on
-    if (this._lodMesh >= 0) { m._lodMesh = this._lodMesh; _pushLod(m) }
-    // the clone is a FRESH gltfio instance — it comes back with the asset's own shadow flags,
-    // not this model's, so a cleared flag has to be re-applied
-    m._castShadows = this._castShadows
-    m._receiveShadows = this._receiveShadows
-    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
-    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: {
-      /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
-      culling?: boolean
-      onProgress?: (p: { loaded: number, total?: number }) => void
-      /** Baked lighting (packages/creator-bake). `true` = a STATIC: loads through the lightmap material so
-       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
-       *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
-       *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
-      lightmap?: boolean
-      /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,
-       *  per-copy tint. Hosts without the tier fall back to the standard shader. */
-      foliage?: boolean
-    } = {},
-  ): Promise<Model> {
-    if (typeof source === "string") {
-      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
-        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
-        return Model.load(resp, options)
-      })
-    }
-    return new Promise<Model>((resolve, reject) => {
-      // the provider path: a foliage model takes the vegetation tier's pair when the host ships it (fetchLocal
-      // id 0 = it does not), a static the lightmap material + its masked twin; anything else the ubershader
-      const foliageWanted = !!options.foliage && !!_creator.setNextGlbLightmapped
-      let foliage = false
-      if (foliageWanted) {
-        const fol = Material.idOf(Material._foliageTemplate())
-        const folMasked = fol ? Material.idOf(Material._foliageMaskedTemplate()) : 0
-        foliage = fol > 0 && folMasked > 0
-        if (foliage) _creator.setNextGlbLightmapped!(fol, folMasked)
-      }
-      const lightmapped = !foliage && !!options.lightmap && !!_creator.setNextGlbLightmapped
-      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()), Material.idOf(Material._lightmapMaskedTemplate()))
-      _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
-        model._foliage = foliage
-        const culling = options.culling ?? Model._cullingDefault()
-        if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
-        resolve(model)
-      }, reject)
-    })
-  }
-}
+// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
+// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
+// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.play('Run', { loop: true })
+
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Node, nodes } from "./Node"
+import { Animator, _pushLod, type LodMode } from "./animation/Animator"
+import { Material } from "./Material"
+
+/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
+ *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
+ *  `world` its skinned position this frame. */
+export interface TrianglePick {
+  /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
+  entity: number
+  node: number
+  nodeName: string
+  mesh: string
+  primitive: number
+  material: string
+  /** the node's lightmap group (scene-file extras), when it has one */
+  lightmapGroup?: number
+  /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
+  triangle: number
+  backface: boolean
+  distance: number
+  point: [number, number, number]
+  bary: [number, number, number]
+  /** the lightmap uv (TEXCOORD_1) at the hit, when the primitive carries one */
+  uv1?: [number, number]
+  skin: string
+  vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
+}
+
+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 (a baked static); clones inherit it. */
+  _lightmapped = false
+  /** @internal loaded through the foliage tier (`Foliage`); clones inherit it. */
+  _foliage = false
+  /** @internal the shadow pair, mirrored here because the bridge writes both at once. */
+  _castShadows = true
+  /** @internal */
+  _receiveShadows = true
+  /** @internal */
+  _culling = true
+  /** @internal -1 = auto (see `lod`) */
+  _lodMesh = -1
+
+  constructor(internalId: number | Handle) {
+    super(internalId)
+    this.aspect(Animator)
+  }
+
+  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
+   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
+   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
+   *  is never wanted. */
+  get castShadows(): boolean { return this._castShadows }
+  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
+
+  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
+  get receiveShadows(): boolean { return this._receiveShadows }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
+
+  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
+   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
+   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
+   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
+   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
+   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
+  get culling(): boolean { return this._culling }
+  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
+  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
+   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
+   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
+   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
+   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
+  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
+  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
+
+  /** @internal the default for a fresh instance (load / clone), decided once per host. */
+  static _cullingDefault(): boolean {
+    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
+    return Model._cullDefault
+  }
+  private static _cullDefault: boolean | undefined
+
+  /** @internal both flags travel together — the bridge walks the instance once. */
+  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
+
+  /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
+   *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
+   *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
+   *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
+   *  only. null = miss, or a host without the pick (desktop today). */
+  pickTriangle(screenX: number, screenY: number): TrianglePick | null {
+    return _creator.pickTriangle?.(this.id, screenX, screenY) ?? null
+  }
+
+  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+   *  the same parent and scene and sharing this model's current transform. The clone has its own
+   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
+  clone(): Model {
+    const m = new Model(_creator.cloneEntity(this.id))
+    const id = m.id
+    if (_creator.entityIsOwned(id)) nodes.pin(m)   // cloned into this model's parent / scene: native owns it
+    m._lightmapped = this._lightmapped
+    m._foliage = this._foliage
+    if (!this._culling) { m._culling = false; _creator.setGlbCulling(id, false) }   // the engine default is on
+    if (this._lodMesh >= 0) { m._lodMesh = this._lodMesh; _pushLod(m) }
+    // the clone is a FRESH gltfio instance — it comes back with the asset's own shadow flags,
+    // not this model's, so a cleared flag has to be re-applied
+    m._castShadows = this._castShadows
+    m._receiveShadows = this._receiveShadows
+    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
+    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: {
+      /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
+      culling?: boolean
+      onProgress?: (p: { loaded: number, total?: number }) => void
+      /** Baked lighting (engines/bake). `true` = a STATIC: loads through the lightmap material so
+       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
+       *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
+       *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
+      lightmap?: boolean
+      /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,
+       *  per-copy tint. Hosts without the tier fall back to the standard shader. */
+      foliage?: boolean
+    } = {},
+  ): Promise<Model> {
+    if (typeof source === "string") {
+      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
+        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
+        return Model.load(resp, options)
+      })
+    }
+    return new Promise<Model>((resolve, reject) => {
+      // the provider path: a foliage model takes the vegetation tier's pair when the host carries it, a
+      // static the lightmap material + its masked twin; anything else the ubershader
+      const foliageWanted = !!options.foliage && !!_creator.setNextGlbLightmapped
+      let foliage = false
+      if (foliageWanted) {
+        const fol = Material._foliageTemplate()
+        const folMasked = fol && Material._foliageMaskedTemplate()
+        foliage = !!fol && !!folMasked
+        if (fol && folMasked) _creator.setNextGlbLightmapped!(Material.idOf(fol), Material.idOf(folMasked))
+      }
+      const lightmapped = !foliage && !!options.lightmap && !!_creator.setNextGlbLightmapped
+      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()), Material.idOf(Material._lightmapMaskedTemplate()))
+      _creator.createGlb((source as unknown as { _h: Handle })._h.id, (root) => {
+        if (!root) { reject(new Error("Failed to load GLB")); return }
+        const model = new Model(root)
+        const entityId = model.id
+        model._lightmapped = lightmapped
+        model._foliage = foliage
+        const culling = options.culling ?? Model._cullingDefault()
+        if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
+        resolve(model)
+      }, reject)
+    })
+  }
+}

package/src/gl/Node.ts

@@ -6,7 +6,8 @@
 // A GLB import is the Model node kind (with the Animator aspect at model.anim). Hierarchy lives here.
 
 import { AspectHost } from "../core/Aspect"
-import { Registry } from "../core/registry"
+import { DEAD_HANDLE, Pins, registerFreedKind } from "../core/pins"
+import { OWNED_KIND_GL_ENTITY } from "../ui/tree"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import { Quat, cw, type QuatLike } from "../math/quat"
 import { Mat4, type Mat4Like } from "../math/mat4"
@@ -31,7 +32,38 @@ export type NodeTweenProps = {
 }
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
-export const nodeRegistry = new Registry<Node>()
+/** @internal The nodes native owns right now (in a scene / under a parent, or engine-created), by
+ *  entity id — what a pick, a contact or an animation event resolves to. See core/pins.ts. */
+export const nodes = new Pins<Node>()
+
+// The loose wrappers, WEAKLY: a read-back (`parent` / `children` / `traverse` / `find`) must hand
+// back the app's OWN handle while it exists. A loose root has no native owner, so no pin — the
+// only other way to reach it from below was a throwaway wrapper, and anything put on that wrapper
+// (IK's rig Animator on a bare tree's top) was lost to the app's handle. WeakRef keeps the owned
+// model intact: the registry never holds a handle alive, a dropped root still finalizes, and a
+// dead entry is dropped when met (or in the sweep every SWEEP registrations).
+const loose = new Map<number, WeakRef<Node>>()
+const SWEEP = 256
+let sinceSweep = 0
+const registerLoose = (n: Node): void => {
+  loose.set(n._h.id, new WeakRef(n))
+  if (++sinceSweep < SWEEP) return
+  sinceSweep = 0
+  for (const [id, ref] of loose) { const w = ref.deref(); if (!w || w._h.id !== id) loose.delete(id) }
+}
+/** @internal The wrapper for an entity id the runtime handed back: the pinned one, else the
+ *  app's live loose handle, else a throwaway over the engine-owned id. */
+export const nodeOf = (id: number): Node => {
+  const pinned = nodes.get(id)
+  if (pinned) return pinned
+  const ref = loose.get(id)
+  if (ref) {
+    const w = ref.deref()
+    if (w && w._h.id === id) return w
+    loose.delete(id)
+  }
+  return new Node(id)
+}
 
 export type NodeEvents = {
   click: (ev: ClickEvent<Node | null>) => void
@@ -67,8 +99,12 @@ const findNodeByWalk = (rootId: number, name: string): number => {
 const worldScratch = new Float32Array(3)
 
 export class Node extends AspectHost<NodeEvents> implements CompWriter {
-  /** Native entity handle. */
-  readonly id: number
+  /** @internal The entity's owned handle (`_h.id` = the entity id; DEAD_HANDLE once destroyed). An
+   *  engine-created entity (a glTF part, an anchor) is wrapped from its number and pinned as the
+   *  engine's; an entity WE created is loose until it gets a parent or a scene. */
+  _h: Handle
+  /** Native entity id. */
+  get id(): number { return this._h.id }
 
   /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
    *  'track' / 'untrack' events; `false` for any non-anchor node. */
@@ -80,10 +116,20 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** Materials assigned through setMaterial, by primitive slot (a Mesh fills slot 0 itself). */
   protected _materials?: Material[]
 
-  constructor(internalId?: number) {
+  constructor(internalId?: number | Handle) {
     super()
-    this.id = internalId ?? _creator.createEntity()
-    nodeRegistry.set(this.id, this)
+    registerFreedKind(OWNED_KIND_GL_ENTITY, nodes)
+    if (internalId === undefined) {
+      const h = _creator.createEntity()
+      this._h = typeof h === "number" ? { id: h } : h   // a number only from a test stub
+      registerLoose(this)
+    } else if (typeof internalId === "number") {
+      this._h = { id: internalId }   // engine-owned: findable while the engine keeps it
+      nodes.pin(this)
+    } else {
+      this._h = internalId           // an owned root the runtime handed us (createGlb, cloneEntity)
+      registerLoose(this)
+    }
   }
 
   /** Geometry, if this node is a Mesh (used by physics auto-shape). Overridden by Mesh. */
@@ -263,29 +309,37 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   // --- hierarchy ---
   get parent(): Node | null {
     const id = _creator.getParent(this.id)
-    return id === 0 ? null : (nodeRegistry.get(id) ?? new Node(id))
+    return id === 0 ? null : nodeOf(id)
   }
   get children(): Node[] {
-    return _creator.getChildren(this.id).map((id) => nodeRegistry.get(id) ?? new Node(id))
+    const n = _creator.getChildCount(this.id)
+    const out: Node[] = []
+    for (let i = 0; i < n; i++) { const id = _creator.getChild(this.id, i); out.push(nodeOf(id)) }
+    return out
   }
   get childCount(): number { return _creator.getChildCount(this.id) }
   getChild(index: number): Node | null {
     const id = _creator.getChild(this.id, index)
-    return id === 0 ? null : (nodeRegistry.get(id) ?? new Node(id))
+    return id === 0 ? null : nodeOf(id)
   }
   /** Parent the given nodes under this one. */
   add(...children: Node[]): this {
-    for (const c of children) _creator.setParent(c.id, this.id, false)
+    for (const c of children) { _creator.setParent(c.id, this.id, false); nodes.pin(c) }
     return this
   }
   setParent(parent: Node | null, worldPositionStays = false): this {
-    if (parent === null) _creator.setParentNull(this.id, worldPositionStays)
-    else _creator.setParent(this.id, parent.id, worldPositionStays)
+    if (parent === null) {
+      _creator.setParentNull(this.id, worldPositionStays)
+      if (!_creator.entityIsOwned(this.id)) nodes.unpin(this.id)   // loose again: the handle owns it
+    } else {
+      _creator.setParent(this.id, parent.id, worldPositionStays)
+      nodes.pin(this)
+    }
     return this
   }
   traverse(callback: (node: Node) => void): void {
     callback(this)
-    _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
+    _creator.traverse(this.id, (id) => callback(nodeOf(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
@@ -313,7 +367,7 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
     const hit = cache.get(name)
     if (hit !== undefined) return hit
     const id = _creator.findNode ? _creator.findNode(this.id, name) : findNodeByWalk(this.id, name)
-    const found = id ? nodeRegistry.get(id) ?? new Node(id) : null
+    const found = id ? nodeOf(id) : null
     cache.set(name, found)
     return found
   }
@@ -372,16 +426,29 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
    *  `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 {
+    if (this._h.id === 0) return
     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)
+    _creator.traverse(this.id, (id) => { const n = nodes.get(id); if (n) subtree.push(n) })
+    for (let i = subtree.length - 1; i >= 0; i--) subtree[i]._detachAll()
+    const id = this.id
+    // Dead NOW — entity ids are recycled, and the runtime's freed report lands a drain later.
+    for (const n of subtree) { nodes.unpin(n.id); n._dead() }
+    _creator.destroyEntity(id)
+  }
+
+  /** @internal The wrapper's resource is gone: no more native calls from here. */
+  _dead(): void {
+    this._xf = 0
+    this._xfKind = 0
+    loose.delete(this._h.id)
+    this._h = DEAD_HANDLE
+  }
+  /** @internal The runtime freed the entity underneath (an ancestor destroyed or dropped): the
+   *  aspects detach (their onDetach runs after the entity is gone) and the wrapper is dead. */
+  _freed(): void {
+    if (this._h.id === 0) return
+    this._detachAll()
+    this._dead()
   }
 }
 

package/src/gl/Particles.ts

@@ -4,7 +4,7 @@
 // All emitter/curve config crosses the bridge as ONE Float32Array of [tag, payloadLen, ...payload]
 // records (_creator.setParticleSystemConfig) — the constructor batches every option into a single
 // call, live setters send a one-record buffer. The tag values mirror CPART_TAG_* in
-// creator-particles/include/creator-particles/creator-particles.h (guarded by tests/particles-tags.test.ts).
+// creator-particles/include/creator-particles/creator-particles.h (guarded by tests/gl/particles-tags.test.ts).
 //
 // Curves over a particle's lifetime are built with curve()/colorCurve() chains — see the builders
 // below. A builder's whole state is the flat `_data` array (the exact record payload), so the
@@ -42,6 +42,7 @@ const TAG_VELOCITY_LIFE = 19
 const TAG_ORDER = 20
 const TAG_SMOOTH_PATH = 21
 const TAG_RIBBON_ORIENT = 22
+const TAG_LIT = 23
 /** `TrailOptions.orient` → the native axis code (0 = the camera-facing default). */
 const RIBBON_AXIS: Record<"camera" | "x" | "y" | "z", number> = { camera: 0, x: 1, y: 2, z: 3 }
 
@@ -54,6 +55,7 @@ export const _particleTags = {
   RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
   ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
   ORDER: TAG_ORDER, SMOOTH_PATH: TAG_SMOOTH_PATH, RIBBON_ORIENT: TAG_RIBBON_ORIENT,
+  LIT: TAG_LIT,
 }
 
 // --- curve builders -----------------------------------------------------------------------------
@@ -304,6 +306,15 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
    *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
   order?: number
+  /** Sprites take the light of the PLACE each one is in — the level's baked light grid (`env.lightmap.volume`).
+   *  A sprite is unlit: its colour is the picture, which is right for fire and wrong for dust — a puff kicked up
+   *  under an awning glows as if it stood in the sun. With `lit` every particle's colour is multiplied by the light
+   *  where it is, relative to the level's OPEN ground: exactly the authored colour out in the sun, the ambient's
+   *  share of it (tinted the way the shade is) under a roof — per particle, so a trail of puffs laid from the sun
+   *  into the shade is lit along its length. Author the colour for the open; nothing else to tune. Without a grid
+   *  — a level with no bake, a host that has none — the colours are drawn as authored. Points, quads, stretch and
+   *  `Trail`; mesh particles are lit by their material. Default false. */
+  lit?: boolean
   /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
    *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
    *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
@@ -492,6 +503,7 @@ export class Particles extends Node {
     if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
     if (options.smooth !== undefined) out.push(TAG_SMOOTH_PATH, 1, options.smooth ? 1 : 0)
     if (options.order !== undefined) out.push(TAG_ORDER, 1, options.order)
+    if (options.lit !== undefined) out.push(TAG_LIT, 1, options.lit ? 1 : 0)
     if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
     if (options.shape !== undefined) pushShape(out, options.shape)
     if (options.velocityOverLife !== undefined) pushVelocityLife(out, options.velocityOverLife)
@@ -547,6 +559,8 @@ export class Particles extends Node {
   /** Lay a frame's spawns along a curve through the emitter's path, not the straight chord. */
   set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
   set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }
+  /** Colours × the baked light where each particle is — see `ParticlesOptions.lit`. */
+  set lit(val: boolean) { this._send([ TAG_LIT, 1, val ? 1 : 0 ]) }
   /** 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))))
@@ -644,6 +658,9 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
    *  frame rate, since a longer frame bows further off its own chord. Default false; see
    *  `ParticlesOptions.smooth`. */
   smooth?: boolean
+  /** The strip takes the baked light of the place each of its points is at — `ParticlesOptions.lit`. Smoke and
+   *  dust trails; leave it off for a glowing one. Default false. */
+  lit?: boolean
   /** Which way the strip's WIDTH points.
    *
    *  `'camera'` (default) rolls the strip about its own length to stay flat to the viewer — it can
@@ -689,6 +706,7 @@ export class Trail extends Node {
       TAG_LIFETIME, 2, time, time,
     ]
     if (options.smooth) out.push(TAG_SMOOTH_PATH, 1, 1)
+    if (options.lit) out.push(TAG_LIT, 1, 1)
     if (options.orient !== undefined || options.faceCamera !== undefined) {
       this._orient = RIBBON_AXIS[options.orient ?? "camera"]
       if (options.faceCamera !== undefined) this._faceCamera = options.faceCamera
@@ -732,6 +750,7 @@ export class Trail extends Node {
 
   /** Follow a curve through the emitter's path instead of the straight chord between frames. */
   set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
+  set lit(val: boolean) { this._send([ TAG_LIT, 1, val ? 1 : 0 ]) }
 
   /** Which way the strip's width points — see `TrailOptions.orient`. Keeps the current `faceCamera`. */
   set orient(val: "camera" | "x" | "y" | "z") {