lecodes-sdk 2.8.1 → 2.8.3

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.18.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.8.1",
+  "version": "2.8.3",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -317,6 +317,10 @@ declare global {
     /** @count count=pages */
     staticsBuildKind?(kind: u32, templateEntity: u32, pages: Uint32Array): u32
     staticsEnd?(): u32
+    /** The cached placement an engine-built static came from: its full node path, "" = not one. The paths outlive
+     *  `staticsEnd` (until the next `staticsBegin`; a destroyed entity is forgotten) so gl/Node.ts `nodeOf` can give
+     *  a hit wall its passive aspects from the scene's def. */
+    staticsPathOf?(entityId: u32): string
     setCulling(entityId: u32, culling: boolean): void
     /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
      *  Optional: an older host leaves everything at the default 4. */
@@ -912,6 +916,9 @@ declare global {
     physicsCreateBody(entityId: u32, shapeId: u32, motion: i32, mass: f32, sensor: boolean, pickOnly: boolean): u32
     /** @ifdef CREATOR_GL_PHYSICS */
     physicsSetPickable(bodyId: u32, pickable: boolean): void
+    /** The motion of the body on `entityId`: 0 static, 1 kinematic, 2 dynamic, -1 no body — read off the engine, so it
+     *  answers for a body the SDK never made (a static the level cache built). @ifdef CREATOR_GL_PHYSICS */
+    physicsMotionOf?(entityId: u32): i32
     /** Surface friction of one body (0 = ice, ~1 = grippy asphalt). Values COMBINE as sqrt(a * b), so
      *  a low value on either side dominates. New bodies start at 0.6 — a neutral solid surface.
      *  The vehicle wheel cast reads the GROUND body's value — this is what caps a car's cornering. @ifdef CREATOR_GL_PHYSICS */

package/src/bridges/tree.d.ts

@@ -267,14 +267,16 @@ export interface HostUI {
    *  dispatch bridge — `onComplete` with the result as ONE value, or with none.
    *  @immediate its callbacks and the borrowed `args` cannot wait for a commit */
   viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-  /** A LAYER root is shown: a pass-through root the runtime lays out at the frame, above every
-   *  destination (the app layer) or over the presented surface (a scene's / a native view's / a
-   *  video's content layer). Its own box is never hit — only its children are — so a touch outside
-   *  them reaches what is under the layer; it is painted after the destination, layers in open
-   *  order. Its children are widgets (the runtime inserts them with insertNode, as under a screen
-   *  root): a widget child with an overlay layer (`overlayColor`, any color — "transparent" too)
-   *  intercepts every touch outside its own box within its root and reports it as the overlay tap. */
-  layerOpen(node: nodeid): void
+  /** A LAYER root is shown: a pass-through root the runtime lays out at the frame. `surface` false =
+   *  the app layer, above everything, screens included; true = the content layer of the presented
+   *  surface (a scene's / a native view's / a video's widgets): right over the surface and UNDER
+   *  every screen — a screen that covers the surface covers its widgets, the screen that leaves
+   *  when the surface is pushed stays over them until its drop. Its own box is never hit — only its
+   *  children are — so a touch outside them reaches what is under the layer; layers of a kind paint
+   *  in open order. Its children are widgets (the runtime inserts them with insertNode, as under a
+   *  screen root): a widget child with an overlay layer (`overlayColor`, any color — "transparent"
+   *  too) intercepts every touch outside its own box within its root and reports it as the overlay tap. */
+  layerOpen(node: nodeid, surface: boolean): void
   /** The layer root is hidden (its view stays; releaseNode says when it is gone). */
   layerClose(node: nodeid): void
   /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle

package/src/core/Aspect.ts

@@ -533,6 +533,13 @@ export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}
   static after?: Function[]
   /** Tick BEFORE these classes within the same phase (`static before = [Camera]`). */
   static before?: Function[]
+  /** DATA ONLY. A `use(...)` of this aspect in a scene file leaves its node STATIC for the level cache (gl/Statics.ts):
+   *  the engine builds the node without a JS object, and the aspect is attached the first time a hit, a contact or
+   *  a pick reaches the node — `hit.node.get(Surface)` answers then. So: fields and the methods the game calls on a
+   *  hit (a tag like `Surface { kind }`, a breakable's hit points), no `update()` (`use()` refuses one) and nothing in
+   *  `onAttach()` the level needs from its first frame. Without it a custom aspect keeps its node on the JS path,
+   *  built at load like any mover. */
+  static passive?: boolean
 
   /** Every live instance of an aspect/system class, in attach order — the registry a game used to
    *  hand-roll as `static all[]`. Live, read-only: copy it (`[...Aspect.all(Barrel)]`) before a loop

package/src/g2/Scene2D.ts

@@ -203,9 +203,12 @@ export class Scene2D implements Presentable {
     return _surfaceWidgets(this)
   }
   /** @internal presentation lifecycle from the runtime */
-  _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
+  // The ACTIVE scene — what the pointer dispatch (g2/touch.ts) routes to — follows the runtime's
+  // presentation, not only open(): a Router.push / pop presents a scene without it, and the first
+  // push of a world had no active scene at all (every touch was dropped until an open() set one).
+  _emitOpen(): void { Scene2D._active = this; for (const cb of this.ol.slice()) cb() }
   /** @internal */
-  _emitClose(): void { for (const cb of this.cl.slice()) cb() }
+  _emitClose(): void { if (Scene2D._active === this) Scene2D._active = null; for (const cb of this.cl.slice()) cb() }
   /** @internal */
   _emitBack(): boolean {
     if (!this._backButtonCallback) return false

package/src/gl/Node.ts

@@ -51,8 +51,14 @@ const registerLoose = (n: Node): void => {
   sinceSweep = 0
   for (const [id, ref] of loose) { const w = ref.deref(); if (!w || w._h.id !== id) loose.delete(id) }
 }
+/** @internal The static level cache's hand into `nodeOf` (gl/Statics.ts sets it while a cached level is up):
+ *  `pathOf` names the placement an engine-built entity came from ("" = not one), `attach` gives that entity's
+ *  fresh wrapper the PASSIVE aspects of the placement's def (Aspect.passive). A wall the engine built has no JS
+ *  node until a hit, a contact or a pick reaches it — this is where it gets one, and its `Surface`, and only then. */
+export const lazyPlacements: { current: { pathOf(id: number): string, attach(node: Node, path: string): void } | null } = { current: null }
+
 /** @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. */
+ *  app's live loose handle, else a wrapper over the engine-owned id (pinned: the next ask finds it). */
 export const nodeOf = (id: number): Node => {
   const pinned = nodes.get(id)
   if (pinned) return pinned
@@ -62,7 +68,18 @@ export const nodeOf = (id: number): Node => {
     if (w && w._h.id === id) return w
     loose.delete(id)
   }
-  return new Node(id)
+  const n = new Node(id)
+  const lazy = lazyPlacements.current
+  if (lazy) { const path = lazy.pathOf(id); if (path) lazy.attach(n, path) }
+  return n
+}
+
+/** @internal `nodeOf(id)` when `id` is a placement the level cache built, else null — a hit inside a model walks
+ *  up to the placement's own entity (gl/touch.ts). */
+export const placementNodeOf = (id: number): Node | null => {
+  if (nodes.get(id)) return nodeOf(id)
+  const lazy = lazyPlacements.current
+  return lazy && lazy.pathOf(id) ? nodeOf(id) : null
 }
 
 export type NodeEvents = {
@@ -472,6 +489,8 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
 
   /** @internal — emit a physics contact/trigger event (the physics-event router can't reach dispatch). */
   _emitCollision(channel: "enter" | "exit", other: Node): void { this.dispatch(channel, other) }
+  /** @internal — does anyone listen on `channel` (the physics-event router asks before it makes a wrapper). */
+  _hasListeners(channel: keyof NodeEvents): boolean { return this.hasListeners(channel) }
 
 
   /** Destroy this node and its whole subtree. Every aspect in the subtree is detached first (its

package/src/gl/Scene.ts

@@ -526,9 +526,15 @@ export class Scene implements Presentable {
     return _surfaceWidgets(this)
   }
   /** @internal presentation lifecycle from the runtime */
-  _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
+  // The ACTIVE scene follows the runtime's presentation, not only open(): a Router.push / pop
+  // presents a scene without it (the 2D twin: Scene2D._emitOpen).
+  _emitOpen(): void { Scene._active = this; glState.activeScene = this; for (const cb of this.ol.slice()) cb() }
   /** @internal */
-  _emitClose(): void { for (const cb of this.cl.slice()) cb() }
+  _emitClose(): void {
+    if (Scene._active === this) Scene._active = null
+    if (glState.activeScene === this) glState.activeScene = null
+    for (const cb of this.cl.slice()) cb()
+  }
   /** @internal */
   _emitBack(): boolean {
     if (!this._backButtonCallback) return false

package/src/gl/Statics.ts

@@ -24,7 +24,7 @@
 
 import { fetch, assetNameOf, assetUrlOf, type FetchResponse } from "../runtime/fetch"
 import { Model, foliageKindOf, type FoliageKind } from "./Model"
-import { Node } from "./Node"
+import { Node, lazyPlacements } from "./Node"
 import { Scene } from "./Scene"
 import { Physics } from "./physics/Physics"
 import { Shape } from "./physics/Shape"
@@ -57,11 +57,49 @@ const movesByPhysics = (def: SceneNodeDef): boolean =>
     ((e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
     || (e.ctor as unknown) === CharacterController)
 
+/** A passive aspect (Aspect.passive): data the engine does not need — attached to the placement's wrapper on the
+ *  first hit (`attachPassive`), never built at load. */
+export const isPassive = (e: AspectEntry<any>): boolean => (e.ctor as { passive?: boolean }).passive === true
+
 const dataAspect = (e: AspectEntry<any>): boolean => {
   const c = e.ctor as unknown
   if (c === Shape) return true
   if (c === Physics) return ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") === "static"
-  return false
+  return isPassive(e)
+}
+
+/** Attach the passive aspects of `def` to `node` (props as written: a passive aspect is data, `ref()`s are not
+ *  resolved). Who gets them: the entity a hit comes back with. A placement's clone, on the first hit, through
+ *  `lazyPlacements` — a covered root with a model included, since its clone is what the ray strikes, not the plain
+ *  JS node the clone hangs under. A root WITHOUT a model (a group tagged `Surface` over its walls) has no clone:
+ *  its JS node takes them at load, and a hit on a wall under it finds them one `parent` up (a game's surface lookup
+ *  walks `hit.node.parent`). */
+export const attachPassive = (node: Node, def: SceneNodeDef): void => {
+  for (const e of def.aspects ?? []) if (isPassive(e)) (node as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(e.ctor, e.props)
+}
+
+/** The covered placements that carry passive aspects, by path: every def under the roots, and a root itself when
+ *  it has a model (its clone is a placement at the root's own path). A model-less root is not here — `attachPassive`
+ *  put its tags on its JS node at load. */
+const passiveByPath = (roots: CoveredRoot[], scene: SceneDef): Map<string, SceneNodeDef> => {
+  const out = new Map<string, SceneNodeDef>()
+  const walk = (defs: Record<string, SceneNodeDef> | undefined, prefix: string, stack: Set<SceneDef>): void => {
+    for (const [ name, nd ] of Object.entries(defs ?? {})) {
+      const path = prefix === "" ? name : `${prefix}/${name}`
+      if ((nd.aspects ?? []).some(isPassive)) out.set(path, nd)
+      walk(nd.children, path, stack)
+      const pdef = nd.prefab !== undefined ? (nd.prefab as { def?: SceneDef }).def : undefined
+      if (pdef && !stack.has(pdef)) walk(pdef.nodes, path, new Set(stack).add(pdef))
+    }
+  }
+  const stack = new Set<SceneDef>([ scene ])
+  for (const r of roots) {
+    if (r.def.model !== undefined && (r.def.aspects ?? []).some(isPassive)) out.set(r.path, r.def)
+    walk(r.def.children, r.path, stack)
+    const pdef = r.def.prefab !== undefined ? (r.def.prefab as { def?: SceneDef }).def : undefined
+    if (pdef && !stack.has(pdef)) walk(pdef.nodes, r.path, new Set(stack).add(pdef))
+  }
+  return out
 }
 
 const cacheable = (def: SceneNodeDef, stack: Set<SceneDef>): boolean => {
@@ -288,8 +326,16 @@ const templates: Model[] = []
 export const build = async (
   opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array,
   template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>,
+  covered: CoveredRoot[], def: SceneDef,
 ): Promise<number> => {
   const sceneId = (scene as unknown as { _id: number })._id
+  // the hand into nodeOf for this level's life (the next cached level replaces it; a level without passive
+  // aspects under its roots installs none — nodeOf then costs what it did)
+  const passive = passiveByPath(covered, def)
+  lazyPlacements.current = passive.size > 0 && _creator.staticsPathOf ? {
+    pathOf: (id) => _creator.staticsPathOf!(id),
+    attach: (node, path) => { const d = passive.get(path); if (d) attachPassive(node, d) },
+  } : null
   const kinds = _creator.staticsBegin!(sceneId, Uint32Array.from(roots.map((r) => r.id)), (opened.resp as unknown as { _h: { id: number } })._h.id)
   if (kinds !== opened.kinds.length) { console.warn(`[static] the engine declined the cache (${kinds} of ${opened.kinds.length} kinds)`); _creator.staticsEnd!(); return 0 }
   await Promise.all(opened.kinds.map(async (k, i) => {

package/src/gl/physics/CharacterController.ts

@@ -33,7 +33,9 @@
 // scaled directly instead of needing a child node for the visuals (a capsule is symmetric about its up
 // axis, so its yaw is physically irrelevant either way).
 //
-// CROUCHING goes through the Shape aspect (`node.aspect(Shape, { capsule: … })`) — see `resizing`.
+// CROUCHING is a property write on the Shape aspect (`hero.shape.capsule = …`) — see `resizing`. The
+// node (the capsule's centre) has moved by the feet difference when the write returns; a first-person
+// camera is placed from the FEET plus an eased eye height, never from the node (docs/3d/physics.md).
 //
 // Note: it collides with solid bodies but PASSES THROUGH triggers, and (v1) is not itself detected by
 // triggers and isn't pointer-pickable while active.
@@ -160,13 +162,18 @@ export class CharacterController extends Aspect<"controller", Node> implements C
    * True while a requested collider resize hasn't taken — you asked to stand up and there is something
    * overhead. Resizing goes through the `Shape` aspect itself:
    *
-   *     hero.aspect(Shape, { capsule: CROUCHED })   // always fits — you are shrinking
-   *     hero.aspect(Shape, { capsule: STANDING })   // may be refused under a low ceiling
-   *     if (hero.controller.resizing) …             // still crouched; call it again next frame
+   *     hero.shape.capsule = CROUCHED               // always fits — you are shrinking
+   *     hero.shape.capsule = STANDING               // may be refused under a low ceiling
+   *     if (hero.controller.resizing) …             // still crouched; write it again next frame
    *
    * A refusal changes nothing, so the retry is just the same call again — and it is an exact headroom
    * test against the real capsule, unlike a hand-rolled raycast (a ray is a line; a capsule has girth).
-   * The FEET stay planted across a resize, so the character neither hovers nor sinks.
+   * The FEET stay planted across a resize, so the character neither hovers nor sinks — which means the
+   * node (the capsule's centre) has ALREADY moved by the feet difference when the write returns. Place
+   * a first-person camera from the feet (`node.y − (halfHeight + radius)` of the capsule worn) plus an
+   * eased eye height; placed from the node it pops by that difference. Write the property: a second
+   * `node.aspect(Shape, …)` builds a fresh Shape (it is handed to the character too, but it is a
+   * rebuild per stance, not a resize).
    */
   get resizing(): boolean {
     return this.node.get(Shape)?._resizeRefused ?? false

package/src/gl/physics/Physics.ts

@@ -15,7 +15,7 @@ import { Aspect } from "../../core/Aspect"
 import type { FieldMeta } from "../../core/fields"
 import type { CompAxis, CompWriter } from "../../core/compWrite"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
-import { nodes, type Node } from "../Node"
+import { nodeOf, type Node } from "../Node"
 import { Shape } from "./Shape"
 
 export type MotionType = "static" | "dynamic" | "kinematic"
@@ -214,13 +214,27 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
     return typeof _creator !== "undefined" && !!_creator && typeof _creator.physicsHasSupport === "function" && _creator.physicsHasSupport()
   }
 
-  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+  /** The motion of the body on `node`, read off the engine: it answers for a body the SDK never made (a static the
+   *  level cache built, which has no `Physics` aspect until a hit reaches it, and no body-making one ever). null = no
+   *  body on this node. The way to tell a wall from a prop on a hit: `Physics.motionOf(hit.node) === "static"`. */
+  static motionOf(node: Node | null): MotionType | null {
+    if (!node) return null
+    if (_creator.physicsMotionOf) {
+      const m = _creator.physicsMotionOf(node.id)
+      return m === 0 ? "static" : m === 1 ? "kinematic" : m === 2 ? "dynamic" : null
+    }
+    return node.get(Physics)?.motion ?? null   // an older host: the aspect is all there is
+  }
+
+  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. `node` is the body's
+   *  node — for a static the level cache built, a wrapper made on this hit (Node.ts nodeOf), carrying the placement's
+   *  passive aspects; its `Physics` is read with `Physics.motionOf`. */
   static raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000): RayHit | null {
     const out = new Float32Array(7)
     const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
     if (!id) return null
     return {
-      node: nodes.get(id) ?? null,
+      node: nodeOf(id),
       point: new Vec3(out[0], out[1], out[2]),
       normal: new Vec3(out[3], out[4], out[5]),
       fraction: out[6],

package/src/gl/physics/Shape.ts

@@ -127,14 +127,25 @@ export class Shape extends Aspect<"shape", Node> {
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
     this._shapeId = this._build()
-    if (this._shapeId) this._createPickBody()
+    if (!this._shapeId) return
+    // A fresh Shape on a node a live CharacterController owns: `node.aspect(Shape, { capsule })`
+    // RE-ATTACHES (aspect() always builds), which is how a game is tempted to crouch. Hand the geometry
+    // to the character exactly as a property write does. A pick body here would instead take the
+    // node's position routing away from the character, and the capsule it wears would never change —
+    // the player's "how tall am I" switches while the body stays, and the eye pops by the difference.
+    if (this.node._xfKind === 1) {
+      if (!this._offerToCharacter(this.node._xf, this._shapeId)) this._sig = ""   // uncommitted: the next write retries
+      return
+    }
+    this._createPickBody()
   }
 
   onDetach(): void {
     if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
     if (this._shapeId) { _creator.physicsDestroyShape(this._shapeId); this._shapeId = 0 }
-    this.node._xf = 0
-    this.node._xfKind = 0
+    // The routing is this Shape's to clear only while one of ITS bodies carries it. A live
+    // CharacterController keeps its own, and the geometry it wears (Jolt holds a reference to it).
+    if (this.node._xfKind !== 1) { this.node._xf = 0; this.node._xfKind = 0 }
   }
 
   /** A dimension, the kind or the origin was written: rebuild the geometry when it actually changed.
@@ -298,17 +309,12 @@ export class Shape extends Aspect<"shape", Node> {
     // and tries again. That retry is the headroom test, and it is exact (the real capsule, not a ray).
     const charId = this.node._xfKind === 1 ? this.node._xf : 0
     if (charId) {
-      if (_creator.characterSetShape?.(charId, id)) {
+      if (this._offerToCharacter(charId, id)) {
         this._shapeId = id
-        this._resizeRefused = false
         _creator.physicsDestroyShape(previous)
       } else {
         _creator.physicsDestroyShape(id)     // drop what we just built; the old collider stays live
         this._sig = previousSig
-        this._resizeRefused = !!_creator.characterSetShape
-        if (!_creator.characterSetShape) {
-          console.warn(`Shape: this host can't resize a live CharacterController — "${this.node.name}" keeps its current collider`)
-        }
       }
       return
     }
@@ -327,6 +333,20 @@ export class Shape extends Aspect<"shape", Node> {
    *  is still using another. Surfaced as `controller.resizing`. */
   _resizeRefused = false
 
+  /** The character this node belongs to tries the geometry on. Jolt validates the fit (standing up
+   *  under a pipe) and can refuse; a refusal changes nothing in the engine. The feet stay planted, so
+   *  on success the node has already moved by the change in the shape's lower bound when this returns. */
+  private _offerToCharacter(charId: number, shapeId: number): boolean {
+    if (!_creator.characterSetShape) {
+      console.warn(`Shape: this host can't resize a live CharacterController — "${this.node.name}" keeps its current collider`)
+      this._resizeRefused = false
+      return false
+    }
+    const ok = _creator.characterSetShape(charId, shapeId)
+    this._resizeRefused = !ok
+    return ok
+  }
+
   private _build(): number {
     this._autoOrigin = null
     this._sig = this._signature()

package/src/gl/physics/physicsEvents.ts

@@ -2,7 +2,7 @@
 // is delivered to BOTH nodes with the other as the argument. type: 0 = enter (contact/overlap began),
 // 1 = exit (ended). Registered lazily on the first trigger/physics body or 'enter'/'exit' listener.
 
-import { nodes } from "../Node"
+import { nodes, nodeOf } from "../Node"
 
 let registered = false
 export const ensurePhysicsEvents = (): void => {
@@ -10,10 +10,15 @@ export const ensurePhysicsEvents = (): void => {
   if (!_creator.setOnPhysicsEvent) return // physics-less build / bridge without the hook
   registered = true
   _creator.setOnPhysicsEvent((a, b, type) => {
-    const na = nodes.get(a)
-    const nb = nodes.get(b)
-    if (!na || !nb) return
+    const ka = nodes.get(a)
+    const kb = nodes.get(b)
     const channel = type === 1 ? "exit" : "enter"
+    // nobody listening on either side: nothing to deliver, and no wrapper made for the other side (a car's
+    // wheels touch every tile of a road the level cache built — a wrapper each would be 15k for nothing)
+    if (!ka?._hasListeners(channel) && !kb?._hasListeners(channel)) return
+    // the side nobody holds (a static the engine built) gets its wrapper now, passive aspects and all (Node.ts nodeOf)
+    const na = ka ?? nodeOf(a)
+    const nb = kb ?? nodeOf(b)
     na._emitCollision(channel, nb)
     nb._emitCollision(channel, na)
   })

package/src/gl/touch.ts

@@ -3,7 +3,7 @@
 
 import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch"
 import { ensureEmitter, setSceneTouchHandlers } from "../ui/tree"
-import { nodes } from "./Node"
+import { nodes, placementNodeOf } from "./Node"
 import { glState } from "./state"
 
 // Hits inside a loaded model (GLB) land on sub-entities the user never created a Node for — walk up
@@ -15,6 +15,9 @@ const resolveHitNode = (entityId: number) => {
     if (id === 0) break
     node = nodes.get(id)
   }
+  // nobody holds any of them: a static the level cache built — its placement's entity up the chain gets a wrapper
+  // now (Node.ts nodeOf), passive aspects and all
+  for (let id = entityId, i = 0; !node && id !== 0 && i < 32; i++, id = _creator.getParent(id)) node = placementNodeOf(id) ?? undefined
   return node ?? null
 }
 

package/src/scene/defineScene.ts

@@ -53,7 +53,7 @@ import { Model, foliageKindOf, type FoliageKind } from "../gl/Model"
 import { Physics } from "../gl/physics/Physics"
 import { CharacterController } from "../gl/physics/CharacterController"
 import { Lightmap, type LightmapDef, type LightmapPrepared } from "../gl/Lightmap"
-import { coveredRoots, defsDigest, bakeDigest, findNode, open as staticsOpen, build as staticsBuild, snapshot as staticsSnapshot, staticsConfig, toolRun, type CoveredRoot, type OpenedCache } from "../gl/Statics"
+import { coveredRoots, defsDigest, bakeDigest, findNode, open as staticsOpen, build as staticsBuild, snapshot as staticsSnapshot, staticsConfig, toolRun, attachPassive, type CoveredRoot, type OpenedCache } from "../gl/Statics"
 import { Foliage, type FoliageOptions } from "../gl/Foliage"
 import { NavMesh } from "../gl/nav/NavMesh"
 import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
@@ -918,6 +918,9 @@ const buildNodes = async (
       if (parentNode) attachHost(parentNode, nd, path).add(node)
       scene.add(node)
       applyNode(node, name, nd)
+      // a root with a model is itself a placement: its clone takes the tags on the first hit (Statics.ts). A group
+      // root has no clone — its tags go here, one `parent` up from a hit on a wall under it
+      if (nd.model === undefined) attachPassive(node, nd)
       cov.node = node
       nodes[path] = node
       return
@@ -1028,7 +1031,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   let cachedMade = 0
   if (opened) {
     const pages = prepared ? Lightmap.pageIds(prepared) : new Uint32Array(0)
-    cachedMade = await staticsBuild(opened, scene, roots.map((r) => covered.get(r.path)!.node!), pages, templateModel)
+    cachedMade = await staticsBuild(opened, scene, roots.map((r) => covered.get(r.path)!.node!), pages, templateModel, roots, def)
   }
   const nodesMs = Date.now() - tLoad
   if (navmesh && !(EDITOR && isEditMode())) registerNavOverrides(def.nodes, nodes)

package/src/scene/grammar.ts

@@ -17,8 +17,16 @@ export type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = {
 
 /** Reference an aspect in a scene file: `aspects: [use(Physics, { motion: 'static' })]`. Props are
  *  typechecked against the aspect's fields, exactly like `node.aspect(Ctor, props)`. */
-export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> =>
-  ({ __use: true, ctor, props })
+export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> => {
+  // a passive aspect (Aspect.passive) is data: the level cache attaches it on the first hit, so an update() on it
+  // would never have run from the level's first frame — refused here, at the scene's own line, not in a raycast
+  if ((ctor as { passive?: boolean }).passive === true) {
+    const proto = (ctor as unknown as { prototype: Record<string, unknown> }).prototype
+    if (typeof proto.update === "function" || typeof proto.updateBefore === "function" || typeof proto.updateFixed === "function")
+      throw new Error(`use(${(ctor as { name?: string }).name ?? "?"}): a passive aspect carries data only — it cannot have update(); drop \`static passive\` or the update`)
+  }
+  return { __use: true, ctor, props }
+}
 
 /** A `make(fn, args)` source entry — see {@link make}. `N` is the node family the factory returns
  *  (3D `Node` by default; a `.scene2d.ts` file's factories return `Node2D`). */

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.8.1"
+export const SDK_VERSION = "2.8.3"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {