@forgeax/engine-physics-rapier3d 0.1.28 → 0.1.30

package/dist/index.mjs

@@ -214,7 +214,9 @@ var RapierPhysicsWorld3D = class {
   }
   step(deltaTime) {
     this.assertActive("step");
+    if (!Number.isFinite(deltaTime) || deltaTime <= 0 || deltaTime > PHYSICS_DT_MAX) return;
     try {
+      this.raw.timestep = deltaTime;
       this.processDerivedCandidates();
       if (this.derivedPoisonedEntities.size > 0) return;
       this.raw.step(this.eventQueue);
@@ -287,6 +289,8 @@ var RapierPhysicsWorld3D = class {
   recordContactObservation(observation, handleA, handleB) {
     let point;
     let normal;
+    let geometricPoint;
+    let geometricNormal;
     try {
       const colliderA = this.raw.getCollider(handleA);
       const colliderB = this.raw.getCollider(handleB);
@@ -295,6 +299,34 @@ var RapierPhysicsWorld3D = class {
           colliderA,
           colliderB,
           (manifold, flipped) => {
+            if (manifold.numSolverContacts() === 0 && geometricPoint === void 0 && manifold.numContacts() > 0) {
+              const first = flipped ? colliderB : colliderA;
+              const second = flipped ? colliderA : colliderB;
+              const types = this.rapierModule.ShapeType;
+              for (const [collider, local] of [
+                [first, manifold.localContactPoint1(0)],
+                [second, manifold.localContactPoint2(0)]
+              ]) {
+                if (local == null || ![types.Ball, types.Cuboid, types.Capsule].includes(collider.shapeType()))
+                  continue;
+                const rotation = collider.rotation();
+                const rotated = quat.transformVec3(
+                  vec3.create(),
+                  [rotation.x, rotation.y, rotation.z, rotation.w],
+                  [local.x, local.y, local.z]
+                );
+                const position = collider.translation();
+                geometricPoint = [
+                  rotated[0] + position.x,
+                  rotated[1] + position.y,
+                  rotated[2] + position.z
+                ];
+                const n = manifold.normal();
+                const direction = flipped ? -1 : 1;
+                geometricNormal = [n.x * direction, n.y * direction, n.z * direction];
+                break;
+              }
+            }
             if (manifold.numSolverContacts?.() > 0) {
               const contact = manifold.solverContactPoint(0);
               const n = manifold.normal();
@@ -311,6 +343,10 @@ var RapierPhysicsWorld3D = class {
       }
     } catch {
     }
+    if (point === void 0 && geometricPoint !== void 0) {
+      point = geometricPoint;
+      normal = geometricNormal;
+    }
     this.derivedContacts.push({
       ...observation,
       ...point === void 0 ? {} : { point },
@@ -538,17 +574,72 @@ var RapierPhysicsWorld3D = class {
     }
     return admitted;
   }
+  admitDerivedShapeCandidates(candidates, commitGeometry) {
+    this.assertActive("admitDerivedShapeCandidates");
+    const records = [];
+    const sources = /* @__PURE__ */ new Map();
+    const constraints = /* @__PURE__ */ new Set();
+    const invalid = (reason) => new DerivedPhysicsError(
+      "derived-candidate-invalid",
+      "one bounded admission contains distinct prepared bodies and constraint updates",
+      "prepare one candidate per body and submit the complete replacement together",
+      { reason }
+    );
+    if (candidates.length === 0 || candidates.length > DERIVED_PHYSICS_LIMITS.maxCandidates)
+      return err(invalid("invalid batch size"));
+    for (const candidate of candidates) {
+      const record = this.derivedCandidates.get(candidate.candidateId);
+      if (record === void 0 || candidate.owner !== this.physicsOwner || candidate.generation !== this.backendGeneration || record.state !== "ready")
+        return err(invalid("batch member is not a current prepared candidate"));
+      if (sources.has(record.input.entity)) return err(invalid("duplicate body"));
+      for (const constraint of record.input.constraints ?? []) {
+        if (constraints.has(constraint.id)) return err(invalid("duplicate constraint update"));
+        constraints.add(constraint.id);
+      }
+      records.push(record);
+      sources.set(record.input.entity, {
+        sourceKey: record.input.sourceKey,
+        revision: record.input.revision
+      });
+    }
+    for (const candidate of candidates) {
+      const checked = this.admitDerivedShapeCandidateInternal(candidate, sources, true);
+      if (!checked.ok) {
+        for (const record of records) {
+          if (this.derivedCandidates.has(record.token.candidateId))
+            this.rejectPreparedCandidate(record, checked.error);
+        }
+        return checked;
+      }
+    }
+    const batch = Object.freeze({
+      records: Object.freeze(records),
+      ...commitGeometry === void 0 ? {} : { commitGeometry }
+    });
+    for (const record of records) record.batch = batch;
+    const queued = [];
+    for (const candidate of candidates) {
+      const admitted = this.admitDerivedShapeCandidateInternal(candidate, sources);
+      if (!admitted.ok) {
+        const first = records[0];
+        if (first !== void 0) this.rejectPreparedCandidate(first, admitted.error);
+        return admitted;
+      }
+      queued.push(admitted.value);
+    }
+    return ok(Object.freeze(queued));
+  }
   getDerivedAdmission(entity) {
-    const record = this.activeDerivedAdmission;
-    if (record === void 0 || entity !== void 0 && record.input.entity !== entity)
-      return void 0;
+    const active = this.activeDerivedAdmission;
+    const record = entity === void 0 ? active : active?.batch?.records.find((item) => item.input.entity === entity) ?? (active?.input.entity === entity ? active : void 0);
+    if (record === void 0) return void 0;
     return {
       entity: record.input.entity,
       revision: record.input.revision,
       fixedStep: this.syncState?.world.getResource(FixedTime).tick ?? this.fixedStep + 1
     };
   }
-  admitDerivedShapeCandidateInternal(candidate, sourceOverrides) {
+  admitDerivedShapeCandidateInternal(candidate, sourceOverrides, validateOnly = false) {
     this.assertActive("admitDerivedShapeCandidate");
     const record = this.derivedCandidates.get(candidate.candidateId);
     if (record === void 0 || candidate.owner !== this.physicsOwner || record.token.owner !== candidate.owner || candidate.generation !== this.backendGeneration) {
@@ -631,6 +722,7 @@ var RapierPhysicsWorld3D = class {
       this.rejectPreparedCandidate(record, stale);
       return err(stale);
     }
+    if (validateOnly) return ok(record.token);
     record.state = "queued";
     this.pendingDerivedCandidates.add(candidate.candidateId);
     const queued = Object.freeze({ ...record.token, state: "queued" });
@@ -692,10 +784,12 @@ var RapierPhysicsWorld3D = class {
         )
       );
     }
-    this.pendingDerivedCandidates.delete(candidate.candidateId);
-    for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
-    record.state = "cancelled";
-    this.releaseDerivedCandidate(candidate.candidateId);
+    for (const member of record.batch?.records ?? [record]) {
+      this.pendingDerivedCandidates.delete(member.token.candidateId);
+      for (const collider of member.nativeColliders) this.removeNativeCollider(collider.handle);
+      member.state = "cancelled";
+      this.releaseDerivedCandidate(member.token.candidateId);
+    }
     return ok(void 0);
   }
   /** Reject all in-flight derived work while preserving the last publication. */
@@ -742,12 +836,68 @@ var RapierPhysicsWorld3D = class {
     const com = body.worldCom();
     const linear = body.linvel();
     const angular = body.angvel();
+    const rotation = body.rotation();
     return Object.freeze({
       centerOfMass: [com.x, com.y, com.z],
       linearVelocity: [linear.x, linear.y, linear.z],
-      angularVelocity: [angular.x, angular.y, angular.z]
+      angularVelocity: [angular.x, angular.y, angular.z],
+      rotation: [rotation.x, rotation.y, rotation.z, rotation.w]
     });
   }
+  applyDerivedImpulse(input) {
+    this.assertActive("applyDerivedImpulse");
+    const refuse = (code, expected) => err(
+      new DerivedPhysicsError(
+        code,
+        expected,
+        "read the committed dynamic body and submit a finite impulse outside pending admission",
+        { entity: input.entity }
+      )
+    );
+    if (this.recoveryBlocked())
+      return refuse("derived-recovery-invalid", "PhysicsWorld is healthy");
+    const record = this.derivedBodies.get(input.entity);
+    const body = this.bodyForEntity(input.entity);
+    if (record === void 0 || body === void 0)
+      return refuse("derived-body-not-found", "a committed derived body exists");
+    if (record.sourceKey !== input.sourceKey || record.revision !== input.revision)
+      return refuse(
+        "derived-candidate-stale",
+        "impulse identity matches the committed body revision"
+      );
+    if (this.derivedPublicationPending || [...this.pendingDerivedCandidates].some(
+      (id) => this.derivedCandidates.get(id)?.input.entity === input.entity
+    ))
+      return refuse("derived-candidate-pending", "the body has no unpublished native mutation");
+    if (rapierBodyTypeToString(this.rapierModule, body.bodyType()) !== "dynamic" || ![input.impulse, input.point].every(
+      (vector) => Array.isArray(vector) && vector.length === 3 && vector.every((value) => Number.isFinite(value) && Number.isFinite(Math.fround(value)))
+    ))
+      return refuse(
+        "derived-candidate-invalid",
+        "a dynamic body receives finite Float32 world vectors"
+      );
+    try {
+      body.applyImpulseAtPoint(
+        { x: input.impulse[0], y: input.impulse[1], z: input.impulse[2] },
+        { x: input.point[0], y: input.point[1], z: input.point[2] },
+        true
+      );
+      const linear = body.linvel(), angular = body.angvel();
+      if (![linear.x, linear.y, linear.z, angular.x, angular.y, angular.z].every(Number.isFinite))
+        throw new Error("native impulse produced non-finite motion");
+      return ok(void 0);
+    } catch (cause) {
+      this.derivedPoisonedEntities.add(input.entity);
+      return err(
+        new DerivedPhysicsError(
+          "derived-backend-failed",
+          "native impulse completes with finite motion",
+          "rebuild the World from a previously committed snapshot",
+          { entity: input.entity, reason: cause instanceof Error ? cause.message : String(cause) }
+        )
+      );
+    }
+  }
   getDerivedRecoveryState() {
     return this.recoveryBlocked() ? "rebuild-required" : "ready";
   }
@@ -844,16 +994,8 @@ var RapierPhysicsWorld3D = class {
       }
       preparedCandidates.push(prepared.value);
     }
-    const candidates = [];
-    for (const prepared of preparedCandidates) {
-      const admitted = this.admitDerivedShapeCandidateInternal(prepared, snapshotSources);
-      if (!admitted.ok) {
-        for (const candidate of preparedCandidates) this.cancelDerivedShapeCandidate(candidate);
-        return admitted;
-      }
-      candidates.push(admitted.value);
-    }
-    return ok(candidates);
+    if (preparedCandidates.length === 0) return ok([]);
+    return this.admitDerivedShapeCandidates(preparedCandidates);
   }
   createDerivedConstraint(input) {
     return this.installDerivedConstraint(input, false);
@@ -969,8 +1111,11 @@ var RapierPhysicsWorld3D = class {
     this.releaseDerivedCandidate(record.token.candidateId);
   }
   rejectPreparedCandidate(record, error) {
-    for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
-    this.rememberDerivedFailure(record, error, "old-state-retained");
+    for (const member of record.batch?.records ?? [record]) {
+      if (!this.derivedCandidates.has(member.token.candidateId)) continue;
+      for (const collider of member.nativeColliders) this.removeNativeCollider(collider.handle);
+      this.rememberDerivedFailure(member, error, "old-state-retained");
+    }
   }
   processDerivedCandidates() {
     if (this.pendingDerivedCandidates.size === 0) return;
@@ -986,329 +1131,358 @@ var RapierPhysicsWorld3D = class {
     const visiting = /* @__PURE__ */ new Set();
     const visited = /* @__PURE__ */ new Set();
     const visit = (record) => {
-      if (visited.has(record.token.candidateId)) return;
-      if (visiting.has(record.token.candidateId)) return;
-      visiting.add(record.token.candidateId);
-      for (const constraint of record.input.constraints ?? []) {
-        for (const endpoint of [
-          [constraint.bodyA, constraint.bodyASource],
-          [constraint.bodyB, constraint.bodyBSource]
-        ]) {
-          const dependency = endpoint[1];
-          const target = pendingByEntity.get(endpoint[0]);
-          if (target !== void 0 && target.input.sourceKey === dependency.sourceKey && target.input.revision === dependency.revision) {
-            visit(target);
-          }
-        }
-      }
-      visiting.delete(record.token.candidateId);
-      visited.add(record.token.candidateId);
-      ordered.push(record);
-    };
-    for (const record of pendingRecords) visit(record);
-    for (const record of ordered) {
-      const id = record.token.candidateId;
-      if (!this.pendingDerivedCandidates.has(id) || record.state !== "queued") continue;
-      const pendingSources = this.pendingDerivedSources();
-      const projected = pendingSources.get(record.input.entity);
-      if (projected !== void 0 && record.input.revision < projected.revision) {
+      const group = record.batch?.records ?? [record];
+      const key = group[0]?.token.candidateId ?? record.token.candidateId;
+      if (visited.has(key)) return;
+      if (visiting.has(key)) {
         this.rejectPreparedCandidate(
           record,
           new DerivedPhysicsError(
-            "derived-candidate-stale",
-            "fixed-step admission publishes only the newest queued body revision",
-            "discard the older queued candidate and submit the latest complete input",
-            {
-              entity: record.input.entity,
-              candidateId: record.token.candidateId,
-              expected: `>=${projected.revision}`,
-              actual: record.input.revision
-            }
+            "derived-constraint-invalid",
+            "cyclic endpoint updates share one batch",
+            "submit mutually dependent body replacements together",
+            { candidateId: key }
           )
         );
-        continue;
+        return;
       }
-      const admissionError = this.validateDerivedAdmission(record.input, pendingSources);
-      if (admissionError !== void 0) {
-        this.rejectPreparedCandidate(record, admissionError);
-        continue;
+      visiting.add(key);
+      for (const member of group) {
+        for (const constraint of member.input.constraints ?? []) {
+          for (const [entity, dependency] of [
+            [constraint.bodyA, constraint.bodyASource],
+            [constraint.bodyB, constraint.bodyBSource]
+          ]) {
+            const target = pendingByEntity.get(entity);
+            if (target !== void 0 && !group.includes(target) && target.input.sourceKey === dependency.sourceKey && target.input.revision === dependency.revision)
+              visit(target);
+          }
+        }
       }
-      const old = this.derivedBodies.get(record.input.entity);
-      if (this.derivedPoisonedEntities.has(record.input.entity)) {
-        for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
-        this.rememberDerivedFailure(
-          record,
-          new DerivedPhysicsError(
-            "derived-recovery-invalid",
-            "the entity is stopped after an unrecoverable native admission failure",
-            "rebuild the PhysicsWorld from the last portable snapshot before retrying",
-            { entity: record.input.entity, candidateId: record.token.candidateId }
-          ),
-          "rebuild-required"
-        );
+      visiting.delete(key);
+      visited.add(key);
+      ordered.push(group);
+    };
+    for (const record of pendingRecords) visit(record);
+    for (const group of ordered) {
+      if (this.derivedPoisonedEntities.size > 0) break;
+      const first = group[0];
+      if (first === void 0) continue;
+      if (group.some(
+        (record) => record.state !== "queued" || !this.pendingDerivedCandidates.has(record.token.candidateId)
+      ))
         continue;
-      }
-      const body = this.bodyForEntity(record.input.entity);
-      if (body === void 0) {
-        for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
-        this.rememberDerivedFailure(
-          record,
-          new DerivedPhysicsError(
+      const sources = this.pendingDerivedSources();
+      let rejected;
+      for (const record of group) {
+        const projected = sources.get(record.input.entity);
+        if (projected !== void 0 && record.input.revision < projected.revision) {
+          rejected = new DerivedPhysicsError(
+            "derived-candidate-stale",
+            "fixed-step admission publishes the final queued body revisions",
+            "discard the older group and prepare a complete replacement",
+            { entity: record.input.entity }
+          );
+        } else if (this.derivedPoisonedEntities.has(record.input.entity)) {
+          rejected = new DerivedPhysicsError(
+            "derived-recovery-invalid",
+            "every batch body has recoverable native state",
+            "rebuild the PhysicsWorld before retrying",
+            { entity: record.input.entity }
+          );
+        } else if (this.bodyForEntity(record.input.entity) === void 0) {
+          rejected = new DerivedPhysicsError(
             "derived-body-not-found",
-            "candidate entity remains a live native body at fixed-step admission",
-            "reconcile the entity and submit a fresh candidate",
-            { entity: record.input.entity, candidateId: record.token.candidateId }
-          ),
-          "old-state-retained"
-        );
+            "every batch body remains live through admission",
+            "reconcile entities and prepare again",
+            { entity: record.input.entity }
+          );
+        } else rejected = this.validateDerivedAdmission(record.input, sources);
+        if (rejected !== void 0) break;
+      }
+      if (rejected !== void 0) {
+        this.rejectPreparedCandidate(first, rejected);
         continue;
       }
-      const oldBodyType = body.bodyType();
-      const oldBodyEnabled = body.isEnabled();
-      const oldVelocity = body.linvel();
-      const oldAngularVelocity = body.angvel();
-      const oldTranslation = body.translation();
-      const oldRotation = body.rotation();
-      const oldCom = body.worldCom();
-      const oldMass = body.mass();
-      const oldAutomaticAdditionalMass = this.entityMap.get(record.input.entity)?.automaticAdditionalMass ?? 0;
-      const oldAutomaticRecordMass = this.entityMap.get(
-        record.input.entity
-      )?.automaticAdditionalMass;
-      const oldSource = this.derivedBodySources.get(record.input.entity);
-      const oldPublication = this.derivedPublications.get(record.input.entity);
-      const oldDensities = this.bodyColliders(body).map((collider) => ({
-        collider,
-        density: typeof collider.density === "function" ? collider.density() : void 0,
-        enabled: typeof collider.isEnabled === "function" ? collider.isEnabled() : true
-      }));
-      const oldConstraints = new Map(this.derivedConstraints);
-      const stagedConstraints = /* @__PURE__ */ new Map();
-      let geometryCommitUncertain = false;
-      try {
-        for (const constraint of record.input.constraints ?? []) {
-          const created = this.createNativeConstraint(constraint);
-          if (!created.ok) throw created.error;
-          stagedConstraints.set(constraint.id, {
-            input: { ...constraint },
-            handle: created.value.handle
-          });
-        }
-        if (record.input.bodyType !== void 0) {
-          const RAPIER = this.rapierModule;
-          const bodyType = record.input.bodyType === "static" ? RAPIER.RigidBodyType.Fixed : record.input.bodyType === "kinematic" ? RAPIER.RigidBodyType.KinematicPositionBased : RAPIER.RigidBodyType.Dynamic;
-          body.setBodyType(bodyType, true);
-        }
-        for (const native of record.nativeColliders) {
-          const collider = this.raw.getCollider(native.handle);
-          if (collider === null || collider === void 0)
-            throw new Error("candidate collider disappeared");
-          collider.setEnabled(true);
-        }
-        const nativeById = new Map(
-          record.input.shapes.map((shape, index) => [
-            shape.id,
-            record.nativeColliders[index]?.handle
-          ])
-        );
-        for (const seam of record.input.seams ?? []) {
-          const firstHandle = nativeById.get(seam.shapeA);
-          const secondHandle = nativeById.get(seam.shapeB);
-          const first = firstHandle === void 0 ? void 0 : this.raw.getCollider(firstHandle);
-          const second = secondHandle === void 0 ? void 0 : this.raw.getCollider(secondHandle);
-          if (first === void 0 || second === void 0 || first === null || second === null) {
-            throw new Error(`derived seam references missing shape ${seam.shapeA}`);
+      const undos = [];
+      for (const record of group) {
+        const id = record.token.candidateId;
+        const old = this.derivedBodies.get(record.input.entity);
+        const body = this.bodyForEntity(record.input.entity);
+        const oldBodyType = body.bodyType();
+        const oldBodyEnabled = body.isEnabled();
+        const oldVelocity = body.linvel();
+        const oldAngularVelocity = body.angvel();
+        const oldTranslation = body.translation();
+        const oldRotation = body.rotation();
+        const oldCom = body.worldCom();
+        const oldMass = body.mass();
+        const oldAutomaticAdditionalMass = this.entityMap.get(record.input.entity)?.automaticAdditionalMass ?? 0;
+        const oldAutomaticRecordMass = this.entityMap.get(
+          record.input.entity
+        )?.automaticAdditionalMass;
+        const oldSource = this.derivedBodySources.get(record.input.entity);
+        const oldPublication = this.derivedPublications.get(record.input.entity);
+        const oldDensities = this.bodyColliders(body).map((collider) => ({
+          collider,
+          density: typeof collider.density === "function" ? collider.density() : void 0,
+          enabled: typeof collider.isEnabled === "function" ? collider.isEnabled() : true
+        }));
+        const oldConstraints = new Map(this.derivedConstraints);
+        const stagedConstraints = /* @__PURE__ */ new Map();
+        let geometryCommitUncertain = false;
+        const rollback = () => {
+          for (const staged of stagedConstraints.values())
+            this.removeNativeConstraint(staged.handle);
+          for (const current of this.derivedConstraints.values())
+            this.removeNativeConstraint(current.handle);
+          this.derivedConstraints.clear();
+          if (old !== void 0) {
+            for (const shape of old.shapes) {
+              const collider = this.raw.getCollider(shape.colliderHandle);
+              if (collider !== null && collider !== void 0) collider.setEnabled(true);
+            }
+            const retiredIndex = this.retiredDerivedBodies.indexOf(old);
+            if (retiredIndex >= 0) this.retiredDerivedBodies.splice(retiredIndex, 1);
+            this.derivedBodies.set(record.input.entity, old);
+            this.derivedBodySources.set(record.input.entity, {
+              sourceKey: old.sourceKey,
+              revision: old.revision
+            });
           }
-          first.combineVoxelStates(second, seam.offset[0], seam.offset[1], seam.offset[2]);
-        }
-        this.applyDerivedMass(
-          body,
-          record.input.massProperties,
-          oldCom,
-          record.input.velocityPolicy ?? "preserve",
-          this.entityMap.get(record.input.entity)?.additionalMass ?? 0,
-          record.input.entity,
-          record.input.shapes,
-          record.nativeColliders
-        );
-        if (record.input.motion !== void 0) {
-          const currentCom = body.worldCom();
-          const targetCom = record.input.motion.centerOfMass;
-          const translation = body.translation();
-          body.setTranslation(
-            {
-              x: translation.x + targetCom[0] - currentCom.x,
-              y: translation.y + targetCom[1] - currentCom.y,
-              z: translation.z + targetCom[2] - currentCom.z
-            },
-            true
-          );
-          body.setLinvel(
-            {
-              x: record.input.motion.linearVelocity[0],
-              y: record.input.motion.linearVelocity[1],
-              z: record.input.motion.linearVelocity[2]
-            },
-            true
-          );
-          body.setAngvel(
-            {
-              x: record.input.motion.angularVelocity[0],
-              y: record.input.motion.angularVelocity[1],
-              z: record.input.motion.angularVelocity[2]
-            },
-            true
-          );
-        }
-        const committedSources = new Map(this.derivedBodySources);
-        committedSources.set(record.input.entity, {
-          sourceKey: record.input.sourceKey,
-          revision: record.input.revision
-        });
-        const replacementConstraintIds = new Set(
-          (record.input.constraints ?? []).map((constraint) => constraint.id)
-        );
-        for (const [constraintId, current] of [...this.derivedConstraints]) {
-          if (replacementConstraintIds.has(constraintId) || this.constraintDependenciesMatch(current.input, committedSources))
-            continue;
-          this.removeNativeConstraint(current.handle);
-          this.derivedConstraints.delete(constraintId);
-        }
-        if (old !== void 0) {
-          for (const shape of old.shapes) {
-            const collider = this.raw.getCollider(shape.colliderHandle);
+          for (const native of record.nativeColliders) {
+            const collider = this.raw.getCollider(native.handle);
             if (collider !== null && collider !== void 0) collider.setEnabled(false);
           }
-          this.retiredDerivedBodies.push(old);
-        }
-        for (const constraint of record.input.constraints ?? []) {
-          const previous = this.derivedConstraints.get(constraint.id);
-          if (previous !== void 0) this.removeNativeConstraint(previous.handle);
-          const staged = stagedConstraints.get(constraint.id);
-          if (staged !== void 0) this.derivedConstraints.set(constraint.id, staged);
-        }
-        const shapes = record.input.shapes.map(
-          (shape, index) => ({
-            input: shape,
-            colliderHandle: record.nativeColliders[index]?.handle
-          })
-        );
-        const committed = {
-          entity: record.input.entity,
-          sourceKey: record.input.sourceKey,
-          generation: this.backendGeneration,
-          revision: record.input.revision,
-          bodyType: record.input.bodyType,
-          velocityPolicy: record.input.velocityPolicy,
-          candidateId: record.token.candidateId,
-          shapes,
-          seams: [...record.input.seams ?? []],
-          massProperties: record.input.massProperties,
-          constraints: [...record.input.constraints ?? []]
+          for (const native of record.nativeColliders) this.removeNativeCollider(native.handle);
+          for (const { collider, density, enabled } of oldDensities) {
+            if (this.raw.getCollider(collider.handle) === null) continue;
+            if (density !== void 0 && typeof collider.setDensity === "function")
+              collider.setDensity(density);
+            if (typeof collider.setEnabled === "function") collider.setEnabled(enabled);
+          }
+          let restored = true;
+          try {
+            body.setBodyType(oldBodyType, true);
+            this.restoreCommittedMass(body, old, oldAutomaticAdditionalMass);
+            body.setTranslation(oldTranslation, true);
+            body.setRotation(oldRotation, true);
+            body.setLinvel(oldVelocity, true);
+            body.setAngvel(oldAngularVelocity, true);
+            body.setEnabled(oldBodyEnabled);
+          } catch {
+            restored = false;
+          }
+          if (restored && !this.restoreNativeConstraints(oldConstraints)) restored = false;
+          if (restored) {
+            const currentMass = body.mass();
+            const currentCom = body.worldCom();
+            const currentVelocity = body.linvel();
+            const currentAngularVelocity = body.angvel();
+            const currentRotation = body.rotation();
+            restored = Number.isFinite(currentMass) && Math.abs(currentMass - oldMass) <= 1e-6 * Math.max(1, Math.abs(oldMass)) && Math.abs(currentCom.x - oldCom.x) <= 1e-6 && Math.abs(currentCom.y - oldCom.y) <= 1e-6 && Math.abs(currentCom.z - oldCom.z) <= 1e-6 && Math.abs(currentVelocity.x - oldVelocity.x) <= 1e-6 && Math.abs(currentVelocity.y - oldVelocity.y) <= 1e-6 && Math.abs(currentVelocity.z - oldVelocity.z) <= 1e-6 && Math.abs(currentAngularVelocity.x - oldAngularVelocity.x) <= 1e-6 && Math.abs(currentAngularVelocity.y - oldAngularVelocity.y) <= 1e-6 && Math.abs(currentAngularVelocity.z - oldAngularVelocity.z) <= 1e-6 && Math.abs(
+              currentRotation.x * oldRotation.x + currentRotation.y * oldRotation.y + currentRotation.z * oldRotation.z + currentRotation.w * oldRotation.w
+            ) >= 1 - 1e-6 && body.bodyType() === oldBodyType && body.isEnabled() === oldBodyEnabled;
+          }
+          if (old === void 0) this.derivedBodies.delete(record.input.entity);
+          else this.derivedBodies.set(record.input.entity, old);
+          if (oldSource === void 0) this.derivedBodySources.delete(record.input.entity);
+          else this.derivedBodySources.set(record.input.entity, oldSource);
+          if (oldPublication === void 0) this.derivedPublications.delete(record.input.entity);
+          else this.derivedPublications.set(record.input.entity, oldPublication);
+          const entityRecord = this.entityMap.get(record.input.entity);
+          if (entityRecord !== void 0 && oldAutomaticRecordMass !== void 0)
+            entityRecord.automaticAdditionalMass = oldAutomaticRecordMass;
+          return restored;
         };
-        if (record.commitGeometry !== void 0) {
-          this.activeDerivedAdmission = record;
+        const restore = (undo) => {
           try {
-            geometryCommitUncertain = true;
-            const geometry = record.commitGeometry();
-            geometryCommitUncertain = false;
-            if (!geometry.ok) throw geometry.error;
-          } finally {
-            this.activeDerivedAdmission = void 0;
+            return undo();
+          } catch {
+            return false;
           }
-          delete record.commitGeometry;
-        }
-        this.derivedBodies.set(record.input.entity, committed);
-        const entityRecord = this.entityMap.get(record.input.entity);
-        if (entityRecord !== void 0) {
-          entityRecord.automaticAdditionalMass = record.input.massProperties?.mode === "explicit" ? 0 : entityRecord.additionalMass;
-        }
-        this.derivedBodySources.set(record.input.entity, {
-          sourceKey: record.input.sourceKey,
-          revision: record.input.revision
-        });
-        this.derivedFailures.delete(record.input.entity);
-        record.state = "queued";
-        this.pendingDerivedCandidates.delete(id);
-      } catch (cause) {
-        for (const staged of stagedConstraints.values()) this.removeNativeConstraint(staged.handle);
-        for (const current of this.derivedConstraints.values())
-          this.removeNativeConstraint(current.handle);
-        this.derivedConstraints.clear();
-        if (old !== void 0) {
-          for (const shape of old.shapes) {
-            const collider = this.raw.getCollider(shape.colliderHandle);
-            if (collider !== null && collider !== void 0) collider.setEnabled(true);
+        };
+        try {
+          for (const constraint of record.input.constraints ?? []) {
+            const created = this.createNativeConstraint(constraint);
+            if (!created.ok) throw created.error;
+            stagedConstraints.set(constraint.id, {
+              input: { ...constraint },
+              handle: created.value.handle
+            });
           }
-          const retiredIndex = this.retiredDerivedBodies.indexOf(old);
-          if (retiredIndex >= 0) this.retiredDerivedBodies.splice(retiredIndex, 1);
-          this.derivedBodies.set(record.input.entity, old);
-          this.derivedBodySources.set(record.input.entity, {
-            sourceKey: old.sourceKey,
-            revision: old.revision
+          if (record.input.bodyType !== void 0) {
+            const RAPIER = this.rapierModule;
+            const bodyType = record.input.bodyType === "static" ? RAPIER.RigidBodyType.Fixed : record.input.bodyType === "kinematic" ? RAPIER.RigidBodyType.KinematicPositionBased : RAPIER.RigidBodyType.Dynamic;
+            body.setBodyType(bodyType, true);
+          }
+          for (const native of record.nativeColliders) {
+            const collider = this.raw.getCollider(native.handle);
+            if (collider === null || collider === void 0)
+              throw new Error("candidate collider disappeared");
+            collider.setEnabled(true);
+          }
+          const nativeById = new Map(
+            record.input.shapes.map((shape, index) => [
+              shape.id,
+              record.nativeColliders[index]?.handle
+            ])
+          );
+          for (const seam of record.input.seams ?? []) {
+            const firstHandle = nativeById.get(seam.shapeA);
+            const secondHandle = nativeById.get(seam.shapeB);
+            const first2 = firstHandle === void 0 ? void 0 : this.raw.getCollider(firstHandle);
+            const second = secondHandle === void 0 ? void 0 : this.raw.getCollider(secondHandle);
+            if (first2 === void 0 || second === void 0 || first2 === null || second === null) {
+              throw new Error(`derived seam references missing shape ${seam.shapeA}`);
+            }
+            first2.combineVoxelStates(second, seam.offset[0], seam.offset[1], seam.offset[2]);
+          }
+          if (record.input.motion?.rotation !== void 0) {
+            const [x, y, z, w] = record.input.motion.rotation;
+            body.setRotation({ x, y, z, w }, true);
+          }
+          this.applyDerivedMass(
+            body,
+            record.input.massProperties,
+            oldCom,
+            record.input.velocityPolicy ?? "preserve",
+            this.entityMap.get(record.input.entity)?.additionalMass ?? 0,
+            record.input.entity,
+            record.input.shapes,
+            record.nativeColliders
+          );
+          if (record.input.motion !== void 0) {
+            const currentCom = body.worldCom();
+            const targetCom = record.input.motion.centerOfMass;
+            const translation = body.translation();
+            body.setTranslation(
+              {
+                x: translation.x + targetCom[0] - currentCom.x,
+                y: translation.y + targetCom[1] - currentCom.y,
+                z: translation.z + targetCom[2] - currentCom.z
+              },
+              true
+            );
+            body.setLinvel(
+              {
+                x: record.input.motion.linearVelocity[0],
+                y: record.input.motion.linearVelocity[1],
+                z: record.input.motion.linearVelocity[2]
+              },
+              true
+            );
+            body.setAngvel(
+              {
+                x: record.input.motion.angularVelocity[0],
+                y: record.input.motion.angularVelocity[1],
+                z: record.input.motion.angularVelocity[2]
+              },
+              true
+            );
+          }
+          const committedSources = new Map(this.derivedBodySources);
+          committedSources.set(record.input.entity, {
+            sourceKey: record.input.sourceKey,
+            revision: record.input.revision
           });
-        }
-        for (const native of record.nativeColliders) {
-          const collider = this.raw.getCollider(native.handle);
-          if (collider !== null && collider !== void 0) collider.setEnabled(false);
-        }
-        for (const native of record.nativeColliders) this.removeNativeCollider(native.handle);
-        for (const { collider, density, enabled } of oldDensities) {
-          if (this.raw.getCollider(collider.handle) === null) continue;
-          if (density !== void 0 && typeof collider.setDensity === "function")
-            collider.setDensity(density);
-          if (typeof collider.setEnabled === "function") collider.setEnabled(enabled);
-        }
-        let restored = true;
-        try {
-          body.setBodyType(oldBodyType, true);
-          this.restoreCommittedMass(body, old, oldAutomaticAdditionalMass);
-          body.setTranslation(oldTranslation, true);
-          body.setRotation(oldRotation, true);
-          body.setLinvel(oldVelocity, true);
-          body.setAngvel(oldAngularVelocity, true);
-          body.setEnabled(oldBodyEnabled);
-        } catch {
-          restored = false;
-        }
-        if (restored && !this.restoreNativeConstraints(oldConstraints)) restored = false;
-        if (restored) {
-          const currentMass = body.mass();
-          const currentCom = body.worldCom();
-          const currentVelocity = body.linvel();
-          const currentAngularVelocity = body.angvel();
-          restored = Number.isFinite(currentMass) && Math.abs(currentMass - oldMass) <= 1e-6 * Math.max(1, Math.abs(oldMass)) && Math.abs(currentCom.x - oldCom.x) <= 1e-6 && Math.abs(currentCom.y - oldCom.y) <= 1e-6 && Math.abs(currentCom.z - oldCom.z) <= 1e-6 && Math.abs(currentVelocity.x - oldVelocity.x) <= 1e-6 && Math.abs(currentVelocity.y - oldVelocity.y) <= 1e-6 && Math.abs(currentVelocity.z - oldVelocity.z) <= 1e-6 && Math.abs(currentAngularVelocity.x - oldAngularVelocity.x) <= 1e-6 && Math.abs(currentAngularVelocity.y - oldAngularVelocity.y) <= 1e-6 && Math.abs(currentAngularVelocity.z - oldAngularVelocity.z) <= 1e-6 && body.bodyType() === oldBodyType && body.isEnabled() === oldBodyEnabled;
-        }
-        if (old === void 0) this.derivedBodies.delete(record.input.entity);
-        else this.derivedBodies.set(record.input.entity, old);
-        if (oldSource === void 0) this.derivedBodySources.delete(record.input.entity);
-        else this.derivedBodySources.set(record.input.entity, oldSource);
-        if (oldPublication === void 0) this.derivedPublications.delete(record.input.entity);
-        else this.derivedPublications.set(record.input.entity, oldPublication);
-        const entityRecord = this.entityMap.get(record.input.entity);
-        if (entityRecord !== void 0 && oldAutomaticRecordMass !== void 0)
-          entityRecord.automaticAdditionalMass = oldAutomaticRecordMass;
-        const error = cause instanceof DerivedPhysicsError ? cause : new DerivedPhysicsError(
-          "derived-backend-failed",
-          "derived admission either commits completely or preserves the prior body state",
-          "inspect the failure receipt and rebuild the PhysicsWorld if recovery is required",
-          {
+          const replacementConstraintIds = new Set(
+            (record.input.constraints ?? []).map((constraint) => constraint.id)
+          );
+          for (const [constraintId, current] of [...this.derivedConstraints]) {
+            if (replacementConstraintIds.has(constraintId) || this.constraintDependenciesMatch(current.input, committedSources))
+              continue;
+            this.removeNativeConstraint(current.handle);
+            this.derivedConstraints.delete(constraintId);
+          }
+          if (old !== void 0) {
+            for (const shape of old.shapes) {
+              const collider = this.raw.getCollider(shape.colliderHandle);
+              if (collider !== null && collider !== void 0) collider.setEnabled(false);
+            }
+            this.retiredDerivedBodies.push(old);
+          }
+          for (const constraint of record.input.constraints ?? []) {
+            const previous = this.derivedConstraints.get(constraint.id);
+            if (previous !== void 0) this.removeNativeConstraint(previous.handle);
+            const staged = stagedConstraints.get(constraint.id);
+            if (staged !== void 0) this.derivedConstraints.set(constraint.id, staged);
+          }
+          const shapes = record.input.shapes.map(
+            (shape, index) => ({
+              input: shape,
+              colliderHandle: record.nativeColliders[index]?.handle
+            })
+          );
+          const committed = {
             entity: record.input.entity,
+            sourceKey: record.input.sourceKey,
+            generation: this.backendGeneration,
+            revision: record.input.revision,
+            bodyType: record.input.bodyType,
+            velocityPolicy: record.input.velocityPolicy,
             candidateId: record.token.candidateId,
-            reason: cause instanceof Error ? cause.message : String(cause)
+            shapes,
+            seams: [...record.input.seams ?? []],
+            massProperties: record.input.massProperties,
+            constraints: [...record.input.constraints ?? []]
+          };
+          const commitGeometry = record === group[group.length - 1] ? record.batch?.commitGeometry ?? record.commitGeometry : void 0;
+          if (commitGeometry !== void 0) {
+            this.activeDerivedAdmission = record;
+            try {
+              geometryCommitUncertain = true;
+              const geometry = commitGeometry();
+              geometryCommitUncertain = false;
+              if (!geometry.ok) throw geometry.error;
+            } finally {
+              this.activeDerivedAdmission = void 0;
+            }
+            delete record.commitGeometry;
           }
-        );
-        if (geometryCommitUncertain) restored = false;
-        if (!restored) {
-          this.derivedPoisonedEntities.add(record.input.entity);
-          this.derivedBodies.delete(record.input.entity);
-          this.derivedPublications.delete(record.input.entity);
+          this.derivedBodies.set(record.input.entity, committed);
+          const entityRecord = this.entityMap.get(record.input.entity);
+          if (entityRecord !== void 0) {
+            entityRecord.automaticAdditionalMass = record.input.massProperties?.mode === "explicit" ? 0 : entityRecord.additionalMass;
+          }
+          this.derivedBodySources.set(record.input.entity, {
+            sourceKey: record.input.sourceKey,
+            revision: record.input.revision
+          });
+          this.derivedFailures.delete(record.input.entity);
+          record.state = "queued";
+          this.pendingDerivedCandidates.delete(id);
+          undos.push(rollback);
+        } catch (cause) {
+          let restored = restore(rollback);
+          for (const undo of undos.reverse()) {
+            if (!restore(undo)) restored = false;
+          }
+          const error = cause instanceof DerivedPhysicsError ? cause : new DerivedPhysicsError(
+            "derived-backend-failed",
+            "derived admission either commits completely or preserves the prior body state",
+            "inspect the failure receipt and rebuild the PhysicsWorld if recovery is required",
+            {
+              entity: record.input.entity,
+              candidateId: record.token.candidateId,
+              reason: cause instanceof Error ? cause.message : String(cause)
+            }
+          );
+          if (geometryCommitUncertain) restored = false;
+          for (const member of group) {
+            if (!restored) {
+              this.derivedPoisonedEntities.add(member.input.entity);
+              this.derivedBodies.delete(member.input.entity);
+              this.derivedPublications.delete(member.input.entity);
+            }
+            this.rememberDerivedFailure(
+              member,
+              error,
+              restored ? "old-state-retained" : "rebuild-required"
+            );
+          }
+          break;
         }
-        this.rememberDerivedFailure(
-          record,
-          error,
-          restored ? "old-state-retained" : "rebuild-required"
-        );
       }
     }
   }
@@ -1328,6 +1502,7 @@ var RapierPhysicsWorld3D = class {
         })
       );
       candidate.state = "published";
+      delete candidate.batch;
     }
   }
   retireDerivedBodies() {
@@ -1360,6 +1535,7 @@ var RapierPhysicsWorld3D = class {
         { x: frame[0], y: frame[1], z: frame[2], w: frame[3] },
         true
       );
+      body.recomputeMassPropertiesFromColliders();
     } else {
       this.restoreAutomaticDensities(
         entity,
@@ -1404,6 +1580,7 @@ var RapierPhysicsWorld3D = class {
         { x: frame[0], y: frame[1], z: frame[2], w: frame[3] },
         true
       );
+      body.recomputeMassPropertiesFromColliders();
       return;
     }
     this.restoreAutomaticMass(body, automaticAdditionalMass);
@@ -2189,6 +2366,7 @@ var RapierPhysicsWorld3D = class {
     );
     if (collider === void 0) {
       const record = this.entityMap.get(entity);
+      this.restoreAutomaticMass(body, record?.additionalMass ?? 0);
       if (record !== void 0) record.automaticAdditionalMass = record.additionalMass;
       return;
     }
@@ -2346,6 +2524,19 @@ var RapierPhysicsWorld3D = class {
   removeEntity(entity) {
     const record = this.entityMap.get(entity);
     if (!record) return;
+    for (const candidate of this.derivedCandidates.values()) {
+      if (candidate.input.entity !== entity || candidate.batch === void 0 || candidate.state !== "ready" && candidate.state !== "queued")
+        continue;
+      this.rejectPreparedCandidate(
+        candidate,
+        new DerivedPhysicsError(
+          "derived-body-not-found",
+          "all grouped bodies remain live until admission",
+          "prepare a new complete group after entity reconciliation",
+          { entity }
+        )
+      );
+    }
     const derived = this.derivedBodies.get(entity);
     if (derived !== void 0) {
       for (const shape of derived.shapes) this.removeNativeCollider(shape.colliderHandle);