lecodes-sdk 0.20.2 → 1.0.0

package/src/gl/{AudioZone.ts → audio/AudioZone.ts}

@@ -1,75 +1,75 @@
-// A reverb zone, as an aspect on a Node (docs/audio-plan.md §2): a box or sphere volume that
-// follows the node; while the listener is inside, the zone's reverb blends onto a bus (the bus's
-// own reverb outside it). Zones nest: the smallest one containing the listener wins. `blend` is
-// how many metres inside the border the crossfade takes — walking through a doorway is smooth.
-//
-//   new Node().aspect(AudioZone, { box: [6, 2.5, 6], reverb: 'hall', blend: 2 })
-//   corridor.aspect(Shape, { box: [1, 1.5, 8] }).aspect(AudioZone, { reverb: 'bathroom' })  // the Shape's box
-//
-// Sizes follow Shape's convention: `box` = HALF-extents, `sphere` = radius, in the node's local
-// units (the node's scale applies). Without host audio the aspect is inert.
-
-import { Aspect } from "../core/Aspect"
-import { reverbBlock, type ReverbParams, type ReverbPreset } from "../audio/Bus"
-import { audio } from "../audio/audio"
-import { audioSupported } from "../audio/support"
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import type { Node } from "./Node"
-import { Shape } from "./Shape"
-
-export class AudioZone extends Aspect<"audioZone", Node> {
-  static readonly aspect = "audioZone"
-
-  private _box: Vec3Like | null = null
-  private _sphere: number | null = null
-  private _reverb: ReverbPreset | ReverbParams = "room"
-  private _blend = 1
-  private _bus = "sfx"
-  /** @internal engine zone id. */
-  _id = 0
-  /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
-  get id(): number { return this._id }
-
-  /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
-  get box(): Vec3Like | null { return this._box }
-  set box(v: Vec3Like | null) { this._box = v; if (v) this._sphere = null; this._push() }
-  /** Radius; falls back to the node's Shape sphere. */
-  get sphere(): number | null { return this._sphere }
-  set sphere(v: number | null) { this._sphere = v; if (v !== null) this._box = null; this._push() }
-  /** A preset name or explicit params (see Bus.reverb). */
-  get reverb(): ReverbPreset | ReverbParams { return this._reverb }
-  set reverb(v: ReverbPreset | ReverbParams) { this._reverb = v; this._push() }
-  /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
-  get blend(): number { return this._blend }
-  set blend(v: number) { this._blend = v; this._push() }
-  /** The bus the zone's reverb rides on. Default `sfx`. */
-  get bus(): string { return this._bus }
-  set bus(v: string) { this._bus = v; this._push() }
-
-  onAttach(): void {
-    if (!audioSupported) return
-    this._id = _creatorAudio.createZone()
-    if (!this._id) return
-    _creatorAudio.attachZone(this._id, this.node.id)
-    this._push()
-  }
-
-  onDetach(): void {
-    if (this._id && audioSupported) _creatorAudio.destroyZone(this._id)
-    this._id = 0
-  }
-
-  private _push(): void {
-    if (!this._id || !audioSupported) return
-    let box = this._box, sphere = this._sphere
-    if (!box && sphere === null) {
-      const shape = this.node.get(Shape)
-      if (shape?.sphere !== undefined) sphere = shape.sphere
-      else if (shape?.box) box = shape.box
-    }
-    const dims = sphere !== null
-      ? new Float32Array([ sphere * 2, sphere * 2, sphere * 2 ])
-      : new Float32Array(box ? [ cx(box) * 2, cy(box) * 2, cz(box) * 2 ] : [ 2, 2, 2 ])
-    _creatorAudio.setZone(this._id, sphere !== null ? 1 : 0, dims, this._blend, audio._busId(this._bus), reverbBlock(this._reverb))
-  }
-}
+// A reverb zone, as an aspect on a Node (docs/audio-plan.md §2): a box or sphere volume that
+// follows the node; while the listener is inside, the zone's reverb blends onto a bus (the bus's
+// own reverb outside it). Zones nest: the smallest one containing the listener wins. `blend` is
+// how many metres inside the border the crossfade takes — walking through a doorway is smooth.
+//
+//   new Node().aspect(AudioZone, { box: [6, 2.5, 6], reverb: 'hall', blend: 2 })
+//   corridor.aspect(Shape, { box: [1, 1.5, 8] }).aspect(AudioZone, { reverb: 'bathroom' })  // the Shape's box
+//
+// Sizes follow Shape's convention: `box` = HALF-extents, `sphere` = radius, in the node's local
+// units (the node's scale applies). Without host audio the aspect is inert.
+
+import { Aspect } from "../../core/Aspect"
+import { reverbBlock, type ReverbParams, type ReverbPreset } from "../../audio/Bus"
+import { audio } from "../../audio/audio"
+import { audioSupported } from "../../audio/support"
+import { cx, cy, cz, type Vec3Like } from "../../math/vec"
+import type { Node } from "../Node"
+import { Shape } from "../physics/Shape"
+
+export class AudioZone extends Aspect<"audioZone", Node> {
+  static readonly aspect = "audioZone"
+
+  private _box: Vec3Like | null = null
+  private _sphere: number | null = null
+  private _reverb: ReverbPreset | ReverbParams = "room"
+  private _blend = 1
+  private _bus = "sfx"
+  /** @internal engine zone id. */
+  _id = 0
+  /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
+  get id(): number { return this._id }
+
+  /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
+  get box(): Vec3Like | null { return this._box }
+  set box(v: Vec3Like | null) { this._box = v; if (v) this._sphere = null; this._push() }
+  /** Radius; falls back to the node's Shape sphere. */
+  get sphere(): number | null { return this._sphere }
+  set sphere(v: number | null) { this._sphere = v; if (v !== null) this._box = null; this._push() }
+  /** A preset name or explicit params (see Bus.reverb). */
+  get reverb(): ReverbPreset | ReverbParams { return this._reverb }
+  set reverb(v: ReverbPreset | ReverbParams) { this._reverb = v; this._push() }
+  /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
+  get blend(): number { return this._blend }
+  set blend(v: number) { this._blend = v; this._push() }
+  /** The bus the zone's reverb rides on. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createZone()
+    if (!this._id) return
+    _creatorAudio.attachZone(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroyZone(this._id)
+    this._id = 0
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    let box = this._box, sphere = this._sphere
+    if (!box && sphere === null) {
+      const shape = this.node.get(Shape)
+      if (shape?.sphere !== undefined) sphere = shape.sphere
+      else if (shape?.box) box = shape.box
+    }
+    const dims = sphere !== null
+      ? new Float32Array([ sphere * 2, sphere * 2, sphere * 2 ])
+      : new Float32Array(box ? [ cx(box) * 2, cy(box) * 2, cz(box) * 2 ] : [ 2, 2, 2 ])
+    _creatorAudio.setZone(this._id, sphere !== null ? 1 : 0, dims, this._blend, audio._busId(this._bus), reverbBlock(this._reverb))
+  }
+}

package/src/gl/{SceneAudio.ts → audio/SceneAudio.ts}

@@ -3,8 +3,8 @@
 // engine reads whatever camera it renders with. Set a node to listen from somewhere else (the
 // player's head in a third-person game, so sounds pan around the character, not the camera).
 
-import { audioSupported } from "../audio/support"
-import type { Node } from "./Node"
+import { audioSupported } from "../../audio/support"
+import type { Node } from "../Node"
 
 export class SceneAudio {
   private _listener: Node | null = null

package/src/gl/{NavAgent.ts → nav/NavAgent.ts}

@@ -20,12 +20,12 @@
 // Without a loaded NavMesh the aspect is inert — `goTo` returns false, nothing throws — so a
 // project stays runnable on a host without navigation.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { CharacterController } from "./CharacterController"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { CharacterController } from "../physics/CharacterController"
 import { NavCrowd, NavMesh, NAV_AGENT, NAV_READ } from "./NavMesh"
-import type { Node } from "./Node"
+import type { Node } from "../Node"
 
 export type NavAgentState = "idle" | "moving" | "arrived" | "blocked" | "offmesh"
 export type NavAgentAvoidance = "off" | "low" | "medium" | "high"

package/src/gl/{NavMesh.ts → nav/NavMesh.ts}

@@ -18,14 +18,14 @@
 // (creator-nav) is the algorithms and the per-step hot path: ONE crowd update + ONE flat read per
 // fixed step for every agent in the scene (`NavCrowd`, a system the mesh attaches to its scene).
 
-import { fetch } from "../runtime/fetch"
-import { System } from "../core/Aspect"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { Geometry } from "./Geometry"
-import { Material } from "./Material"
-import { Mesh } from "./Mesh"
-import type { Node } from "./Node"
-import type { Scene } from "./Scene"
+import { fetch } from "../../runtime/fetch"
+import { System } from "../../core/Aspect"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { Geometry } from "../Geometry"
+import { Material } from "../Material"
+import { Mesh } from "../Mesh"
+import type { Node } from "../Node"
+import type { Scene } from "../Scene"
 import type { NavAgent } from "./NavAgent"
 
 // Fixed-order layouts — keep in step with creator-nav/creator-nav.h (CNAV_AGENT_* / CNAV_READ_*).

package/src/gl/{CharacterController.ts → physics/CharacterController.ts}

@@ -38,12 +38,12 @@
 // 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.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Vec3, cx, cy, cz, type Vec2Like, type Vec3Like } from "../math/vec"
-import type { CompAxis, CompWriter } from "../core/compWrite"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Vec3, cx, cy, cz, type Vec2Like, type Vec3Like } from "../../math/vec"
+import type { CompAxis, CompWriter } from "../../core/compWrite"
 import { Shape } from "./Shape"
-import type { Node } from "./Node"
+import type { Node } from "../Node"
 
 /** Where the character's feet are, as reported by the solver after the last step. */
 export type GroundState = "ground" | "slope" | "unsupported" | "air"

package/src/gl/{Physics.ts → physics/Physics.ts}

@@ -11,11 +11,11 @@
 // velocity / applyImpulse. Reading node.position is free (native already wrote it). A `position` write
 // is a TELEPORT that reaches the body (Shape routes it), which is how a kinematic body is placed too.
 
-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 { nodeRegistry, type Node } from "./Node"
+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 { nodeRegistry, type Node } from "../Node"
 import { Shape } from "./Shape"
 
 export type MotionType = "static" | "dynamic" | "kinematic"
@@ -95,6 +95,7 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
   }
 
   private _bodyId = 0
+  private static _refusedWarned = false
 
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
@@ -107,6 +108,12 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
     }
     const shapeId = shape._claim() // drop the pick-only body; reuse its shape
     this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
+    // The engine refuses a body past its limit (4 096 unless configured) — silently, and a level that
+    // crosses it loses whatever loads LAST (the terrain, streamed in after the props): say so once.
+    if (!this._bodyId && shapeId && !Physics._refusedWarned) {
+      Physics._refusedWarned = true
+      console.warn(`Physics: the engine refused a body for "${this.node.name}" — the body limit is reached? Raise it before the level loads: Physics.configure({ maxBodies })`)
+    }
     // A fresh body already carries DEFAULT_FRICTION host-side, so only a NAMED surface has to
     // travel — the common case costs no bridge call at all.
     if (this._friction !== DEFAULT_FRICTION) _creator.physicsSetFriction?.(this._bodyId, this._friction)

package/src/gl/{Ragdoll.ts → physics/Ragdoll.ts}

@@ -26,10 +26,10 @@
 // lie: the pose holds, nothing can wake them, the solver skips them. Raycasts hit it either way, and
 // a frozen `'all'` body is an obstacle you can stand on.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import { Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { Node } from "../Node"
 import { DEFAULT_FRICTION } from "./Physics"
 
 export interface RagdollHinge {
@@ -71,7 +71,8 @@ const STRIDE = 12
 
 // Bone names per humanoid role, tried in order: Mixamo / MotusMan / Unity-style first, then UE-style.
 // `node.bone()` already matches the part after a `:` / `|` prefix (`mixamorig:Hips`).
-const HUMANOID: Record<string, string[]> = {
+/** @internal shared with DynamicBone's `colliders: 'humanoid'` */
+export const HUMANOID: Record<string, string[]> = {
   hips: [ "Hips", "pelvis", "Pelvis", "hip" ],
   spine: [ "Spine", "spine_01", "spine", "Spine1" ],
   neck: [ "Neck", "neck_01", "neck" ],
@@ -96,7 +97,8 @@ const HUMANOID: Record<string, string[]> = {
  *  legs, hands and feet where the rig has them): sizes for a ~1.8 m human, mass shares from body
  *  segment tables, knees and elbows as hinges that fold the natural way for a model standing in a
  *  T- or A-pose facing +Z. */
-const humanoidParts = (find: (role: string) => string | null): RagdollPart[] => {
+/** @internal shared with DynamicBone's `colliders: 'humanoid'` */
+export const humanoidParts = (find: (role: string) => string | null): RagdollPart[] => {
   const hips = find("hips"), spine = find("spine"), neck = find("neck"), head = find("head")
   if (!hips) throw new Error("Ragdoll 'humanoid': no hips bone (Hips / pelvis) on this model — list the parts by name")
   const parts: RagdollPart[] = []

package/src/gl/{Shape.ts → physics/Shape.ts}

@@ -17,9 +17,9 @@
 // pick body is a STATIC snapshot at attach time — for a moving pickable object add a Physics body
 // (which follows the sim), rather than relying on the pick body.
 
-import { Aspect } from "../core/Aspect"
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import type { Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import { cx, cy, cz, type Vec3Like } from "../../math/vec"
+import type { Node } from "../Node"
 
 /** Which geometry a Shape uses — the one-of the fields below encode (see `_build`'s order). */
 export type ShapeKind = "auto" | "box" | "sphere" | "cylinder" | "capsule" | "mesh" | "convex" | "heightfield"

package/src/gl/{Trigger.ts → physics/Trigger.ts}

@@ -1,45 +1,45 @@
-// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
-// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
-// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
-//
-//   const goal = new Mesh(box(), material)
-//     .aspect(Shape, { box: [1, 2, 1] })
-//     .aspect(Trigger)
-//   goal.addEventListener('enter', other => win(other))
-//   goal.addEventListener('exit',  other => …)
-
-import { Aspect } from "../core/Aspect"
-import { Shape } from "./Shape"
-import { ensurePhysicsEvents } from "./physicsEvents"
-import type { Node } from "./Node"
-
-export class Trigger extends Aspect<"trigger", Node> {
-  static readonly aspect = "trigger"
-
-  private _bodyId = 0
-  /** Native body id (0 if no physics support). */
-  get id(): number { return this._bodyId }
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
-    if (!shape) {
-      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
-    }
-    const shapeId = shape._claim()
-    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
-    shape._ownBody(this._bodyId)
-    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
-  }
-
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    const shape = this.node.get(Shape)
-    if (shape) {
-      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
-      shape._recreatePickBody()
-    }
-  }
-
-  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
-}
+// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
+//
+//   const goal = new Mesh(box(), material)
+//     .aspect(Shape, { box: [1, 2, 1] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => …)
+
+import { Aspect } from "../../core/Aspect"
+import { Shape } from "./Shape"
+import { ensurePhysicsEvents } from "./physicsEvents"
+import type { Node } from "../Node"
+
+export class Trigger extends Aspect<"trigger", Node> {
+  static readonly aspect = "trigger"
+
+  private _bodyId = 0
+  /** Native body id (0 if no physics support). */
+  get id(): number { return this._bodyId }
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    const shapeId = shape._claim()
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
+    shape._ownBody(this._bodyId)
+    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()
+    }
+  }
+
+  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
+}

package/src/gl/{physicsEvents.ts → 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 { nodeRegistry } from "./Node"
+import { nodeRegistry } from "../Node"
 
 let registered = false
 export const ensurePhysicsEvents = (): void => {

package/src/gl/{Terrain.ts → terrain/Terrain.ts}

@@ -31,16 +31,16 @@
 // headless, an older build) gets the same chunks as child Mesh nodes from gl/terrainMesh.ts — the
 // project runs everywhere, normal maps just read flat there.
 
-import { Node } from "./Node"
-import { Mesh } from "./Mesh"
-import { Model } from "./Model"
-import { Material } from "./Material"
-import { Texture } from "./Texture"
-import { Geometry } from "./Geometry"
-import { Shape } from "./Shape"
-import { Color, type ColorInput } from "../core/color"
-import { fetch } from "../runtime/fetch"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Node } from "../Node"
+import { Mesh } from "../Mesh"
+import { Model } from "../Model"
+import { Material } from "../Material"
+import { Texture } from "../Texture"
+import { Geometry } from "../Geometry"
+import { Shape } from "../physics/Shape"
+import { Color, type ColorInput } from "../../core/color"
+import { fetch } from "../../runtime/fetch"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
 import {
   buildTerrainChunk, chunkCounts, faceNormalAt, gridRaycast, heightAt as gridHeightAt, normalAt as gridNormalAt, type TerrainGrid,
 } from "./terrainMesh"

package/src/gl/{terrainMesh.ts → terrain/terrainMesh.ts}

@@ -9,7 +9,7 @@
 //     read wrong on those hosts — the accepted fallback cost.
 // Keep the hole / split rule in step with terrain.cpp buildChunk and Jolt's HeightFieldShape.
 
-import { Geometry } from "./Geometry"
+import { Geometry } from "../Geometry"
 
 export type TerrainGrid = {
   sizeX: number