lecodes-sdk 2.8.1 → 2.8.2

package/dist/types/core/Aspect.d.ts

@@ -78,6 +78,13 @@ export declare abstract class Aspect<K extends string, P = Node, E extends Event
     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
      *  that detaches. Empty in the scene editor (aspects are inert data there). */

package/dist/types/gl/Statics.d.ts

@@ -3,6 +3,7 @@ import { Model, type FoliageKind } from "./Model";
 import { Node } from "./Node";
 import { Scene } from "./Scene";
 import type { SceneDef, SceneNodeDef } from "../scene/defineScene";
+import type { AspectEntry } from "../scene/grammar";
 import type { BakeData } from "./Lightmap";
 import { type Digest } from "./staticsFormat";
 export { bakeDigest, type Digest } from "./staticsFormat";
@@ -17,6 +18,16 @@ export type CoveredRoot = {
     path: string;
     def: SceneNodeDef;
 };
+/** 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 declare const isPassive: (e: AspectEntry<any>) => boolean;
+/** 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 declare const attachPassive: (node: Node, def: SceneNodeDef) => void;
 /** The maximal cacheable subtrees among `defs`, depth first: through `children`, and through a prefab's nodes
  *  (paths run through the prefab's path, as the bake's keys do). */
 export declare const coveredRoots: (defs: Record<string, SceneNodeDef> | undefined, scene: SceneDef) => CoveredRoot[];
@@ -53,4 +64,4 @@ export declare const open: (url: string, defs: Digest, bake: Digest) => Promise<
  *  templates load through `template` (one per kind, as the level's slow path would load them), the engine clones
  *  each at its placements as it resolves. `pages` = the bake's light/aux texture ids interleaved (empty = no bake
  *  bound). Resolves to the placements made. */
-export declare const build: (opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array, template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>) => Promise<number>;
+export declare const build: (opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array, template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>, covered: CoveredRoot[], def: SceneDef) => Promise<number>;

package/dist/types/gl/physics/CharacterController.d.ts

@@ -47,13 +47,18 @@ export declare class CharacterController extends Aspect<"controller", Node> impl
      * 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;
     /** True while standing on walkable ground. */

package/dist/types/gl/physics/Physics.d.ts

@@ -87,6 +87,12 @@ export declare class Physics extends Aspect<"physics", Node> implements CompWrit
     /** Whether this host has 3D physics (an engine built with CREATOR_GL_PHYSICS). False, never a
      *  throw, where there is no 3D engine at all. */
     static get supported(): boolean;
-    /** 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;
+    /** 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?: number): RayHit | null;
 }

package/dist/types/gl/physics/Shape.d.ts

@@ -138,6 +138,10 @@ export declare class Shape extends Aspect<"shape", Node> {
     static fitBounds(bounds: ShapeBounds, scale: Vec3Like, kind?: ShapeKind): ShapeFit;
     private _createPickBody;
     private _rebuild;
+    /** 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;
     private _build;
     private _applyOrigin;
     private _signature;

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.8.1";
+export declare const SDK_VERSION = "2.8.2";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from