lecodes-sdk 1.2.0 → 2.0.0

package/src/gl/Mesh.ts

@@ -1,120 +1,120 @@
-// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
-// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
-
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import {
-  Geometry,
-  type CapsuleOptions,
-  type CylinderOptions,
-  type PlaneOptions,
-  type SphereOptions,
-} from "./Geometry"
-import { Material } from "./Material"
-import { Node } from "./Node"
-
-/** Common transform/render options every primitive factory accepts. */
-export type MeshOptions = {
-  material?: Material
-  position?: Vec3Like
-  eulerAngles?: Vec3Like
-  scale?: Vec3Like | number
-  name?: string
-  castShadows?: boolean
-  receiveShadows?: boolean
-  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
-  renderPriority?: number
-}
-
-export class Mesh extends Node {
-  private _geometry?: Geometry
-
-  constructor(geometry?: Geometry, material?: Material) {
-    super()
-    if (geometry) {
-      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, geometry.uv1, geometry.colors)
-    }
-  }
-
-  override get geometry(): Geometry | undefined { return this._geometry }
-  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
-   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
-  setGeometry(geometry: Geometry): this {
-    this._geometry = geometry
-    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
-    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
-    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
-    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
-    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
-    if (this._culling !== undefined) this.culling = this._culling
-    if (this._castShadows !== undefined) this.castShadows = this._castShadows
-    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
-    return this
-  }
-  private _renderPriority?: number
-  private _culling?: boolean
-  private _castShadows?: boolean
-  private _receiveShadows?: boolean
-
-  /** 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) { this._culling = v; _creator.setCulling(this.id, v) }
-  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
-   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
-   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
-   *  after it can cover it. Write-only; a host that predates the call ignores it. */
-  set renderPriority(v: number) {
-    this._renderPriority = v
-    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
-    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
-  }
-  private static _warnedPriority = false
-  set castShadows(v: boolean) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
-  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
-
-  // --- factories ---
-
-  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    // 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 {
-    return apply(new Mesh(Geometry.sphere(options), options.material), options)
-  }
-
-  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
-  }
-
-  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
-  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.capsule(options), options.material), options)
-  }
-
-  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.plane(options), options.material), options)
-  }
-
-  /** Wrap a custom Geometry. */
-  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
-    return apply(new Mesh(geometry, options.material), options)
-  }
-}
-
-const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
-
-const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
-  if (o.position) mesh.position = o.position
-  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
-  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
-  if (o.name !== undefined) mesh.name = o.name
-  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
-  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
-  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
-  return mesh
-}
+// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
+// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
+
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import {
+  Geometry,
+  type CapsuleOptions,
+  type CylinderOptions,
+  type PlaneOptions,
+  type SphereOptions,
+} from "./Geometry"
+import { Material } from "./Material"
+import { Node } from "./Node"
+
+/** Common transform/render options every primitive factory accepts. */
+export type MeshOptions = {
+  material?: Material
+  position?: Vec3Like
+  eulerAngles?: Vec3Like
+  scale?: Vec3Like | number
+  name?: string
+  castShadows?: boolean
+  receiveShadows?: boolean
+  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
+  renderPriority?: number
+}
+
+export class Mesh extends Node {
+  private _geometry?: Geometry
+
+  constructor(geometry?: Geometry, material?: Material) {
+    super()
+    if (geometry) {
+      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, geometry.uv1, geometry.colors)
+    }
+  }
+
+  override get geometry(): Geometry | undefined { return this._geometry }
+  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
+   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
+  setGeometry(geometry: Geometry): this {
+    this._geometry = geometry
+    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
+    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
+    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
+    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
+    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
+    if (this._culling !== undefined) this.culling = this._culling
+    if (this._castShadows !== undefined) this.castShadows = this._castShadows
+    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
+    return this
+  }
+  private _renderPriority?: number
+  private _culling?: boolean
+  private _castShadows?: boolean
+  private _receiveShadows?: boolean
+
+  /** 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) { this._culling = v; _creator.setCulling(this.id, v) }
+  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
+   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
+   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
+   *  after it can cover it. Write-only; a host that predates the call ignores it. */
+  set renderPriority(v: number) {
+    this._renderPriority = v
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
+  }
+  private static _warnedPriority = false
+  set castShadows(v: boolean) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
+
+  // --- factories ---
+
+  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
+    // 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 {
+    return apply(new Mesh(Geometry.sphere(options), options.material), options)
+  }
+
+  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
+  }
+
+  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
+  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.capsule(options), options.material), options)
+  }
+
+  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.plane(options), options.material), options)
+  }
+
+  /** Wrap a custom Geometry. */
+  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
+    return apply(new Mesh(geometry, options.material), options)
+  }
+}
+
+const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
+
+const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
+  if (o.position) mesh.position = o.position
+  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
+  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
+  if (o.name !== undefined) mesh.name = o.name
+  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
+  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
+  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
+  return mesh
+}

package/src/gl/Model.ts

@@ -5,7 +5,7 @@
 //   hero.anim.play('Run', { loop: true })
 
 import { fetch, type FetchResponse } from "../runtime/fetch"
-import { Node } from "./Node"
+import { Node, nodes } from "./Node"
 import { Animator, _pushLod, type LodMode } from "./animation/Animator"
 import { Material } from "./Material"
 
@@ -20,12 +20,16 @@ export interface TrianglePick {
   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 }[] }[]
 }
@@ -47,7 +51,7 @@ export class Model extends Node {
   /** @internal -1 = auto (see `lod`) */
   _lodMesh = -1
 
-  constructor(internalId: number) {
+  constructor(internalId: number | Handle) {
     super(internalId)
     this.aspect(Animator)
   }
@@ -95,16 +99,16 @@ export class Model extends Node {
    *  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
+    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 id = _creator.cloneEntity(this.id)
-    const m = new Model(id)
+    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
@@ -124,7 +128,7 @@ export class Model extends Node {
       /** 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
+      /** 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. */
@@ -141,21 +145,22 @@ export class Model extends Node {
       })
     }
     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
+      // 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.idOf(Material._foliageTemplate())
-        const folMasked = fol ? Material.idOf(Material._foliageMaskedTemplate()) : 0
-        foliage = fol > 0 && folMasked > 0
-        if (foliage) _creator.setNextGlbLightmapped!(fol, folMasked)
+        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 { _id: number })._id, (entityId: number) => {
-        if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
-        const model = new Model(entityId)
+      _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()

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