@ignifx/physics 0.2.0 → 0.3.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.
package/dist/index.d.ts CHANGED
@@ -276,23 +276,8 @@ interface SimulationHandles {
276
276
  //#endregion
277
277
  //#region src/components/collider.d.ts
278
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.
279
+ * Collider dimensions use local units and the entity's scale at build time; call `rebuild` after
280
+ * changing scale. Material assets take precedence over inline material, then project defaults.
296
281
  */
297
282
  /**
298
283
  * The fields every collider declares. It is a function because a field kind is a function call and
@@ -456,26 +441,10 @@ interface CharacterCollision {
456
441
  //#endregion
457
442
  //#region src/components/rigidbody.d.ts
458
443
  /**
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()`.
444
+ * Simulate colliders on a root entity; parented bodies log `IGX-0907` because backend pose writes
445
+ * are local. Collision events default to `auto`, following attached callbacks.
446
+ * Velocity limits are world settings; per-body damping, gravity factors, sleep thresholds, and
447
+ * explicit wake-up are unavailable in the pinned Lite adapter.
479
448
  */
480
449
  /**
481
450
  * How a body moves.
@@ -664,25 +633,9 @@ export declare class Rigidbody extends Component implements ComponentHooks {
664
633
  //#endregion
665
634
  //#region src/components/character-controller.d.ts
666
635
  /**
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".
636
+ * Sum `move` displacements during `fixedUpdate` and apply them in the physics step.
637
+ * The controller owns world position after the step; game code owns rotation and gravity.
638
+ * `supportState` is the last step's result. `pushStrength` scales Lite's default strength, not newtons.
686
639
  */
687
640
  /**
688
641
  * How the character is supported by whatever is under it.
@@ -1136,21 +1089,9 @@ export declare function physicsError(code: PhysicsErrorCode, message: string, op
1136
1089
  //#endregion
1137
1090
  //#region src/queries.d.ts
1138
1091
  /**
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.
1092
+ * Raycasts return backend body identities. Shape casts use backend hit geometry and the local
1093
+ * body-bounds index for identity; overlaps use that index entirely. Shape-cast identities and
1094
+ * overlap results are bounds-accurate, not exact shape intersections.
1154
1095
  */
1155
1096
  /**
1156
1097
  * Options every query accepts.
@@ -1163,6 +1104,27 @@ interface QueryOptions {
1163
1104
  /** Whether trigger volumes count as hits. Defaults to `false`. */
1164
1105
  readonly hitTriggers?: boolean;
1165
1106
  }
1107
+ /**
1108
+ * Options a shape sweep accepts, on top of {@link QueryOptions}.
1109
+ *
1110
+ * @remarks
1111
+ * `ignore` exists because a sweep that starts at or inside a body — a camera boom leaving its
1112
+ * target's capsule, a step probe leaving the character's own feet — reports that body at fraction
1113
+ * zero and nothing else. Lite's sweep can exclude exactly one body, and cannot filter by layer at
1114
+ * all (`ShapeCastQuery` has `ignoreBody` and no collision masks, unlike `physicsRaycast`), so
1115
+ * `layerMask` decides which hit is *attributed* an entity while `ignore` is the one body the
1116
+ * geometry itself passes through. Added 2026-09-08.
1117
+ *
1118
+ * @public
1119
+ */
1120
+ interface ShapeCastOptions extends QueryOptions {
1121
+ /**
1122
+ * An entity whose body the sweep passes through — usually the caller's own. A `Rigidbody`, a
1123
+ * collider-only static, and a `CharacterController` capsule are all accepted; an entity with no
1124
+ * body is ignored.
1125
+ */
1126
+ readonly ignore?: Entity | null;
1127
+ }
1166
1128
  /**
1167
1129
  * A shape to sweep or to test for overlaps. It is a description, not a component: the service builds
1168
1130
  * the Havok shape for the call and releases it afterwards.
@@ -1379,7 +1341,8 @@ declare class PhysicsRuntime {
1379
1341
  markControllerDirty(component: CharacterController): void;
1380
1342
  /**
1381
1343
  * 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).
1344
+ * pose the `Update` system wrote at the top of the previous frame's `Update`
1345
+ * (`09-physics.md` §1, spike S4.3).
1383
1346
  */
1384
1347
  restorePoses(): void;
1385
1348
  /**
@@ -1408,6 +1371,16 @@ declare class PhysicsRuntime {
1408
1371
  * @returns The record, or `null`.
1409
1372
  */
1410
1373
  recordOf(entity: Entity): BodyRecord | null;
1374
+ /**
1375
+ * The Havok body an entity's physics is, whether that is a `Rigidbody`, a collider-only static, or
1376
+ * a `CharacterController`'s capsule — which is what a sweep names to pass through it
1377
+ * (`ShapeCastOptions.ignore`).
1378
+ *
1379
+ * @param entity - The entity.
1380
+ * @returns The body, or `null` when the entity has none yet: a body is built on the fixed step
1381
+ * after its components attach, so a query in the same frame finds nothing to ignore.
1382
+ */
1383
+ bodyOf(entity: Entity): LitePhysicsBody | null;
1411
1384
  /**
1412
1385
  * The record a Lite node belongs to, which is how a Havok event or query result becomes an entity.
1413
1386
  *
@@ -1626,14 +1599,20 @@ export declare class PhysicsService {
1626
1599
  * Lite's `shapeCast` reports no body (`index.d.ts` 11497), so `entity` is resolved against the
1627
1600
  * extension's body-bounds index and is bounds-accurate rather than shape-accurate.
1628
1601
  *
1602
+ * The sweep itself cannot be filtered by layer — Lite's `ShapeCastQuery` carries no collision
1603
+ * masks — so a body outside `layerMask` still stops the sweep; it is merely reported with
1604
+ * `entity: null`. What the sweep *can* do is pass through one body, `options.ignore`, which is
1605
+ * how a camera boom leaves its target's capsule and a step probe leaves the character's own feet
1606
+ * without reporting them at fraction zero (2026-09-08).
1607
+ *
1629
1608
  * @param shape - The shape to sweep.
1630
1609
  * @param from - The start position.
1631
1610
  * @param to - The end position.
1632
- * @param options - Layer mask and trigger behaviour.
1611
+ * @param options - Layer mask, trigger behaviour, and the one entity to sweep through.
1633
1612
  * @returns The hit, or `null`.
1634
1613
  * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
1635
1614
  */
1636
- shapeCast(shape: QueryShape, from: Vec3Like, to: Vec3Like, options?: QueryOptions): ShapeCastHit | null;
1615
+ shapeCast(shape: QueryShape, from: Vec3Like, to: Vec3Like, options?: ShapeCastOptions): ShapeCastHit | null;
1637
1616
  /**
1638
1617
  * Lists the entities a positioned shape overlaps (`09-physics.md` §5).
1639
1618
  *
@@ -1691,25 +1670,9 @@ export declare class PhysicsService {
1691
1670
  //#endregion
1692
1671
  //#region src/extension.d.ts
1693
1672
  /**
1694
- * The `@ignifx/physics` extension (`docs/architecture/09-physics.md`, `04-extensions.md` §1).
1695
- *
1696
- * ## Why the world is built in `onStart` rather than in `register`
1697
- *
1698
- * `register` runs before `createApp` builds the Lite engine and the `World`
1699
- * (`packages/core/src/app/app.ts`, `initialize`), and the Havok world needs the world's layer table
1700
- * and the kernel's physics hooks. So `register` declares everything — components, settings, the
1701
- * loader, the error codes, the three systems, the service, the `app.physics` property — against a
1702
- * {@link PhysicsHost} holder, and `onStart` loads Havok, builds the runtime, and fills the holder in.
1703
- *
1704
- * ## Where `HavokPhysics.wasm` comes from
1705
- *
1706
- * The package declares `ignifx.assets.public`, so the Vite plugin copies the binary **unhashed and
1707
- * by base name** into the public asset path (`packages/vite-plugin/src/plugin.ts`,
1708
- * `generateBundle`). The default asset root and the default public path are the same directory, so
1709
- * the address is the bare file name and `app.assets.resolveUrl("HavokPhysics.wasm")` is the URL —
1710
- * not a package-scoped address like `ignifx/HavokPhysics.wasm`, which nothing would serve. Under
1711
- * Node the loader falls back to the installed `@babylonjs/havok` package, so a headless app needs no
1712
- * configuration.
1673
+ * Create the physics runtime in `onStart`, after the world and its layer table exist.
1674
+ * The Vite plugin copies `HavokPhysics.wasm` into public assets under its base name.
1675
+ * Headless loading falls back to the installed Havok package.
1713
1676
  */
1714
1677
  /**
1715
1678
  * What `physics()` accepts.
@@ -1775,5 +1738,5 @@ export declare const physics: (options?: PhysicsOptions) => Extension;
1775
1738
  */
1776
1739
  export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
1777
1740
  //#endregion
1778
- 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 };
1741
+ export type { BodyType, CapsuleDirection, CharacterCollision, Collision, CollisionEventMode, CollisionIdentityMode, ContactPoint, FreezeRotation, InterpolationMode, KinematicSyncMode, PhysicsDebugViewer, PhysicsErrorOptions, PhysicsLiteHandles, PhysicsMaterialValues, PhysicsOptions, PhysicsSettings, QueryOptions, QueryShape, RaycastHit, RigidbodyLiteHandles, ShapeCastHit, ShapeCastOptions, SupportStateName, TriggerEvent, VelocityLimitSettings };
1779
1742
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/settings.ts","../src/material.ts","../src/lite/havok.ts","../src/components/collider.ts","../src/events.ts","../src/components/rigidbody.ts","../src/components/character-controller.ts","../src/components/colliders.ts","../src/errors.ts","../src/queries.ts","../src/runtime/body-record.ts","../src/runtime/runtime.ts","../src/runtime/host.ts","../src/service.ts","../src/extension.ts","../src/schemas.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/settings.ts","../src/material.ts","../src/lite/havok.ts","../src/components/collider.ts","../src/events.ts","../src/components/rigidbody.ts","../src/components/character-controller.ts","../src/components/colliders.ts","../src/errors.ts","../src/queries.ts","../src/runtime/body-record.ts","../src/runtime/runtime.ts","../src/runtime/host.ts","../src/service.ts","../src/extension.ts","../src/schemas.ts"],"mappings":"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"}
package/dist/index.js CHANGED
@@ -17,26 +17,10 @@ const PhysicsHostKey = createServiceKey("@ignifx/physics:host");
17
17
  //#endregion
18
18
  //#region src/components/rigidbody.ts
19
19
  /**
20
- * The `Rigidbody` component (`docs/architecture/09-physics.md` §2.1): what makes an entity's
21
- * colliders a simulated, kinematic, or explicitly static Havok body.
22
- *
23
- * ## Corrections to §2.1, all forced by `@babylonjs/lite@1.27.0`
24
- *
25
- * - **`collisionEvents` is a three-valued enum, not a boolean.** §2.1 describes a field whose value
26
- * is "auto"; a schema field has one kind and one value (ADR-0004), so the field is
27
- * `"auto" | "on" | "off"` and `"auto"` is the default. `"auto"` is what §2.1 actually specifies:
28
- * recomputed from `ctx.entityImplements` whenever a component is added to or removed from the
29
- * entity.
30
- * - **`velocityLimits` is not a per-body field.** Lite exposes `setPhysicsVelocityLimits(world, …)`
31
- * only (`index.d.ts` 10880) — there is no per-body clamp — so the limits live in the `physics`
32
- * settings section and the field is absent.
33
- * - **A body's entity must be a root entity.** Lite's post-step sync writes `node.position` and
34
- * `node.rotationQuaternion`, which are *local* values (`lib/physics/havok.js:_syncBodyToNode`), so
35
- * a parented entity would be simulated in its parent's space. The extension reports `IGX-0907`
36
- * and simulates it anyway rather than silently misplacing it.
37
- *
38
- * Not available in Lite 1.27.0 and therefore absent, as §2.1 already records: per-body damping,
39
- * per-body gravity factor, sleep thresholds, and an explicit `wakeUp()`.
20
+ * Simulate colliders on a root entity; parented bodies log `IGX-0907` because backend pose writes
21
+ * are local. Collision events default to `auto`, following attached callbacks.
22
+ * Velocity limits are world settings; per-body damping, gravity factors, sleep thresholds, and
23
+ * explicit wake-up are unavailable in the pinned Lite adapter.
40
24
  */
41
25
  /**
42
26
  * How a body moves.
@@ -241,25 +225,9 @@ function rigidbodySchema() {
241
225
  //#endregion
242
226
  //#region src/components/character-controller.ts
243
227
  /**
244
- * The `CharacterController` component (`docs/architecture/09-physics.md` §2.3): Lite's kinematic
245
- * capsule with collide-and-slide, support detection, and dynamic-body pushing.
246
- *
247
- * ## How it is driven
248
- *
249
- * Call {@link CharacterController.move} from `fixedUpdate`. The requested displacements of one step
250
- * are summed and handed to Lite's `moveWithCollisions` by the step system, so two scripts moving the
251
- * same character compose instead of fighting. After the step the controller owns the entity's world
252
- * **position**; rotation stays user-controlled.
253
- *
254
- * ## Corrections to §2.3
255
- *
256
- * - `supportState` is read from the last step's `checkSupport` probe, which the step system runs
257
- * once per step; reading it does not probe again.
258
- * - Gravity is **not** applied by this component. §2.3 already says so: a bare controller is purely
259
- * kinematic and the 3D toolkit's controllers integrate gravity through `checkSupport` +
260
- * `integrate` (Phase 7). {@link CharacterController.move} is the whole input.
261
- * - `pushStrength` scales Lite's `characterStrength`, whose default is `1e38` — effectively
262
- * "infinite". A `pushStrength` of `1` therefore means "Lite's default", not "one newton".
228
+ * Sum `move` displacements during `fixedUpdate` and apply them in the physics step.
229
+ * The controller owns world position after the step; game code owns rotation and gravity.
230
+ * `supportState` is the last step's result. `pushStrength` scales Lite's default strength, not newtons.
263
231
  */
264
232
  /**
265
233
  * How the character is supported by whatever is under it.
@@ -746,23 +714,8 @@ function numberAt(object, key, fallback) {
746
714
  //#endregion
747
715
  //#region src/components/collider.ts
748
716
  /**
749
- * The collider contract (`docs/architecture/09-physics.md` §2.2). Every collider shares four
750
- * fields — `center`, `isTrigger`, a material, and a layer override — and answers two questions the
751
- * body builder asks: what Havok shape it is, and how big its local bounding box is.
752
- *
753
- * ## The one correction to §2.2
754
- *
755
- * §2.2 writes the material field as `material: asset(PhysicsMaterial) | inline { … }`. A schema
756
- * field has exactly one kind (ADR-0004), so the union is split into two fields:
757
- * {@link Collider.material} (an asset reference) and {@link Collider.inlineMaterial} (a record).
758
- * The asset wins, the inline record is the fallback, and `physics.defaultMaterial` is the last
759
- * resort.
760
- *
761
- * ## Shape sizes and scale
762
- *
763
- * Sizes are authored in local units and multiplied by the entity's lossy scale when the shape is
764
- * built. Havok has no way to rescale a built shape, so changing the scale afterwards needs
765
- * {@link Collider.rebuild}, exactly as §2.2 says.
717
+ * Collider dimensions use local units and the entity's scale at build time; call `rebuild` after
718
+ * changing scale. Material assets take precedence over inline material, then project defaults.
766
719
  */
767
720
  /**
768
721
  * The fields every collider declares. It is a function because a field kind is a function call and
@@ -2163,6 +2116,18 @@ function probeSupport(controller, deltaSeconds, gravity, groundNormal) {
2163
2116
  return toSupportState(surface.supportedState);
2164
2117
  }
2165
2118
  /**
2119
+ * The Havok body a controller's capsule is, which is what a query names to sweep *past* the
2120
+ * character rather than into it (`ShapeCastOptions.ignore`).
2121
+ *
2122
+ * @param controller - The controller.
2123
+ * @returns Its body handle.
2124
+ *
2125
+ * @internal
2126
+ */
2127
+ function controllerBody(controller) {
2128
+ return controller.getBody();
2129
+ }
2130
+ /**
2166
2131
  * Reads the controller's resolved position.
2167
2132
  *
2168
2133
  * @param controller - The controller.
@@ -2538,7 +2503,8 @@ var PhysicsRuntime = class {
2538
2503
  }
2539
2504
  /**
2540
2505
  * Restores the authoritative pose of every interpolated body and controller, undoing the display
2541
- * pose the `PreRender` system wrote (`09-physics.md` §1, spike S4.3).
2506
+ * pose the `Update` system wrote at the top of the previous frame's `Update`
2507
+ * (`09-physics.md` §1, spike S4.3).
2542
2508
  */
2543
2509
  restorePoses() {
2544
2510
  for (let index = 0; index < this.#records.length; index += 1) {
@@ -2612,6 +2578,24 @@ var PhysicsRuntime = class {
2612
2578
  return this.#byEntity.get(entity) ?? null;
2613
2579
  }
2614
2580
  /**
2581
+ * The Havok body an entity's physics is, whether that is a `Rigidbody`, a collider-only static, or
2582
+ * a `CharacterController`'s capsule — which is what a sweep names to pass through it
2583
+ * (`ShapeCastOptions.ignore`).
2584
+ *
2585
+ * @param entity - The entity.
2586
+ * @returns The body, or `null` when the entity has none yet: a body is built on the fixed step
2587
+ * after its components attach, so a query in the same frame finds nothing to ignore.
2588
+ */
2589
+ bodyOf(entity) {
2590
+ const record = this.#byEntity.get(entity);
2591
+ if (record !== void 0) return record.body;
2592
+ for (let index = 0; index < this.#controllers.length; index += 1) {
2593
+ const controller = this.#controllers[index];
2594
+ if (controller !== void 0 && controller.component.entity === entity) return controllerBody(controller.controller);
2595
+ }
2596
+ return null;
2597
+ }
2598
+ /**
2615
2599
  * The record a Lite node belongs to, which is how a Havok event or query result becomes an entity.
2616
2600
  *
2617
2601
  * @param node - The node.
@@ -2810,7 +2794,8 @@ var PhysicsRuntime = class {
2810
2794
  /**
2811
2795
  * Publishes the frame's counters and zeroes the accumulators. The kernel resets `FrameSample` each
2812
2796
  * frame but not diagnostics **groups** (`Diagnostics.beginFrame`), so a group that reports
2813
- * per-frame totals resets itself — and `PreRender` is where a frame's fixed steps are all done.
2797
+ * per-frame totals resets itself — and the top of `Update`, where the display pose is written, is
2798
+ * the first point in a frame at which every fixed step of that frame is done.
2814
2799
  */
2815
2800
  #publishCounters() {
2816
2801
  this.#counters.set(this.#index("bodies"), this.#records.length);
@@ -3551,25 +3536,42 @@ function unknownLayer(name) {
3551
3536
  //#endregion
3552
3537
  //#region src/runtime/systems.ts
3553
3538
  /**
3554
- * The three systems `docs/architecture/01-lifecycle-and-time.md` §3 step 4 and `09-physics.md` §1
3555
- * put physics in the frame with:
3539
+ * The three systems `docs/architecture/01-lifecycle-and-time.md` §3 and `09-physics.md` §1 put
3540
+ * physics in the frame with:
3556
3541
  *
3557
3542
  * ```
3558
3543
  * Systems(FixedUpdate, -100) restore the authoritative pose of interpolated bodies
3559
3544
  * scripts.fixedUpdate(dt) forces, velocities, CharacterController.move()
3560
3545
  * Systems(FixedUpdate, 100) step Havok, snapshot poses, dispatch collision and trigger events
3561
- * Systems(PreRender, -500) write lerp(prev, cur, time.fixedStepAlpha)
3546
+ * ── the fixed loop ends; time.fixedStepAlpha is final ──
3547
+ * Systems(Update, -900) write lerp(prev, cur, time.fixedStepAlpha)
3548
+ * scripts.update / lateUpdate, animation, rendering — all read the display pose
3562
3549
  * ```
3563
3550
  *
3551
+ * **Why the display pose is written at the top of `Update` and not in `PreRender`** (2026-09-08).
3552
+ * It used to be written in `PreRender`, after `lateUpdate`. Camera rigs run in `lateUpdate`, so they
3553
+ * framed the character where the last fixed step left it while the renderer drew it at
3554
+ * `lerp(prev, cur, alpha)`: up to one fixed step of motion of relative judder every frame, which is
3555
+ * exactly what a follow camera makes visible. Writing the pose before `scripts.update` means every
3556
+ * consumer of a transform outside the fixed loop — scripts, animation, camera rigs, the render sync
3557
+ * — sees the same pose the frame presents, which is Unity's model. The simulation is unaffected:
3558
+ * the restore system at `FixedUpdate −100` runs before `scripts.fixedUpdate`, so `fixedUpdate` and
3559
+ * Havok still see the authoritative pose.
3560
+ *
3564
3561
  * Everything here is `@internal`.
3565
3562
  */
3566
3563
  /** The `FixedUpdate` order the restore system runs at. */
3567
3564
  const PHYSICS_RESTORE_ORDER = -100;
3568
- /** The `PreRender` order the interpolation system runs at. */
3569
- const PHYSICS_INTERPOLATE_ORDER = -500;
3570
3565
  /**
3571
- * Undoes the display pose the interpolation system wrote, so `fixedUpdate` and Havok both see the
3572
- * authoritative pose (spike S4.3).
3566
+ * The `Update` order the interpolation system runs at. Negative, so it lands in
3567
+ * `Systems(Update, order < 0)` — after the fixed loop and lifecycle flush B, before
3568
+ * `scripts.update` — and low enough that a game's own `Update` systems can still be ordered in
3569
+ * front of it if they must see the authoritative pose.
3570
+ */
3571
+ const PHYSICS_INTERPOLATE_ORDER = -900;
3572
+ /**
3573
+ * Undoes the display pose the interpolation system wrote at the top of the previous `Update`, so
3574
+ * `fixedUpdate` and Havok both see the authoritative pose (spike S4.3).
3573
3575
  *
3574
3576
  * @internal
3575
3577
  */
@@ -3725,13 +3727,17 @@ function castRay(world, from, to, membership, collideWith, hitTriggers, point, n
3725
3727
  * @param from - The start position.
3726
3728
  * @param to - The end position.
3727
3729
  * @param hitTriggers - Whether trigger volumes count as hits.
3730
+ * @param ignoreBody - One body the sweep passes through, or `null`. Lite's `ShapeCastQuery` takes
3731
+ * exactly one (`ignoreBody`, `index.d.ts` 11494) and — unlike `physicsRaycast` — no
3732
+ * `membership`/`collideWith` pair, so this is the only filtering a sweep can do inside Havok; a
3733
+ * layer mask is applied to the *attribution* of the hit by the service, never to the sweep.
3728
3734
  * @param point - Written with the contact point on the hit body.
3729
3735
  * @param normal - Written with the contact normal on the hit body.
3730
3736
  * @param out - Written with the hit flag and the sweep fraction.
3731
3737
  *
3732
3738
  * @internal
3733
3739
  */
3734
- function sweepShape(world, shape, rotation, from, to, hitTriggers, point, normal, out) {
3740
+ function sweepShape(world, shape, rotation, from, to, hitTriggers, ignoreBody, point, normal, out) {
3735
3741
  const result = shapeCast(world, {
3736
3742
  shape,
3737
3743
  rotation: {
@@ -3750,7 +3756,8 @@ function sweepShape(world, shape, rotation, from, to, hitTriggers, point, normal
3750
3756
  y: to.y,
3751
3757
  z: to.z
3752
3758
  },
3753
- shouldHitTriggers: hitTriggers
3759
+ shouldHitTriggers: hitTriggers,
3760
+ ...ignoreBody === null ? {} : { ignoreBody }
3754
3761
  });
3755
3762
  out.hit = result.hasHit;
3756
3763
  out.fraction = result.fraction;
@@ -3938,24 +3945,32 @@ var PhysicsService = class {
3938
3945
  * Lite's `shapeCast` reports no body (`index.d.ts` 11497), so `entity` is resolved against the
3939
3946
  * extension's body-bounds index and is bounds-accurate rather than shape-accurate.
3940
3947
  *
3948
+ * The sweep itself cannot be filtered by layer — Lite's `ShapeCastQuery` carries no collision
3949
+ * masks — so a body outside `layerMask` still stops the sweep; it is merely reported with
3950
+ * `entity: null`. What the sweep *can* do is pass through one body, `options.ignore`, which is
3951
+ * how a camera boom leaves its target's capsule and a step probe leaves the character's own feet
3952
+ * without reporting them at fraction zero (2026-09-08).
3953
+ *
3941
3954
  * @param shape - The shape to sweep.
3942
3955
  * @param from - The start position.
3943
3956
  * @param to - The end position.
3944
- * @param options - Layer mask and trigger behaviour.
3957
+ * @param options - Layer mask, trigger behaviour, and the one entity to sweep through.
3945
3958
  * @returns The hit, or `null`.
3946
3959
  * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
3947
3960
  */
3948
3961
  shapeCast(shape, from, to, options) {
3949
3962
  this.#requireStep("shapeCast");
3950
3963
  this.#rt().countQuery();
3964
+ const ignored = options?.ignore ?? null;
3965
+ const ignoredBody = ignored === null ? null : this.#rt().bodyOf(ignored);
3951
3966
  const handle = this.#buildQueryShape(shape);
3952
3967
  try {
3953
- sweepShape(this.#rt().world, handle, Quat.identity(), from, to, options?.hitTriggers === true, this.#point, this.#normal, this.#sweepResult);
3968
+ sweepShape(this.#rt().world, handle, Quat.identity(), from, to, options?.hitTriggers === true, ignoredBody, this.#point, this.#normal, this.#sweepResult);
3954
3969
  } finally {
3955
3970
  destroyShape(this.#rt().world, handle);
3956
3971
  }
3957
3972
  if (!this.#sweepResult.hit) return null;
3958
- const record = this.#recordAt(this.#point, options);
3973
+ const record = this.#recordAt(this.#point, options, ignored);
3959
3974
  const distance = Math.hypot(to.x - from.x, to.y - from.y, to.z - from.z) * this.#sweepResult.fraction;
3960
3975
  return {
3961
3976
  entity: record?.entity ?? null,
@@ -4130,15 +4145,17 @@ var PhysicsService = class {
4130
4145
  *
4131
4146
  * @param point - The point.
4132
4147
  * @param options - Layer mask and trigger behaviour.
4148
+ * @param ignored - The entity the sweep was told to pass through, which can therefore not be the
4149
+ * one it hit.
4133
4150
  * @returns The record, or `null`.
4134
4151
  */
4135
- #recordAt(point, options) {
4152
+ #recordAt(point, options, ignored = null) {
4136
4153
  const records = this.#rt().records;
4137
4154
  let best = null;
4138
4155
  let bestDistance = Number.POSITIVE_INFINITY;
4139
4156
  for (let index = 0; index < records.length; index += 1) {
4140
4157
  const record = records[index];
4141
- if (record === void 0 || !this.#accepts(record, options)) continue;
4158
+ if (record === void 0 || record.entity === ignored || !this.#accepts(record, options)) continue;
4142
4159
  const centre = record.currentPosition;
4143
4160
  const extents = record.halfExtents;
4144
4161
  if (Math.abs(point.x - centre.x) > extents.x + BOUNDS_EPSILON || Math.abs(point.y - centre.y) > extents.y + BOUNDS_EPSILON || Math.abs(point.z - centre.z) > extents.z + BOUNDS_EPSILON) continue;
@@ -4369,7 +4386,7 @@ const physics = defineExtension((options = {}) => {
4369
4386
  order: 100
4370
4387
  });
4371
4388
  ctx.registerSystem(new PhysicsInterpolationSystem(host), {
4372
- phase: Phase.PreRender,
4389
+ phase: Phase.Update,
4373
4390
  order: PHYSICS_INTERPOLATE_ORDER
4374
4391
  });
4375
4392
  },