@babylonjs/lite 1.0.0 → 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,12 +85,44 @@ 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
  *  (compute / copy / object-list) needs the same surface. */
 export declare function addPassDependencies(pass: Pass, deps: RenderTarget | readonly RenderTarget[]): void;
 
+/**
+ * Adds a child shape to a container shape with an explicit local transform.
+ * @param world - The physics world.
+ * @param container - Parent container shape.
+ * @param child - Child shape to append.
+ * @param translation - Child translation in container space.
+ * @param rotation - Child rotation in container space.
+ * @param scale - Child scale in container space.
+ */
+export declare function addPhysicsShapeChild(world: PhysicsWorld, container: PhysicsShape, child: PhysicsShape, translation?: Vec3, rotation?: Quat, scale?: Vec3): void;
+
+/**
+ * Adds a child shape to a container, deriving its local transform from two scene nodes.
+ * @param world - The physics world.
+ * @param container - Parent container shape.
+ * @param parentNode - Scene node associated with the container shape.
+ * @param child - Child shape to append.
+ * @param childNode - Scene node associated with the child shape.
+ */
+export declare function addPhysicsShapeChildFromParent(world: PhysicsWorld, container: PhysicsShape, parentNode: SceneNode, child: PhysicsShape, childNode: SceneNode): void;
+
 /** Create a `RenderPass`, wire it to the task currently recording, and return
  *  it. Must be called from inside `Task.record()` so the FG can associate the
  *  new pass with the right task (mirrors BJS `frameGraph.addRenderPass`).
@@ -151,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;
 
@@ -347,6 +385,23 @@ declare type AnyMaterial = StandardMaterialProps | PbrMaterialProps;
  */
 export declare function appendSpriteAtlasFrames(engine: EngineContext, atlas: SpriteAtlas, sources: readonly SpriteAtlasFrameSource[]): number[];
 
+/**
+ * Applies a force for one fixed physics timestep, matching Babylon.js PhysicsBody.applyForce.
+ * @param world - The physics world.
+ * @param body - The physics body to update.
+ * @param force - Force vector.
+ * @param location - World-space application point.
+ */
+export declare function applyPhysicsBodyForce(world: PhysicsWorld, body: PhysicsBody, force: Vec3, location: Vec3): void;
+
+/**
+ * Applies a world-space impulse to a physics body.
+ * @param body - The physics body to update.
+ * @param impulse - Impulse vector.
+ * @param location - World-space application point.
+ */
+export declare function applyPhysicsBodyImpulse(body: PhysicsBody, impulse: Vec3, location: Vec3): void;
+
 /**
  * Apply a one-shot linear impulse (kg·m/s) to a body at a world `point` (defaults to the body's
  * current position / centre of mass), waking it if asleep. Used to shoot, throw, or shove a prop.
@@ -523,7 +578,9 @@ export declare function attachFreeControl(camera: FreeCamera, canvas: HTMLCanvas
  *  - Left-drag: pan (the cursor stays anchored to the globe surface).
  *  - Middle/right-drag: rotate (yaw + pitch / tilt).
  *  - Wheel: zoom (toward the cursor by default).
- *  - Keyboard: arrows = tilt, W/A/S/D = pan, +/- = zoom.
+ *  - Touch: single-finger drag = pan; two-finger pinch = zoom toward the centroid,
+ *    promoting to a pan once the centroid drifts ≥ 20 px.
+ *  - Keyboard: arrows = pan, Ctrl+arrows = tilt (pitch/yaw), +/- = zoom along the look vector.
  *
  * Movement uses Babylon.js's framerate-independent physics model (velocity +
  * inertial decay). Globe picking is analytic ray-sphere against the planet
@@ -848,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;
@@ -895,6 +952,45 @@ export declare const CAP_NONE = 0;
 /** Cap mode: close only the start of the tube/extrusion. */
 export declare const CAP_START = 1;
 
+/**
+ * CreateCapsule — matches Babylon.js MeshBuilder.CreateCapsule default options.
+ *
+ * Generates a capsule (a cylinder capped by two hemispheres) or a "pill" when
+ * `radiusTop`/`radiusBottom` differ. Vertex/normal/UV generation and index
+ * winding are ported verbatim from `@babylonjs/core/Meshes/Builders/capsuleBuilder.js`
+ * to guarantee parity. The default Y-up orientation is used (the `orientation`
+ * remap of the Babylon builder is intentionally omitted to keep the API small).
+ */
+/** Geometry buffers produced by {@link createCapsuleData}. */
+export declare interface CapsuleData {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+
+/** Options for `createCapsuleData`. Subset of Babylon's CreateCapsule. */
+export declare interface CapsuleOptions {
+    /** Total height of the capsule including both caps. Default 1. */
+    height?: number;
+    /** Radius of the cylindrical body and both caps. Default 0.25. */
+    radius?: number;
+    /** Radius of the top cap; defaults to `radius`. */
+    radiusTop?: number;
+    /** Radius of the bottom cap; defaults to `radius`. */
+    radiusBottom?: number;
+    /** Number of radial segments around the capsule. Default 16. */
+    tessellation?: number;
+    /** Number of height segments along the cylindrical body. Default 2. */
+    subdivisions?: number;
+    /** Number of segments per cap; defaults applied to both caps. Default 6. */
+    capSubdivisions?: number;
+    /** Number of segments for the top cap; defaults to `capSubdivisions`. */
+    topCapSubdivisions?: number;
+    /** Number of segments for the bottom cap; defaults to `capSubdivisions`. */
+    bottomCapSubdivisions?: number;
+}
+
 /**
  * Capture the current canvas backbuffer of a {@link SurfaceContext} — the final presented
  * frame (post-processing and all) with NO HTML/DOM overlay, since those are never drawn
@@ -921,6 +1017,64 @@ export declare const CAP_START = 1;
  */
 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;
@@ -1106,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
@@ -1284,6 +1463,16 @@ export declare function createBox(engine: EngineContext, size?: number): Mesh;
  *  Set the matching option to `false` to display only one of them. */
 export declare function createCameraGizmo(engine: EngineContext, layer: UtilityLayer, options?: CameraGizmoOptions): CameraGizmo;
 
+/** Create a capsule (cylinder capped by two hemispheres) mesh. Caller must assign material. */
+export declare function createCapsule(engine: EngineContext, options?: CapsuleOptions): Mesh;
+
+/**
+ * Build capsule geometry data.
+ * @param options - Capsule dimensions and tessellation.
+ * @returns Positions, normals, UVs, and indices for the capsule mesh.
+ */
+export declare function createCapsuleData(options?: CapsuleOptions): CapsuleData;
+
 /**
  * Create a post-process task that simulates chromatic aberration by shifting color channels outward from a center point.
  * @param config - Aberration parameters and source/target settings.
@@ -1555,10 +1744,35 @@ export declare function createGroundFromHeightMap(engine: EngineContext, url: st
  */
 export declare function createHavokWorld(scene: SceneContext, hknp: any, gravity?: Vec3): PhysicsWorld;
 
+/**
+ * Create a Havok heightfield collision shape. Attach it to a STATIC body bound to the
+ * ground mesh so the heightfield aligns with the visible terrain.
+ * @param world - The physics world.
+ * @param options - Ground mesh source or explicit heightfield parameters.
+ * @returns The created shape handle.
+ */
+export declare function createHeightFieldShape(world: PhysicsWorld, options: HeightFieldShapeOptions): PhysicsShape;
+
 /** Create a hemispheric light. Returns plain data — caller adds to scene.
  *  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.
@@ -1691,7 +1905,7 @@ export declare function createPcfSpotlightShadowGenerator(engine: EngineContext,
 /**
  * Create a physics aggregate: body + shape + material wired together.
  * `mass === 0` → STATIC, `mass > 0` → DYNAMIC.
- * Shape geometry is auto-sized from the mesh bounding box when not specified.
+ * Primitive shape geometry is auto-sized from the mesh bounding box when not specified.
  */
 export declare function createPhysicsAggregate(world: PhysicsWorld, node: Mesh, type: PhysicsShapeType, options: PhysicsAggregateOptions): PhysicsAggregate;
 
@@ -1706,13 +1920,41 @@ export declare function createPhysicsAggregate(world: PhysicsWorld, node: Mesh,
 export declare function createPhysicsBody(world: PhysicsWorld, node: SceneNode, motionType: PhysicsMotionType, startsAsleep?: boolean): PhysicsBody;
 
 /**
- * Creates a collision shape (sphere, box, capsule, or cylinder) from the given options.
+ * 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.
+ * @param bodyA - Parent body.
+ * @param bodyB - Child body.
+ * @param type - Constraint type.
+ * @param options - Pivot and axis options.
+ * @param limits - Optional 6DoF limits.
+ */
+export declare function createPhysicsConstraint(world: PhysicsWorld, bodyA: PhysicsBody, bodyB: PhysicsBody, type: PhysicsConstraintType, options?: PhysicsConstraintOptions, limits?: readonly PhysicsConstraintLimit[]): PhysicsConstraint;
+
+/**
+ * Creates a collision shape from the given options.
  * @param world - The physics world.
  * @param options - The shape type and its geometry parameters.
  * @returns The created shape handle.
  */
 export declare function createPhysicsShape(world: PhysicsWorld, options: PhysicsShapeOptions): PhysicsShape;
 
+/** Creates a tree-shakable Physics V2 debug viewer for a scene/world pair. */
+export declare function createPhysicsViewer(scene: SceneContext, world: PhysicsWorld, options?: PhysicsViewerOptions): PhysicsViewer;
+
 /** Create a plane (unit quad facing -Z). Caller must assign material. */
 export declare function createPlane(engine: EngineContext, options?: PlaneOptions): Mesh;
 
@@ -2024,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;
 
@@ -2254,6 +2499,9 @@ export declare function disposeLightGizmo(gizmo: LightGizmo, layer: UtilityLayer
  */
 export declare function disposePhysics(world: PhysicsWorld): void;
 
+/** Disposes all physics debug meshes and unregisters the viewer update hook. */
+export declare function disposePhysicsViewer(viewer: PhysicsViewer): void;
+
 /** Dispose GPU resources owned by this picker. */
 export declare function disposePicker(picker: GpuPicker): void;
 
@@ -2308,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)`.
  *
@@ -2495,7 +2746,11 @@ export declare interface EngineContext extends SurfaceContext {
      *  `createSurface(engine, canvas, ...)` to append more. */
     readonly surfaces: readonly [SurfaceContext, ...SurfaceContext[]];
    /** Number of GPU draw calls in the last rendered frame, summed across all surfaces. */
     drawCallCount: number;
-    /**
+    /** GPU time spent on the last measured frame, in milliseconds — 0 until the first measured frame and
+     *  while GPU timing is disabled (the default). Enable with {@link setGpuTimingEnabled}; query device
+     *  capability with {@link isGpuTimingSupported}. Updates a frame or two behind, since the timestamp
+     *  readback is async and off the render critical path, so reading it does not perturb the value. */
+    gpuFrameTimeMs: number;
    /**
      * When true, world matrices are computed using Float64 intermediate precision
      * and downcast to Float32 at GPU upload time. Defaults to false.
      */
@@ -3003,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;
 
@@ -3075,6 +3339,9 @@ export declare function getPickedUV(info: PickingInfo): [number, number] | null;
 /** Compute the projection matrix for a camera. Cached per worldMatrixVersion + aspect. */
 export declare function getProjectionMatrix(camera: Camera, aspectRatio: number): Mat4;
 
+/** Return the latest task GPU timing snapshot without stalling the GPU or CPU. */
+export declare function getRenderTaskGpuTimings(engine: EngineContext): RenderTaskGpuTimings;
+
 /**
  * Resolves the current instance index of the sprite referenced by `handle`.
  * @param handle - Handle of the sprite to resolve.
@@ -3316,6 +3583,27 @@ declare interface HdrLoadOptions {
     skyboxSize?: number;
 }
 
+/** Options for {@link createHeightFieldShape}. */
+export declare interface HeightFieldShapeOptions {
+    /**
+     * Ground mesh whose world-space vertex grid defines the heightfield. When set, the
+     * sample count, world size, and height data are derived from the mesh (the explicit
+     * fields below are ignored). The mesh must be a regular `(N+1)×(N+1)` grid such as the
+     * one produced by `createGroundFromHeightMap`.
+     */
+    groundMesh?: Mesh;
+    /** Explicit: number of height samples along X. */
+    numHeightFieldSamplesX?: number;
+    /** Explicit: number of height samples along Z. */
+    numHeightFieldSamplesZ?: number;
+    /** Explicit: world-space size along X. */
+    heightFieldSizeX?: number;
+    /** Explicit: world-space size along Z. */
+    heightFieldSizeZ?: number;
+    /** Explicit: row-major height samples (`numHeightFieldSamplesX * numHeightFieldSamplesZ`). */
+    heightFieldData?: Float32Array;
+}
+
 export declare interface HemisphericLight extends LightBase {
     readonly lightType: "hemispheric";
     direction: ObservableVec3;
@@ -3325,6 +3613,30 @@ export declare interface HemisphericLight extends LightBase {
     groundColor: [number, number, number];
 }
 
+/** 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;
@@ -3362,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. */
@@ -3408,6 +3720,14 @@ export declare function isGizmoInteracting(canvas: HTMLCanvasElement): boolean;
  *  produces a stray orbit even if the async pick is slow. */
 export declare function isGizmoPickPending(canvas: HTMLCanvasElement): boolean;
 
+/** Whether GPU frame-time measurement is available on this engine's device — i.e. the adapter offered
+ *  the WebGPU `timestamp-query` feature (requested opportunistically by {@link createEngine}). When false,
+ *  {@link setGpuTimingEnabled} is a no-op and {@link EngineContext.gpuFrameTimeMs} stays 0. */
+export declare function isGpuTimingSupported(engine: EngineContext): boolean;
+
+/** Whether per-render-task GPU timing can run on this engine's WebGPU device. */
+export declare function isRenderTaskGpuTimingSupported(engine: EngineContext): boolean;
+
 /**
  * Returns `true` if the sprite referenced by `handle` is still present in its layer.
  * @param handle - Handle to test.
@@ -3424,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 {
@@ -3518,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
@@ -3655,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;
 
@@ -3870,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;
@@ -4089,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.
@@ -4181,6 +4536,38 @@ export declare function onBeforeRender(scene: SceneContext, cb: (deltaMs: number
  */
 export declare function onCsmReceiverUpdate(sg: ShadowGenerator, cb: (data: Float32Array) => void): () => void;
 
+/**
+ * Registers a callback to run after each physics step, once dynamic body transforms have been
+ * synced back to their nodes and before the frame is rendered. Use this for per-step logic that
+ * must observe (or react to) the freshly-integrated state — e.g. tracking a marker to a body's
+ * post-step pose, or applying a force whose effect should integrate on the next step.
+ * @param world - The physics world to hook.
+ * @param cb - Callback invoked with the world timestep (seconds) after each step.
+ */
+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;
@@ -4382,12 +4769,241 @@ export declare interface PhysicsAggregateOptions {
     center?: Vec3;
     startAsleep?: boolean;
     isTriggerShape?: boolean;
+    /**
+     * Optional pre-built shape. When provided, it is used directly and the
+     * primitive-shape build path is skipped. This lets callers supply
+     * mesh/convex-hull shapes (built via `createPhysicsShape`) without pulling
+     * the mesh-shape code into `createPhysicsAggregate` itself.
+     */
+    shape?: PhysicsShape;
 }
 
 /** Opaque handle to a Havok rigid body, bound to a scene node and a motion type. */
 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;
+    readonly type: PhysicsConstraintType;
+    readonly options: PhysicsConstraintOptions;
+    readonly limits?: readonly PhysicsConstraintLimit[];
+}
+
+/** Axis addressed by a Physics V2 constraint limit. */
+export declare const enum PhysicsConstraintAxis {
+    LINEAR_X = 0,
+    LINEAR_Y = 1,
+    LINEAR_Z = 2,
+    ANGULAR_X = 3,
+    ANGULAR_Y = 4,
+    ANGULAR_Z = 5,
+    LINEAR_DISTANCE = 6
+}
+
+/** Minimal constraint debug data consumed by the Lite PhysicsViewer. */
+export declare interface PhysicsConstraintDebug {
+    readonly bodyA: PhysicsBody;
+    readonly bodyB: PhysicsBody;
+    readonly pivotA: Vec3;
+    readonly pivotB: Vec3;
+    readonly axisA?: Vec3;
+    readonly axisB?: Vec3;
+    readonly perpAxisA?: Vec3;
+    readonly perpAxisB?: Vec3;
+    readonly type?: number;
+}
+
+/** Limit options used by 6DoF constraints. */
+export declare interface PhysicsConstraintLimit {
+    axis: PhysicsConstraintAxis;
+    minLimit?: number;
+    maxLimit?: number;
+    stiffness?: number;
+    damping?: number;
+}
+
+/** Pivot/axis options used to create a physics constraint. */
+export declare interface PhysicsConstraintOptions {
+    pivotA?: Vec3;
+    pivotB?: Vec3;
+    axisA?: Vec3;
+    axisB?: Vec3;
+    perpAxisA?: Vec3;
+    perpAxisB?: Vec3;
+    maxDistance?: number;
+    collision?: boolean;
+}
+
+/** Type of Havok Physics V2 constraint. */
+export declare const enum PhysicsConstraintType {
+    BALL_AND_SOCKET = 1,
+    DISTANCE = 2,
+    HINGE = 3,
+    SLIDER = 4,
+    LOCK = 5,
+    PRISMATIC = 6,
+    SIX_DOF = 7
+}
+
+/** Mass properties applied to a physics body. Omitted fields keep Havok's shape-derived values. */
+export declare interface PhysicsMassProperties {
+    centerOfMass?: Vec3;
+    mass?: number;
+    inertia?: Vec3;
+    inertiaOrientation?: Quat;
+}
+
 /** How a body moves: `STATIC` (immovable), `ANIMATED` (driven by the node transform), or `DYNAMIC` (simulated). */
 export declare const enum PhysicsMotionType {
     STATIC = 0,
@@ -4395,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 {
 
@@ -4402,6 +5044,10 @@ export declare interface PhysicsShape {
 export declare interface PhysicsShapeOptions {
     type: PhysicsShapeType;
     parameters?: PhysicsShapeParameters;
+    /** Mesh or transform hierarchy used when `type` is `MESH` or `CONVEX_HULL`. */
+    mesh?: SceneNode;
+    /** When true, mesh and convex-hull shapes accumulate descendant meshes under `mesh`. */
+    includeChildMeshes?: boolean;
 }
 
 /** Geometry parameters describing a collision shape; which fields apply depends on the shape type. */
@@ -4426,12 +5072,55 @@ 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;
+    readonly world: PhysicsWorld;
+
+/** Options used when creating a physics debug viewer. */
+export declare interface PhysicsViewerOptions {
+    /** RGBA debug line color. Defaults to opaque white, matching Babylon.js PhysicsViewer. */
+    color?: readonly [number, number, number, number];
+}
+
 /** Pure-state handle to a Havok physics world: the WASM module, the native world, its bodies, and the timestep. */
 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-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. */
 export declare interface PickingInfo {
     hit: boolean;
@@ -4461,6 +5150,18 @@ 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;
 }
 
 /** Sampler and format overrides for `createTexture2DFromPixels()`. */
@@ -4836,7 +5537,7 @@ export declare type QuadCurve = {
 };
 
 /** Quaternion rotation */
-declare interface Quat {
+export declare interface Quat {
     x: number;
     y: number;
     z: number;
@@ -4862,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. */
@@ -4971,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;
 
@@ -5145,13 +5883,46 @@ export declare interface RenderTaskConfig {
     /** Use canvas dimensions, not render-target dimensions, for this pass's scene UBO aspect. */
     cs?: boolean;
     /** Scene-texture transmission settings. `copyCount: 0` copies before every transmissive draw.
-     *  `generateMipmaps: false` allocates only mip 0 for the refraction texture and skips mip generation. */
+     *  `generateMipmaps: false` allocates only mip 0 for the refraction texture and skips mip generation.
+     *  `mipLevelCount` caps the generated chain when a material only samples low explicit LODs. */
     transmission?: {
         copyCount?: number;
         generateMipmaps?: boolean;
+        mipLevelCount?: number;
     };
 }
 
+/** GPU time measured for one frame-graph task in one rendered frame. */
+export declare interface RenderTaskGpuTiming {
+    /** Execution-order index within the measured frame. Useful when several tasks share the same name. */
+    readonly index: number;
+    /** The task's existing frame-graph label (`Task.name`, e.g. `"shadow"`, `"scene"`, `"post-process"`). */
+    readonly name: string;
+    /** GPU duration for this task in milliseconds. */
+    readonly durationMs: number;
+}
+
+/** Latest per-task GPU timing snapshot for an engine. */
+export declare interface RenderTaskGpuTimings {
+    /** `unsupported` when the WebGPU device lacks `timestamp-query`; `pending` until the first readback lands. */
+    readonly status: RenderTaskGpuTimingStatus;
+    /** Whether this engine's device exposes WebGPU timestamp queries. */
+    readonly supported: boolean;
+    /** Whether task timing is currently enabled and recording future frames. */
+    readonly enabled: boolean;
+    /** Monotonic profiler frame index for the snapshot. `0` means no measured frame has completed yet. */
+    readonly frameIndex: number;
+    /** Measured tasks in frame execution order. Empty until `status === "available"`. */
+    readonly tasks: readonly RenderTaskGpuTiming[];
+    /** Number of tasks skipped in that frame because the profiler's query-set capacity was exceeded. */
+    readonly droppedTaskCount: number;
+    /** Readback failure message when `status === "error"`. */
+    readonly error?: string;
+}
+
+/** Availability / lifecycle state for per-frame-graph-task GPU timings. */
+export declare type RenderTaskGpuTimingStatus = "unsupported" | "disabled" | "pending" | "available" | "error";
+
 /** Sampler / format overrides for `createRenderTexture2D()`. */
 export declare interface RenderTexture2DOptions {
     /** Address mode U. Default 'clamp-to-edge'. */
@@ -5243,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 {
@@ -5464,6 +6238,46 @@ export declare function setFog(scene: SceneContext, config: FogConfig): void;
 /** Set one or more orientation fields at once (single recompute). Omitted fields keep their value. */
 export declare function setGeospatialOrientation(camera: GeospatialCamera, orientation: GeospatialOrientation): void;
 
+/** Enable or disable per-frame GPU timing. Disabled by default and a no-op on devices where
+ *  {@link isGpuTimingSupported} is false. While on, {@link EngineContext.gpuFrameTimeMs} is updated each
+ *  frame with the measured GPU time — the time the GPU spends on that frame's work, not CPU/wall-clock
+ *  time — a frame or two behind via an async, non-blocking readback.
+ *
+ *  Implementation: the timer module is dynamic-imported on the first enable, so engines that never call
+ *  this ship none of it. Once loaded, three tiny per-frame hooks are installed on the engine; while timing
+ *  is off they are undefined and {@link renderFrame} only optional-chains them (a no-op short-circuit), so
+ *  scenes that never enable timing pay effectively nothing. The opening/closing timestamps are written into
+ *  the frame's command encoder so the GPU runs them contiguously around just that frame's passes. The first
+ *  enable takes effect a microtask later (the GPU resources are created lazily, then reused); subsequent
+ *  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;
+
 /** Raise (or lower) the maximum number of scene lights in the shared lights UBO.
  *  Must be called BEFORE scene pipelines are compiled — existing pipelines
  *  and UBOs bake the cap into their WGSL/layout. */
@@ -5493,22 +6307,45 @@ 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;
 
+/**
+ * Sets a body's mass properties, preserving Havok's shape-derived values for omitted fields.
+ * @param world - The physics world.
+ * @param body - The body to update.
+ * @param properties - Mass-property overrides.
+ */
+export declare function setPhysicsBodyMassProperties(world: PhysicsWorld, body: PhysicsBody, properties: PhysicsMassProperties): void;
+
 /**
  * Switch a body's motion type at runtime (e.g. ANIMATED/kinematic while a prop is grabbed, then
  * DYNAMIC on release). Mutates `body.motionType` so the per-frame step syncs it the right way
@@ -5516,6 +6353,24 @@ export declare function setPhysicsBodyMass(world: PhysicsWorld, body: PhysicsBod
  */
 export declare function setPhysicsBodyMotionType(world: PhysicsWorld, body: PhysicsBody, motionType: PhysicsMotionType): void;
 
+/**
+ * Enable or disable pre-step synchronization from a node transform to its Havok body.
+ * @param body - The physics body to update.
+ * @param enabled - When true, the node transform is written to Havok before each physics step.
+ */
+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.
@@ -5540,6 +6395,34 @@ export declare function setPhysicsBodyTransform(world: PhysicsWorld, body: Physi
  */
 export declare function setPhysicsGravity(world: PhysicsWorld, gravity: Vec3, worldPosition?: Vec3): void;
 
+/**
+ * Sets the Havok filter collide mask for a collision shape.
+ * @param world - The physics world.
+ * @param shape - The shape to update.
+ * @param collideMask - Bitmask describing which collision groups this shape collides with.
+ */
+export declare function setPhysicsShapeFilterCollideMask(world: PhysicsWorld, shape: PhysicsShape, collideMask: number): void;
+
+/**
+ * Sets the Havok filter membership mask for a collision shape.
+ * @param world - The physics world.
+ * @param shape - The shape to update.
+ * @param membershipMask - Bitmask describing which collision group this shape belongs to.
+ */
+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.
@@ -5566,6 +6449,15 @@ export declare function setPhysicsVelocityLimits(world: PhysicsWorld, maxLinear:
 
 export declare function setPositionGizmoLocalCoordinates(gizmo: PositionGizmo, useLocal: boolean): void;
 
+/** Enable or disable per-frame-graph-task GPU timing.
+ *
+ * The profiling implementation is loaded with a dynamic import on first enable. Engines that never call this
+ * function do not fetch the profiler chunk or carry task-timing code in the always-fetched frame graph.
+ * The returned snapshot is `unsupported` if the device lacks WebGPU `timestamp-query`, `pending` immediately
+ * after enable, and `available` once a later frame's async timestamp readback completes.
+ */
+export declare function setRenderTaskGpuTimingEnabled(engine: EngineContext, enabled: boolean): Promise<RenderTaskGpuTimings>;
+
 export declare function setRotationGizmoLocalCoordinates(gizmo: RotationGizmo, useLocal: boolean): void;
 
 /** Toggle local-coord mode on the per-axis scale arrows.  The uniform-scale
@@ -5581,6 +6473,9 @@ export declare function setShaderFloat(material: ShaderMaterial, name: string, v
  *  straight into a matrix uniform without laundering through a typed array. */
 export declare function setShaderMatrix(material: ShaderMaterial, name: string, value: Float32Array | Mat4): void;
 
+/** Bind (or clear) a declared read-only storage buffer. */
+export declare function setShaderStorageBuffer(material: ShaderMaterial, name: string, buffer: GPUBuffer | null): void;
+
 /** Bind (or clear) the texture for a declared sampler, enforcing that depth and
  *  non-depth samplers receive a matching `Texture2D`.
  *  @param material - Target material.
@@ -5721,6 +6616,7 @@ export declare interface ShaderMaterial extends Material {
     readonly attributes: readonly ShaderAttributeName[];
     readonly uniformDecls: readonly ShaderUniformDecl[];
     readonly samplerDecls: readonly ShaderSamplerDecl[];
+    readonly storageBufferDecls: readonly ShaderStorageBufferDecl[];
     readonly defines: readonly ShaderDefine[];
     readonly needAlphaBlending: boolean;
     readonly blendMode: "alpha" | "additive";
@@ -5730,6 +6626,7 @@ export declare interface ShaderMaterial extends Material {
     readonly backFaceCulling: boolean;
     readonly depthWrite: boolean;
     readonly depthCompare: GPUCompareFunction;
+    readonly depthOnlyFragment: boolean;
     readonly depthBias: number;
     readonly depthBiasSlopeScale: number;
 
@@ -5742,6 +6639,7 @@ export declare interface ShaderMaterialOptions {
     readonly attributes: readonly ShaderAttributeName[];
     readonly uniforms?: readonly ShaderUniformOption[];
     readonly samplers?: readonly ShaderSamplerOption[];
+    readonly storageBuffers?: readonly ShaderStorageBufferOption[];
     readonly defines?: ShaderDefineMap;
     readonly needAlphaBlending?: boolean;
     /** Blend equation used when `needAlphaBlending` is set. "alpha" (default) is
@@ -5759,6 +6657,10 @@ export declare interface ShaderMaterialOptions {
     readonly backFaceCulling?: boolean;
     readonly depthWrite?: boolean;
     readonly depthCompare?: GPUCompareFunction;
+    /** Compile/run the fragment stage even for depth-only render targets (no colour attachments).
+     *  Use for depth-only casters that need `discard` (alpha/clip masks). The fragment shader must not
+     *  declare colour outputs when drawn into a depth-only target. Default false. */
+    readonly depthOnlyFragment?: boolean;
     /** Constant depth-bias added in the pipeline's depth-stencil state (units of the depth format's minimum
      *  representable value). Lets a surface that hugs another (e.g. tiles overlapping a cone, decals) win the
      *  depth test consistently and avoid z-fighting. Default 0 (no bias). */
@@ -5798,6 +6700,15 @@ export declare interface ShaderSamplerDecl {
 /** A sampler entry: either a bare sampler name or an explicit declaration. */
 export declare type ShaderSamplerOption = string | ShaderSamplerDecl;
 
+/** A storage buffer declaration. `type` is the WGSL variable type, e.g. `array<vec4<f32>>`. */
+declare interface ShaderStorageBufferDecl {
+    readonly name: string;
+    readonly type: string;
+}
+
+/** A storage-buffer entry: a read-only WGSL storage binding declaration. */
+declare type ShaderStorageBufferOption = ShaderStorageBufferDecl;
+
 /** Built-in uniform names automatically populated by the renderer each frame
  *  (transforms, camera position, screen size, alpha cutoff). */
 export declare type ShaderSystemUniformName = "world" | "view" | "projection" | "viewProjection" | "worldView" | "worldViewProjection" | "cameraPosition" | "screenSize" | "alphaCutoff";
@@ -5826,8 +6737,93 @@ export declare interface ShadowTask extends Task {
     readonly name: "shadow";
 }
 
+/**
+ * Sweep a shape from `startPosition` to `endPosition` (orientation fixed) and return the
+ * first body it hits.
+ *
+ * `hitPoint` is the world-space contact point on the hit body; `fraction` is where along
+ * the sweep contact first occurs. Run at least one physics step first so the broadphase exists.
+ * @param world - The physics world to query.
+ * @param query - Swept shape, orientation, and start/end positions.
+ * @returns The cast result; `hasHit` is `false` when the sweep clears every body.
+ */
+export declare function shapeCast(world: PhysicsWorld, query: ShapeCastQuery): ShapeCastResult;
+
+/** Query parameters for {@link shapeCast}. */
+export declare interface ShapeCastQuery {
+    /** Shape to sweep through the world. */
+    shape: PhysicsShape;
+    /** World-space orientation held constant during the sweep. */
+    rotation: Quat;
+    /** World-space sweep start position. */
+    startPosition: Vec3;
+    /** World-space sweep end position. */
+    endPosition: Vec3;
+    /** Whether trigger volumes count as hits. Default `false`. */
+    shouldHitTriggers?: boolean;
+}
+
+/** Result of a {@link shapeCast} query. */
+export declare interface ShapeCastResult {
+    /** Whether the swept shape hit a body. */
+    hasHit: boolean;
+    /** Fraction along the sweep (`startPosition`→`endPosition`) where contact first occurs. */
+    fraction: number;
+    /** Contact point on the swept shape (query-shape space). */
+    inputHitPoint: Vec3;
+    /** Contact point on the hit body (world space). */
+    hitPoint: Vec3;
+    /** Surface normal at the swept-shape contact. */
+    inputHitNormal: Vec3;
+    /** Surface normal at the hit-body contact. */
+    hitNormal: Vec3;
+}
+
+/**
+ * Find the closest point between a query shape and the nearest body in the world.
+ *
+ * The query shape is positioned at `position`/`rotation` and tested against the world's
+ * broadphase. When a body is found within `maxDistance`, `inputHitPoint` is the closest
+ * point on the query shape and `hitPoint` is the closest point on the hit body (world
+ * space). Run at least one physics step first so the broadphase exists.
+ * @param world - The physics world to query.
+ * @param query - Query shape, transform, and search distance.
+ * @returns The proximity result; `hasHit` is `false` when nothing is within range.
+ */
+export declare function shapeProximity(world: PhysicsWorld, query: ShapeProximityQuery): ShapeProximityResult;
+
+/** Query parameters for {@link shapeProximity}. */
+export declare interface ShapeProximityQuery {
+    /** Shape to test for proximity. */
+    shape: PhysicsShape;
+    /** World-space position of the query shape. */
+    position: Vec3;
+    /** World-space orientation of the query shape. */
+    rotation: Quat;
+    /** Maximum distance to search for a nearby body. */
+    maxDistance: number;
+    /** Whether trigger volumes count as hits. Default `false`. */
+    shouldHitTriggers?: boolean;
+}
+
+/** Result of a {@link shapeProximity} query. */
+export declare interface ShapeProximityResult {
+    /** Whether a body was found within `maxDistance`. */
+    hasHit: boolean;
+    /** Distance between the closest points. */
+    distance: number;
+    /** Closest point on the query shape (query-shape local space in a zero-offset world). */
+    inputHitPoint: Vec3;
+    /** Closest point on the hit body (world space). */
+    hitPoint: Vec3;
+    /** Surface normal at the query-shape closest point. */
+    inputHitNormal: Vec3;
+    /** Surface normal at the hit-body closest point. */
+    hitNormal: Vec3;
+}
+
 /** 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]. */
@@ -5845,6 +6841,12 @@ declare interface SheenProps {
     albedoScaling?: boolean;
 }
 
+/** Shows a Havok Physics V2 body as a wireframe debug mesh. */
+export declare function showPhysicsBody(viewer: PhysicsViewer, body: PhysicsBody): Mesh | null;
+
+/** Shows a simplified Physics V2 constraint overlay: local axes (with arrowheads) plus angular-limit disks. */
+export declare function showPhysicsConstraint(viewer: PhysicsViewer, constraint: PhysicsConstraintDebug): Mesh[];
+
 /** Connects a skeleton to its GPU bone texture for per-frame updates. */
 declare interface SkeletonBinding {
     readonly jointNodes: readonly number[];
@@ -6286,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. */
@@ -6369,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,
@@ -6720,6 +7729,14 @@ export declare interface TransmissionOptions {
      *  stack) and just need the opaque scene color exposed to a custom transmissive
      *  `ShaderMaterial`. */
     linear?: boolean;
+    /** Override how many times the scene-colour grab is refreshed per frame. `0` means before every
+     *  transmissive draw; the default is once before the first transmissive draw. */
+    copyCount?: number;
+    /** Set false when the transmissive material never samples the scene-colour grab above mip 0. */
+    generateMipmaps?: boolean;
+    /** Cap the scene-colour grab mip chain. Use this when the material samples explicit low LODs only, so
+     *  unused tiny mips are not regenerated every frame. Ignored when `generateMipmaps` is false. */
+    mipLevelCount?: number;
 }
 
 /** Options for `createTubeData`: a circular cross-section swept along a path. */
@@ -6989,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 { }