@forgeax/engine-physics 0.1.26 → 0.1.28

package/src/index.ts

@@ -27,6 +27,37 @@ export {
   registerPhysicsComponents,
   rigidBodyTypeFromF32,
 } from './components';
+export type {
+  DerivedPhysicsCandidate,
+  DerivedPhysicsCandidateInput,
+  DerivedPhysicsCandidateState,
+  DerivedPhysicsErrorCode,
+  DerivedPhysicsErrorDetail,
+  DerivedPhysicsFailure,
+  DerivedPhysicsMotion,
+  DerivedPhysicsPublication,
+  DerivedPhysicsSnapshot,
+  DerivedShapeSeamInput,
+  DerivedShapeState,
+  PhysicsConstraintBodyDependency,
+  PhysicsConstraintInput,
+  PhysicsContactObservation,
+  PhysicsMassProperties,
+  PhysicsQuaternion,
+  PhysicsVector,
+  PhysicsVelocityPolicy,
+  VoxelCell,
+  VoxelShapeInput,
+} from './derived-physics';
+export {
+  cloneDerivedPhysicsInput,
+  DERIVED_PHYSICS_LIMITS,
+  DerivedPhysicsError,
+  estimateDerivedPhysicsInputBytes,
+  normalizeVoxelShapeInput,
+  preserveCenterOfMassVelocity,
+  validateMassProperties,
+} from './derived-physics';
 export type { PhysicsErrorCode, PhysicsErrorDetail } from './errors';
 
 export { PHYSICS_ERROR_HINTS, PhysicsError } from './errors';

package/src/physics-world.ts

@@ -5,6 +5,19 @@
 // AI users obtain it via `world.getResource<PhysicsWorld>('PhysicsWorld')`.
 
 import type { Vec2, Vec3 } from '@forgeax/engine-math';
+import type { Result } from '@forgeax/engine-types';
+import type {
+  DerivedPhysicsCandidate,
+  DerivedPhysicsCandidateInput,
+  DerivedPhysicsError,
+  DerivedPhysicsFailure,
+  DerivedPhysicsMotion,
+  DerivedPhysicsPublication,
+  DerivedPhysicsSnapshot,
+  DerivedShapeState,
+  PhysicsConstraintInput,
+  PhysicsContactObservation,
+} from './derived-physics';
 
 /**
  * Raycast hit result — returned by `PhysicsWorld.raycast()`.
@@ -65,7 +78,7 @@ export interface PhysicsWorld {
    * (unlike `world.set(entity, Transform, { translation: ... })` on
    * dynamic bodies, which would cause a velocity spike).
    *
-   * @param entity - the entity (must have RigidBody + Collider).
+   * @param entity - the entity with a registered native body.
    * @param position - new world-space position.
    */
   teleport(entity: number, position: Vec3): void;
@@ -105,7 +118,7 @@ export interface PhysicsWorld {
    *
    * Returns `true` after `ensureBody` has created a Rapier body for the entity
    * (which happens asynchronously via WASM fire-and-forget load + tick pipeline).
-   * Always returns `false` for entities that have no `RigidBody` + `Collider`.
+   * A RigidBody-only 3D entity is a native body even before derived shapes arrive.
    *
    * AI-user contract: before calling `moveAndSlide` inside a per-frame driver,
    * guard with `if (!pw.hasBody(entity)) return;` to avoid `body-not-found`
@@ -113,6 +126,70 @@ export interface PhysicsWorld {
    * `physicsSyncBackend` tick that builds the body.
    */
   hasBody(entity: number): boolean;
+
+  /**
+   * Prepare a replacement set of local derived shapes without making it
+   * queryable. The Rapier 3D implementation backs these shapes with one
+   * native world and one ECS body; 2D backends may omit this optional seam.
+   */
+  prepareDerivedShapeCandidate?: (
+    input: DerivedPhysicsCandidateInput,
+  ) => Result<DerivedPhysicsCandidate, DerivedPhysicsError>;
+  /**
+   * Queue a prepared candidate. The optional synchronous geometry commit runs
+   * after fallible native preparation, before step/publication. It must either
+   * commit its complete ECS binding or return failure without changing it.
+   * Returned failure restores old physics; a thrown callback has uncertain ECS
+   * writes and requires rebuild. Reentrant physics access is refused.
+   */
+  admitDerivedShapeCandidate?: (
+    candidate: DerivedPhysicsCandidate,
+    commitGeometry?: () => Result<void, Error>,
+  ) => Result<DerivedPhysicsCandidate, DerivedPhysicsError>;
+  /** Borrowed ordering proof, present only inside the paired geometry commit. */
+  getDerivedAdmission?: (
+    entity?: number,
+  ) =>
+    | { readonly entity: number; readonly revision: number; readonly fixedStep: number }
+    | undefined;
+  /** Cancel a candidate that has not been published. */
+  cancelDerivedShapeCandidate?: (
+    candidate: DerivedPhysicsCandidate,
+  ) => Result<void, DerivedPhysicsError>;
+  /** Invalidate pending candidates without touching the last committed state. */
+  invalidateDerivedShapeCandidates?: (reason?: string) => void;
+  /** Read the most recent fixed-step publication for one body. */
+  getDerivedPublication?: (entity: number) => DerivedPhysicsPublication | undefined;
+  /** Read the structured failure from the latest rejected admission, if any. */
+  getDerivedFailure?: (entity: number) => DerivedPhysicsFailure | undefined;
+  /** Read the committed body type without exposing a native Rapier body. */
+  getDerivedBodyType?: (entity: number) => 'static' | 'dynamic' | 'kinematic' | undefined;
+  /** Read whether a native admission failure requires a full World rebuild. */
+  getDerivedRecoveryState?: () => 'ready' | 'rebuild-required';
+  /** Read detached mass evidence without exposing a native body handle. */
+  getDerivedBodyMass?: (entity: number) => number | undefined;
+  /** Read the committed world-space COM and velocities for one derived body. */
+  getDerivedMotion?: (entity: number) => DerivedPhysicsMotion | undefined;
+  /** Read the currently committed local shape identities for one body. */
+  getDerivedShapes?: (entity: number) => readonly DerivedShapeState[];
+  /** Read detached contact observations from the latest fixed-step drain. */
+  getContactObservations?: () => readonly PhysicsContactObservation[];
+  /** Complete the fixed-step publication after ECS writeback/contact sync. */
+  finalizeDerivedFixedStep?: () => void;
+  /** Capture portable, committed input for explicit rebuild/recovery. */
+  captureDerivedPhysicsState?: () => DerivedPhysicsSnapshot;
+  /** Restore a previously captured input through normal candidate admission. */
+  restoreDerivedPhysicsState?: (
+    snapshot: DerivedPhysicsSnapshot,
+  ) => Result<readonly DerivedPhysicsCandidate[], DerivedPhysicsError>;
+  /** Create/update/remove constraints in the same solver as ordinary bodies. */
+  createDerivedConstraint?: (
+    input: PhysicsConstraintInput,
+  ) => Result<{ readonly id: string; readonly revision: number }, DerivedPhysicsError>;
+  updateDerivedConstraint?: (
+    input: PhysicsConstraintInput,
+  ) => Result<{ readonly id: string; readonly revision: number }, DerivedPhysicsError>;
+  removeDerivedConstraint?: (id: string) => Result<void, DerivedPhysicsError>;
 }
 
 /** 2D raycast hit result. */

package/src/plugin-factory.ts

@@ -3,9 +3,9 @@
 // physicsPlugin lives in @forgeax/engine-physics (the interface package, C-9)
 // and accepts an interface->backend dependency inversion: its async apply
 // dynamic-imports the rapier 2D / 3D backend on demand. The backends are
-// declared as devDependencies in this package's package.json (a regular
+// optional peerDependencies in this package's package.json (a regular
 // dependency would form a physics <-> rapier cycle since the backends depend on
-// the interface package); the consuming app declares the real runtime dep.
+// the interface package); the consuming app declares the selected runtime dep.
 //
 // charter awareness:
 //   P3 explicit failure: WASM load failure rejects plugin activation and the