@ignifx/physics 0.10.0 → 0.12.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.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { Component, IgnifxError, MeshAsset, Phase, Quat, Signal, Vec3, array, asset, bool, createDefaults, createServiceKey, defineExtension, defineSchema, describeSchema, enumOf, f32, lerp, map, optional, record, str, u32, vec3 } from "@ignifx/core";
2
- import { addPhysicsShapeChild, applyPhysicsBodyForce, applyPhysicsBodyImpulse, createHavokWorld, createHeightFieldShape, createNullEngine, createPhysicsBody, createPhysicsCharacterController, createPhysicsShape, createPhysicsViewer, createSceneContext, disposePhysics, disposePhysicsViewer, disposeScene, getPhysicsBodyAngularVelocity, getPhysicsBodyLinearVelocity, lockPhysicsBodyRotationAxes, onPhysicsAfterStep, onPhysicsCollision, onPhysicsTriggerBodies, physicsRaycast, releasePhysicsShape, removePhysicsBody, setPhysicsBodyAngularVelocity, setPhysicsBodyCollisionEventsEnabled, setPhysicsBodyLinearVelocity, setPhysicsBodyMass, setPhysicsBodyPrestepType, setPhysicsBodyShape, setPhysicsBodyTransform, setPhysicsGravity, setPhysicsShapeFilterCollideMask, setPhysicsShapeFilterMembershipMask, setPhysicsShapeIsTrigger, setPhysicsShapeMaterial, setPhysicsTimestep, setPhysicsVelocityLimits, shapeCast, shapeProximity, showPhysicsBody, stepScene, unlockPhysicsBodyRotationAxes } from "@babylonjs/lite";
2
+ import { addPhysicsShapeChild, applyPhysicsBodyForce, applyPhysicsBodyImpulse, createHavokWorld, createHeightFieldShape, createNullEngine, createPhysicsBody, createPhysicsCharacterController, createPhysicsShape, createPhysicsViewer, createSceneContext, disposePhysics, disposePhysicsViewer, disposeScene, getPhysicsBodyAngularVelocity, getPhysicsBodyLinearVelocity, hidePhysicsBody, lockPhysicsBodyRotationAxes, onPhysicsAfterStep, onPhysicsCollision, onPhysicsTriggerBodies, physicsRaycast, releasePhysicsShape, removePhysicsBody, setPhysicsBodyAngularVelocity, setPhysicsBodyCollisionEventsEnabled, setPhysicsBodyLinearVelocity, setPhysicsBodyMass, setPhysicsBodyPrestepType, setPhysicsBodyShape, setPhysicsBodyTransform, setPhysicsGravity, setPhysicsShapeFilterCollideMask, setPhysicsShapeFilterMembershipMask, setPhysicsShapeIsTrigger, setPhysicsShapeMaterial, setPhysicsTimestep, setPhysicsVelocityLimits, shapeCast, shapeProximity, showPhysicsBody, stepScene, unlockPhysicsBodyRotationAxes } from "@babylonjs/lite";
3
3
  import HavokPhysics from "@babylonjs/havok";
4
4
  //#region src/runtime/runtime-key.ts
5
5
  /**
@@ -88,6 +88,15 @@ var Rigidbody = class Rigidbody extends Component {
88
88
  this.rebuild();
89
89
  }
90
90
  /**
91
+ * Rebuilds the body after a tool changed fields from outside: an editor's inspector, or a hot
92
+ * reload's new default (`ComponentHooks.onValidate`).
93
+ *
94
+ * @param fields - The fields that changed.
95
+ */
96
+ onValidate(fields) {
97
+ this.rebuild();
98
+ }
99
+ /**
91
100
  * Rebuilds the body at the start of the next fixed step. Call it after changing `bodyType`,
92
101
  * `mass`, `freezeRotation`, or the entity's scale.
93
102
  */
@@ -283,6 +292,15 @@ var CharacterController = class CharacterController extends Component {
283
292
  onDetach() {
284
293
  this.#runtime()?.releaseController(this);
285
294
  }
295
+ /**
296
+ * Rebuilds the body after a tool changed fields from outside: an editor's inspector, or a hot
297
+ * reload's new default (`ComponentHooks.onValidate`).
298
+ *
299
+ * @param fields - The fields that changed.
300
+ */
301
+ onValidate(fields) {
302
+ this.rebuild();
303
+ }
286
304
  /** Rebuilds the capsule at the start of the next fixed step. */
287
305
  rebuild() {
288
306
  this.#runtime()?.markControllerDirty(this);
@@ -763,6 +781,15 @@ var Collider = class extends Component {
763
781
  this.rebuild();
764
782
  }
765
783
  /**
784
+ * Rebuilds the body after a tool changed fields from outside: an editor's inspector, or a hot
785
+ * reload's new default (`ComponentHooks.onValidate`).
786
+ *
787
+ * @param fields - The fields that changed.
788
+ */
789
+ onValidate(fields) {
790
+ this.rebuild();
791
+ }
792
+ /**
766
793
  * Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
767
794
  * changing a size, a `center`, `isTrigger`, or the entity's scale.
768
795
  *
@@ -784,6 +811,17 @@ var Collider = class extends Component {
784
811
  resolveMaterial(fallback) {
785
812
  return this.material?.value ?? this.inlineMaterial ?? fallback;
786
813
  }
814
+ /**
815
+ * Appends this collider's outline, as line segments in the body's space with the scale applied,
816
+ * for `PhysicsService.colliderOutlines`. A collider whose shape cannot be outlined without its
817
+ * geometry appends nothing.
818
+ *
819
+ * @param scale - The entity's lossy scale.
820
+ * @param out - The segment list: six numbers per segment.
821
+ *
822
+ * @internal
823
+ */
824
+ outlineToRef(scale, out) {}
787
825
  };
788
826
  //#endregion
789
827
  //#region src/lite/havok.ts
@@ -1392,6 +1430,231 @@ function afterStep(world, callback) {
1392
1430
  callback();
1393
1431
  });
1394
1432
  }
1433
+ /** A full turn in radians. */
1434
+ const TURN = Math.PI * 2;
1435
+ /** The world axes. */
1436
+ const X_AXIS = [
1437
+ 1,
1438
+ 0,
1439
+ 0
1440
+ ];
1441
+ const Y_AXIS = [
1442
+ 0,
1443
+ 1,
1444
+ 0
1445
+ ];
1446
+ const Z_AXIS = [
1447
+ 0,
1448
+ 0,
1449
+ 1
1450
+ ];
1451
+ /**
1452
+ * The axis a capsule stands along, and the two axes across it.
1453
+ *
1454
+ * @param direction - `"x"`, `"y"`, or `"z"`.
1455
+ * @returns `[along, across, across]`.
1456
+ *
1457
+ * @internal
1458
+ */
1459
+ function capsuleAxes(direction) {
1460
+ if (direction === "x") return [
1461
+ X_AXIS,
1462
+ Y_AXIS,
1463
+ Z_AXIS
1464
+ ];
1465
+ return direction === "y" ? [
1466
+ Y_AXIS,
1467
+ X_AXIS,
1468
+ Z_AXIS
1469
+ ] : [
1470
+ Z_AXIS,
1471
+ X_AXIS,
1472
+ Y_AXIS
1473
+ ];
1474
+ }
1475
+ /**
1476
+ * Appends one segment.
1477
+ *
1478
+ * @param out - The segment list.
1479
+ * @param a - The first end.
1480
+ * @param b - The second end.
1481
+ *
1482
+ * @internal
1483
+ */
1484
+ function pushSegment(out, a, b) {
1485
+ out.push(a.x, a.y, a.z, b.x, b.y, b.z);
1486
+ }
1487
+ /**
1488
+ * Appends the twelve edges of an axis-aligned box.
1489
+ *
1490
+ * @param out - The segment list.
1491
+ * @param center - The box centre.
1492
+ * @param half - Half its size along each axis.
1493
+ *
1494
+ * @internal
1495
+ */
1496
+ function pushBox(out, center, half) {
1497
+ const x0 = center.x - half.x;
1498
+ const x1 = center.x + half.x;
1499
+ const y0 = center.y - half.y;
1500
+ const y1 = center.y + half.y;
1501
+ const z0 = center.z - half.z;
1502
+ const z1 = center.z + half.z;
1503
+ for (const [y, z] of [
1504
+ [y0, z0],
1505
+ [y0, z1],
1506
+ [y1, z0],
1507
+ [y1, z1]
1508
+ ]) out.push(x0, y, z, x1, y, z);
1509
+ for (const [x, z] of [
1510
+ [x0, z0],
1511
+ [x0, z1],
1512
+ [x1, z0],
1513
+ [x1, z1]
1514
+ ]) out.push(x, y0, z, x, y1, z);
1515
+ for (const [x, y] of [
1516
+ [x0, y0],
1517
+ [x0, y1],
1518
+ [x1, y0],
1519
+ [x1, y1]
1520
+ ]) out.push(x, y, z0, x, y, z1);
1521
+ }
1522
+ /**
1523
+ * Appends an arc of a circle in the plane of two axes.
1524
+ *
1525
+ * @param out - The segment list.
1526
+ * @param center - The circle's centre.
1527
+ * @param u - The axis angle `0` points along.
1528
+ * @param v - The axis angle `π / 2` points along.
1529
+ * @param radius - The radius.
1530
+ * @param from - The start angle, in radians.
1531
+ * @param to - The end angle, in radians.
1532
+ *
1533
+ * @internal
1534
+ */
1535
+ function pushArc(out, center, u, v, radius, from = 0, to = TURN) {
1536
+ const steps = Math.max(1, Math.round(32 * Math.abs(to - from) / TURN));
1537
+ let previousCos = Math.cos(from);
1538
+ let previousSin = Math.sin(from);
1539
+ for (let step = 1; step <= steps; step += 1) {
1540
+ const angle = from + (to - from) * step / steps;
1541
+ const cos = Math.cos(angle);
1542
+ const sin = Math.sin(angle);
1543
+ out.push(center.x + radius * (u[0] * previousCos + v[0] * previousSin), center.y + radius * (u[1] * previousCos + v[1] * previousSin), center.z + radius * (u[2] * previousCos + v[2] * previousSin), center.x + radius * (u[0] * cos + v[0] * sin), center.y + radius * (u[1] * cos + v[1] * sin), center.z + radius * (u[2] * cos + v[2] * sin));
1544
+ previousCos = cos;
1545
+ previousSin = sin;
1546
+ }
1547
+ }
1548
+ /**
1549
+ * Appends a sphere's three great circles.
1550
+ *
1551
+ * @param out - The segment list.
1552
+ * @param center - The centre.
1553
+ * @param radius - The radius.
1554
+ *
1555
+ * @internal
1556
+ */
1557
+ function pushSphere(out, center, radius) {
1558
+ pushArc(out, center, X_AXIS, Y_AXIS, radius);
1559
+ pushArc(out, center, Y_AXIS, Z_AXIS, radius);
1560
+ pushArc(out, center, Z_AXIS, X_AXIS, radius);
1561
+ }
1562
+ /**
1563
+ * Appends a capsule: a ring at each end of its segment, four lines joining them, and the two
1564
+ * half-circle profiles of each cap.
1565
+ *
1566
+ * @param out - The segment list.
1567
+ * @param center - The capsule's centre.
1568
+ * @param direction - The axis it stands along.
1569
+ * @param radius - Its radius.
1570
+ * @param halfSegment - Half the length of the segment between the cap centres.
1571
+ *
1572
+ * @internal
1573
+ */
1574
+ function pushCapsule(out, center, direction, radius, halfSegment) {
1575
+ const [along, u, v] = capsuleAxes(direction);
1576
+ const top = offset(center, along, halfSegment);
1577
+ const bottom = offset(center, along, -halfSegment);
1578
+ pushTube(out, top, bottom, u, v, radius);
1579
+ for (const across of [u, v]) {
1580
+ pushArc(out, top, across, along, radius, 0, Math.PI);
1581
+ pushArc(out, bottom, across, along, radius, Math.PI, TURN);
1582
+ }
1583
+ }
1584
+ /**
1585
+ * Appends a cylinder standing along the Y axis: a ring at each end and four lines joining them.
1586
+ *
1587
+ * @param out - The segment list.
1588
+ * @param center - The cylinder's centre.
1589
+ * @param radius - Its radius.
1590
+ * @param halfHeight - Half its height.
1591
+ *
1592
+ * @internal
1593
+ */
1594
+ function pushCylinder(out, center, radius, halfHeight) {
1595
+ pushTube(out, offset(center, Y_AXIS, halfHeight), offset(center, Y_AXIS, -halfHeight), X_AXIS, Z_AXIS, radius);
1596
+ }
1597
+ /**
1598
+ * Moves an outline from body space into world space, in place, and packs it.
1599
+ *
1600
+ * @param local - The segments in body space, scale applied.
1601
+ * @param position - The body's world position.
1602
+ * @param rotation - The body's world rotation.
1603
+ * @returns The segments in world space.
1604
+ *
1605
+ * @internal
1606
+ */
1607
+ function placeOutline(local, position, rotation) {
1608
+ const out = new Float32Array(local.length);
1609
+ const { x: qx, y: qy, z: qz, w: qw } = rotation;
1610
+ for (let index = 0; index + 2 < local.length; index += 3) {
1611
+ const x = local[index] ?? 0;
1612
+ const y = local[index + 1] ?? 0;
1613
+ const z = local[index + 2] ?? 0;
1614
+ const tx = 2 * (qy * z - qz * y);
1615
+ const ty = 2 * (qz * x - qx * z);
1616
+ const tz = 2 * (qx * y - qy * x);
1617
+ out[index] = x + qw * tx + (qy * tz - qz * ty) + position.x;
1618
+ out[index + 1] = y + qw * ty + (qz * tx - qx * tz) + position.y;
1619
+ out[index + 2] = z + qw * tz + (qx * ty - qy * tx) + position.z;
1620
+ }
1621
+ return out;
1622
+ }
1623
+ /**
1624
+ * Appends two rings and the four lines joining them.
1625
+ *
1626
+ * @param out - The segment list.
1627
+ * @param top - The centre of one ring.
1628
+ * @param bottom - The centre of the other.
1629
+ * @param u - One axis across the tube.
1630
+ * @param v - The other.
1631
+ * @param radius - The radius.
1632
+ */
1633
+ function pushTube(out, top, bottom, u, v, radius) {
1634
+ pushArc(out, top, u, v, radius);
1635
+ pushArc(out, bottom, u, v, radius);
1636
+ for (const [axis, sign] of [
1637
+ [u, 1],
1638
+ [u, -1],
1639
+ [v, 1],
1640
+ [v, -1]
1641
+ ]) pushSegment(out, offset(top, axis, sign * radius), offset(bottom, axis, sign * radius));
1642
+ }
1643
+ /**
1644
+ * A point moved along an axis.
1645
+ *
1646
+ * @param point - The start.
1647
+ * @param axis - The unit axis.
1648
+ * @param distance - How far.
1649
+ * @returns A fresh point.
1650
+ */
1651
+ function offset(point, axis, distance) {
1652
+ return {
1653
+ x: point.x + axis[0] * distance,
1654
+ y: point.y + axis[1] * distance,
1655
+ z: point.z + axis[2] * distance
1656
+ };
1657
+ }
1395
1658
  //#endregion
1396
1659
  //#region src/components/colliders.ts
1397
1660
  /**
@@ -1460,6 +1723,19 @@ var BoxCollider = class BoxCollider extends Collider {
1460
1723
  halfExtentsToRef(scale, out) {
1461
1724
  out.set(this.size.x * abs(scale.x) / 2, this.size.y * abs(scale.y) / 2, this.size.z * abs(scale.z) / 2);
1462
1725
  }
1726
+ /**
1727
+ * Appends the box's twelve edges.
1728
+ *
1729
+ * @param scale - The entity's lossy scale.
1730
+ * @param out - The segment list.
1731
+ *
1732
+ * @internal
1733
+ */
1734
+ outlineToRef(scale, out) {
1735
+ const half = new Vec3();
1736
+ this.halfExtentsToRef(scale, half);
1737
+ pushBox(out, scaled(this.center, scale), half);
1738
+ }
1463
1739
  };
1464
1740
  /**
1465
1741
  * A sphere collider. Non-uniform scale is not representable as a sphere, so the largest scale axis
@@ -1500,6 +1776,17 @@ var SphereCollider = class SphereCollider extends Collider {
1500
1776
  const radius = this.radius * maxAxis(scale);
1501
1777
  out.set(radius, radius, radius);
1502
1778
  }
1779
+ /**
1780
+ * Appends the sphere's three great circles.
1781
+ *
1782
+ * @param scale - The entity's lossy scale.
1783
+ * @param out - The segment list.
1784
+ *
1785
+ * @internal
1786
+ */
1787
+ outlineToRef(scale, out) {
1788
+ pushSphere(out, scaled(this.center, scale), this.radius * maxAxis(scale));
1789
+ }
1503
1790
  };
1504
1791
  /**
1505
1792
  * A capsule collider: a cylinder with hemispherical caps, standing along one axis.
@@ -1548,6 +1835,19 @@ var CapsuleCollider = class CapsuleCollider extends Collider {
1548
1835
  const half = Math.max(radius, this.height * axisScale(this.direction, scale) / 2);
1549
1836
  out.set(this.direction === "x" ? half : radius, this.direction === "y" ? half : radius, this.direction === "z" ? half : radius);
1550
1837
  }
1838
+ /**
1839
+ * Appends the capsule's end rings, its sides, and its caps.
1840
+ *
1841
+ * @param scale - The entity's lossy scale.
1842
+ * @param out - The segment list.
1843
+ *
1844
+ * @internal
1845
+ */
1846
+ outlineToRef(scale, out) {
1847
+ const radius = this.radius * radialScale(this.direction, scale);
1848
+ const half = Math.max(0, this.height * axisScale(this.direction, scale) / 2 - radius);
1849
+ pushCapsule(out, scaled(this.center, scale), this.direction, radius, half);
1850
+ }
1551
1851
  };
1552
1852
  /**
1553
1853
  * A cylinder collider standing along Y.
@@ -1599,6 +1899,18 @@ var CylinderCollider = class CylinderCollider extends Collider {
1599
1899
  const radius = this.radius * Math.max(abs(scale.x), abs(scale.z));
1600
1900
  out.set(radius, this.height * abs(scale.y) / 2, radius);
1601
1901
  }
1902
+ /**
1903
+ * Appends the cylinder's end rings and its sides.
1904
+ *
1905
+ * @param scale - The entity's lossy scale.
1906
+ * @param out - The segment list.
1907
+ *
1908
+ * @internal
1909
+ */
1910
+ outlineToRef(scale, out) {
1911
+ const radius = this.radius * Math.max(abs(scale.x), abs(scale.z));
1912
+ pushCylinder(out, scaled(this.center, scale), radius, this.height * abs(scale.y) / 2);
1913
+ }
1602
1914
  };
1603
1915
  /**
1604
1916
  * A collider built from real geometry: either an explicit `MeshAsset` or, when `mesh` is
@@ -1715,6 +2027,35 @@ var HeightfieldCollider = class HeightfieldCollider extends Collider {
1715
2027
  halfExtentsToRef(scale, out) {
1716
2028
  out.set(this.size.x * abs(scale.x) / 2, this.size.y * abs(scale.y) / 2, this.size.z * abs(scale.z) / 2);
1717
2029
  }
2030
+ /**
2031
+ * Appends the bounding box of the samples: the field's extent across, centred on the entity as
2032
+ * Havok places it, and from its lowest to its highest sample in height. `center` does not apply
2033
+ * to a heightfield.
2034
+ *
2035
+ * @param scale - The entity's lossy scale.
2036
+ * @param out - The segment list.
2037
+ *
2038
+ * @internal
2039
+ */
2040
+ outlineToRef(scale, out) {
2041
+ let low = Number.POSITIVE_INFINITY;
2042
+ let high = Number.NEGATIVE_INFINITY;
2043
+ for (const height of this.heights) {
2044
+ low = Math.min(low, height);
2045
+ high = Math.max(high, height);
2046
+ }
2047
+ if (low > high) return;
2048
+ const y = abs(scale.y);
2049
+ pushBox(out, {
2050
+ x: 0,
2051
+ y: (low + high) / 2 * y,
2052
+ z: 0
2053
+ }, {
2054
+ x: this.size.x * abs(scale.x) / 2,
2055
+ y: (high - low) / 2 * y,
2056
+ z: this.size.z * abs(scale.z) / 2
2057
+ });
2058
+ }
1718
2059
  };
1719
2060
  /**
1720
2061
  * Builds the `BoxCollider` schema.
@@ -2313,6 +2654,13 @@ var PhysicsRuntime = class {
2313
2654
  #triggerCount = 0;
2314
2655
  #contactCount = 0;
2315
2656
  #stepped = false;
2657
+ /** Whether the app is an editor's scene view, where bodies exist and nothing steps (ADR-0028). */
2658
+ #isEditMode;
2659
+ #observer = null;
2660
+ /** The last failure reported for each entity whose body could not be built, in edit mode. */
2661
+ #failures = /* @__PURE__ */ new WeakMap();
2662
+ /** The entities `IGX-0907` (a body on a child entity) has been logged for, once each. */
2663
+ #warnedChildren = /* @__PURE__ */ new WeakSet();
2316
2664
  #disposed = false;
2317
2665
  #queries = 0;
2318
2666
  #stepsThisFrame = 0;
@@ -2332,6 +2680,7 @@ var PhysicsRuntime = class {
2332
2680
  this.#simulation = options.simulation;
2333
2681
  this.#world = options.world;
2334
2682
  this.#counters = options.counters;
2683
+ this.#isEditMode = options.ctx.app.isEditMode;
2335
2684
  this.#contacts.push(this.#contactPoint);
2336
2685
  setGravity(this.#world, this.#settings.gravity);
2337
2686
  const gravity = this.#settings.gravity;
@@ -2366,6 +2715,23 @@ var PhysicsRuntime = class {
2366
2715
  return this.#stepped;
2367
2716
  }
2368
2717
  /**
2718
+ * Whether this runtime belongs to an edit-mode app, where bodies are kept in sync with the world
2719
+ * by {@link PhysicsRuntime.syncEditMode} and never stepped (ADR-0028, amendment of 2026-10-20).
2720
+ *
2721
+ * @returns `true` in an editor's scene view.
2722
+ */
2723
+ get isEditMode() {
2724
+ return this.#isEditMode;
2725
+ }
2726
+ /**
2727
+ * Sets who hears about bodies coming and going.
2728
+ *
2729
+ * @param observer - The observer, or `null` to stop.
2730
+ */
2731
+ setBodyObserver(observer) {
2732
+ this.#observer = observer;
2733
+ }
2734
+ /**
2369
2735
  * Every body, in creation order.
2370
2736
  *
2371
2737
  * @returns The records.
@@ -2442,6 +2808,25 @@ var PhysicsRuntime = class {
2442
2808
  this.#dispatchContacts();
2443
2809
  }
2444
2810
  /**
2811
+ * Brings the bodies in line with the world without stepping, which is all an edit-mode app ever
2812
+ * does with them (ADR-0028, amendment of 2026-10-20): it builds, rebuilds, and removes bodies for
2813
+ * component and layer changes, and re-places every body and capsule whose transform moved, so a
2814
+ * query sees what the editor shows. Havok is never stepped, so nothing falls, no contact or
2815
+ * trigger event is produced, and no pose is written back to a transform.
2816
+ *
2817
+ * @remarks
2818
+ * A moved body is removed and added again with the shapes it has: a teleport alone leaves Havok's
2819
+ * broadphase where the body was, so a ray at the new place would miss it until a step. A changed
2820
+ * scale rebuilds the shapes too.
2821
+ */
2822
+ syncEditMode() {
2823
+ if (this.#disposed) return;
2824
+ this.#syncLayers();
2825
+ this.#followTransforms();
2826
+ this.#reconcile();
2827
+ this.#publishCounters();
2828
+ }
2829
+ /**
2445
2830
  * Writes the interpolated display pose of every interpolated body and controller.
2446
2831
  *
2447
2832
  * @param alpha - `time.fixedStepAlpha`, in `[0, 1)`.
@@ -2784,18 +3169,94 @@ var PhysicsRuntime = class {
2784
3169
  }
2785
3170
  }
2786
3171
  /**
3172
+ * Re-places every body and capsule whose transform changed since it was placed, for
3173
+ * {@link PhysicsRuntime.syncEditMode}. A body whose lossy scale changed is rebuilt instead.
3174
+ */
3175
+ #followTransforms() {
3176
+ for (let index = 0; index < this.#records.length; index += 1) {
3177
+ const record = this.#records[index];
3178
+ if (record === void 0 || this.#dirty.has(record.entity)) continue;
3179
+ const transform = record.entity.transform;
3180
+ if (transform.worldMatrixVersion === record.placedVersion) continue;
3181
+ if (nearlyEqual(transform.lossyScale, record.placedScale)) this.#replace(record);
3182
+ else this.markDirty(record.entity);
3183
+ }
3184
+ for (let index = 0; index < this.#controllers.length; index += 1) {
3185
+ const record = this.#controllers[index];
3186
+ if (record !== void 0 && record.entity.transform.worldMatrixVersion !== record.placedVersion) this.markControllerDirty(record.component);
3187
+ }
3188
+ }
3189
+ /**
3190
+ * Removes a body and adds it again where its node now is, keeping its shapes.
3191
+ *
3192
+ * @param record - The record whose entity moved.
3193
+ */
3194
+ #replace(record) {
3195
+ const root = record.shapes.at(-1);
3196
+ if (root === void 0) {
3197
+ this.markDirty(record.entity);
3198
+ return;
3199
+ }
3200
+ const previous = record.body;
3201
+ destroyBody(this.#world, previous);
3202
+ record.body = this.#createBody(record.node, root, record.rigidbody, record.motion);
3203
+ record.collisionEvents = false;
3204
+ this.#applyCollisionEvents(record);
3205
+ readNodePose(record.node, record.currentPosition, record.currentRotation);
3206
+ record.previousPosition.copyFrom(record.currentPosition);
3207
+ record.previousRotation.copyFrom(record.currentRotation);
3208
+ record.placedVersion = record.entity.transform.worldMatrixVersion;
3209
+ this.#observer?.replaced(previous, record.body);
3210
+ }
3211
+ /**
2787
3212
  * Rebuilds every body marked dirty, and every controller.
2788
3213
  */
2789
3214
  #reconcile() {
2790
3215
  if (this.#dirty.size > 0) {
2791
3216
  const pending = [...this.#dirty];
2792
3217
  this.#dirty.clear();
2793
- for (const entity of pending) this.#rebuildEntity(entity);
3218
+ for (const entity of pending) this.#guarded(entity, null, () => {
3219
+ this.#rebuildEntity(entity);
3220
+ });
2794
3221
  }
2795
3222
  if (this.#dirtyControllers.size > 0) {
2796
3223
  const pending = [...this.#dirtyControllers];
2797
3224
  this.#dirtyControllers.clear();
2798
- for (const component of pending) this.#rebuildController(component);
3225
+ for (const component of pending) this.#guarded(component.entity, component, () => {
3226
+ this.#rebuildController(component);
3227
+ });
3228
+ }
3229
+ }
3230
+ /**
3231
+ * Runs one entity's rebuild. In an edit-mode app a failure (a collider naming an undeclared
3232
+ * layer, say) is reported through `app.onError` once per entity and message and the other
3233
+ * entities still build, so one broken entity never stops the editor's queries; the entity
3234
+ * builds again when its components change. A game rethrows, as before.
3235
+ *
3236
+ * @param entity - The entity being rebuilt.
3237
+ * @param component - The controller being rebuilt, or `null` for a body.
3238
+ * @param rebuild - The work.
3239
+ */
3240
+ #guarded(entity, component, rebuild) {
3241
+ if (!this.#isEditMode) {
3242
+ rebuild();
3243
+ return;
3244
+ }
3245
+ try {
3246
+ rebuild();
3247
+ this.#failures.delete(entity);
3248
+ } catch (error) {
3249
+ const message = error instanceof Error ? error.message : String(error);
3250
+ if (this.#failures.get(entity) !== message) {
3251
+ this.#failures.set(entity, message);
3252
+ this.#ctx.app.onError.emit({
3253
+ error,
3254
+ source: "extension",
3255
+ phase: null,
3256
+ entity,
3257
+ component
3258
+ });
3259
+ }
2799
3260
  }
2800
3261
  }
2801
3262
  /**
@@ -2824,7 +3285,10 @@ var PhysicsRuntime = class {
2824
3285
  const colliders = collidersOf(entity);
2825
3286
  if (colliders.length === 0) return;
2826
3287
  const rigidbody = entity.getComponent(Rigidbody);
2827
- if (entity.parent !== null) this.#ctx.log.warn(`${PhysicsErrorCode.bodyOnChildEntity}: {entity} carries a physics body but is not a root entity; Havok writes its local pose.`, entity.name);
3288
+ if (entity.parent !== null && !this.#warnedChildren.has(entity)) {
3289
+ this.#warnedChildren.add(entity);
3290
+ this.#ctx.log.warn(`${PhysicsErrorCode.bodyOnChildEntity}: {entity} carries a physics body but is not a root entity; Havok writes its local pose.`, entity.name);
3291
+ }
2828
3292
  const record = this.#build(entity, rigidbody, colliders);
2829
3293
  this.#records.push(record);
2830
3294
  if (record.motion === BodyMotion.dynamic && carriedLinear !== null && carriedAngular !== null) {
@@ -2883,6 +3347,8 @@ var PhysicsRuntime = class {
2883
3347
  halfExtents: boundsOf(colliders, scale),
2884
3348
  staticVersion: entity.transform.worldMatrixVersion,
2885
3349
  reportedMove: false,
3350
+ placedVersion: entity.transform.worldMatrixVersion,
3351
+ placedScale: scale.clone(),
2886
3352
  disconnects: []
2887
3353
  };
2888
3354
  readNodePose(node, record.currentPosition, record.currentRotation);
@@ -2892,6 +3358,7 @@ var PhysicsRuntime = class {
2892
3358
  this.#byNode.set(node, record);
2893
3359
  this.#applyCollisionEvents(record);
2894
3360
  this.#watchEntity(record);
3361
+ this.#observer?.added(body);
2895
3362
  return record;
2896
3363
  }
2897
3364
  /**
@@ -2928,10 +3395,16 @@ var PhysicsRuntime = class {
2928
3395
  return shapes;
2929
3396
  }
2930
3397
  const root = createContainer(this.#world);
2931
- for (const collider of colliders) {
2932
- const child = this.#buildShape(collider, scale, node, layer, defaults);
2933
- shapes.push(child);
2934
- addContainerChild(this.#world, root, child, Vec3.zero(), Quat.identity());
3398
+ try {
3399
+ for (const collider of colliders) {
3400
+ const child = this.#buildShape(collider, scale, node, layer, defaults);
3401
+ shapes.push(child);
3402
+ addContainerChild(this.#world, root, child, Vec3.zero(), Quat.identity());
3403
+ }
3404
+ } catch (error) {
3405
+ destroyShape(this.#world, root);
3406
+ for (const shape of shapes) destroyShape(this.#world, shape);
3407
+ throw error;
2935
3408
  }
2936
3409
  setShapeFilter(this.#world, root, membershipOf(layer), this.#collideMaskOf(layer));
2937
3410
  shapes.push(root);
@@ -2965,8 +3438,8 @@ var PhysicsRuntime = class {
2965
3438
  * @returns The shape.
2966
3439
  */
2967
3440
  #buildShape(collider, scale, node, layer, defaults) {
2968
- const shape = collider.createShape(this.#world, scale, node);
2969
3441
  const effective = this.#layerOf(collider, layer);
3442
+ const shape = collider.createShape(this.#world, scale, node);
2970
3443
  setShapeFilter(this.#world, shape, membershipOf(effective), this.#collideMaskOf(effective));
2971
3444
  const material = collider.resolveMaterial(defaults);
2972
3445
  setShapeMaterial(this.#world, shape, material.friction, material.restitution, material.staticFriction);
@@ -3004,7 +3477,7 @@ var PhysicsRuntime = class {
3004
3477
  * @returns `true` when interpolation applies.
3005
3478
  */
3006
3479
  #shouldInterpolate(rigidbody, motion) {
3007
- if (!this.#settings.interpolation || motion === BodyMotion.static || rigidbody === null) return false;
3480
+ if (this.#isEditMode || !this.#settings.interpolation || motion === BodyMotion.static || rigidbody === null) return false;
3008
3481
  return rigidbody.interpolation === "interpolate";
3009
3482
  }
3010
3483
  /**
@@ -3149,7 +3622,8 @@ var PhysicsRuntime = class {
3149
3622
  halfExtents: capsuleHalfExtents(component.height, component.radius, new Vec3()),
3150
3623
  previousPosition: centre.clone(),
3151
3624
  currentPosition: centre.clone(),
3152
- interpolate: this.#settings.interpolation && component.interpolation === "interpolate",
3625
+ interpolate: !this.#isEditMode && this.#settings.interpolation && component.interpolation === "interpolate",
3626
+ placedVersion: component.transform.worldMatrixVersion,
3153
3627
  disconnect: () => {}
3154
3628
  };
3155
3629
  record.disconnect = onControllerPush(controller, (push) => {
@@ -3338,6 +3812,7 @@ var PhysicsRuntime = class {
3338
3812
  #teardown(record) {
3339
3813
  for (const disconnect of record.disconnects) disconnect();
3340
3814
  record.disconnects = [];
3815
+ this.#observer?.removed(record.body);
3341
3816
  destroyBody(this.#world, record.body);
3342
3817
  for (let index = record.shapes.length - 1; index >= 0; index -= 1) {
3343
3818
  const shape = record.shapes[index];
@@ -3590,6 +4065,36 @@ var PhysicsInterpolationSystem = class {
3590
4065
  this.#host.runtime?.interpolate(ctx.time.fixedStepAlpha);
3591
4066
  }
3592
4067
  };
4068
+ /**
4069
+ * Where the edit-mode sync system runs: in `PreRender`, after every script, tween and animation of
4070
+ * the frame has moved what it moves, and before the render sync, so the debug viewer draws bodies
4071
+ * where the frame shows their entities.
4072
+ */
4073
+ const PHYSICS_EDIT_SYNC_ORDER = -800;
4074
+ /**
4075
+ * Keeps the bodies of an edit-mode app in line with the world, without stepping
4076
+ * (ADR-0028, amendment of 2026-10-20). It is registered only in an edit-mode app, so a game never
4077
+ * pays for it.
4078
+ *
4079
+ * @internal
4080
+ */
4081
+ var PhysicsEditSyncSystem = class {
4082
+ /** The name diagnostics and error reports use. */
4083
+ name = "physics-edit-sync";
4084
+ #host;
4085
+ /**
4086
+ * Binds the system to the runtime holder.
4087
+ *
4088
+ * @param host - The holder the runtime lands in.
4089
+ */
4090
+ constructor(host) {
4091
+ this.#host = host;
4092
+ }
4093
+ /** Builds, re-places, and removes bodies for this frame's changes. */
4094
+ update() {
4095
+ this.#host.runtime?.syncEditMode();
4096
+ }
4097
+ };
3593
4098
  //#endregion
3594
4099
  //#region src/lite/gpu/viewer.ts
3595
4100
  /**
@@ -3616,6 +4121,17 @@ function showBody(viewer, body) {
3616
4121
  showPhysicsBody(viewer, body);
3617
4122
  }
3618
4123
  /**
4124
+ * Stops drawing one body and disposes its debug mesh. A body the viewer is not drawing is ignored.
4125
+ *
4126
+ * @param viewer - The viewer.
4127
+ * @param body - The body to hide.
4128
+ *
4129
+ * @internal
4130
+ */
4131
+ function hideBody(viewer, body) {
4132
+ hidePhysicsBody(viewer, body);
4133
+ }
4134
+ /**
3619
4135
  * Disposes every debug mesh and unregisters the viewer's update hook.
3620
4136
  *
3621
4137
  * @param viewer - The viewer.
@@ -3866,7 +4382,8 @@ var PhysicsService = class {
3866
4382
  * @param maxDistance - How far to travel; defaults to 10 km.
3867
4383
  * @param options - Layer mask and trigger behaviour.
3868
4384
  * @returns The hit, or `null` when the ray clears everything.
3869
- * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
4385
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet, outside
4386
+ * edit mode.
3870
4387
  */
3871
4388
  raycast(origin, direction, maxDistance = DEFAULT_RAY_DISTANCE, options) {
3872
4389
  this.#requireStep("raycast");
@@ -3922,7 +4439,8 @@ var PhysicsService = class {
3922
4439
  * @param to - The end position.
3923
4440
  * @param options - Layer mask, trigger behaviour, and the one entity to sweep through.
3924
4441
  * @returns The hit, or `null`.
3925
- * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
4442
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet, outside
4443
+ * edit mode.
3926
4444
  */
3927
4445
  shapeCast(shape, from, to, options) {
3928
4446
  this.#requireStep("shapeCast");
@@ -3964,7 +4482,8 @@ var PhysicsService = class {
3964
4482
  * @param options - Layer mask and trigger behaviour.
3965
4483
  * @returns The overlapping entities, each once: bodies in creation order, then characters in
3966
4484
  * creation order. The array is reused between calls.
3967
- * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
4485
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet, outside
4486
+ * edit mode.
3968
4487
  */
3969
4488
  overlap(shape, position, rotation, options) {
3970
4489
  this.#requireStep("overlap");
@@ -3990,7 +4509,8 @@ var PhysicsService = class {
3990
4509
  * @param maxDistance - How far to search.
3991
4510
  * @param options - Trigger behaviour.
3992
4511
  * @returns The distance, or `Number.POSITIVE_INFINITY` when nothing is in range.
3993
- * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet.
4512
+ * @throws IgnifxError with code `IGX-0902` in development when no fixed step has run yet, outside
4513
+ * edit mode.
3994
4514
  */
3995
4515
  distanceToNearest(shape, position, maxDistance, options) {
3996
4516
  this.#requireStep("distanceToNearest");
@@ -4011,6 +4531,7 @@ var PhysicsService = class {
4011
4531
  if (enabled === (this.#viewer !== null) || enabled && this.#host.runtime === null) return;
4012
4532
  if (!enabled) {
4013
4533
  if (this.#viewer !== null) {
4534
+ this.#host.runtime?.setBodyObserver(null);
4014
4535
  destroyViewer(this.#viewer);
4015
4536
  this.#viewer = null;
4016
4537
  }
@@ -4020,13 +4541,71 @@ var PhysicsService = class {
4020
4541
  this.#app.log.warn("The physics debug viewer needs a GPU device; a headless app has none.");
4021
4542
  return;
4022
4543
  }
4023
- const viewer = createViewer(this.#app.lite.scene, this.#rt().world);
4544
+ const runtime = this.#rt();
4545
+ const viewer = createViewer(this.#app.lite.scene, runtime.world);
4024
4546
  this.#viewer = viewer;
4025
- const records = this.#rt().records;
4547
+ const records = runtime.records;
4026
4548
  for (let index = 0; index < records.length; index += 1) {
4027
4549
  const record = records[index];
4028
4550
  if (record !== void 0) showBody(viewer, record.body);
4029
4551
  }
4552
+ const shown = /* @__PURE__ */ new Map();
4553
+ runtime.setBodyObserver({
4554
+ added: (body) => {
4555
+ showBody(viewer, body);
4556
+ },
4557
+ removed: (body) => {
4558
+ hideBody(viewer, shown.get(body) ?? body);
4559
+ shown.delete(body);
4560
+ },
4561
+ replaced: (previous, next) => {
4562
+ shown.set(next, shown.get(previous) ?? previous);
4563
+ shown.delete(previous);
4564
+ }
4565
+ });
4566
+ }
4567
+ /**
4568
+ * The outlines of an entity's enabled colliders, as world-space line segments: what an editor
4569
+ * draws as collider gizmos (ADR-0028, amendment of 2026-10-20).
4570
+ *
4571
+ * @remarks
4572
+ * Each outline is built from the collider's fields, the entity's world pose, and its lossy scale,
4573
+ * the same inputs Havok's shape is built from, so it works in any app, headless included, and
4574
+ * before the first step. A box draws its edges; a sphere its three great circles; a capsule and a
4575
+ * cylinder their end rings, sides, and (for a capsule) caps; a `HeightfieldCollider` the bounding
4576
+ * box of its samples. A `MeshCollider` has no outline, because its triangles live on the GPU: its
4577
+ * `lines` is empty, and an editor draws the mesh's own wireframe instead.
4578
+ *
4579
+ * @param entity - The entity whose colliders to outline.
4580
+ * @returns One outline per enabled collider, in component order; empty when it has none or the
4581
+ * entity is inactive in the hierarchy, which builds no body.
4582
+ *
4583
+ * @example
4584
+ * ```ts
4585
+ * for (const outline of app.physics.colliderOutlines(selected)) {
4586
+ * drawLines(outline.lines, outline.isTrigger ? "orange" : "green");
4587
+ * }
4588
+ * ```
4589
+ */
4590
+ colliderOutlines(entity) {
4591
+ const outlines = [];
4592
+ if (entity.isDestroyed || !entity.activeInHierarchy) return outlines;
4593
+ const transform = entity.transform;
4594
+ const position = transform.position;
4595
+ const rotation = transform.rotation;
4596
+ const scale = transform.lossyScale;
4597
+ const local = [];
4598
+ for (const component of entity.components) {
4599
+ if (!(component instanceof Collider) || !component.enabled) continue;
4600
+ local.length = 0;
4601
+ component.outlineToRef(scale, local);
4602
+ outlines.push({
4603
+ collider: component,
4604
+ isTrigger: component.isTrigger,
4605
+ lines: placeOutline(local, position, rotation)
4606
+ });
4607
+ }
4608
+ return outlines;
4030
4609
  }
4031
4610
  /**
4032
4611
  * Whether the viewer is currently drawing.
@@ -4056,7 +4635,8 @@ var PhysicsService = class {
4056
4635
  * Whether at least one fixed step has completed, which is when Havok has built its broadphase and
4057
4636
  * queries become legal (`09-physics.md` §5). A script that queries from `lateUpdate` or `update`
4058
4637
  * checks this on the first frame, where the fixed loop may not have run yet, instead of catching
4059
- * `IGX-0902`.
4638
+ * `IGX-0902`. An edit-mode app never steps, so this stays `false` there, and its queries answer
4639
+ * anyway (ADR-0028, amendment of 2026-10-20).
4060
4640
  *
4061
4641
  * @returns `true` once the first step has run.
4062
4642
  */
@@ -4064,13 +4644,20 @@ var PhysicsService = class {
4064
4644
  return this.#rt().hasStepped;
4065
4645
  }
4066
4646
  /**
4067
- * Refuses a query that ran before Havok built its broadphase (`09-physics.md` §5).
4647
+ * Refuses a query that ran before Havok built its broadphase (`09-physics.md` §5). In an
4648
+ * edit-mode app, which never steps, it brings the bodies in line with the world instead, so the
4649
+ * query sees what the editor shows (ADR-0028, amendment of 2026-10-20).
4068
4650
  *
4069
4651
  * @param query - The query name, for the diagnostic.
4070
- * @throws IgnifxError with code `IGX-0902` when no step has completed.
4652
+ * @throws IgnifxError with code `IGX-0902` when no step has completed, outside edit mode.
4071
4653
  */
4072
4654
  #requireStep(query) {
4073
- if (this.#rt().hasStepped) return;
4655
+ const runtime = this.#rt();
4656
+ if (runtime.isEditMode) {
4657
+ runtime.syncEditMode();
4658
+ return;
4659
+ }
4660
+ if (runtime.hasStepped) return;
4074
4661
  throw physicsError(PhysicsErrorCode.queryBeforeStep, `${query}() ran before the first fixed step.`, {
4075
4662
  context: { query },
4076
4663
  hint: "Step the app at least once (app.step(1 / 60)) before querying; Havok builds its broadphase in the first step."
@@ -4363,6 +4950,10 @@ const physics = defineExtension((options = {}) => {
4363
4950
  order: PHYSICS_INTERPOLATE_ORDER,
4364
4951
  editMode: "skip"
4365
4952
  });
4953
+ if (ctx.app.isEditMode) ctx.registerSystem(new PhysicsEditSyncSystem(host), {
4954
+ phase: Phase.PreRender,
4955
+ order: PHYSICS_EDIT_SYNC_ORDER
4956
+ });
4366
4957
  },
4367
4958
  async onStart(app) {
4368
4959
  const ctx = context;