@babylonjs/lite 1.0.1 → 1.1.0

package/index.d.ts

@@ -1,3 +1,6 @@
+/** Axis-aligned bounding box represented as `[min, max]` XYZ tuples. */
+export declare type Aabb = [min: [number, number, number], max: [number, number, number]];
+
 /** Increment ref count on a Texture2D. First acquire sets count to 1. */
 export declare function acquireTexture(tex: Texture2D): void;
 
@@ -82,6 +85,17 @@ export declare function addDepthHostedSpriteLayer(scene: SceneContext, layer: Sp
  */
 export declare function addFacingBillboardSystem(scene: SceneContext, system: FacingBillboardSpriteSystem): void;
 
+/**
+ * Add one logical hierarchy instance and return its slot index.
+ *
+ * The same root matrix is expanded into each descendant mesh's thin-instance
+ * buffer so child offsets, rotations, and scales are preserved.
+ *
+ * @param pool - Pool created by {@link createHierarchyInstancePool}.
+ * @param matrix - Desired world matrix for the hierarchy root instance.
+ */
+export declare function addHierarchyInstance(pool: HierarchyInstancePool, matrix: Mat4): number;
+
 /** Add one or more render-target dependencies to the pass. Idempotent
  *  (Set semantics). Mirrors BJS `FrameGraphRenderPass.addDependencies`,
  *  promoted onto the base `Pass` because every future pass type
@@ -172,6 +186,9 @@ export declare function addThinInstance(mesh: Mesh, matrix: Mat4): number;
  */
 export declare function addToScene(scene: SceneContext, entity: Mesh | LightBase | Camera | ShadowGenerator | TransformNode | AssetContainer): void;
 
+/** Add two vectors component-wise. */
+export declare function addVec3(a: Vec3, b: Vec3): Vec3;
+
 /** Request the agent to move toward a world target (constrained by navmesh). */
 export declare function agentGoto(crowd: NavCrowd, index: number, destination: Vec3): void;
 
@@ -888,7 +905,7 @@ export declare interface BoundingBoxGizmoOptions {
  *  The view/projection matrix caches below are allocated by the camera factory
  *  via the process-global `allocateMat4()` singleton — F32 by default, F64
  *  after any HPM engine is constructed (see
- *  `docs/architecture/33-high-precision-matrix.md`). The storage
+ *  `docs/lite/architecture/36-high-precision-matrix.md`). The storage
  *  type is fixed at construction and never changes. */
 export declare interface Camera {
     fov: number;
@@ -1000,6 +1017,64 @@ export declare interface CapsuleOptions {
  */
 export declare function captureScreenshot(surface: SurfaceContext): Promise<Screenshot>;
 
+/**
+ * Collision event fired by {@link PhysicsCharacterController.onTriggerCollisionObservable}
+ * for every dynamic body the character pushes during a step. Mirrors Babylon.js'
+ * `onTriggerCollisionObservable` payload (minus its `colliderIndex`, which has no Lite equivalent).
+ */
+export declare interface CharacterCollisionEvent {
+    /** The dynamic physics body the character contacted. Its `.node.name` identifies the collider. */
+    collider: PhysicsBody;
+    /** Impulse (world space) the character applied to the collider at the contact point. */
+    impulse: Vec3;
+    /** World-space position of the contact at which the impulse was applied. */
+    impulsePosition: Vec3;
+}
+
+/**
+ * Minimal single-event observable used by {@link PhysicsCharacterController} for collision
+ * callbacks. Kept local to the physics module (no dependency on gizmo/observable code) so the
+ * character-controller graph stays self-contained and tree-shakeable.
+ */
+export declare class CharacterCollisionObservable {
+    private _subs;
+    /**
+     * Subscribe to collision events.
+     * @param cb - Callback invoked for each dynamic-body contact during a step.
+     * @returns A disposer that removes the subscription when called.
+     */
+    add(cb: (event: CharacterCollisionEvent) => void): () => void;
+    /**
+     * Notify all subscribers of a collision event.
+     * @param event - The collision event payload.
+     */
+    notify(event: CharacterCollisionEvent): void;
+}
+
+/** Contact state of the character against the geometry beneath it. */
+export declare const enum CharacterSupportedState {
+    /** No surface within reach. */
+    UNSUPPORTED = 0,
+    /** Touching a surface too steep to stand on; the character slides. */
+    SLIDING = 1,
+    /** Standing on a walkable surface. */
+    SUPPORTED = 2
+}
+
+/** Surface information returned by {@link PhysicsCharacterController.checkSupport}. */
+export declare interface CharacterSurfaceInfo {
+    /** Whether the supporting surface belongs to a dynamic (simulated) body. */
+    isSurfaceDynamic: boolean;
+    /** Whether the character is unsupported, sliding, or supported. */
+    supportedState: CharacterSupportedState;
+    /** Average normal of the supporting surfaces (world space). */
+    averageSurfaceNormal: Vec3;
+    /** Average linear velocity induced by the supporting surfaces. */
+    averageSurfaceVelocity: Vec3;
+    /** Average angular velocity induced by the supporting surfaces. */
+    averageAngularSurfaceVelocity: Vec3;
+}
+
 /** A post-process task that offsets the red/green/blue channels to simulate lens chromatic aberration. */
 export declare interface ChromaticAberrationPostProcessTask extends PostProcessTask {
     aberrationAmount: number;
@@ -1185,6 +1260,31 @@ export declare interface ClusteredPointLightOptions {
     intensity?: number;
 }
 
+/** RGB color */
+export declare interface Color3 {
+    r: number;
+    g: number;
+    b: number;
+}
+
+/** RGBA color */
+export declare interface Color4 {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+
+/** Compute an AABB by folding XYZ min/max over a positions buffer.
+ *
+ *  When `world` is provided each position is transformed by it before being
+ *  folded (column-major Mat4: m[col*4+row]). Otherwise the AABB is computed
+ *  in the positions' own space.
+ *
+ *  Returns `[[+Inf,+Inf,+Inf],[-Inf,-Inf,-Inf]]` for empty input — callers
+ *  that care can check `isFinite(min[0])`. */
+export declare function computeAabb(positions: Float32Array, world?: Mat4): Aabb;
+
 /**
  * Build the east/north/up orthonormal basis at a point on the globe (left-handed
  * convention). `up` is the geocentric normal (normalized position); `east` and
@@ -1657,6 +1757,22 @@ export declare function createHeightFieldShape(world: PhysicsWorld, options: Hei
  *  Matches Babylon.js HemisphericLight behavior. */
 export declare function createHemisphericLight(direction?: [number, number, number], intensity?: number): HemisphericLight;
 
+/**
+ * Build a fixed-capacity thin-instance pool from a template hierarchy.
+ *
+ * Call before `registerScene()`, after the hierarchy's parent links are
+ * established. Fresh `loadGltf()` hierarchies are also supported: this helper
+ * materializes child parent links from the `children` arrays before snapshotting
+ * template world matrices.
+ *
+ * The template meshes are converted to thin-instanced meshes with an active
+ * count of zero, so they do not draw until instances are added.
+ *
+ * @param root - Root transform node or mesh for the template hierarchy.
+ * @param capacity - Maximum number of active logical hierarchy instances.
+ */
+export declare function createHierarchyInstancePool(root: SceneNode, capacity: number): HierarchyInstancePool;
+
 /**
  * Create a frame-graph task that applies the scene's image-processing settings
  * (exposure, contrast, tone mapping) to a color source and draws it to the swapchain.
@@ -1803,6 +1919,20 @@ export declare function createPhysicsAggregate(world: PhysicsWorld, node: Mesh,
  */
 export declare function createPhysicsBody(world: PhysicsWorld, node: SceneNode, motionType: PhysicsMotionType, startsAsleep?: boolean): PhysicsBody;
 
+/**
+ * Create a Havok physics character controller.
+ *
+ * The controller adds a kinematic capsule body to `world` and resolves collisions by sweeping
+ * that capsule each step. Drive it from a per-physics-step callback (e.g. `onPhysicsAfterStep`)
+ * by calling {@link PhysicsCharacterController.moveWithCollisions} with the desired displacement,
+ * then read {@link PhysicsCharacterController.getPosition} to update your display mesh.
+ * @param world - The physics world to add the character to.
+ * @param position - Initial world-space position of the character.
+ * @param options - Capsule dimensions.
+ * @returns The character controller instance.
+ */
+export declare function createPhysicsCharacterController(world: PhysicsWorld, position: Vec3, options: PhysicsCharacterControllerOptions): PhysicsCharacterController;
+
 /**
  * Creates and enables a Havok constraint between two physics bodies.
  * @param world - The physics world.
@@ -2136,6 +2266,9 @@ export declare interface CrossFadeAnimationGroupsOptions {
     readonly toWeight?: number;
 }
 
+/** Compute the right-handed cross product `a x b`. */
+export declare function crossVec3(a: Vec3, b: Vec3): Vec3;
+
 /** Returns the boolean union (`a` ∪ `b`) of two solids as a new solid. */
 export declare function csg2Add(a: Csg2Solid, b: Csg2Solid): Csg2Solid;
 
@@ -2423,6 +2556,9 @@ export declare function disposeUniformEffectWrapper(wrapper: UniformEffectWrappe
 /** Dispose the utility layer's underlying scene. Idempotent. */
 export declare function disposeUtilityLayer(utility: UtilityLayer): void;
 
+/** Compute the dot product of two vectors. */
+export declare function dotVec3(a: Vec3, b: Vec3): number;
+
 /**
  * A per-pass draw binding produced by `Renderable.bind(engine, target)`.
  *
@@ -3122,6 +3258,15 @@ export declare function getCameraPosition(camera: Camera): Vec3;
 /** Snap a position to the closest point on the navmesh. */
 export declare function getClosestPoint(plugin: NavigationPlugin, position: Vec3): Vec3;
 
+/**
+ * Flatten a loaded asset container's entity tree to its renderable `Mesh` nodes
+ * (those carrying GPU geometry), matching the flat `meshes` array Babylon.js
+ * loaders return. Useful for camera-framing and per-mesh inspection after a load.
+ *
+ * Tree-shakeable: only callers that import this pull it into their bundle.
+ */
+export declare function getContainerMeshes(container: AssetContainer): Mesh[];
+
 /** Returns the render-target aspect ratio adjusted for the camera's normalized viewport, or the raw ratio if none. */
 export declare function getEffectiveAspectRatio(camera: Camera | null | undefined, targetWidth: number, targetHeight: number): number;
 
@@ -3471,6 +3616,27 @@ export declare interface HemisphericLight extends LightBase {
 /** Hides a body that was previously shown with {@link showPhysicsBody}. */
 export declare function hidePhysicsBody(viewer: PhysicsViewer, body: PhysicsBody): boolean;
 
+/**
+ * A fixed-capacity thin-instance pool for a transform-node hierarchy.
+ *
+ * The source meshes become the render carriers for the pool: each descendant
+ * mesh receives its own thin-instance matrix buffer, and one logical hierarchy
+ * instance updates the matching slot in every buffer.
+ */
+export declare interface HierarchyInstancePool {
+    /** Template hierarchy root used to build the pool. */
+    readonly root: SceneNode;
+    /** Maximum number of logical hierarchy instances that can be active. */
+    readonly capacity: number;
+    /** Descendant meshes driven by this pool. */
+    readonly meshes: readonly Mesh[];
+    /**
+     * Current active logical hierarchy instance count.
+     * Prefer {@link addHierarchyInstance}, {@link removeHierarchyInstance}, and
+     * {@link setHierarchyInstanceCount} over mutating this field directly.
+     */
+    count: number;
+
 /** Image processing configuration. */
 export declare interface ImageProcessingConfig {
     exposure: number;
@@ -3508,7 +3674,7 @@ export declare interface IParentable {
 }
 
 /** Iridescence thin-film properties. Maps to BJS PBRMaterial.iridescence and KHR_materials_iridescence. */
-declare interface IridescenceProps {
+export declare interface IridescenceProps {
     /** Whether iridescence is active. Default false. */
     isEnabled?: boolean;
     /** Iridescence blend intensity (0=off, 1=full). Default 1.0 for native PBR; glTF default is supplied by the loader. */
@@ -3578,6 +3744,12 @@ export declare interface IWorldMatrixProvider {
     readonly worldMatrixVersion: number;
 }
 
+/** Compute the Euclidean length of a vector. */
+export declare function lengthVec3(v: Vec3): number;
+
+/** Linearly interpolate from vector `a` to vector `b` by factor `t`. */
+export declare function lerpVec3(a: Vec3, b: Vec3, t: number): Vec3;
+
 /** Shared base for all light types.
  *  Provides pipeline integration callbacks so render pipelines are light-agnostic. */
 export declare interface LightBase extends IWorldMatrixProvider, IParentable {
@@ -3672,6 +3844,17 @@ declare interface LoadBabylonOptions {
  */
 export declare function loadBasisTexture2D(engine: EngineContext, url: string, opts?: Texture2DOptions): Promise<Texture2D>;
 
+/**
+ * Load a DDS cubemap environment for PBR IBL.
+ * Uploads ALL mip levels (prefiltered data) and computes spherical harmonics
+ * from mip 0 face data for irradiance lighting.
+ */
+export declare function loadDdsEnvironment(scene: SceneContext, url: string, options: {
+    brdfUrl: string;
+    skipSkybox?: boolean;
+    skipGround?: boolean;
+}): Promise<EnvironmentTextures>;
+
 /**
  * Load a Babylon.js .env environment file and upload cubemap + BRDF LUT to GPU.
  * BRDF LUT is decoded from a pre-baked RGBD PNG (matching BJS's embedded
@@ -3809,12 +3992,24 @@ export declare interface Mat4 {
    readonly length: 16;
 /** Compose TRS (translation * rotation * scale) into a single Mat4. */
 export declare function mat4Compose(tx: number, ty: number, tz: number, qx: number, qy: number, qz: number, qw: number, sx: number, sy: number, sz: number): Mat4;
 
+/** Create a rotation matrix from a quaternion. */
+export declare function mat4FromQuat(qx: number, qy: number, qz: number, qw: number): Mat4;
+
 /** Create a new identity Mat4. */
 export declare function mat4Identity(): Mat4;
 
 /** Compute inverse of a Mat4. Returns null if singular. */
 export declare function mat4Invert(input: Mat4): Mat4 | null;
 
+/** LookAt matrix (right-handed). Matches Babylon.js Matrix.LookAtLHToRef with LH convention. */
+export declare function mat4LookAtLH(eye: Vec3, target: Vec3, up: Vec3): Mat4;
+
+/** Multiply two Mat4: out = a * b (column-major). */
+export declare function mat4Multiply(a: Mat4, b: Mat4): Mat4;
+
+/** Reverse-Z perspective projection (left-handed, zero-to-one depth). */
+export declare function mat4PerspectiveLH(fov: number, aspect: number, near: number, far: number): Mat4;
+
 /** Create a scaling matrix. */
 export declare function mat4Scale(x: number, y: number, z: number): Mat4;
 
@@ -3935,9 +4130,7 @@ export declare interface Mesh extends SceneNode {
     thinInstances?: ThinInstanceData | null;
     /** When `false`, the GPU picker skips this mesh.  Defaults to `true`
      *  (undefined behaves as pickable).  Mirrors BJS `AbstractMesh.isPickable`. */
-    pickable?: boolean;
-    /** Optional per-mesh GPU-picking clip volumes. Fragments inside any volume are ignored by the GPU picker. */
-    pickingClipVolumes?: readonly PickingClipVolume[] | null;
+    pickable?: boolean;
 
 /** Opaque GPU geometry handle (user never touches these). */
 export declare interface MeshGPU {
@@ -4026,6 +4219,9 @@ export declare interface NavMeshSource {
     indices: ArrayLike<number>;
 }
 
+/** Negate every vector component. */
+export declare function negateVec3(v: Vec3): Vec3;
+
 /** Parsed block in the graph. */
 declare interface NodeBlock {
     readonly id: number;
@@ -4245,6 +4441,9 @@ export declare function normalizeRadians(angle: number): number;
  */
 export declare function normalizeVec3(x: number, y: number, z: number, epsilon?: number): Vec3Tuple;
 
+/** Normalize a `Vec3` object, returning `{ x: 0, y: 0, z: 0 }` for degenerate input. */
+export declare function normalizeVec3Object(v: Vec3): Vec3;
+
 /**
  * A 4-component quaternion whose `x`/`y`/`z`/`w` setters fire an `onDirty` callback
  * when a component actually changes, letting the hierarchy system detect rotation updates.
@@ -4347,6 +4546,28 @@ export declare function onCsmReceiverUpdate(sg: ShadowGenerator, cb: (data: Floa
  */
 export declare function onPhysicsAfterStep(world: PhysicsWorld, cb: (timestep: number) => void): void;
 
+/**
+ * Register a callback invoked once per collision event after each physics step.
+ *
+ * The events are produced by the Havok world step, so they are drained via the post-step hook
+ * ({@link onPhysicsAfterStep}). Enable events on the participating bodies first with
+ * {@link setPhysicsBodyCollisionEventsEnabled}, otherwise the stream is empty.
+ * @param world - The physics world to listen on.
+ * @param cb - Callback invoked with each {@link PhysicsCollisionInfo} as it is read.
+ */
+export declare function onPhysicsCollision(world: PhysicsWorld, cb: (info: PhysicsCollisionInfo) => void): void;
+
+/**
+ * Register a callback invoked once per trigger event after each physics step.
+ *
+ * The events are produced by the Havok world step, so they are drained via the post-step
+ * hook ({@link onPhysicsAfterStep}). Flag the participating shape with
+ * {@link setPhysicsShapeIsTrigger} first, otherwise the stream is empty.
+ * @param world - The physics world to listen on.
+ * @param cb - Callback invoked with each {@link PhysicsTriggerInfo} as it is read.
+ */
+export declare function onPhysicsTrigger(world: PhysicsWorld, cb: (info: PhysicsTriggerInfo) => void): void;
+
 /** Register a callback to run when `disposeScene` is called. Used to tie
  *  user-owned GPU resources (e.g. a `SpriteRenderer`) to the scene's lifetime. */
 export declare function onSceneDispose(scene: SceneContext, cb: () => void): void;
@@ -4561,6 +4782,156 @@ export declare interface PhysicsAggregateOptions {
 export declare interface PhysicsBody {
    readonly node: SceneNode;
     readonly motionType: PhysicsMotionType;
 
+/**
+ * A physics-driven character controller. Create one with
+ * {@link createPhysicsCharacterController}; drive it each physics step with
+ * {@link PhysicsCharacterController.moveWithCollisions} and read back the resolved position
+ * with {@link PhysicsCharacterController.getPosition}.
+ */
+export declare class PhysicsCharacterController {
+    /** Minimum separation kept from surfaces, in metres. Default `0.05`. */
+    keepDistance: number;
+    /** Extra distance over which a contact is still tracked. Default `0.1`. */
+    keepContactTolerance: number;
+    /** Maximum number of cast iterations per integration step. Default `10`. */
+    maxCastIterations: number;
+    /** Speed at which penetrations are pushed out. Default `1.0`. */
+    penetrationRecoverySpeed: number;
+    /** Static-friction coefficient against surfaces. Default `0`. */
+    staticFriction: number;
+    /** Dynamic-friction coefficient against surfaces. Default `1`. */
+    dynamicFriction: number;
+    /** Cosine of the steepest slope the character can stand on. Default `0.5` (60°). */
+    maxSlopeCosine: number;
+    /** Upper bound on per-solve character speed. Default `10`. */
+    maxCharacterSpeedForSolver: number;
+    /** World up vector. Default `(0, 1, 0)`. */
+    up: Vec3;
+    /** Push strength applied to dynamic bodies the character contacts. Default `1e38`. */
+    characterStrength: number;
+    /** Acceleration factor used by {@link calculateMovement}. Default `0.05`. */
+    acceleration: number;
+    /** Maximum world-space acceleration used by {@link calculateMovement}. Default `50`. */
+    maxAcceleration: number;
+    /** Character mass used when reacting to gravity against dynamic bodies. Default `0`. */
+    characterMass: number;
+    /**
+     * Fires once per dynamic body the character pushes during a step, just before the reactive
+     * impulse is applied. Mirrors Babylon.js' `onTriggerCollisionObservable`. Subscribe with
+     * `.add(cb)`; the returned disposer removes the subscription.
+     */
+    readonly onTriggerCollisionObservable: CharacterCollisionObservable;
+    private readonly _world;
+    private readonly _shape;
+    private readonly _node;
+    private readonly _body;
+    private readonly _startCollector;
+    private readonly _castCollector;
+    private _position;
+    private _velocity;
+    private _lastVelocity;
+    private _lastDisplacement;
+    private _orientation;
+    private _manifold;
+    private _lastInvDeltaTime;
+    private _frameId;
+    private readonly _contactAngleSensitivity;
+    private readonly _displacementEps;
+    private readonly _bodyTracking;
+    /** Construct a controller. Prefer the {@link createPhysicsCharacterController} factory. */
+    constructor(world: PhysicsWorld, position: Vec3, options: PhysicsCharacterControllerOptions);
+    /** Release the controller's body, shape, and query collectors. */
+    dispose(): void;
+    /** Get the current character position (world space). The returned vector is owned by the controller. */
+    getPosition(): Vec3;
+    /** Teleport the character to a new position, clearing any swept motion. */
+    setPosition(position: Vec3): void;
+    /** Get the current character velocity (world space). The returned vector is owned by the controller. */
+    getVelocity(): Vec3;
+    /** Set the character velocity (world space). */
+    setVelocity(velocity: Vec3): void;
+    /**
+     * Move the character by a displacement this physics step, sliding along any geometry it meets.
+     * @param displacement - Requested world-space displacement for this step.
+     */
+    moveWithCollisions(displacement: Vec3): void;
+    /**
+     * Advance the controller using a velocity already chosen for this step (instead of a raw
+     * displacement). Mirrors Babylon.js' `integrate`: it picks a cast direction from the current
+     * velocity and surface info, then runs the collide-and-slide.
+     * @param deltaTime - Step duration in seconds.
+     * @param surfaceInfo - Surface info from a prior {@link checkSupport} call.
+     * @param gravity - Gravity applied to the character this step.
+     */
+    integrate(deltaTime: number, surfaceInfo: CharacterSurfaceInfo, gravity: Vec3): void;
+    /**
+     * Probe the surface under the character along a direction (usually gravity) to classify support.
+     * @param deltaTime - Step duration in seconds.
+     * @param direction - Direction to probe, usually the gravity direction.
+     * @returns Support classification and averaged surface motion/normal.
+     */
+    checkSupport(deltaTime: number, direction: Vec3): CharacterSurfaceInfo;
+    /**
+     * Compute a target velocity from the current state, a desired velocity, and surface info — a
+     * helper for steering input into surface-aware motion.
+     * @param deltaTime - Step duration in seconds.
+     * @param forwardWorld - Character forward direction (world space).
+     * @param surfaceNormal - Supporting surface normal.
+     * @param currentVelocity - Current character velocity.
+     * @param surfaceVelocity - Velocity induced by the surface.
+     * @param desiredVelocity - Desired character velocity.
+     * @param upWorld - Up vector (world space).
+     * @returns The new velocity vector.
+     */
+    calculateMovement(deltaTime: number, forwardWorld: Vec3, surfaceNormal: Vec3, currentVelocity: Vec3, surfaceVelocity: Vec3, desiredVelocity: Vec3, upWorld: Vec3): Vec3;
+    private _integrateManifolds;
+    private _castWithCollectors;
+    private _findBody;
+    private _contactFromCast;
+    private _validateManifold;
+    private _updateManifold;
+    private _compareContacts;
+    private _findContact;
+    private _getMassProperties;
+    private _getComWorld;
+    private _getPointVelocity;
+    private _getInvMass;
+    private _createSurfaceConstraint;
+    private _addMaxSlopePlane;
+    private _resolveConstraintPenetration;
+    private _createConstraintsFromManifold;
+    private _resolveContacts;
+    private _getOutput;
+    private _sortInfo;
+    private _solve1d;
+    private _solveTest1d;
+    private _solve2d;
+    private _solve3d;
+    private _examineActivePlanes;
+    private _copyPlane;
+    private _simplexSolverSolve;
+}
+
+/** Options describing the character's collision capsule. */
+export declare interface PhysicsCharacterControllerOptions {
+    /** Total capsule height (tip to tip), in metres. Default `1.8`. */
+    capsuleHeight: number;
+    /** Capsule radius, in metres. Default `0.6`. */
+    capsuleRadius: number;
+}
+
+/** A single collision event reported by Havok after a physics step. */
+export declare interface PhysicsCollisionInfo {
+    /** Phase of the contact: a new contact, an ongoing contact, or a contact that just ended. */
+    type: "STARTED" | "CONTINUED" | "FINISHED";
+    /** World-space contact point (closest point on the first body). */
+    point: Vec3;
+    /** World-space contact normal at the contact point. */
+    normal: Vec3;
+    /** Magnitude of the impulse applied to resolve the contact (0 for `FINISHED`). */
+    impulse: number;
+}
+
 /** Opaque handle to a Havok constraint between two bodies. */
 export declare interface PhysicsConstraint {
    readonly bodyA: PhysicsBody;
     readonly bodyB: PhysicsBody;
@@ -4640,6 +5011,32 @@ export declare const enum PhysicsMotionType {
     DYNAMIC = 2
 }
 
+/**
+ * How a moved transform node is propagated to its physics body before each step.
+ * `DISABLED` skips the sync, `TELEPORT` snaps the body to the node (`HP_Body_SetQTransform`),
+ * and `ACTION` sets the body's velocity so it reaches the node (`HP_Body_SetTargetQTransform`,
+ * dragging resting bodies via friction). Values match Babylon.js `PhysicsPrestepType`.
+ */
+export declare const enum PhysicsPrestepType {
+    DISABLED = 0,
+    TELEPORT = 1,
+    ACTION = 2
+}
+
+/**
+ * Cast a ray from `from` to `to` and return the first body it hits.
+ *
+ * `collideWith`/`membership` filter which bodies the ray can hit (by their shape filter masks).
+ * For MESH shapes the hit triangle index is reported; non-mesh shapes report `-1`. Run at least
+ * one physics step first so the broadphase exists.
+ * @param world - The physics world to query.
+ * @param from - World-space ray origin.
+ * @param to - World-space ray end point.
+ * @param query - Optional collision-filter masks and trigger behaviour.
+ * @returns The raycast result; `hasHit` is `false` when the ray clears every matching body.
+ */
+export declare function physicsRaycast(world: PhysicsWorld, from: Vec3, to: Vec3, query?: RaycastQuery): RaycastResult;
+
 /** Opaque handle to a Havok collision shape. */
 export declare interface PhysicsShape {
 
@@ -4675,6 +5072,12 @@ export declare const enum PhysicsShapeType {
     HEIGHTFIELD = 7
 }
 
+/** A single trigger-volume event reported by Havok after a physics step. */
+export declare interface PhysicsTriggerInfo {
+    /** `ENTERED` when a body enters the trigger volume, `EXITED` when it leaves. */
+    type: "ENTERED" | "EXITED";
+}
+
 /** Pure-state handle for Havok Physics V2 debug rendering. */
 export declare interface PhysicsViewer {
     readonly scene: SceneContext;
@@ -4692,13 +5095,30 @@ export declare interface PhysicsWorld {
 /** Pick the mesh at CSS-space canvas coordinates, matching Babylon.js Scene.pick. Returns a PickingInfo. */
 export declare function pickAsync(picker: GpuPicker, x: number, y: number, options?: PickOptions): Promise<PickingInfo>;
 
-/** Optional GPU-picking discard volume. The picker clips fragments in a bounded local frame:
- *  `a=(origin.x, origin.z, tangent.x, tangent.z)`, `b=(baseY, halfWidth, springY, rise)`,
- *  `c=(ringT, depthHalf, flatFlag, _)`. */
-declare interface PickingClipVolume {
-    readonly a: readonly [number, number, number, number];
-    readonly b: readonly [number, number, number, number];
-    readonly c: readonly [number, number, number, number];
+/**
+ * Optional GPU-side discard rule for {@link pickAsync}.
+ *
+ * This lets apps remove pick hits with custom WGSL while keeping the main scene
+ * render untouched. The WGSL must define
+ * `fn shouldDiscardPick(input: PickDiscardInput) -> bool`.
+ */
+export declare interface PickDiscardRule {
+    /** Stable cache key for the generated picking pipeline set. Change it when the WGSL or layout changes. */
+    readonly key: string;
+    /** WGSL source that defines `shouldDiscardPick(input: PickDiscardInput) -> bool`. */
+    readonly wgsl: string;
+    /** Optional typed-array storage inputs exposed to the discard WGSL at group 2. */
+    readonly storage?: readonly PickDiscardStorage[];
+}
+
+/** Storage data for a pick discard rule. Lite injects the WGSL declaration and owns the GPU buffer upload. */
+declare interface PickDiscardStorage {
+    /** WGSL variable name declared at `@group(2) @binding(index)`; must be unique within the rule. */
+    readonly name: string;
+    /** WGSL storage type, for example `array<vec4<f32>>`. */
+    readonly type: string;
+    /** Per-mesh data for the current pick. Return `null` to draw that mesh with the default picker. */
+    readonly data: (mesh: Mesh) => ArrayBufferView | null | undefined;
 }
 
 /** Result of a GPU pick operation. */
@@ -4730,6 +5150,16 @@ export declare interface PickOptions {
      *  structure behind/around them. When omitted, every mesh is pickable (previous behaviour). Applied
      *  identically to the id-assignment and id-resolve passes so ids stay consistent. */
     filter?: (mesh: Mesh) => boolean;
+    /** Optional GPU fragment-discard extension for app-specific pick removal.
+     *
+     *  `wgsl` is injected into the regular and thin-instance picking shaders and must define:
+     *
+     *  `fn shouldDiscardPick(input: PickDiscardInput) -> bool`
+     *
+     *  The input exposes only generic picker data: `worldPos`, `pickId`, `thinInstanceIndex`,
+     *  `hasThinInstance`, and `instanceExtras` (the original thin-instance matrix w lanes, zero for
+     *  non-instanced meshes). Storage entries are uploaded and bound by Lite for the current pick only. */
+    discard?: PickDiscardRule;
     /** Dev-only diagnostics: logs the pick ray, pixel, pick id/depth and resolved mesh. */
     debugLabel?: string;
 }
@@ -5107,7 +5537,7 @@ export declare type QuadCurve = {
 };
 
 /** Quaternion rotation */
-declare interface Quat {
+export declare interface Quat {
     x: number;
     y: number;
     z: number;
@@ -5133,6 +5563,32 @@ export declare function raycast(plugin: NavigationPlugin, start: Vec3, end: Vec3
     hitPoint?: Vec3;
 };
 
+/** Query parameters for {@link physicsRaycast}. */
+export declare interface RaycastQuery {
+    /** Bitmask describing which collision groups the ray belongs to. Default `~0` (all). */
+    membership?: number;
+    /** Bitmask describing which collision groups the ray collides with. Default `~0` (all). */
+    collideWith?: number;
+    /** Whether trigger volumes count as hits. Default `false`. */
+    shouldHitTriggers?: boolean;
+}
+
+/** Result of a {@link physicsRaycast} query. */
+export declare interface RaycastResult {
+    /** Whether the ray hit a body. */
+    hasHit: boolean;
+    /** World-space contact point. */
+    hitPoint: Vec3;
+    /** Surface normal at the contact point. */
+    hitNormal: Vec3;
+    /** Distance from the ray origin (`from`) to the contact point. */
+    hitDistance: number;
+    /** Index of the triangle hit on a MESH shape, or `-1` for non-mesh shapes. */
+    triangleIndex: number;
+    /** The body that was hit, or `null` when nothing was hit (or the body is not tracked). */
+    body: PhysicsBody | null;
+}
+
 /** Rebuild renderables whose pipeline/bind-group feature state depends on a material.
  *  Use after texture, sampler, bind-group layout, culling, or feature changes.
  *  UBO-only scalar/vector changes should use markMaterialUboDirty instead. */
@@ -5242,6 +5698,17 @@ export declare function removeBillboardSpriteIndex(system: BillboardSpriteSystem
  *  Standalone function for tree-shaking — only included when actually used. */
 export declare function removeFromScene(scene: SceneContext, mesh: Mesh): void;
 
+/**
+ * Remove one logical hierarchy instance with O(1) swap-remove semantics.
+ *
+ * If `index` is not the last active slot, the last logical instance moves into
+ * `index` in every descendant mesh buffer.
+ *
+ * @param pool - Pool created by {@link createHierarchyInstancePool}.
+ * @param index - Active logical instance index to remove.
+ */
+export declare function removeHierarchyInstance(pool: HierarchyInstancePool, index: number): void;
+
 /** Remove a mesh from this task's renderable + binding lists. Idempotent. */
 export declare function removeMeshFromTask(task: RenderTask, mesh: object): void;
 
@@ -5547,6 +6014,9 @@ export declare interface ScaleGizmoOptions {
     thickness?: number;
 }
 
+/** Multiply every component of `v` by scalar `s`. */
+export declare function scaleVec3(v: Vec3, s: number): Vec3;
+
 /** Scattering sub-feature. Presence enables screen-space subsurface scattering.
  *  NOTE: PrePass/SSS pipeline is not yet implemented — this type is reserved. */
 declare interface ScatteringProps {
@@ -5782,6 +6252,28 @@ export declare function setGeospatialOrientation(camera: GeospatialCamera, orien
  *  toggles are synchronous. */
 export declare function setGpuTimingEnabled(engine: EngineContext, enabled: boolean): void;
 
+/**
+ * Set the active logical hierarchy instance count without reallocating buffers.
+ *
+ * This mirrors {@link setThinInstanceCount}: it only changes how many existing
+ * slots draw. Newly exposed slots are not initialized here; use
+ * {@link addHierarchyInstance} when growing with a new matrix, or immediately
+ * call {@link setHierarchyInstanceMatrix} before the next frame.
+ *
+ * @param pool - Pool created by {@link createHierarchyInstancePool}.
+ * @param count - New active logical instance count, from 0 to `pool.capacity`.
+ */
+export declare function setHierarchyInstanceCount(pool: HierarchyInstancePool, count: number): void;
+
+/**
+ * Update one logical hierarchy instance's root matrix.
+ *
+ * @param pool - Pool created by {@link createHierarchyInstancePool}.
+ * @param index - Active logical instance index to update.
+ * @param matrix - Desired world matrix for the hierarchy root instance.
+ */
+export declare function setHierarchyInstanceMatrix(pool: HierarchyInstancePool, index: number, matrix: Mat4): void;
+
 /** Override the URL of the KTX2/Basis decoder script (and, optionally, the URLs of the WASM/JS transcoder
  *  modules it pulls). Call before the first KHR_texture_basisu texture loads. */
 export declare function setKtx2DecoderUrl(url: string, wasmUrls?: Record<string, Record<string, string>>): void;
@@ -5815,19 +6307,34 @@ export declare function setParent(child: Mesh, parent: IWorldMatrixProvider | nu
  */
 export declare function setPhysicsBodyAngularVelocity(world: PhysicsWorld, body: PhysicsBody, velocity: Vec3): void;
 
+/**
+ * Enable or disable collision-event reporting for a single body by setting its Havok event mask.
+ *
+ * Only bodies with events enabled contribute to the stream read by {@link onPhysicsCollision};
+ * a collision is reported when at least one of the two touching bodies has events enabled.
+ * @param world - The physics world owning the body.
+ * @param body - The body to toggle collision events on.
+ * @param enabled - `true` to report STARTED/CONTINUED/FINISHED events, `false` to silence the body.
+ */
+export declare function setPhysicsBodyCollisionEventsEnabled(world: PhysicsWorld, body: PhysicsBody, enabled: boolean): void;
+
 /**
  * Set a body's linear velocity (m/s) directly — e.g. to impart a throw velocity on release.
  */
 export declare function setPhysicsBodyLinearVelocity(world: PhysicsWorld, body: PhysicsBody, velocity: Vec3): void;
 
 /**
- * Sets a body's mass and a matching diagonal inertia tensor.
+ * Sets a body's mass, preserving the shape-derived inertia tensor, centre of mass, and inertia
+ * orientation (matching Babylon.js `HavokPlugin` — only the mass scalar is overridden). A body with
+ * no shape attached yet has no inertia tensor to derive, so it falls back to an isotropic inertia
+ * proportional to the mass until a shape is set.
  * @param world - The physics world.
  * @param body - The body to update.
  * @param mass - Mass in kilograms.
- * @param centerOfMass - Optional body-local centre of mass (defaults to the origin). Use this when the
- *   collision shape is offset from the body's reference frame (e.g. a prop whose body origin sits at
- *   its base but whose shape is centred on its middle) so it tumbles around its real centre.
+ * @param centerOfMass - Optional body-local centre of mass override. When omitted, the shape-derived
+ *   centre of mass is preserved. Use this when the collision shape is offset from the body's reference
+ *   frame (e.g. a prop whose body origin sits at its base but whose shape is centred on its middle)
+ *   so it tumbles around its real centre.
  */
 export declare function setPhysicsBodyMass(world: PhysicsWorld, body: PhysicsBody, mass: number, centerOfMass?: Vec3): void;
 
@@ -5853,6 +6360,17 @@ export declare function setPhysicsBodyMotionType(world: PhysicsWorld, body: Phys
  */
 export declare function setPhysicsBodyPreStep(body: PhysicsBody, enabled: boolean): void;
 
+/**
+ * Sets how a moved transform node is propagated to its physics body before each step.
+ * `TELEPORT` snaps the body to the node, `ACTION` sets a velocity toward it (so resting bodies are
+ * dragged along by friction), and `DISABLED` skips the pre-step sync entirely. Setting any type
+ * other than `DISABLED` automatically enables prestep syncing for the body (equivalent to
+ * {@link setPhysicsBodyPreStep}), so STATIC/DYNAMIC bodies are synced without an extra call.
+ * @param body - The physics body to update.
+ * @param type - The prestep behaviour to apply.
+ */
+export declare function setPhysicsBodyPrestepType(body: PhysicsBody, type: PhysicsPrestepType): void;
+
 /**
  * Assigns a collision shape to a body.
  * @param world - The physics world.
@@ -5893,6 +6411,18 @@ export declare function setPhysicsShapeFilterCollideMask(world: PhysicsWorld, sh
  */
 export declare function setPhysicsShapeFilterMembershipMask(world: PhysicsWorld, shape: PhysicsShape, membershipMask: number): void;
 
+/**
+ * Flag a collision shape as a trigger volume (or clear the flag).
+ *
+ * A trigger shape detects overlaps and reports {@link PhysicsTriggerInfo} events but does
+ * not produce a physical collision response — bodies pass through it. Attach the flagged
+ * shape to a body in the world, then listen with {@link onPhysicsTrigger}.
+ * @param world - The physics world owning the shape.
+ * @param shape - The collision shape to flag.
+ * @param isTrigger - `true` to make the shape a trigger volume, `false` for a solid shape.
+ */
+export declare function setPhysicsShapeIsTrigger(world: PhysicsWorld, shape: PhysicsShape, isTrigger: boolean): void;
+
 /**
  * Sets a shape's surface material properties.
  * @param world - The physics world.
@@ -6293,7 +6823,7 @@ export declare interface ShapeProximityResult {
 }
 
 /** Sheen layer properties. Maps to BJS PBRMaterial.sheen sub-object. */
-declare interface SheenProps {
+export declare interface SheenProps {
     /** Whether sheen is active. Default false. */
     isEnabled: boolean;
     /** Sheen color (linear RGB). Default [1, 1, 1]. */
@@ -6758,6 +7288,10 @@ export declare interface StandardMaterialProps extends Material {
     lightmapLevel: number;
     /** Lightmap UV channel. 0=UV1, 1=UV2. Default 1 (BJS convention). */
     lightmapCoordIndex: 0 | 1;
+    /** When true, the lightmap is a baked shadowmap that multiplies the final color
+     *  (`color *= lightmap * level`) instead of being added. Matches BJS
+     *  StandardMaterial.useLightmapAsShadowmap. Default false. */
+    useLightmapAsShadowmap: boolean;
     /** Optional opacity texture. Multiplies alpha (.a channel). */
     opacityTexture: Texture2D | null;
     /** Opacity texture intensity. Default 1.0. */
@@ -6841,6 +7375,9 @@ export declare interface SubSurfaceProps {
     refraction?: RefractionProps;
 }
 
+/** Subtract vector `b` from vector `a` component-wise. */
+export declare function subVec3(a: Vec3, b: Vec3): Vec3;
+
 /**
  * Per-canvas rendering surface — owns the GPU canvas context, swapchain format, MSAA
  * configuration, and the list of `RenderingContext`s (scenes, effect renderers,
@@ -7469,12 +8006,29 @@ export declare interface Vec3 {
     z: number;
 }
 
+/** Create a plain `{ x, y, z }` vector object. */
+export declare function vec3(x: number, y: number, z: number): Vec3;
+
 /** 3-component vector as a fixed-length `[x, y, z]` tuple. */
 export declare type Vec3Tuple = [number, number, number];
 
+/** Unit vector pointing up on the positive Y axis. */
+export declare const Vec3Up: Readonly<Vec3>;
+
+/** 4-component vector (homogeneous coords, quaternion, tangent) */
+export declare interface Vec4 {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+
 /** Babylon Lite version string. */
 export declare const VERSION = "0.1.0";
 
 declare interface VertexAttribute {
 
+/** Write Vec3 into a Float32Array at the given byte offset (for uniform buffers). */
+export declare function writeVec3(out: Float32Array, offset: number, v: Vec3): void;
+
 export { }