@ignifx/physics 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1770 @@
1
+ import { App, AssetHandle, AssetLoader, Component, ComponentHooks, DiagnosticsGroup, Disconnect, Entity, ErrorContext, Extension, ExtensionContext, IgnifxError, JsonValue, LayerMask, LiteEngine, LiteScene, LiteSceneNode, MeshAsset, MutableVec3, Quat, QuatLike, Schema, SchemaDescription, Signal, Vec3, Vec3Like } from "@ignifx/core";
2
+ import { PhysicsBody, PhysicsShape, PhysicsWorld } from "@babylonjs/lite";
3
+ //#region src/settings.d.ts
4
+ /**
5
+ * The `physics` project settings section (`docs/architecture/09-physics.md` §6). `fixedDeltaTime` is
6
+ * **not** here: the fixed step is shared with the core `time` section, and the extension reads it
7
+ * from `app.time.fixedDeltaTime` on every step so a game that changes it at runtime keeps Lite's
8
+ * per-step delta in sync.
9
+ */
10
+ /**
11
+ * The section name as it appears in `ignifx.config.ts`.
12
+ *
13
+ * @public
14
+ */
15
+ export declare const PHYSICS_SETTINGS_SECTION = "physics";
16
+ /**
17
+ * The value {@link PhysicsSettings.havokWasm} carries when the address comes from the manifest.
18
+ *
19
+ * @public
20
+ */
21
+ export declare const HAVOK_WASM_AUTO = "auto";
22
+ /**
23
+ * A surface material, either as the `physics.defaultMaterial` setting or inline on a collider
24
+ * (`09-physics.md` §2.2, §2.4).
25
+ *
26
+ * @public
27
+ */
28
+ interface PhysicsMaterialValues {
29
+ /** The dynamic friction coefficient. */
30
+ readonly friction: number;
31
+ /** The static friction coefficient. */
32
+ readonly staticFriction: number;
33
+ /** How much of the approach speed is returned, `0` to `1`. */
34
+ readonly restitution: number;
35
+ }
36
+ /**
37
+ * The world-wide speed clamps Havok applies (`setPhysicsVelocityLimits`, `index.d.ts` 10880). A
38
+ * value of `0` means "leave Havok's own default alone".
39
+ *
40
+ * @public
41
+ */
42
+ interface VelocityLimitSettings {
43
+ /** Maximum linear speed in metres per second, or `0` for Havok's default. */
44
+ readonly linear: number;
45
+ /** Maximum angular speed in radians per second, or `0` for Havok's default. */
46
+ readonly angular: number;
47
+ }
48
+ /**
49
+ * The resolved `physics` settings section.
50
+ *
51
+ * @example
52
+ * ```ts
53
+ * // ignifx.config.ts
54
+ * export default {
55
+ * layers: { layers: ["Default", "Player", "Enemy"] },
56
+ * physics: {
57
+ * gravity: { x: 0, y: -9.81, z: 0 },
58
+ * collisionMatrix: { Player: ["Default", "Enemy"], Enemy: ["Default"] },
59
+ * },
60
+ * };
61
+ * ```
62
+ *
63
+ * @public
64
+ */
65
+ interface PhysicsSettings {
66
+ /** World gravity in metres per second squared. */
67
+ readonly gravity: Vec3Like;
68
+ /**
69
+ * Which layers each layer collides with. A layer the map does not mention collides with
70
+ * everything, which is what makes the default project need no matrix at all.
71
+ */
72
+ readonly collisionMatrix: Readonly<Record<string, readonly string[]>>;
73
+ /** The material a collider with no material of its own uses. */
74
+ readonly defaultMaterial: PhysicsMaterialValues;
75
+ /** The world speed clamps. */
76
+ readonly velocityLimits: VelocityLimitSettings;
77
+ /** Whether dynamic bodies and character controllers interpolate between fixed steps. */
78
+ readonly interpolation: boolean;
79
+ /** `"auto"` to resolve `HavokPhysics.wasm` through the asset manifest, or an explicit URL. */
80
+ readonly havokWasm: string;
81
+ }
82
+ /**
83
+ * Builds the schema the `physics` section is validated against.
84
+ *
85
+ * @remarks
86
+ * It is a function, not a module-level constant: every field kind is a function call, and module
87
+ * scope holds declarations and immutable constants only (`CONSTITUTION.md` §3.5).
88
+ *
89
+ * @returns The schema.
90
+ *
91
+ * @public
92
+ */
93
+ export declare function physicsSettingsSchema(): Schema;
94
+ /**
95
+ * The values used when a project omits the `physics` section.
96
+ *
97
+ * @returns A fresh defaults object.
98
+ *
99
+ * @public
100
+ */
101
+ export declare function defaultPhysicsSettings(): PhysicsSettings;
102
+ //#endregion
103
+ //#region src/material.d.ts
104
+ /**
105
+ * The `ignifx.physicsmaterial` asset (`docs/architecture/09-physics.md` §2.4,
106
+ * `05-assets-and-loading.md` §5): a surface's friction and bounciness, saved next to the scene that
107
+ * uses it so an artist can retune a floor without touching code.
108
+ */
109
+ /**
110
+ * The asset type name `.physicsmaterial.json` addresses resolve to.
111
+ *
112
+ * @public
113
+ */
114
+ export declare const PHYSICS_MATERIAL_ASSET_TYPE = "physicsmaterial";
115
+ /**
116
+ * The address suffix that selects the loader.
117
+ *
118
+ * @public
119
+ */
120
+ export declare const PHYSICS_MATERIAL_FILE_EXTENSION = ".physicsmaterial.json";
121
+ /**
122
+ * The `format` string every physics-material document declares.
123
+ *
124
+ * @public
125
+ */
126
+ export declare const PHYSICS_MATERIAL_FILE_FORMAT = "ignifx.physicsmaterial";
127
+ /**
128
+ * The file format version; `1` before ignifx 1.0.
129
+ *
130
+ * @public
131
+ */
132
+ export declare const PHYSICS_MATERIAL_FORMAT_VERSION = 1;
133
+ /**
134
+ * A loaded surface material. The values are the ones Havok's `setPhysicsShapeMaterial` takes
135
+ * (`index.d.ts` 10853).
136
+ *
137
+ * @example
138
+ * ```ts
139
+ * const ice = await app.assets.load<PhysicsMaterial>("materials/ice.physicsmaterial.json");
140
+ * floor.addComponent(BoxCollider, { size: { x: 10, y: 1, z: 10 }, material: ice });
141
+ * ```
142
+ *
143
+ * @public
144
+ */
145
+ export declare class PhysicsMaterial implements PhysicsMaterialValues {
146
+ /** The asset type token, so `asset(PhysicsMaterial)` fields resolve. */
147
+ static assetType: string;
148
+ /** A human-readable name, used in diagnostics. */
149
+ readonly name: string;
150
+ /** The dynamic friction coefficient. */
151
+ readonly friction: number;
152
+ /** The static friction coefficient. */
153
+ readonly staticFriction: number;
154
+ /** How much of the approach speed is returned, `0` to `1`. */
155
+ readonly restitution: number;
156
+ /**
157
+ * Wraps parsed values. The loader constructs these; game code uses
158
+ * {@link PhysicsMaterial.fromValues} when it wants one in code.
159
+ *
160
+ * @param name - A human-readable name.
161
+ * @param values - Friction, static friction, and restitution.
162
+ */
163
+ constructor(name: string, values: PhysicsMaterialValues);
164
+ /**
165
+ * Builds a material in code, filling in the fields the caller omitted.
166
+ *
167
+ * @param name - A human-readable name.
168
+ * @param values - Any subset of the three coefficients.
169
+ * @returns The material.
170
+ *
171
+ * @example
172
+ * ```ts
173
+ * const bouncy = PhysicsMaterial.fromValues("bouncy", { restitution: 0.9 });
174
+ * ```
175
+ */
176
+ static fromValues(name: string, values: Partial<PhysicsMaterialValues>): PhysicsMaterial;
177
+ }
178
+ /**
179
+ * Builds the loader for `.physicsmaterial.json` files.
180
+ *
181
+ * @returns The loader, ready for `ctx.registerAssetLoader`.
182
+ *
183
+ * @public
184
+ */
185
+ export declare function createPhysicsMaterialLoader(): AssetLoader<PhysicsMaterial>;
186
+ /**
187
+ * Parses one `ignifx.physicsmaterial` document.
188
+ *
189
+ * @param address - The address it came from, for the diagnostic.
190
+ * @param document - The parsed JSON.
191
+ * @returns The material.
192
+ * @throws IgnifxError with code `IGX-0904` when the document is not one this build can read.
193
+ *
194
+ * @public
195
+ */
196
+ export declare function parsePhysicsMaterial(address: string, document: JsonValue): PhysicsMaterial;
197
+ /**
198
+ * Describes the `ignifx.physicsmaterial` file format for the documentation harness
199
+ * (`docs/architecture/16-docs-harness-and-skill.md` §3).
200
+ *
201
+ * @returns The description of the top-level file fields.
202
+ *
203
+ * @public
204
+ */
205
+ export declare function describePhysicsMaterialFileFormat(): SchemaDescription;
206
+ //#endregion
207
+ //#region src/lite/havok.d.ts
208
+ /**
209
+ * The Havok half of this package's Babylon Lite adapter (ADR-0002, ADR-0003,
210
+ * `docs/architecture/09-physics.md` §1). Every `@babylonjs/lite` symbol the extension uses is named
211
+ * here once, so the rest of `src/` never imports Lite (`ignifx/no-lite-outside-adapter`).
212
+ *
213
+ * ## Facts verified against `@babylonjs/lite@1.27.0`
214
+ *
215
+ * - `createHavokWorld(scene, hknp, gravity)` (`index.d.ts` 2592, `lib/physics/havok.js:44`) unshifts
216
+ * one step callback onto `scene._beforeRender`. Hosting it on a **null-engine** scene and driving
217
+ * that scene with `stepScene` (12438) is what gives ignifx the accumulator ADR-0003 requires.
218
+ * - `_stepWorld` (`lib/physics/havok.js:73-107`) pre-syncs node→body only for `ANIMATED` bodies and
219
+ * for bodies with `_preStep` set, then steps once, then syncs body→node for `DYNAMIC` bodies. A
220
+ * `DYNAMIC` body therefore never reads its node, which is what makes the interpolated display
221
+ * pose of `09-physics.md` §1 safe (spike S4.3).
222
+ * - `_syncBodyToNode` writes `node.position` / `node.rotationQuaternion` — the node's **local** TRS.
223
+ * A body's node must therefore be a root node for its pose to be world space; the extension
224
+ * reports `IGX-0907` otherwise.
225
+ * - `setPhysicsTimestep(world, dt)` (10863) stores `dt * 1000` in `world._fixedDeltaMs`, and the
226
+ * step clamps at 100 ms (`MAX_STEP_MS`), so the fixed step and Lite's step agree exactly.
227
+ *
228
+ * Everything here is `@internal`.
229
+ */
230
+ /**
231
+ * Lite's opaque Havok world handle.
232
+ *
233
+ * @internal
234
+ */
235
+ type LitePhysicsWorld = PhysicsWorld;
236
+ /**
237
+ * Lite's opaque Havok body handle. It carries the node it is bound to, which is how the extension
238
+ * resolves a body back to an entity.
239
+ *
240
+ * @internal
241
+ */
242
+ type LitePhysicsBody = PhysicsBody;
243
+ /**
244
+ * Lite's opaque Havok collision-shape handle.
245
+ *
246
+ * @internal
247
+ */
248
+ type LitePhysicsShape = PhysicsShape;
249
+ /**
250
+ * How a body moves, in ignifx's vocabulary. The numbers are Lite's `PhysicsMotionType` values
251
+ * (`index.d.ts` 8543) so no translation table is needed on a per-body path.
252
+ *
253
+ * @internal
254
+ */
255
+ declare const BodyMotion: {
256
+ /** Immovable; `PhysicsMotionType.STATIC`. */
257
+ readonly static: 0;
258
+ /** Driven by the node transform; `PhysicsMotionType.ANIMATED`. */
259
+ readonly kinematic: 1;
260
+ /** Simulated; `PhysicsMotionType.DYNAMIC`. */
261
+ readonly dynamic: 2;
262
+ };
263
+ /**
264
+ * The union of {@link BodyMotion} values.
265
+ *
266
+ * @internal
267
+ */
268
+ type BodyMotion = (typeof BodyMotion)[keyof typeof BodyMotion];
269
+ /** The engine and scene the simulation runs on. */
270
+ interface SimulationHandles {
271
+ /** Lite's null engine — no device, no surface. */
272
+ readonly engine: LiteEngine;
273
+ /** A scene with no default render task, advanced only by {@link stepSimulation}. */
274
+ readonly scene: LiteScene;
275
+ }
276
+ //#endregion
277
+ //#region src/components/collider.d.ts
278
+ /**
279
+ * The collider contract (`docs/architecture/09-physics.md` §2.2). Every collider shares four
280
+ * fields — `center`, `isTrigger`, a material, and a layer override — and answers two questions the
281
+ * body builder asks: what Havok shape it is, and how big its local bounding box is.
282
+ *
283
+ * ## The one correction to §2.2
284
+ *
285
+ * §2.2 writes the material field as `material: asset(PhysicsMaterial) | inline { … }`. A schema
286
+ * field has exactly one kind (ADR-0004), so the union is split into two fields:
287
+ * {@link Collider.material} (an asset reference) and {@link Collider.inlineMaterial} (a record).
288
+ * The asset wins, the inline record is the fallback, and `physics.defaultMaterial` is the last
289
+ * resort.
290
+ *
291
+ * ## Shape sizes and scale
292
+ *
293
+ * Sizes are authored in local units and multiplied by the entity's lossy scale when the shape is
294
+ * built. Havok has no way to rescale a built shape, so changing the scale afterwards needs
295
+ * {@link Collider.rebuild}, exactly as §2.2 says.
296
+ */
297
+ /**
298
+ * The fields every collider declares. It is a function because a field kind is a function call and
299
+ * module scope holds declarations only (`CONSTITUTION.md` §3.5).
300
+ *
301
+ * @returns The shared field declarations, ready to spread into a collider's own schema.
302
+ *
303
+ * @public
304
+ */
305
+ export declare function colliderFields(): Schema;
306
+ /**
307
+ * The base class of every collider. It is never registered on its own; `entity.getComponents` and
308
+ * `world.components` accept it because the concrete colliders extend it.
309
+ *
310
+ * @public
311
+ */
312
+ export declare abstract class Collider extends Component implements ComponentHooks {
313
+ /** Several colliders on one entity form one compound body (`09-physics.md` §2.2). */
314
+ static allowMultiple: boolean;
315
+ /** The shape's offset from the entity origin, in local units. */
316
+ center: Vec3Like;
317
+ /** When `true` the shape reports overlaps and resolves no contacts. */
318
+ isTrigger: boolean;
319
+ /** A `.physicsmaterial.json` reference; wins over {@link Collider.inlineMaterial}. */
320
+ material: AssetHandle<PhysicsMaterial> | null;
321
+ /** An inline surface, used when {@link Collider.material} is `null`. */
322
+ inlineMaterial: PhysicsMaterialValues | null;
323
+ /** The name of the layer this collider filters as, or `""` to use `entity.layer`. */
324
+ layerOverride: string;
325
+ /**
326
+ * Applies the shared defaults. A concrete collider calls `super()` and then applies its own.
327
+ */
328
+ constructor();
329
+ /** Marks the entity's body for a rebuild at the start of the next fixed step. */
330
+ onAttach(): void;
331
+ /** Marks the entity's body for a rebuild, which removes this collider from it. */
332
+ onDetach(): void;
333
+ /**
334
+ * Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
335
+ * changing a size, a centre, `isTrigger`, or the entity's scale.
336
+ *
337
+ * @example
338
+ * ```ts
339
+ * box.size = { x: 2, y: 2, z: 2 };
340
+ * box.rebuild();
341
+ * ```
342
+ */
343
+ rebuild(): void;
344
+ /**
345
+ * Resolves the surface this collider presents to Havok.
346
+ *
347
+ * @param fallback - The world's `physics.defaultMaterial`.
348
+ * @returns The asset's values, the inline values, or the fallback.
349
+ */
350
+ resolveMaterial(fallback: PhysicsMaterialValues): PhysicsMaterialValues;
351
+ /**
352
+ * Builds the Havok shape this collider stands for.
353
+ *
354
+ * @param world - The Havok world.
355
+ * @param scale - The entity's lossy scale.
356
+ * @param node - The entity's Lite node, for the colliders that read geometry from it.
357
+ * @returns The shape handle.
358
+ *
359
+ * @internal
360
+ */
361
+ abstract createShape(world: LitePhysicsWorld, scale: Vec3Like, node: LiteSceneNode): LitePhysicsShape;
362
+ /**
363
+ * Writes the half-extents of this collider's local bounding box, scale applied. The service's
364
+ * `overlap` and `shapeCast` use it to resolve entities that Lite's queries do not identify.
365
+ *
366
+ * @param scale - The entity's lossy scale.
367
+ * @param out - The vector to write.
368
+ *
369
+ * @internal
370
+ */
371
+ abstract halfExtentsToRef(scale: Vec3Like, out: MutableVec3): void;
372
+ }
373
+ //#endregion
374
+ //#region src/events.d.ts
375
+ /**
376
+ * The payloads `onTriggerEnter`/`onTriggerExit` and `onCollisionEnter`/`Stay`/`Exit` receive
377
+ * (`docs/architecture/09-physics.md` §4).
378
+ *
379
+ * Both objects are **pooled**: the same instances are reused for every event of a step, so a script
380
+ * that needs a value after its callback returns must copy it out. That is what makes event dispatch
381
+ * allocation-free on the steady path (coding standards §7).
382
+ */
383
+ /**
384
+ * One contact point of a collision. Pooled with its owning {@link Collision}.
385
+ *
386
+ * @public
387
+ */
388
+ interface ContactPoint {
389
+ /** The world-space contact point. */
390
+ readonly point: Vec3Like;
391
+ /** The world-space contact normal. */
392
+ readonly normal: Vec3Like;
393
+ /** The magnitude of the impulse Havok applied to resolve it; `0` for a contact that just ended. */
394
+ readonly impulse: number;
395
+ }
396
+ /**
397
+ * What a script's `onTriggerEnter`/`onTriggerExit` is handed.
398
+ *
399
+ * @example
400
+ * ```ts
401
+ * class Pickup extends Script implements ScriptCallbacks {
402
+ * static typeId = "mygame/Pickup";
403
+ * onTriggerEnter(trigger: TriggerEvent): void {
404
+ * if (trigger.other?.tags.has("player") === true) {
405
+ * this.entity.destroy();
406
+ * }
407
+ * }
408
+ * }
409
+ * ```
410
+ *
411
+ * @public
412
+ */
413
+ interface TriggerEvent {
414
+ /** The entity that entered or left, or `null` when Havok no longer tracks its body. */
415
+ readonly other: Entity | null;
416
+ /** The other entity's first collider, or `null`. Lite reports no shape identity (§4). */
417
+ readonly otherCollider: Collider | null;
418
+ /** The entity whose script is being called. */
419
+ readonly self: Entity;
420
+ }
421
+ /**
422
+ * What a script's `onCollisionEnter`/`onCollisionStay`/`onCollisionExit` is handed.
423
+ *
424
+ * @remarks
425
+ * `other` is `null` under the default `collisionIdentities: "upstream"` mode, because
426
+ * `@babylonjs/lite@1.27.0` reports collisions without body identities (§4, ADR-0013). Register
427
+ * `physics({ collisionIdentities: "internal" })` to opt into the waived drain that recovers them.
428
+ *
429
+ * @public
430
+ */
431
+ interface Collision {
432
+ /** The entity that was hit, or `null` when the identity is unavailable. */
433
+ readonly other: Entity | null;
434
+ /** The other entity's first collider, or `null`. */
435
+ readonly otherCollider: Collider | null;
436
+ /** The entity whose script is being called. */
437
+ readonly self: Entity;
438
+ /** The contacts of this event. Pooled; valid only during the callback. */
439
+ readonly contacts: readonly ContactPoint[];
440
+ /** The relative velocity at the contact, or `null` when a body identity is unavailable. */
441
+ readonly relativeVelocity: Vec3Like | null;
442
+ }
443
+ /**
444
+ * What `CharacterController.onCollided` reports: one dynamic body the character pushed this step.
445
+ *
446
+ * @public
447
+ */
448
+ interface CharacterCollision {
449
+ /** The entity that was pushed, or `null` when it is not an ignifx body. */
450
+ readonly other: Entity | null;
451
+ /** The world-space impulse the character applied. */
452
+ readonly impulse: Vec3Like;
453
+ /** Where the impulse was applied. */
454
+ readonly point: Vec3Like;
455
+ }
456
+ //#endregion
457
+ //#region src/components/rigidbody.d.ts
458
+ /**
459
+ * The `Rigidbody` component (`docs/architecture/09-physics.md` §2.1): what makes an entity's
460
+ * colliders a simulated, kinematic, or explicitly static Havok body.
461
+ *
462
+ * ## Corrections to §2.1, all forced by `@babylonjs/lite@1.27.0`
463
+ *
464
+ * - **`collisionEvents` is a three-valued enum, not a boolean.** §2.1 describes a field whose value
465
+ * is "auto"; a schema field has one kind and one value (ADR-0004), so the field is
466
+ * `"auto" | "on" | "off"` and `"auto"` is the default. `"auto"` is what §2.1 actually specifies:
467
+ * recomputed from `ctx.entityImplements` whenever a component is added to or removed from the
468
+ * entity.
469
+ * - **`velocityLimits` is not a per-body field.** Lite exposes `setPhysicsVelocityLimits(world, …)`
470
+ * only (`index.d.ts` 10880) — there is no per-body clamp — so the limits live in the `physics`
471
+ * settings section and the field is absent.
472
+ * - **A body's entity must be a root entity.** Lite's post-step sync writes `node.position` and
473
+ * `node.rotationQuaternion`, which are *local* values (`lib/physics/havok.js:_syncBodyToNode`), so
474
+ * a parented entity would be simulated in its parent's space. The extension reports `IGX-0907`
475
+ * and simulates it anyway rather than silently misplacing it.
476
+ *
477
+ * Not available in Lite 1.27.0 and therefore absent, as §2.1 already records: per-body damping,
478
+ * per-body gravity factor, sleep thresholds, and an explicit `wakeUp()`.
479
+ */
480
+ /**
481
+ * How a body moves.
482
+ *
483
+ * @public
484
+ */
485
+ export declare const BODY_TYPES: readonly ["dynamic", "kinematic", "static"];
486
+ /**
487
+ * The union of {@link BODY_TYPES}.
488
+ *
489
+ * @public
490
+ */
491
+ type BodyType = (typeof BODY_TYPES)[number];
492
+ /**
493
+ * Whether a body's display pose is interpolated between fixed steps.
494
+ *
495
+ * @public
496
+ */
497
+ export declare const INTERPOLATION_MODES: readonly ["none", "interpolate"];
498
+ /**
499
+ * The union of {@link INTERPOLATION_MODES}.
500
+ *
501
+ * @public
502
+ */
503
+ type InterpolationMode = (typeof INTERPOLATION_MODES)[number];
504
+ /**
505
+ * Whether collision callbacks are delivered for this body.
506
+ *
507
+ * @public
508
+ */
509
+ export declare const COLLISION_EVENT_MODES: readonly ["auto", "on", "off"];
510
+ /**
511
+ * The union of {@link COLLISION_EVENT_MODES}.
512
+ *
513
+ * @public
514
+ */
515
+ type CollisionEventMode = (typeof COLLISION_EVENT_MODES)[number];
516
+ /**
517
+ * How a moved kinematic node reaches Havok.
518
+ *
519
+ * @public
520
+ */
521
+ export declare const KINEMATIC_SYNC_MODES: readonly ["teleport", "velocity"];
522
+ /**
523
+ * The union of {@link KINEMATIC_SYNC_MODES}.
524
+ *
525
+ * @public
526
+ */
527
+ type KinematicSyncMode = (typeof KINEMATIC_SYNC_MODES)[number];
528
+ /**
529
+ * Whether each rotation axis is frozen.
530
+ *
531
+ * @public
532
+ */
533
+ interface FreezeRotation {
534
+ /** Freeze rotation about X. */
535
+ readonly x: boolean;
536
+ /** Freeze rotation about Y. */
537
+ readonly y: boolean;
538
+ /** Freeze rotation about Z. */
539
+ readonly z: boolean;
540
+ }
541
+ /**
542
+ * The Babylon Lite objects a `Rigidbody` owns. Unstable escape hatch
543
+ * (`docs/architecture/00-overview.md` §3).
544
+ *
545
+ * @public
546
+ */
547
+ interface RigidbodyLiteHandles {
548
+ /** The Havok body, or `null` before the first fixed step has built it. */
549
+ readonly body: LitePhysicsBody | null;
550
+ }
551
+ /**
552
+ * Makes an entity's colliders a Havok body (`09-physics.md` §2.1).
553
+ *
554
+ * @example
555
+ * ```ts
556
+ * const crate = world.createEntity("Crate");
557
+ * crate.transform.position = { x: 0, y: 5, z: 0 };
558
+ * crate.addComponent(BoxCollider, { size: { x: 1, y: 1, z: 1 } });
559
+ * crate.addComponent(Rigidbody, { mass: 2 });
560
+ * ```
561
+ *
562
+ * @public
563
+ */
564
+ export declare class Rigidbody extends Component implements ComponentHooks {
565
+ #private;
566
+ /** The namespaced registration id. */
567
+ static typeId: string;
568
+ /** One body per entity. */
569
+ static allowMultiple: boolean;
570
+ /** The serialized field declarations (ADR-0004). */
571
+ static schema: Schema;
572
+ bodyType: BodyType;
573
+ mass: number;
574
+ startAsleep: boolean;
575
+ freezeRotation: FreezeRotation;
576
+ interpolation: InterpolationMode;
577
+ collisionEvents: CollisionEventMode;
578
+ kinematicSync: KinematicSyncMode;
579
+ /** Applies the schema defaults, exactly as `Component.define` would. */
580
+ constructor();
581
+ /** Marks the entity's body for a rebuild at the start of the next fixed step. */
582
+ onAttach(): void;
583
+ /** Marks the entity's body for a rebuild, which turns it back into an implicit static body. */
584
+ onDetach(): void;
585
+ /**
586
+ * Rebuilds the body at the start of the next fixed step. Call it after changing `bodyType`,
587
+ * `mass`, `freezeRotation`, or the entity's scale.
588
+ */
589
+ rebuild(): void;
590
+ /**
591
+ * The Babylon Lite handles this component owns.
592
+ *
593
+ * @returns The Havok body, or `null` before the first fixed step built it.
594
+ */
595
+ get lite(): RigidbodyLiteHandles;
596
+ /**
597
+ * The body's linear velocity in metres per second.
598
+ *
599
+ * @returns A freshly allocated vector; use {@link Rigidbody.linearVelocityToRef} in hot code.
600
+ */
601
+ get linearVelocity(): Vec3;
602
+ /**
603
+ * Replaces the body's linear velocity.
604
+ *
605
+ * @param value - Metres per second, world space.
606
+ */
607
+ set linearVelocity(value: Vec3Like);
608
+ /**
609
+ * Reads the linear velocity without allocating.
610
+ *
611
+ * @param out - The vector to write.
612
+ * @returns `out`.
613
+ */
614
+ linearVelocityToRef(out: MutableVec3): MutableVec3;
615
+ /**
616
+ * The body's angular velocity in radians per second.
617
+ *
618
+ * @returns A freshly allocated vector; use {@link Rigidbody.angularVelocityToRef} in hot code.
619
+ */
620
+ get angularVelocity(): Vec3;
621
+ /**
622
+ * Replaces the body's angular velocity.
623
+ *
624
+ * @param value - Radians per second, world space.
625
+ */
626
+ set angularVelocity(value: Vec3Like);
627
+ /**
628
+ * Reads the angular velocity without allocating.
629
+ *
630
+ * @param out - The vector to write.
631
+ * @returns `out`.
632
+ */
633
+ angularVelocityToRef(out: MutableVec3): MutableVec3;
634
+ /**
635
+ * Applies a force for one fixed step. Call it from `fixedUpdate`.
636
+ *
637
+ * @param force - Newtons, world space.
638
+ * @param point - Where to apply it; defaults to the entity's world position.
639
+ *
640
+ * @example
641
+ * ```ts
642
+ * fixedUpdate(): void {
643
+ * this.body.addForce({ x: 0, y: 20, z: 0 });
644
+ * }
645
+ * ```
646
+ */
647
+ addForce(force: Vec3Like, point?: Vec3Like): void;
648
+ /**
649
+ * Applies an instantaneous impulse.
650
+ *
651
+ * @param impulse - Newton-seconds, world space.
652
+ * @param point - Where to apply it; defaults to the entity's world position.
653
+ */
654
+ addImpulse(impulse: Vec3Like, point?: Vec3Like): void;
655
+ /**
656
+ * Moves the body without integrating a velocity, and resets the interpolation history so the
657
+ * display pose does not slide across the gap.
658
+ *
659
+ * @param position - The new world position.
660
+ * @param rotation - The new world rotation; defaults to the current one.
661
+ */
662
+ teleport(position: Vec3Like, rotation?: QuatLike): void;
663
+ }
664
+ //#endregion
665
+ //#region src/components/character-controller.d.ts
666
+ /**
667
+ * The `CharacterController` component (`docs/architecture/09-physics.md` §2.3): Lite's kinematic
668
+ * capsule with collide-and-slide, support detection, and dynamic-body pushing.
669
+ *
670
+ * ## How it is driven
671
+ *
672
+ * Call {@link CharacterController.move} from `fixedUpdate`. The requested displacements of one step
673
+ * are summed and handed to Lite's `moveWithCollisions` by the step system, so two scripts moving the
674
+ * same character compose instead of fighting. After the step the controller owns the entity's world
675
+ * **position**; rotation stays user-controlled.
676
+ *
677
+ * ## Corrections to §2.3
678
+ *
679
+ * - `supportState` is read from the last step's `checkSupport` probe, which the step system runs
680
+ * once per step; reading it does not probe again.
681
+ * - Gravity is **not** applied by this component. §2.3 already says so: a bare controller is purely
682
+ * kinematic and the 3D toolkit's controllers integrate gravity through `checkSupport` +
683
+ * `integrate` (Phase 7). {@link CharacterController.move} is the whole input.
684
+ * - `pushStrength` scales Lite's `characterStrength`, whose default is `1e38` — effectively
685
+ * "infinite". A `pushStrength` of `1` therefore means "Lite's default", not "one newton".
686
+ */
687
+ /**
688
+ * How the character is supported by whatever is under it.
689
+ *
690
+ * @public
691
+ */
692
+ export declare const SUPPORT_STATES: readonly ["unsupported", "sliding", "supported"];
693
+ /**
694
+ * The union of {@link SUPPORT_STATES}.
695
+ *
696
+ * @public
697
+ */
698
+ type SupportStateName = (typeof SUPPORT_STATES)[number];
699
+ /**
700
+ * A kinematic capsule that walks, slides, and pushes (`09-physics.md` §2.3).
701
+ *
702
+ * @example
703
+ * ```ts
704
+ * class Walk extends Script implements ScriptCallbacks {
705
+ * static typeId = "mygame/Walk";
706
+ * fixedUpdate(dt: number): void {
707
+ * const controller = this.entity.requireComponent(CharacterController);
708
+ * controller.move({ x: 2 * dt, y: 0, z: 0 });
709
+ * }
710
+ * }
711
+ * ```
712
+ *
713
+ * @public
714
+ */
715
+ export declare class CharacterController extends Component implements ComponentHooks {
716
+ #private;
717
+ /** The namespaced registration id. */
718
+ static typeId: string;
719
+ /** One controller per entity. */
720
+ static allowMultiple: boolean;
721
+ /** The serialized field declarations (ADR-0004). */
722
+ static schema: Schema;
723
+ radius: number;
724
+ height: number;
725
+ center: Vec3Like;
726
+ slopeLimit: number;
727
+ skinWidth: number;
728
+ pushStrength: number;
729
+ interpolation: InterpolationMode;
730
+ /** Applies the schema defaults. */
731
+ constructor();
732
+ /** Creates the Lite controller at the start of the next fixed step. */
733
+ onAttach(): void;
734
+ /** Releases the Lite controller. */
735
+ onDetach(): void;
736
+ /** Rebuilds the capsule at the start of the next fixed step. */
737
+ rebuild(): void;
738
+ /**
739
+ * Requests a displacement for this fixed step. Displacements accumulate until the step runs.
740
+ *
741
+ * @param displacement - The world-space displacement to attempt.
742
+ */
743
+ move(displacement: Vec3Like): void;
744
+ /**
745
+ * Sets the controller's velocity, which is what `integrate` advances.
746
+ *
747
+ * @param velocity - Metres per second, world space.
748
+ */
749
+ setVelocity(velocity: Vec3Like): void;
750
+ /**
751
+ * The controller's current velocity.
752
+ *
753
+ * @returns A freshly allocated vector.
754
+ */
755
+ get velocity(): Vec3;
756
+ /**
757
+ * Whether the character is standing on a walkable surface.
758
+ *
759
+ * @returns `true` when the last step's probe reported `supported`.
760
+ */
761
+ get isGrounded(): boolean;
762
+ /**
763
+ * How the character was supported at the end of the last step.
764
+ *
765
+ * @returns `"unsupported"`, `"sliding"`, or `"supported"`.
766
+ */
767
+ get supportState(): SupportStateName;
768
+ /**
769
+ * The averaged normal of the supporting surface.
770
+ *
771
+ * @returns A live view; copy it if you keep it.
772
+ */
773
+ get groundNormal(): Vec3;
774
+ /**
775
+ * Emitted once per dynamic body the character pushed during a step.
776
+ *
777
+ * @returns The signal, created on first access.
778
+ */
779
+ get onCollided(): Signal<CharacterCollision>;
780
+ /**
781
+ * Changes the capsule height without losing the controller's state — the crouch primitive.
782
+ *
783
+ * @param height - The new total height, tip to tip.
784
+ * @param preserveFeet - Whether the foot position stays fixed; defaults to `true`.
785
+ */
786
+ setHeight(height: number, preserveFeet?: boolean): void;
787
+ /**
788
+ * Teleports the character, clearing any swept motion and the interpolation history.
789
+ *
790
+ * @param position - The new world position of the entity.
791
+ */
792
+ teleport(position: Vec3Like): void;
793
+ /**
794
+ * The displacement requested so far this step, consumed by the step system.
795
+ *
796
+ * @returns A live view of the accumulator.
797
+ *
798
+ * @internal
799
+ */
800
+ takePendingMove(): Vec3;
801
+ /**
802
+ * Records the outcome of a step.
803
+ *
804
+ * @param state - The support classification.
805
+ * @param normal - The averaged supporting normal.
806
+ *
807
+ * @internal
808
+ */
809
+ applyStepResult(state: SupportStateName, normal: Vec3Like): void;
810
+ /**
811
+ * Emits `onCollided` if anything is listening.
812
+ *
813
+ * @param collision - The push to report.
814
+ *
815
+ * @internal
816
+ */
817
+ reportPush(collision: CharacterCollision): void;
818
+ }
819
+ //#endregion
820
+ //#region src/components/colliders.d.ts
821
+ /**
822
+ * The concrete colliders (`docs/architecture/09-physics.md` §2.2). Each one maps to exactly one
823
+ * Havok shape type (`index.d.ts` 8606) and bakes its `center` into the shape's own parameters, so a
824
+ * single collider needs no compound wrapper.
825
+ *
826
+ * Sizes are authored in local units and multiplied by the entity's lossy scale when the shape is
827
+ * built; Havok cannot rescale a built shape, so a later scale change needs `collider.rebuild()`.
828
+ */
829
+ /**
830
+ * The axis a capsule stands along.
831
+ *
832
+ * @public
833
+ */
834
+ export declare const CAPSULE_DIRECTIONS: readonly ["x", "y", "z"];
835
+ /**
836
+ * The union of {@link CAPSULE_DIRECTIONS}.
837
+ *
838
+ * @public
839
+ */
840
+ type CapsuleDirection = (typeof CAPSULE_DIRECTIONS)[number];
841
+ /**
842
+ * A box collider, sized in local units (`09-physics.md` §2.2).
843
+ *
844
+ * @example
845
+ * ```ts
846
+ * const floor = world.createEntity("Floor");
847
+ * floor.addComponent(BoxCollider, { size: { x: 20, y: 1, z: 20 } });
848
+ * ```
849
+ *
850
+ * @public
851
+ */
852
+ export declare class BoxCollider extends Collider {
853
+ /** The namespaced registration id. */
854
+ static typeId: string;
855
+ /** The serialized field declarations (ADR-0004). */
856
+ static schema: Schema;
857
+ size: Vec3Like;
858
+ /** Applies this collider's defaults on top of the shared ones. */
859
+ constructor();
860
+ /**
861
+ * Builds this collider's Havok shape.
862
+ *
863
+ * @param world - The Havok world the shape belongs to.
864
+ * @param scale - The entity's lossy scale, applied to the authored dimensions.
865
+ * @returns The shape handle.
866
+ */
867
+ createShape(world: LitePhysicsWorld, scale: Vec3Like): LitePhysicsShape;
868
+ /**
869
+ * Writes half the size of this collider's local bounding box, scale applied.
870
+ *
871
+ * @param scale - The entity's lossy scale.
872
+ * @param out - The vector to write.
873
+ */
874
+ halfExtentsToRef(scale: Vec3Like, out: MutableVec3): void;
875
+ }
876
+ /**
877
+ * A sphere collider. Non-uniform scale is not representable as a sphere, so the largest scale axis
878
+ * wins — the same rule Unity applies.
879
+ *
880
+ * @public
881
+ */
882
+ export declare class SphereCollider extends Collider {
883
+ /** The namespaced registration id. */
884
+ static typeId: string;
885
+ /** The serialized field declarations. */
886
+ static schema: Schema;
887
+ radius: number;
888
+ /** Applies this collider's defaults on top of the shared ones. */
889
+ constructor();
890
+ /**
891
+ * Builds this collider's Havok shape.
892
+ *
893
+ * @param world - The Havok world the shape belongs to.
894
+ * @param scale - The entity's lossy scale, applied to the authored dimensions.
895
+ * @returns The shape handle.
896
+ */
897
+ createShape(world: LitePhysicsWorld, scale: Vec3Like): LitePhysicsShape;
898
+ /**
899
+ * Writes half the size of this collider's local bounding box, scale applied.
900
+ *
901
+ * @param scale - The entity's lossy scale.
902
+ * @param out - The vector to write.
903
+ */
904
+ halfExtentsToRef(scale: Vec3Like, out: MutableVec3): void;
905
+ }
906
+ /**
907
+ * A capsule collider: a cylinder with hemispherical caps, standing along one axis.
908
+ *
909
+ * @remarks
910
+ * `height` is the **total** tip-to-tip height, so a capsule shorter than `2 * radius` degenerates to
911
+ * a sphere of that radius rather than inverting.
912
+ *
913
+ * @public
914
+ */
915
+ export declare class CapsuleCollider extends Collider {
916
+ /** The namespaced registration id. */
917
+ static typeId: string;
918
+ /** The serialized field declarations. */
919
+ static schema: Schema;
920
+ radius: number;
921
+ height: number;
922
+ direction: CapsuleDirection;
923
+ /** Applies this collider's defaults on top of the shared ones. */
924
+ constructor();
925
+ /**
926
+ * Builds this collider's Havok shape.
927
+ *
928
+ * @param world - The Havok world the shape belongs to.
929
+ * @param scale - The entity's lossy scale, applied to the authored dimensions.
930
+ * @returns The shape handle.
931
+ */
932
+ createShape(world: LitePhysicsWorld, scale: Vec3Like): LitePhysicsShape;
933
+ /**
934
+ * Writes half the size of this collider's local bounding box, scale applied.
935
+ *
936
+ * @param scale - The entity's lossy scale.
937
+ * @param out - The vector to write.
938
+ */
939
+ halfExtentsToRef(scale: Vec3Like, out: MutableVec3): void;
940
+ }
941
+ /**
942
+ * A cylinder collider standing along Y.
943
+ *
944
+ * @public
945
+ */
946
+ export declare class CylinderCollider extends Collider {
947
+ /** The namespaced registration id. */
948
+ static typeId: string;
949
+ /** The serialized field declarations. */
950
+ static schema: Schema;
951
+ radius: number;
952
+ height: number;
953
+ /** Applies this collider's defaults on top of the shared ones. */
954
+ constructor();
955
+ /**
956
+ * Builds this collider's Havok shape.
957
+ *
958
+ * @param world - The Havok world the shape belongs to.
959
+ * @param scale - The entity's lossy scale, applied to the authored dimensions.
960
+ * @returns The shape handle.
961
+ */
962
+ createShape(world: LitePhysicsWorld, scale: Vec3Like): LitePhysicsShape;
963
+ /**
964
+ * Writes half the size of this collider's local bounding box, scale applied.
965
+ *
966
+ * @param scale - The entity's lossy scale.
967
+ * @param out - The vector to write.
968
+ */
969
+ halfExtentsToRef(scale: Vec3Like, out: MutableVec3): void;
970
+ }
971
+ /**
972
+ * A collider built from real geometry: either an explicit `MeshAsset` or, when `mesh` is
973
+ * `null`, whatever the entity's `MeshRenderer`/`Model` put under its node.
974
+ *
975
+ * @remarks
976
+ * **Headless is not supported.** `@babylonjs/lite@1.27.0` documents mesh and convex-hull colliders
977
+ * as unavailable on the null engine (`index.d.ts` 2781), and a headless `MeshAsset` uploads no
978
+ * geometry at all (`MeshAsset.lite.mesh` is `null`), so building one reports `IGX-0906` instead of
979
+ * producing an empty shape. Use a primitive collider in headless tests.
980
+ *
981
+ * @public
982
+ */
983
+ export declare class MeshCollider extends Collider {
984
+ #private;
985
+ /** The namespaced registration id. */
986
+ static typeId: string;
987
+ /** The serialized field declarations. */
988
+ static schema: Schema;
989
+ mesh: AssetHandle<MeshAsset> | null;
990
+ convex: boolean;
991
+ includeChildren: boolean;
992
+ /** Applies this collider's defaults on top of the shared ones. */
993
+ constructor();
994
+ /**
995
+ * Builds this collider's Havok shape from real geometry.
996
+ *
997
+ * @param world - The Havok world the shape belongs to.
998
+ * @param _scale - Unused: a mesh shape carries the geometry's own world scale.
999
+ * @param node - The entity's node, whose meshes supply the vertices when `mesh` is `null`.
1000
+ * @returns The shape handle.
1001
+ */
1002
+ createShape(world: LitePhysicsWorld, _scale: Vec3Like, node: LiteSceneNode): LitePhysicsShape;
1003
+ /**
1004
+ * Writes half the size of this collider's local bounding box — zero, because measuring a triangle
1005
+ * soup means reading its vertices, which is GPU territory.
1006
+ *
1007
+ * @param _scale - Unused.
1008
+ * @param out - The vector to write.
1009
+ */
1010
+ halfExtentsToRef(_scale: Vec3Like, out: MutableVec3): void;
1011
+ }
1012
+ /**
1013
+ * A heightfield collider: a regular grid of height samples in the XZ plane, which is what a terrain
1014
+ * uses (`index.d.ts` 2601, 6266).
1015
+ *
1016
+ * @remarks
1017
+ * Only Lite's **explicit** heightfield path is used, because the `groundMesh` path reads
1018
+ * `mesh._cpuPositions` and `worldMatrix` and therefore needs a GPU. `heights` is row-major with
1019
+ * `samplesX * samplesZ` entries.
1020
+ *
1021
+ * @public
1022
+ */
1023
+ export declare class HeightfieldCollider extends Collider {
1024
+ /** The namespaced registration id. */
1025
+ static typeId: string;
1026
+ /** The serialized field declarations. */
1027
+ static schema: Schema;
1028
+ heights: number[];
1029
+ samplesX: number;
1030
+ samplesZ: number;
1031
+ size: Vec3Like;
1032
+ /** Applies this collider's defaults on top of the shared ones. */
1033
+ constructor();
1034
+ /**
1035
+ * Builds this collider's Havok shape.
1036
+ *
1037
+ * @param world - The Havok world the shape belongs to.
1038
+ * @param scale - The entity's lossy scale, applied to the authored dimensions.
1039
+ * @returns The shape handle.
1040
+ */
1041
+ createShape(world: LitePhysicsWorld, scale: Vec3Like): LitePhysicsShape;
1042
+ /**
1043
+ * Writes half the size of this collider's local bounding box, scale applied.
1044
+ *
1045
+ * @param scale - The entity's lossy scale.
1046
+ * @param out - The vector to write.
1047
+ */
1048
+ halfExtentsToRef(scale: Vec3Like, out: MutableVec3): void;
1049
+ }
1050
+ //#endregion
1051
+ //#region src/errors.d.ts
1052
+ /**
1053
+ * The diagnostic codes `@ignifx/physics` owns. The package sits in the `09` subsystem range of
1054
+ * `docs/architecture/15-devtools-and-diagnostics.md` §1, so every code reads `IGX-09##`.
1055
+ *
1056
+ * The table lives here rather than in `@ignifx/core`'s `CoreErrorCode`: an extension owns its own
1057
+ * codes and hands them to the app through `ExtensionContext.registerErrorCodes`
1058
+ * (`docs/architecture/04-extensions.md` §3).
1059
+ */
1060
+ /**
1061
+ * Every diagnostic code `@ignifx/physics` can throw or report, keyed by an intention-revealing name
1062
+ * so call sites read as prose and the compiler catches typos (coding standards §5.2).
1063
+ *
1064
+ * @example
1065
+ * ```ts
1066
+ * throw physicsError(PhysicsErrorCode.queryBeforeStep, "raycast() ran before the first step.", {
1067
+ * context: { query: "raycast" },
1068
+ * });
1069
+ * ```
1070
+ *
1071
+ * @public
1072
+ */
1073
+ export declare const PhysicsErrorCode: {
1074
+ /** An entity with colliders but no `Rigidbody` moved after its implicit static body was placed. */
1075
+ readonly movedStaticBody: "IGX-0901";
1076
+ /** A query ran before the first completed fixed step, so Havok has no broadphase yet. */
1077
+ readonly queryBeforeStep: "IGX-0902";
1078
+ /** The Havok WebAssembly module could not be loaded. */
1079
+ readonly havokUnavailable: "IGX-0903";
1080
+ /** A `.physicsmaterial.json` file is not an `ignifx.physicsmaterial` document this build reads. */
1081
+ readonly invalidMaterialFile: "IGX-0904";
1082
+ /** The `physics.collisionMatrix` setting names a layer the project does not declare. */
1083
+ readonly unknownLayer: "IGX-0905";
1084
+ /** A `MeshCollider` has no geometry to build a shape from. */
1085
+ readonly colliderGeometryUnavailable: "IGX-0906";
1086
+ /** A physics body was built for an entity that has a parent, whose node pose is not world space. */
1087
+ readonly bodyOnChildEntity: "IGX-0907";
1088
+ /** The ADR-0013 collision drain refused to bind because Babylon Lite's internals moved. */
1089
+ readonly internalDrainUnavailable: "IGX-0908";
1090
+ };
1091
+ /**
1092
+ * The union of the codes the `PhysicsErrorCode` table declares.
1093
+ *
1094
+ * @public
1095
+ */
1096
+ export type PhysicsErrorCode = (typeof PhysicsErrorCode)[keyof typeof PhysicsErrorCode];
1097
+ /**
1098
+ * The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
1099
+ * Context keys appear in braces, matching the core table's convention.
1100
+ *
1101
+ * @public
1102
+ */
1103
+ export declare const PHYSICS_ERROR_MESSAGES: Readonly<Record<string, string>>;
1104
+ /**
1105
+ * Options accepted by {@link physicsError}: the same subset of `IgnifxErrorOptions` this package
1106
+ * uses.
1107
+ *
1108
+ * @public
1109
+ */
1110
+ interface PhysicsErrorOptions {
1111
+ /** Identifiers that locate the failure. */
1112
+ readonly context?: ErrorContext;
1113
+ /** One sentence telling the developer what to do about it. */
1114
+ readonly hint?: string;
1115
+ /** The failure being wrapped, when there is one. */
1116
+ readonly cause?: unknown;
1117
+ }
1118
+ /**
1119
+ * Builds an `IgnifxError` carrying one of this package's codes.
1120
+ *
1121
+ * @param code - The code from the `PhysicsErrorCode` table.
1122
+ * @param message - The actionable development sentence.
1123
+ * @param options - Context identifiers, a remedy hint, and the wrapped cause.
1124
+ * @returns The error to throw or to reject with.
1125
+ *
1126
+ * @example
1127
+ * ```ts
1128
+ * throw physicsError(PhysicsErrorCode.unknownLayer, "physics.collisionMatrix names Enemy.", {
1129
+ * context: { layer: "Enemy" },
1130
+ * });
1131
+ * ```
1132
+ *
1133
+ * @public
1134
+ */
1135
+ export declare function physicsError(code: PhysicsErrorCode, message: string, options?: PhysicsErrorOptions): IgnifxError;
1136
+ //#endregion
1137
+ //#region src/queries.d.ts
1138
+ /**
1139
+ * The query vocabulary of `app.physics` (`docs/architecture/09-physics.md` §5).
1140
+ *
1141
+ * ## Two corrections to §5
1142
+ *
1143
+ * `@babylonjs/lite@1.27.0` reports a body identity for **`physicsRaycast` only**: `ShapeCastResult`
1144
+ * and `ShapeProximityResult` carry points and normals but no body (`index.d.ts` 11497, 11540), and
1145
+ * `shapeProximity`'s collector has capacity `1`, so it can never list more than one hit
1146
+ * (`lib/physics/havok-queries.js:7`). So:
1147
+ *
1148
+ * - `shapeCast` runs Lite's sweep for the geometry and resolves `entity` against the extension's own
1149
+ * body-bounds index. It is exact about *where* the sweep hit and bounds-accurate about *what*.
1150
+ * - `overlap` is answered entirely from that index — the entities whose world bounds intersect the
1151
+ * query shape's world bounds — because Lite cannot list overlaps at all.
1152
+ *
1153
+ * Both are documented as bounds-accurate rather than shape-accurate until an upstream API lands.
1154
+ */
1155
+ /**
1156
+ * Options every query accepts.
1157
+ *
1158
+ * @public
1159
+ */
1160
+ interface QueryOptions {
1161
+ /** Which layers the query may hit. Defaults to everything. */
1162
+ readonly layerMask?: LayerMask;
1163
+ /** Whether trigger volumes count as hits. Defaults to `false`. */
1164
+ readonly hitTriggers?: boolean;
1165
+ }
1166
+ /**
1167
+ * A shape to sweep or to test for overlaps. It is a description, not a component: the service builds
1168
+ * the Havok shape for the call and releases it afterwards.
1169
+ *
1170
+ * @public
1171
+ */
1172
+ type QueryShape = {
1173
+ readonly kind: "sphere";
1174
+ readonly radius: number;
1175
+ } | {
1176
+ readonly kind: "box";
1177
+ readonly size: Vec3Like;
1178
+ } | {
1179
+ readonly kind: "capsule";
1180
+ readonly radius: number;
1181
+ readonly height: number;
1182
+ };
1183
+ /**
1184
+ * What a ray hit.
1185
+ *
1186
+ * @remarks
1187
+ * The object is freshly allocated per hit, so it is safe to keep. Queries are not a per-frame path
1188
+ * for most games; a game that raycasts every frame should hoist the result and reuse the vectors it
1189
+ * copies out of it.
1190
+ *
1191
+ * @public
1192
+ */
1193
+ interface RaycastHit {
1194
+ /** The entity that was hit. */
1195
+ readonly entity: Entity;
1196
+ /** The collider on that entity, or `null` when the entity has none registered any more. */
1197
+ readonly collider: Collider | null;
1198
+ /** The world-space contact point. */
1199
+ readonly point: Vec3Like;
1200
+ /** The world-space surface normal. */
1201
+ readonly normal: Vec3Like;
1202
+ /** The distance from the ray origin, in metres. */
1203
+ readonly distance: number;
1204
+ /** The triangle index on a `MeshCollider`, or `-1` for a primitive. */
1205
+ readonly triangleIndex: number;
1206
+ }
1207
+ /**
1208
+ * What a shape sweep hit.
1209
+ *
1210
+ * @public
1211
+ */
1212
+ interface ShapeCastHit {
1213
+ /** The entity the swept shape hit, or `null` when the bounds index cannot identify it. */
1214
+ readonly entity: Entity | null;
1215
+ /** The collider on that entity, or `null`. */
1216
+ readonly collider: Collider | null;
1217
+ /** The world-space contact point on the hit body. */
1218
+ readonly point: Vec3Like;
1219
+ /** The world-space contact normal on the hit body. */
1220
+ readonly normal: Vec3Like;
1221
+ /** How far along the sweep the contact occurs, in `[0, 1]`. */
1222
+ readonly fraction: number;
1223
+ /** The distance travelled before contact, in metres. */
1224
+ readonly distance: number;
1225
+ }
1226
+ //#endregion
1227
+ //#region src/runtime/body-record.d.ts
1228
+ /**
1229
+ * One entity's physics representation. The runtime keeps these in creation order, which is the
1230
+ * iteration order every per-step loop uses — body creation order is what decides Havok's internal
1231
+ * ordering, so keeping it stable is part of determinism (`docs/architecture/09-physics.md` §8).
1232
+ *
1233
+ * @internal
1234
+ */
1235
+ interface BodyRecord {
1236
+ /** The entity the body belongs to. */
1237
+ readonly entity: Entity;
1238
+ /** The entity's Lite node; the body's pose is this node's **local** TRS. */
1239
+ readonly node: LiteSceneNode;
1240
+ /** The `Rigidbody`, or `null` for the implicit static body of a collider-only entity. */
1241
+ rigidbody: Rigidbody | null;
1242
+ /** The colliders that make up the body's shape, in component order. */
1243
+ colliders: Collider[];
1244
+ /** The Havok body. */
1245
+ body: LitePhysicsBody;
1246
+ /** Every shape the record owns, root last; released together when the body is torn down. */
1247
+ shapes: LitePhysicsShape[];
1248
+ /** How the body moves. */
1249
+ motion: BodyMotion;
1250
+ /** Whether the display pose is interpolated between fixed steps. */
1251
+ interpolate: boolean;
1252
+ /** The layer the filter masks were built from, so a runtime change is noticed. */
1253
+ layer: number;
1254
+ /** Whether collision events are currently enabled on the body. */
1255
+ collisionEvents: boolean;
1256
+ /** The pose at the end of the previous fixed step. */
1257
+ readonly previousPosition: Vec3;
1258
+ /** The rotation at the end of the previous fixed step. */
1259
+ readonly previousRotation: Quat;
1260
+ /** The authoritative pose at the end of the last fixed step. */
1261
+ readonly currentPosition: Vec3;
1262
+ /** The authoritative rotation at the end of the last fixed step. */
1263
+ readonly currentRotation: Quat;
1264
+ /** Half the world-space bounding box, used by `overlap` and `shapeCast` entity resolution. */
1265
+ readonly halfExtents: Vec3;
1266
+ /** `Transform.worldMatrixVersion` when an implicit static body was placed (`IGX-0901`). */
1267
+ staticVersion: number;
1268
+ /** Whether the `IGX-0901` diagnostic has already been reported for this body. */
1269
+ reportedMove: boolean;
1270
+ /** Signal connections the record owns, dropped when it is torn down. */
1271
+ disconnects: Disconnect[];
1272
+ }
1273
+ //#endregion
1274
+ //#region src/runtime/runtime.d.ts
1275
+ /**
1276
+ * The per-app physics runtime: the Havok world, the bodies, the character controllers, the event
1277
+ * drains, and the three things the systems ask it to do each frame — restore, step, interpolate
1278
+ * (`docs/architecture/09-physics.md` §1).
1279
+ *
1280
+ * Everything here is `@internal`; the public surface is `PhysicsService`, `Rigidbody`, the
1281
+ * colliders, and `CharacterController`.
1282
+ */
1283
+ /**
1284
+ * How collision events learn which bodies took part (`09-physics.md` §4, ADR-0013).
1285
+ *
1286
+ * @public
1287
+ */
1288
+ export declare const COLLISION_IDENTITY_MODES: readonly ["upstream", "internal"];
1289
+ /**
1290
+ * The union of {@link COLLISION_IDENTITY_MODES}.
1291
+ *
1292
+ * @public
1293
+ */
1294
+ type CollisionIdentityMode = (typeof COLLISION_IDENTITY_MODES)[number];
1295
+ /** What the extension hands the runtime. */
1296
+ interface PhysicsRuntimeOptions {
1297
+ /** The extension registration surface; the physics kernel hooks live on it. */
1298
+ readonly ctx: ExtensionContext;
1299
+ /** The resolved `physics` settings section. */
1300
+ readonly settings: PhysicsSettings;
1301
+ /** The null-engine scene the world is hosted on. */
1302
+ readonly simulation: SimulationHandles;
1303
+ /** The Havok world. */
1304
+ readonly world: LitePhysicsWorld;
1305
+ /** Which collision-identity path to use. */
1306
+ readonly collisionIdentities: CollisionIdentityMode;
1307
+ /** The `physics` diagnostics group. */
1308
+ readonly counters: DiagnosticsGroup;
1309
+ }
1310
+ /**
1311
+ * The counters `09-physics.md` §9 and the plan's diagnostics deliverable name.
1312
+ *
1313
+ * @public
1314
+ */
1315
+ export declare const PHYSICS_DIAGNOSTICS_COUNTERS: readonly string[];
1316
+ /**
1317
+ * The diagnostics group name.
1318
+ *
1319
+ * @public
1320
+ */
1321
+ export declare const PHYSICS_DIAGNOSTICS_GROUP = "physics";
1322
+ /**
1323
+ * The per-app physics runtime.
1324
+ *
1325
+ * @internal
1326
+ */
1327
+ declare class PhysicsRuntime {
1328
+ #private;
1329
+ /**
1330
+ * Builds the runtime, applies the world settings, and registers the event drains.
1331
+ *
1332
+ * @param options - The context, settings, scene, world, identity mode, and counters.
1333
+ * @throws IgnifxError with code `IGX-0905` when the collision matrix names an unknown layer, or
1334
+ * `IGX-0908` when the internal drain does not recognise this Babylon Lite build.
1335
+ */
1336
+ constructor(options: PhysicsRuntimeOptions);
1337
+ /**
1338
+ * The Havok world, for the query and viewer paths.
1339
+ *
1340
+ * @returns The world handle.
1341
+ */
1342
+ get world(): LitePhysicsWorld;
1343
+ /**
1344
+ * Whether at least one fixed step has run, which is what Havok's broadphase needs before a query
1345
+ * can answer (`09-physics.md` §5).
1346
+ *
1347
+ * @returns `true` once a step has completed.
1348
+ */
1349
+ get hasStepped(): boolean;
1350
+ /**
1351
+ * Every body, in creation order.
1352
+ *
1353
+ * @returns The records.
1354
+ */
1355
+ get records(): readonly BodyRecord[];
1356
+ /**
1357
+ * The resolved settings.
1358
+ *
1359
+ * @returns The `physics` section.
1360
+ */
1361
+ get settings(): PhysicsSettings;
1362
+ /**
1363
+ * Replaces world gravity.
1364
+ *
1365
+ * @param gravity - The new acceleration vector.
1366
+ */
1367
+ setGravity(gravity: Vec3Like): void;
1368
+ /**
1369
+ * Marks an entity's body for a rebuild at the start of the next fixed step.
1370
+ *
1371
+ * @param entity - The entity whose colliders or `Rigidbody` changed.
1372
+ */
1373
+ markDirty(entity: Entity): void;
1374
+ /**
1375
+ * Marks a character controller for a rebuild at the start of the next fixed step.
1376
+ *
1377
+ * @param component - The controller component.
1378
+ */
1379
+ markControllerDirty(component: CharacterController): void;
1380
+ /**
1381
+ * Restores the authoritative pose of every interpolated body and controller, undoing the display
1382
+ * pose the `PreRender` system wrote (`09-physics.md` §1, spike S4.3).
1383
+ */
1384
+ restorePoses(): void;
1385
+ /**
1386
+ * Runs one fixed step: reconcile, step Havok, snapshot poses, dispatch events.
1387
+ *
1388
+ * @param fixedDeltaSeconds - The fixed step in seconds.
1389
+ */
1390
+ step(fixedDeltaSeconds: number): void;
1391
+ /**
1392
+ * Writes the interpolated display pose of every interpolated body and controller.
1393
+ *
1394
+ * @param alpha - `time.fixedStepAlpha`, in `[0, 1)`.
1395
+ */
1396
+ interpolate(alpha: number): void;
1397
+ /**
1398
+ * The Havok body of an entity, for the `.lite` escape hatch and the debug viewer.
1399
+ *
1400
+ * @param entity - The entity.
1401
+ * @returns The body handle, or `null`.
1402
+ */
1403
+ bodyHandleOf(entity: Entity): BodyRecord["body"] | null;
1404
+ /**
1405
+ * The record an entity owns.
1406
+ *
1407
+ * @param entity - The entity.
1408
+ * @returns The record, or `null`.
1409
+ */
1410
+ recordOf(entity: Entity): BodyRecord | null;
1411
+ /**
1412
+ * The record a Lite node belongs to, which is how a Havok event or query result becomes an entity.
1413
+ *
1414
+ * @param node - The node.
1415
+ * @returns The record, or `null`.
1416
+ */
1417
+ recordOfNode(node: LiteSceneNode | null): BodyRecord | null;
1418
+ /** Counts one query for the diagnostics group. */
1419
+ countQuery(): void;
1420
+ /**
1421
+ * Reads a body's linear velocity.
1422
+ *
1423
+ * @param entity - The entity.
1424
+ * @param out - The vector to write; left untouched when there is no body.
1425
+ */
1426
+ readLinear(entity: Entity, out: MutableVec3): void;
1427
+ /**
1428
+ * Reads a body's angular velocity.
1429
+ *
1430
+ * @param entity - The entity.
1431
+ * @param out - The vector to write.
1432
+ */
1433
+ readAngular(entity: Entity, out: MutableVec3): void;
1434
+ /**
1435
+ * Sets a body's linear velocity.
1436
+ *
1437
+ * @param entity - The entity.
1438
+ * @param velocity - Metres per second, world space.
1439
+ */
1440
+ setLinearVelocity(entity: Entity, velocity: Vec3Like): void;
1441
+ /**
1442
+ * Sets a body's angular velocity.
1443
+ *
1444
+ * @param entity - The entity.
1445
+ * @param velocity - Radians per second, world space.
1446
+ */
1447
+ setAngularVelocity(entity: Entity, velocity: Vec3Like): void;
1448
+ /**
1449
+ * Applies a force for one fixed step.
1450
+ *
1451
+ * @param entity - The entity.
1452
+ * @param force - Newtons, world space.
1453
+ * @param point - The application point.
1454
+ */
1455
+ addForce(entity: Entity, force: Vec3Like, point: Vec3Like): void;
1456
+ /**
1457
+ * Applies an impulse.
1458
+ *
1459
+ * @param entity - The entity.
1460
+ * @param impulse - Newton-seconds, world space.
1461
+ * @param point - The application point.
1462
+ */
1463
+ addImpulse(entity: Entity, impulse: Vec3Like, point: Vec3Like): void;
1464
+ /**
1465
+ * Teleports a body and resets its interpolation history.
1466
+ *
1467
+ * @param entity - The entity.
1468
+ * @param position - The new world position.
1469
+ * @param rotation - The new world rotation.
1470
+ */
1471
+ teleport(entity: Entity, position: Vec3Like, rotation: QuatLike): void;
1472
+ /**
1473
+ * Sets a character controller's velocity.
1474
+ *
1475
+ * @param component - The controller component.
1476
+ * @param velocity - Metres per second, world space.
1477
+ */
1478
+ setControllerVelocity(component: CharacterController, velocity: Vec3Like): void;
1479
+ /**
1480
+ * Reads a character controller's velocity.
1481
+ *
1482
+ * @param component - The controller component.
1483
+ * @param out - The vector to write.
1484
+ */
1485
+ readControllerVelocity(component: CharacterController, out: MutableVec3): void;
1486
+ /**
1487
+ * Reads a character controller's world position.
1488
+ *
1489
+ * @param component - The controller component.
1490
+ * @param out - The vector to write.
1491
+ */
1492
+ readControllerPosition(component: CharacterController, out: MutableVec3): void;
1493
+ /**
1494
+ * Rebuilds a controller's capsule in place.
1495
+ *
1496
+ * @param component - The controller component.
1497
+ * @param preserveFeet - Whether the foot position stays fixed.
1498
+ */
1499
+ resizeController(component: CharacterController, preserveFeet: boolean): void;
1500
+ /**
1501
+ * Teleports a controller and resets its interpolation history.
1502
+ *
1503
+ * @param component - The controller component.
1504
+ * @param position - The new entity world position.
1505
+ */
1506
+ teleportController(component: CharacterController, position: Vec3Like): void;
1507
+ /**
1508
+ * Releases a controller's Lite resources.
1509
+ *
1510
+ * @param component - The controller component.
1511
+ */
1512
+ releaseController(component: CharacterController): void;
1513
+ /**
1514
+ * Tears every body and controller down, then releases the Havok world **before** the simulation
1515
+ * scene, which is the order `docs/architecture/07-rendering.md` §7 requires.
1516
+ */
1517
+ dispose(): void;
1518
+ }
1519
+ //#endregion
1520
+ //#region src/runtime/host.d.ts
1521
+ /**
1522
+ * The one mutable cell between `register` and `onStart`.
1523
+ *
1524
+ * `Extension.register` runs **before** `createApp` builds the Lite engine and the world
1525
+ * (`packages/core/src/app/app.ts`, `initialize`), and the Havok world needs both. So the extension
1526
+ * declares its systems and its service in `register` — which is where `04-extensions.md` §1 says
1527
+ * everything is declared — and they all read the runtime through this holder, which `onStart` fills
1528
+ * in once Havok has loaded.
1529
+ *
1530
+ * @internal
1531
+ */
1532
+ declare class PhysicsHost {
1533
+ /** The runtime, or `null` until `onStart` has built it. */
1534
+ runtime: PhysicsRuntime | null;
1535
+ }
1536
+ //#endregion
1537
+ //#region src/service.d.ts
1538
+ /**
1539
+ * The Babylon Lite objects the physics extension owns. Unstable escape hatch
1540
+ * (`docs/architecture/00-overview.md` §3).
1541
+ *
1542
+ * @public
1543
+ */
1544
+ interface PhysicsLiteHandles {
1545
+ /** Lite's Havok world handle. */
1546
+ readonly world: LitePhysicsWorld;
1547
+ /** The null-engine scene the world is stepped on; also `world.lite.simulationScene`. */
1548
+ readonly simulationScene: LiteScene;
1549
+ }
1550
+ /**
1551
+ * The wireframe overlay `@ignifx/devtools` toggles (`09-physics.md` §9).
1552
+ *
1553
+ * @public
1554
+ */
1555
+ interface PhysicsDebugViewer {
1556
+ /**
1557
+ * Whether Lite's physics viewer is drawing the bodies into the **render** scene. It needs a GPU
1558
+ * device, so switching it on in a headless app is a no-op that logs a warning.
1559
+ */
1560
+ enabled: boolean;
1561
+ }
1562
+ /**
1563
+ * The service behind `app.physics`.
1564
+ *
1565
+ * @example
1566
+ * ```ts
1567
+ * const hit = app.physics.raycast({ x: 0, y: 10, z: 0 }, { x: 0, y: -1, z: 0 }, 20);
1568
+ * if (hit !== null) {
1569
+ * app.log.info("ray hit {name} at {y}", hit.entity.name, hit.point.y);
1570
+ * }
1571
+ * ```
1572
+ *
1573
+ * @public
1574
+ */
1575
+ export declare class PhysicsService {
1576
+ #private;
1577
+ /**
1578
+ * Wraps the holder the extension fills in from `onStart`.
1579
+ *
1580
+ * @param app - The app the service belongs to.
1581
+ * @param host - The holder the runtime lands in.
1582
+ * @param settings - The resolved `physics` settings section.
1583
+ *
1584
+ * @internal
1585
+ */
1586
+ constructor(app: App, host: PhysicsHost, settings: PhysicsSettings);
1587
+ /**
1588
+ * World gravity in metres per second squared.
1589
+ *
1590
+ * @returns A live view; writing to it does nothing, assign the property instead.
1591
+ */
1592
+ get gravity(): Vec3;
1593
+ /**
1594
+ * Replaces world gravity, which every body feels from the next fixed step.
1595
+ *
1596
+ * @param value - The new acceleration vector, in metres per second squared.
1597
+ */
1598
+ set gravity(value: Vec3Like);
1599
+ /**
1600
+ * The wireframe overlay.
1601
+ *
1602
+ * @returns The viewer toggle.
1603
+ */
1604
+ get debugViewer(): PhysicsDebugViewer;
1605
+ /**
1606
+ * The Babylon Lite handles.
1607
+ *
1608
+ * @returns The Havok world and the simulation scene.
1609
+ */
1610
+ get lite(): PhysicsLiteHandles;
1611
+ /**
1612
+ * Casts a ray and returns the first entity it hits (`09-physics.md` §5).
1613
+ *
1614
+ * @param origin - The world-space origin.
1615
+ * @param direction - The direction; it is normalised for you.
1616
+ * @param maxDistance - How far to travel; defaults to 10 km.
1617
+ * @param options - Layer mask and trigger behaviour.
1618
+ * @returns The hit, or `null` when the ray clears everything.
1619
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
1620
+ */
1621
+ raycast(origin: Vec3Like, direction: Vec3Like, maxDistance?: number, options?: QueryOptions): RaycastHit | null;
1622
+ /**
1623
+ * Sweeps a shape and returns the first contact (`09-physics.md` §5).
1624
+ *
1625
+ * @remarks
1626
+ * Lite's `shapeCast` reports no body (`index.d.ts` 11497), so `entity` is resolved against the
1627
+ * extension's body-bounds index and is bounds-accurate rather than shape-accurate.
1628
+ *
1629
+ * @param shape - The shape to sweep.
1630
+ * @param from - The start position.
1631
+ * @param to - The end position.
1632
+ * @param options - Layer mask and trigger behaviour.
1633
+ * @returns The hit, or `null`.
1634
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
1635
+ */
1636
+ shapeCast(shape: QueryShape, from: Vec3Like, to: Vec3Like, options?: QueryOptions): ShapeCastHit | null;
1637
+ /**
1638
+ * Lists the entities a positioned shape overlaps (`09-physics.md` §5).
1639
+ *
1640
+ * @remarks
1641
+ * Lite's `shapeProximity` reports one hit and no identity (`index.d.ts` 11540,
1642
+ * `lib/physics/havok-queries.js:7`), so this is answered from the extension's own bounds index:
1643
+ * every registered body whose world bounding box intersects the query shape's. It is conservative
1644
+ * — a body whose box overlaps but whose shape does not is listed.
1645
+ *
1646
+ * @param shape - The query shape.
1647
+ * @param position - Its world position.
1648
+ * @param rotation - Its world rotation; accepted for forward compatibility and currently unused,
1649
+ * because the bounds test is axis-aligned.
1650
+ * @param options - Layer mask and trigger behaviour.
1651
+ * @returns The overlapping entities, in body creation order. The array is reused between calls.
1652
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
1653
+ */
1654
+ overlap(shape: QueryShape, position: Vec3Like, rotation?: Quat, options?: QueryOptions): readonly Entity[];
1655
+ /**
1656
+ * How far the nearest body is from a positioned shape, which is the one thing Lite's
1657
+ * `shapeProximity` answers exactly.
1658
+ *
1659
+ * @param shape - The query shape.
1660
+ * @param position - Its world position.
1661
+ * @param maxDistance - How far to search.
1662
+ * @param options - Trigger behaviour.
1663
+ * @returns The distance, or `Number.POSITIVE_INFINITY` when nothing is in range.
1664
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
1665
+ */
1666
+ distanceToNearest(shape: QueryShape, position: Vec3Like, maxDistance: number, options?: QueryOptions): number;
1667
+ /**
1668
+ * Shows or hides Lite's wireframe bodies.
1669
+ *
1670
+ * @param enabled - Whether the viewer draws.
1671
+ */
1672
+ setDebugViewerEnabled(enabled: boolean): void;
1673
+ /**
1674
+ * Whether the viewer is currently drawing.
1675
+ *
1676
+ * @returns `true` when a viewer exists.
1677
+ */
1678
+ isDebugViewerEnabled(): boolean;
1679
+ /** Releases the viewer, if one is up. Called from the extension's `dispose`. */
1680
+ dispose(): void;
1681
+ }
1682
+ //#endregion
1683
+ //#region src/extension.d.ts
1684
+ /**
1685
+ * The `@ignifx/physics` extension (`docs/architecture/09-physics.md`, `04-extensions.md` §1).
1686
+ *
1687
+ * ## Why the world is built in `onStart` rather than in `register`
1688
+ *
1689
+ * `register` runs before `createApp` builds the Lite engine and the `World`
1690
+ * (`packages/core/src/app/app.ts`, `initialize`), and the Havok world needs the world's layer table
1691
+ * and the kernel's physics hooks. So `register` declares everything — components, settings, the
1692
+ * loader, the error codes, the three systems, the service, the `app.physics` property — against a
1693
+ * {@link PhysicsHost} holder, and `onStart` loads Havok, builds the runtime, and fills the holder in.
1694
+ *
1695
+ * ## Where `HavokPhysics.wasm` comes from
1696
+ *
1697
+ * The package declares `ignifx.assets.public`, so the Vite plugin copies the binary **unhashed and
1698
+ * by base name** into the public asset path (`packages/vite-plugin/src/plugin.ts`,
1699
+ * `generateBundle`). The default asset root and the default public path are the same directory, so
1700
+ * the address is the bare file name and `app.assets.resolveUrl("HavokPhysics.wasm")` is the URL —
1701
+ * not a package-scoped address like `ignifx/HavokPhysics.wasm`, which nothing would serve. Under
1702
+ * Node the loader falls back to the installed `@babylonjs/havok` package, so a headless app needs no
1703
+ * configuration.
1704
+ */
1705
+ /**
1706
+ * What `physics()` accepts.
1707
+ *
1708
+ * @public
1709
+ */
1710
+ interface PhysicsOptions {
1711
+ /**
1712
+ * How collision callbacks learn which bodies took part (ADR-0013). `"upstream"` is the default and
1713
+ * delivers contacts with `other === null`, because `@babylonjs/lite@1.27.0` reports no identities;
1714
+ * `"internal"` opts into the waived adapter-internal drain that recovers them.
1715
+ */
1716
+ readonly collisionIdentities?: CollisionIdentityMode;
1717
+ /** An already-instantiated Havok module, which skips loading entirely. */
1718
+ readonly havok?: unknown;
1719
+ /** The `HavokPhysics.wasm` bytes, for a host that reads them itself. */
1720
+ readonly wasmBinary?: ArrayBuffer;
1721
+ }
1722
+ declare module "@ignifx/core" {
1723
+ interface App {
1724
+ /** 3D physics: gravity, queries, the debug viewer, and the Lite escape hatch. */
1725
+ readonly physics: PhysicsService;
1726
+ }
1727
+ }
1728
+ /**
1729
+ * Builds the physics extension.
1730
+ *
1731
+ * @param options - The collision-identity mode and, optionally, where Havok comes from.
1732
+ * @returns The extension descriptor.
1733
+ *
1734
+ * @example
1735
+ * ```ts
1736
+ * const app = await createApp({ headless: true, extensions: [physics()] });
1737
+ * ```
1738
+ *
1739
+ * @public
1740
+ */
1741
+ export declare const physics: (options?: PhysicsOptions) => Extension;
1742
+ //#endregion
1743
+ //#region src/schemas.d.ts
1744
+ /**
1745
+ * The documentation harness's view of everything `@ignifx/physics` declares
1746
+ * (`docs/architecture/16-docs-harness-and-skill.md` §3, `scripts/README.md`).
1747
+ *
1748
+ * `pnpm docs:schemas` imports the built entry point, calls {@link describeSchemas}, and turns the
1749
+ * result into `skills/ignifx/references/formats/<format>.md`. Keys are namespaced `<package>/<Name>`
1750
+ * type ids; the file format is keyed `ignifx/physicsmaterial-file` for the same reason `@ignifx/core`
1751
+ * keys its file formats that way — the harness rejects a key with no `/` and groups pages by
1752
+ * `format`.
1753
+ */
1754
+ /**
1755
+ * Describes every component and file format this package declares.
1756
+ *
1757
+ * @returns The records, keyed by namespaced type id.
1758
+ *
1759
+ * @example
1760
+ * ```ts
1761
+ * const schemas = describeSchemas();
1762
+ * schemas["ignifx/Rigidbody"].fields["mass"].default; // 1
1763
+ * ```
1764
+ *
1765
+ * @public
1766
+ */
1767
+ export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
1768
+ //#endregion
1769
+ export type { BodyType, CapsuleDirection, CharacterCollision, Collision, CollisionEventMode, CollisionIdentityMode, ContactPoint, FreezeRotation, InterpolationMode, KinematicSyncMode, PhysicsDebugViewer, PhysicsErrorOptions, PhysicsLiteHandles, PhysicsMaterialValues, PhysicsOptions, PhysicsSettings, QueryOptions, QueryShape, RaycastHit, RigidbodyLiteHandles, ShapeCastHit, SupportStateName, TriggerEvent, VelocityLimitSettings };
1770
+ //# sourceMappingURL=index.d.ts.map