@babylonjs/lite 1.0.0 → 1.0.1

package/index.d.ts

@@ -88,6 +88,27 @@ export declare function addFacingBillboardSystem(scene: SceneContext, system: Fa
  *  (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`).
@@ -347,6 +368,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 +561,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
@@ -895,6 +935,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
@@ -1284,6 +1363,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,6 +1644,15 @@ 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;
@@ -1691,7 +1789,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 +1804,27 @@ 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.
+ * 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;
 
@@ -2254,6 +2366,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;
 
@@ -2495,7 +2610,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.
      */
@@ -3075,6 +3194,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 +3438,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 +3468,9 @@ 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;
+
 /** Image processing configuration. */
 export declare interface ImageProcessingConfig {
     exposure: number;
@@ -3408,6 +3554,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.
@@ -3781,7 +3935,9 @@ 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;
+    pickable?: boolean;
+    /** Optional per-mesh GPU-picking clip volumes. Fragments inside any volume are ignored by the GPU picker. */
+    pickingClipVolumes?: readonly PickingClipVolume[] | null;
 
 /** Opaque GPU geometry handle (user never touches these). */
 export declare interface MeshGPU {
@@ -4181,6 +4337,16 @@ 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 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 +4548,91 @@ 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;
 
+/** 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,
@@ -4402,6 +4647,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 +4675,32 @@ export declare const enum PhysicsShapeType {
     HEIGHTFIELD = 7
 }
 
+/** 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-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];
+}
+
 /** Result of a GPU pick operation. */
 export declare interface PickingInfo {
     hit: boolean;
@@ -4461,6 +4730,8 @@ 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;
+    /** Dev-only diagnostics: logs the pick ray, pixel, pick id/depth and resolved mesh. */
+    debugLabel?: string;
 }
 
 /** Sampler and format overrides for `createTexture2DFromPixels()`. */
@@ -5145,13 +5416,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'. */
@@ -5464,6 +5768,24 @@ 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;
+
+/** 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. */
@@ -5509,6 +5831,14 @@ export declare function setPhysicsBodyLinearVelocity(world: PhysicsWorld, body:
  */
 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 +5846,13 @@ 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;
+
 /**
  * Assigns a collision shape to a body.
  * @param world - The physics world.
@@ -5540,6 +5877,22 @@ 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;
+
 /**
  * Sets a shape's surface material properties.
  * @param world - The physics world.
@@ -5566,6 +5919,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 +5943,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 +6086,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 +6096,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 +6109,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 +6127,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 +6170,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,6 +6207,91 @@ 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 {
     /** Whether sheen is active. Default false. */
@@ -5845,6 +6311,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[];
@@ -6720,6 +7192,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. */