@forgeax/engine-physics-rapier3d 0.0.0-dev.8d955ade1c79

package/dist/index.mjs

@@ -0,0 +1,977 @@
+import { defineSystem, FixedTime, componentDefinition, Disabled, FixedUpdate } from '@forgeax/engine-ecs';
+import { createWorldProjection } from '@forgeax/engine-ecs/projection';
+import { vec3, quat, mat4 } from '@forgeax/engine-math';
+import { CollidingEntities, PhysicsError, PHYSICS_ERROR_HINTS, CharacterController, rigidBodyTypeFromF32, RigidBody, Collider, colliderShapeFromF32, RIGID_BODY_TYPE_STATIC, registerPhysicsComponents, PhysicsSet } from '@forgeax/engine-physics';
+import { ChildOf } from '@forgeax/engine-scene';
+import { PhysicsError as PhysicsError$1 } from '@forgeax/engine-types';
+
+// src/rapier-physics-world-3d.ts
+var DEG_TO_RAD = Math.PI / 180;
+function applyKccTuning(ctrl, cc) {
+  ctrl.setMaxSlopeClimbAngle(cc.maxSlopeClimbDeg * DEG_TO_RAD);
+  ctrl.setMinSlopeSlideAngle(cc.minSlopeSlideDeg * DEG_TO_RAD);
+  ctrl.setSlideEnabled(true);
+  if (cc.autoStepMaxHeight === 0) {
+    ctrl.disableAutostep();
+  } else {
+    ctrl.enableAutostep(cc.autoStepMaxHeight, cc.autoStepMinWidth, false);
+  }
+  if (cc.snapToGroundDist === 0) {
+    ctrl.disableSnapToGround();
+  } else {
+    ctrl.enableSnapToGround(cc.snapToGroundDist);
+  }
+}
+function rapierBodyTypeToString(rapier, bodyType) {
+  if (bodyType === rapier.RigidBodyType.Dynamic) return "dynamic";
+  if (bodyType === rapier.RigidBodyType.Fixed) return "static";
+  return "kinematic";
+}
+var RapierPhysicsWorld3D = class {
+  /** Rapier 3D World instance owning all bodies, colliders, and pipeline. */
+  raw;
+  rapierModule;
+  /** Entity (raw number) -> PhysicsEntityRecord mapping. */
+  entityMap = /* @__PURE__ */ new Map();
+  /** Pending teleports: entity -> target position, applied on next sync. */
+  pendingTeleports = /* @__PURE__ */ new Map();
+  /** Event queue for collision events. */
+  eventQueue;
+  /**
+   * Active overlap set per entity, maintained by draining the event queue each
+   * step. `started` events add the pair both ways; `stopped` events remove it.
+   * Read out into each entity's `CollidingEntities` component by
+   * `writebackCollidingEntities`. Covers both solid contacts and sensor
+   * intersections (Rapier emits CollisionEvent for both).
+   */
+  collisionPairs = /* @__PURE__ */ new Map();
+  pendingCollisionEvents = [];
+  collisionEventHistory = [];
+  currentGravity;
+  /**
+   * Lazily-built Rapier KinematicCharacterController per character entity
+   * (plan-strategy D-1/D-3). `moveAndSlide` creates one on first call; the
+   * `Collider.onRemove` hook (registerPhysicsSystems) clears it on despawn.
+   * Public so AC-11 despawn tests can assert `kccCache.size === 0`.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Rapier KinematicCharacterController from dynamic module
+  kccCache = /* @__PURE__ */ new Map();
+  kccOffsets = /* @__PURE__ */ new Map();
+  /**
+   * ECS World + components wired in by `registerPhysicsSystems`, so
+   * `moveAndSlide` can read CharacterController tuning and write Transform +
+   * grounded back. Undefined until systems are registered — the input-validation
+   * error paths (body / collider) fire before these are read, so direct
+   * `pw.moveAndSlide()` calls in error tests need no World.
+   */
+  moveContext;
+  /** Persistent ECS query + projection cursor for incremental backend sync. */
+  syncState;
+  disposed = false;
+  constructor(rapier) {
+    this.rapierModule = rapier;
+    this.raw = new rapier.World({ x: 0, y: -9.81, z: 0 });
+    this.eventQueue = new rapier.EventQueue(true);
+    this.currentGravity = { x: 0, y: -9.81, z: 0 };
+  }
+  // ─── PhysicsWorld interface ────────────────────────────────────────────
+  setGravity(gravity) {
+    this.assertActive("setGravity");
+    const x = gravity[0] ?? 0;
+    const y = gravity[1] ?? 0;
+    const z = gravity[2] ?? 0;
+    this.raw.gravity = { x, y, z };
+    this.currentGravity = { x, y, z };
+  }
+  getGravity() {
+    const { x, y, z } = this.currentGravity;
+    return vec3.create(x, y, z);
+  }
+  raycast(origin, direction, maxDist, filterMask) {
+    this.assertActive("raycast");
+    const RAPIER = this.rapierModule;
+    const RayCtor = RAPIER.Ray;
+    const ray = new RayCtor(
+      { x: origin[0] ?? 0, y: origin[1] ?? 0, z: origin[2] ?? 0 },
+      { x: direction[0] ?? 0, y: direction[1] ?? 0, z: direction[2] ?? 0 }
+    );
+    const hit = this.raw.castRayAndGetNormal(
+      ray,
+      maxDist,
+      true,
+      void 0,
+      filterMask
+    );
+    if (hit === null) return void 0;
+    const point = ray.pointAt(hit.timeOfImpact);
+    const colliderParentBody = hit.collider.parent();
+    const entity = colliderParentBody !== null ? colliderParentBody.userData : 0;
+    return {
+      entity,
+      point: vec3.create(point.x, point.y, point.z),
+      normal: vec3.create(hit.normal.x, hit.normal.y, hit.normal.z),
+      timeOfImpact: hit.timeOfImpact
+    };
+  }
+  teleport(entity, position) {
+    this.assertActive("teleport");
+    this.pendingTeleports.set(entity, {
+      x: position[0] ?? 0,
+      y: position[1] ?? 0,
+      z: position[2] ?? 0
+    });
+  }
+  step(deltaTime) {
+    this.assertActive("step");
+    this.raw.step(this.eventQueue);
+    this.drainRapierCollisionEvents();
+  }
+  /**
+   * Drain the Rapier event queue into `collisionPairs`. Each event names two
+   * collider handles + a `started` flag; we resolve each collider to its owning
+   * entity (collider.parent() -> body.userData) and add/remove the symmetric
+   * pair. This is what populates `CollidingEntities` for sensor pickup + contact
+   * queries (the queue is otherwise drained-on-overflow and never observed).
+   */
+  drainRapierCollisionEvents() {
+    this.eventQueue.drainCollisionEvents((handle1, handle2, started) => {
+      const a = this.colliderHandleToEntity(handle1);
+      const b = this.colliderHandleToEntity(handle2);
+      if (a === void 0 || b === void 0) return;
+      const changed = started ? this.addPair(a, b) : this.removePair(a, b);
+      if (!changed) return;
+      this.pushCollisionEvent({
+        type: started ? "started" : "stopped",
+        entityA: a,
+        entityB: b
+      });
+    });
+  }
+  /** Resolve a Rapier collider handle to its owning ECS entity, or undefined. */
+  colliderHandleToEntity(colliderHandle) {
+    const collider = this.raw.getCollider(colliderHandle);
+    if (collider === null || collider === void 0) return void 0;
+    const body = collider.parent();
+    if (body === null || body === void 0) return void 0;
+    return body.userData;
+  }
+  addPair(a, b) {
+    let setA = this.collisionPairs.get(a);
+    if (!setA) {
+      setA = /* @__PURE__ */ new Set();
+      this.collisionPairs.set(a, setA);
+    }
+    if (setA.has(b)) return false;
+    setA.add(b);
+    let setB = this.collisionPairs.get(b);
+    if (!setB) {
+      setB = /* @__PURE__ */ new Set();
+      this.collisionPairs.set(b, setB);
+    }
+    setB.add(a);
+    return true;
+  }
+  removePair(a, b) {
+    const removedA = this.collisionPairs.get(a)?.delete(b) ?? false;
+    const removedB = this.collisionPairs.get(b)?.delete(a) ?? false;
+    return removedA || removedB;
+  }
+  pushCollisionEvent(event) {
+    const ordered = event.entityA <= event.entityB ? event : { ...event, entityA: event.entityB, entityB: event.entityA };
+    this.pendingCollisionEvents.push(ordered);
+    this.collisionEventHistory.push(ordered);
+  }
+  /**
+   * Write the current overlap set into each entity's `CollidingEntities`
+   * component (entities that carry it). Called by the PhysicsCollisionSync
+   * system after writeback. Entities with no current overlaps get an empty set,
+   * so a Core that the player has left clears correctly. Only entities that own
+   * a CollidingEntities component are written (others are skipped).
+   */
+  writebackCollidingEntities(world, collidingComponent) {
+    for (const [entity, others] of this.collisionPairs) {
+      const handle = entity;
+      if (!world.get(handle, collidingComponent).ok) continue;
+      world.set(handle, collidingComponent, { entities: [...others] });
+    }
+  }
+  drainCollisionEvents() {
+    return this.pendingCollisionEvents.splice(0);
+  }
+  getCollisionPairs() {
+    return new Map([...this.collisionPairs].map(([entity, others]) => [entity, new Set(others)]));
+  }
+  getCollisionEventHistory() {
+    return [...this.collisionEventHistory];
+  }
+  getPendingTeleports() {
+    return [...this.pendingTeleports].map(([entity, target]) => [entity, { ...target }]);
+  }
+  getKinematicControllerStates() {
+    return [...this.kccOffsets].sort(([first], [second]) => first - second).map(([entity, offset]) => ({ entity, offset }));
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.syncState = void 0;
+    this.moveContext = void 0;
+    if (typeof this.raw.free === "function") this.raw.free();
+    if (typeof this.eventQueue.free === "function") this.eventQueue.free();
+    this.entityMap.clear();
+    this.pendingTeleports.clear();
+    this.collisionPairs.clear();
+    this.pendingCollisionEvents.length = 0;
+    this.collisionEventHistory.length = 0;
+    this.kccCache.clear();
+    this.kccOffsets.clear();
+    this.disposed = true;
+  }
+  getBodyCount() {
+    return this.entityMap.size;
+  }
+  hasBody(entity) {
+    return this.entityMap.has(entity);
+  }
+  /**
+   * Wire the ECS World + Transform / CharacterController components needed by
+   * `moveAndSlide` to read tuning and write back pose + grounded. Called once by
+   * `registerPhysicsSystems` (plan-strategy D-1/D-7).
+   */
+  setMoveContext(world, transform, characterController) {
+    this.assertActive("setMoveContext");
+    this.moveContext = { world, transform, characterController };
+  }
+  /** Release the persistent ECS readers owned by one system registration. */
+  clearEcsContext(world) {
+    if (this.syncState?.world === world) this.syncState = void 0;
+    if (this.moveContext?.world === world) this.moveContext = void 0;
+  }
+  moveAndSlide(entity, desiredDelta) {
+    this.assertActive("moveAndSlide");
+    return this.computeMove(entity, desiredDelta);
+  }
+  assertActive(operation) {
+    if (this.disposed) {
+      throw new Error(`RapierPhysicsWorld3D.${operation} cannot run on a disposed instance`);
+    }
+  }
+  /**
+   * Shared moveAndSlide core (plan-strategy D-1/D-2/D-4/D-6/D-7).
+   *
+   * The three Fail-Fast entry checks (body / collider / kinematic) throw
+   * structured PhysicsError before the World is read, so error-path tests can
+   * call this without registered systems.
+   */
+  computeMove(entity, desiredDelta) {
+    const record = this.entityMap.get(entity);
+    if (!record) {
+      throw new PhysicsError({
+        code: "body-not-found",
+        expected: "a registered Rapier body for this entity",
+        hint: PHYSICS_ERROR_HINTS["body-not-found"],
+        detail: { code: "body-not-found", entity }
+      });
+    }
+    const body = this.raw.bodies.get(record.bodyHandle);
+    if (!body) {
+      throw new PhysicsError({
+        code: "body-not-found",
+        expected: "a registered Rapier body for this entity",
+        hint: PHYSICS_ERROR_HINTS["body-not-found"],
+        detail: { code: "body-not-found", entity }
+      });
+    }
+    if (body.numColliders() === 0) {
+      throw new PhysicsError({
+        code: "collider-not-found",
+        expected: "a Collider attached to this entity body",
+        hint: PHYSICS_ERROR_HINTS["collider-not-found"],
+        detail: { code: "collider-not-found", entity }
+      });
+    }
+    const RAPIER = this.rapierModule;
+    if (body.bodyType() !== RAPIER.RigidBodyType.KinematicPositionBased) {
+      throw new PhysicsError({
+        code: "controller-requires-kinematic",
+        expected: "RigidBody.type === 'kinematic'",
+        hint: PHYSICS_ERROR_HINTS["controller-requires-kinematic"],
+        detail: {
+          code: "controller-requires-kinematic",
+          entity,
+          bodyType: rapierBodyTypeToString(RAPIER, body.bodyType())
+        }
+      });
+    }
+    const collider = body.collider(0);
+    const cc = this.readCharacterController(entity);
+    const ctrl = this.ensureKcc(entity, cc.offset);
+    applyKccTuning(ctrl, cc);
+    const delta = { x: desiredDelta[0] ?? 0, y: desiredDelta[1] ?? 0, z: desiredDelta[2] ?? 0 };
+    ctrl.computeColliderMovement(
+      collider,
+      delta,
+      RAPIER.QueryFilterFlags.EXCLUDE_SENSORS,
+      void 0,
+      // biome-ignore lint/suspicious/noExplicitAny: Rapier Collider in filter predicate
+      (other) => other.handle !== collider.handle
+    );
+    const movement = ctrl.computedMovement();
+    const grounded = ctrl.computedGrounded();
+    const t = body.translation();
+    const next = { x: t.x + movement.x, y: t.y + movement.y, z: t.z + movement.z };
+    body.setNextKinematicTranslation(next);
+    body.setTranslation(next, true);
+    this.raw.propagateModifiedBodyPositionsToColliders();
+    const ctx = this.moveContext;
+    if (ctx) {
+      ctx.world.set(entity, ctx.transform, {
+        pos: [next.x, next.y, next.z]
+      });
+      ctx.world.set(entity, ctx.characterController, { grounded });
+    }
+    return vec3.create(movement.x, movement.y, movement.z);
+  }
+  /**
+   * Read CharacterController tuning fields for an entity from the ECS World,
+   * falling back to schema defaults when the World is not wired (defensive;
+   * the kinematic check upstream means a valid character always has the World).
+   */
+  readCharacterController(entity) {
+    const ctx = this.moveContext;
+    if (ctx) {
+      const r = ctx.world.get(entity, ctx.characterController);
+      if (r.ok) {
+        const v = r.value;
+        return {
+          offset: v.offset,
+          maxSlopeClimbDeg: v.maxSlopeClimbDeg,
+          minSlopeSlideDeg: v.minSlopeSlideDeg,
+          autoStepMaxHeight: v.autoStepMaxHeight,
+          autoStepMinWidth: v.autoStepMinWidth,
+          snapToGroundDist: v.snapToGroundDist
+        };
+      }
+    }
+    return componentDefinition(CharacterController).defaults;
+  }
+  /**
+   * Lazily build a Rapier KinematicCharacterController for `entity` (cached).
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Rapier KinematicCharacterController from dynamic module
+  ensureKcc(entity, offset) {
+    const cached = this.kccCache.get(entity);
+    if (cached) return cached;
+    const ctrl = this.raw.createCharacterController(offset);
+    this.kccCache.set(entity, ctrl);
+    this.kccOffsets.set(entity, offset);
+    return ctrl;
+  }
+  /** Remove backend rows whose Collider disappeared from the World query. */
+  pruneMissingEntities(active) {
+    for (const entity of this.entityMap.keys()) {
+      if (!active.has(entity)) this.removeEntity(entity);
+    }
+  }
+  bodyForEntity(entity) {
+    const record = this.entityMap.get(entity);
+    if (!record) return void 0;
+    return this.raw.bodies.get(record.bodyHandle) ?? void 0;
+  }
+  isCommittedFixedBody(entity) {
+    return this.bodyForEntity(entity)?.bodyType() === this.rapierModule.RigidBodyType.Fixed;
+  }
+  reconcileTransformlessCompatibility(entity, staticByEcs) {
+    if (!staticByEcs || !this.isCommittedFixedBody(entity)) {
+      this.removeEntity(entity);
+      return;
+    }
+    this.removeKccController(entity);
+  }
+  resetForFullReconcile(transformlessStatic) {
+    for (const entity of [...this.entityMap.keys()]) {
+      if (transformlessStatic.has(entity) && this.isCommittedFixedBody(entity)) {
+        this.removeKccController(entity);
+        continue;
+      }
+      this.removeEntity(entity);
+    }
+  }
+  fullReconcilePhysicsState(state) {
+    const descriptors = [];
+    const transformlessStatic = /* @__PURE__ */ new Set();
+    for (const row of state.query) {
+      if (!row.has(state.transformComponent)) {
+        if (physicsRowIsStatic(row)) transformlessStatic.add(row.entity);
+        continue;
+      }
+      const descriptor = readPhysicsSyncDescriptor(row, state.transformComponent);
+      if (descriptor !== void 0) descriptors.push(descriptor);
+    }
+    this.resetForFullReconcile(transformlessStatic);
+    for (const descriptor of descriptors) {
+      this.ensureBody(
+        descriptor.entity,
+        descriptor.transform,
+        descriptor.rigidBody,
+        descriptor.collider
+      );
+    }
+    state.initialized = true;
+  }
+  reconcilePhysicsDelta(state, entity, delta) {
+    const row = state.query.at(entity);
+    if (row === void 0) {
+      this.removeEntity(entity);
+      return;
+    }
+    if (!row.has(state.transformComponent)) {
+      if (delta.colliderChanged || delta.rigidBodyChanged) {
+        this.removeEntity(entity);
+        return;
+      }
+      this.reconcileTransformlessCompatibility(entity, physicsRowIsStatic(row));
+      return;
+    }
+    const descriptor = readPhysicsSyncDescriptor(row, state.transformComponent);
+    if (descriptor === void 0) {
+      this.removeEntity(entity);
+      return;
+    }
+    if (this.hasBody(entity) && (delta.colliderChanged || delta.rigidBodyChanged)) {
+      this.removeEntity(entity);
+    }
+    if (!this.hasBody(entity)) {
+      this.ensureBody(entity, descriptor.transform, descriptor.rigidBody, descriptor.collider);
+      return;
+    }
+    if (delta.characterControllerChanged) {
+      const cachedOffset = this.kccOffsets.get(entity);
+      const hadCachedReceipt = this.kccCache.has(entity);
+      const finalOffset = descriptor.characterControllerOffset;
+      if (!descriptor.hasCharacterController) {
+        this.removeKccController(entity);
+      } else if (hadCachedReceipt && (delta.characterControllerRemoved || finalOffset === void 0 || !Object.is(cachedOffset, finalOffset))) {
+        this.removeKccController(entity);
+        if (finalOffset !== void 0) this.ensureKcc(entity, finalOffset);
+      }
+    }
+    if (!delta.transformChanged && !delta.characterControllerRemoved) return;
+    const bodyType = rigidBodyTypeFromF32(descriptor.rigidBody.type);
+    if (bodyType === "static") {
+      this.syncAuthoredPose(entity, descriptor.transform, descriptor.collider, "static");
+    } else if (bodyType === "kinematic" && !descriptor.hasCharacterController) {
+      this.syncAuthoredPose(entity, descriptor.transform, descriptor.collider, "kinematic");
+    }
+  }
+  /** @internal ECS system bridge; consumers should register PhysicsSyncBackend. */
+  _syncFromEcs(world, transformComponent) {
+    this.assertActive("syncFromEcs");
+    let state = this.syncState;
+    if (state === void 0 || state.world !== world || state.transformComponent !== transformComponent) {
+      const queryResult = world.query({
+        read: [Collider],
+        optional: [transformComponent, RigidBody, CharacterController, ChildOf]
+      });
+      if (!queryResult.ok) return;
+      state = {
+        world,
+        transformComponent,
+        query: queryResult.value,
+        projection: createWorldProjection(world, {
+          components: [
+            transformComponent,
+            Collider,
+            RigidBody,
+            CharacterController,
+            ChildOf,
+            Disabled
+          ]
+        }),
+        initialized: false
+      };
+      this.syncState = state;
+    }
+    if (!state.initialized) {
+      this.fullReconcilePhysicsState(state);
+      return;
+    }
+    const evidence = state.projection.poll();
+    if (evidence.status === "rebuild") {
+      this.fullReconcilePhysicsState(state);
+      return;
+    }
+    if (evidence.changes.length === 0) return;
+    const deltas = /* @__PURE__ */ new Map();
+    for (const change of evidence.changes) {
+      let delta = deltas.get(change.entity);
+      if (delta === void 0) {
+        delta = {
+          transformChanged: false,
+          colliderChanged: false,
+          rigidBodyChanged: false,
+          characterControllerChanged: false,
+          characterControllerRemoved: false
+        };
+        deltas.set(change.entity, delta);
+      }
+      if (change.kind === "entity-removed") continue;
+      if (change.component === void 0) {
+        this.fullReconcilePhysicsState(state);
+        return;
+      }
+      if (change.component === transformComponent) {
+        delta.transformChanged = true;
+      } else if (change.component === Collider) {
+        delta.colliderChanged = true;
+      } else if (change.component === RigidBody) {
+        delta.rigidBodyChanged = true;
+      } else if (change.component === CharacterController) {
+        delta.characterControllerChanged = true;
+        if (change.kind === "component-removed") delta.characterControllerRemoved = true;
+      } else if (change.component === ChildOf) {
+        delta.transformChanged = true;
+      } else if (change.component !== Disabled) {
+        this.fullReconcilePhysicsState(state);
+        return;
+      }
+    }
+    for (const [entity, delta] of deltas) this.reconcilePhysicsDelta(state, entity, delta);
+  }
+  /**
+   * Remove an entity's cached KCC and unregister it from the Rapier world
+   * (plan-strategy D-3). Idempotent — safe for entities that never moved.
+   */
+  removeKccController(entity) {
+    const ctrl = this.kccCache.get(entity);
+    this.kccOffsets.delete(entity);
+    if (!ctrl) return;
+    this.raw.removeCharacterController(ctrl);
+    this.kccCache.delete(entity);
+  }
+  // ─── ECS→Rapier bridge (D-2) ──────────────────────────────────────────
+  /**
+   * Ensure a Rapier body and collider exist for an ECS entity (idempotent).
+   *
+   * When `entityMap` already contains the entity this returns immediately.
+   * Otherwise creates a Rapier RigidBody (dynamic / fixed / kinematic) +
+   * Collider (cuboid / ball / capsule) from the ECS component data, sets
+   * `body.userData = entity`, and registers the pairing via `registerBody`.
+   *
+   * @param entity      Raw ECS entity number (stored in Rapier body.userData).
+   * @param transform   ECS Transform fields: { posX, posY, posZ, ... }.
+   * @param rigidBody   ECS RigidBody fields: { type (enum num), mass, ... }.
+   * @param collider    ECS Collider fields: { shape (enum num), radius, ... }.
+   *
+   * Plan-strategy D-2 + D-3: enum→Rapier desc mapping consumes
+   * rigidBodyTypeFromF32 / colliderShapeFromF32 helpers; closed switch with
+   * no default — TypeScript enforces exhaustiveness on the string-union arms.
+   */
+  ensureBody(entity, transform, rigidBody, collider) {
+    this.assertActive("ensureBody");
+    if (this.entityMap.has(entity)) return;
+    const RAPIER = this.rapierModule;
+    const rbType = rigidBodyTypeFromF32(rigidBody.type);
+    let body;
+    switch (rbType) {
+      case "dynamic": {
+        const desc = RAPIER.RigidBodyDesc.dynamic().setTranslation(transform.position.x, transform.position.y, transform.position.z).setRotation(transform.rotation).setLinearDamping(rigidBody.linearDamping).setAngularDamping(rigidBody.angularDamping).setGravityScale(rigidBody.gravityScale);
+        if (rigidBody.mass > 0) {
+          desc.setAdditionalMass(rigidBody.mass);
+        }
+        if (rigidBody.ccdEnabled) {
+          desc.setCcdEnabled(true);
+        }
+        body = this.raw.createRigidBody(desc);
+        break;
+      }
+      case "static": {
+        const desc = RAPIER.RigidBodyDesc.fixed().setTranslation(transform.position.x, transform.position.y, transform.position.z).setRotation(transform.rotation);
+        body = this.raw.createRigidBody(desc);
+        break;
+      }
+      case "kinematic": {
+        const desc = RAPIER.RigidBodyDesc.kinematicPositionBased().setTranslation(transform.position.x, transform.position.y, transform.position.z).setRotation(transform.rotation);
+        if (rigidBody.ccdEnabled) {
+          desc.setCcdEnabled(true);
+        }
+        body = this.raw.createRigidBody(desc);
+        break;
+      }
+    }
+    body.userData = entity;
+    this.registerBody(entity, body.handle);
+    const scaleX = Math.abs(transform.scale.x);
+    const scaleY = Math.abs(transform.scale.y);
+    const scaleZ = Math.abs(transform.scale.z);
+    const activeEvents = RAPIER.ActiveEvents.COLLISION_EVENTS;
+    const activeCollisionTypes = RAPIER.ActiveCollisionTypes.ALL;
+    const cShape = colliderShapeFromF32(collider.shape);
+    switch (cShape) {
+      case "cuboid": {
+        const desc = RAPIER.ColliderDesc.cuboid(
+          collider.halfExtents[0] * scaleX,
+          collider.halfExtents[1] * scaleY,
+          collider.halfExtents[2] * scaleZ
+        ).setFriction(collider.friction).setRestitution(collider.restitution).setDensity(collider.density).setCollisionGroups(collider.collisionGroups).setSolverGroups(collider.solverGroups).setActiveEvents(activeEvents).setActiveCollisionTypes(activeCollisionTypes);
+        if (collider.isSensor) desc.setSensor(true);
+        this.raw.createCollider(desc, body);
+        break;
+      }
+      case "sphere": {
+        const desc = RAPIER.ColliderDesc.ball(
+          collider.radius * Math.max(scaleX, scaleY, scaleZ)
+        ).setFriction(collider.friction).setRestitution(collider.restitution).setDensity(collider.density).setCollisionGroups(collider.collisionGroups).setSolverGroups(collider.solverGroups).setActiveEvents(activeEvents).setActiveCollisionTypes(activeCollisionTypes);
+        if (collider.isSensor) desc.setSensor(true);
+        this.raw.createCollider(desc, body);
+        break;
+      }
+      case "capsule": {
+        const desc = RAPIER.ColliderDesc.capsule(
+          collider.halfHeight * scaleY,
+          collider.radius * Math.max(scaleX, scaleZ)
+        ).setFriction(collider.friction).setRestitution(collider.restitution).setDensity(collider.density).setCollisionGroups(collider.collisionGroups).setSolverGroups(collider.solverGroups).setActiveEvents(activeEvents).setActiveCollisionTypes(activeCollisionTypes);
+        if (collider.isSensor) desc.setSensor(true);
+        this.raw.createCollider(desc, body);
+        break;
+      }
+    }
+  }
+  /**
+   * Synchronize a static or kinematic body's Rapier pose and collider shape from
+   * the resolved Transform pose. Dynamic bodies own their pose after creation.
+   */
+  syncAuthoredPose(entity, transform, collider, bodyType) {
+    this.assertActive("syncAuthoredPose");
+    const record = this.entityMap.get(entity);
+    if (!record) return;
+    const body = this.raw.bodies.get(record.bodyHandle);
+    if (!body) return;
+    if (bodyType === "static") {
+      body.setTranslation(transform.position, true);
+      body.setRotation(transform.rotation, true);
+    } else {
+      body.setNextKinematicTranslation(transform.position);
+      body.setNextKinematicRotation(transform.rotation);
+    }
+    const rapierCollider = body.collider(0);
+    if (!rapierCollider) return;
+    const scaleX = Math.abs(transform.scale.x);
+    const scaleY = Math.abs(transform.scale.y);
+    const scaleZ = Math.abs(transform.scale.z);
+    switch (colliderShapeFromF32(collider.shape)) {
+      case "cuboid":
+        rapierCollider.setHalfExtents({
+          x: collider.halfExtents[0] * scaleX,
+          y: collider.halfExtents[1] * scaleY,
+          z: collider.halfExtents[2] * scaleZ
+        });
+        break;
+      case "sphere":
+        rapierCollider.setRadius(collider.radius * Math.max(scaleX, scaleY, scaleZ));
+        break;
+      case "capsule":
+        rapierCollider.setHalfHeight(collider.halfHeight * scaleY);
+        rapierCollider.setRadius(collider.radius * Math.max(scaleX, scaleZ));
+        break;
+    }
+  }
+  // ─── ECS integration helpers ───────────────────────────────────────────
+  /**
+   * Register an ECS entity with its Rapier body handle.
+   */
+  registerBody(entity, bodyHandle) {
+    this.entityMap.set(entity, { bodyHandle });
+  }
+  /**
+   * Apply all pending teleports to their respective bodies.
+   */
+  applyPendingTeleports() {
+    for (const [entity, target] of this.pendingTeleports) {
+      const record = this.entityMap.get(entity);
+      if (!record) continue;
+      const body = this.raw.bodies.get(record.bodyHandle);
+      if (!body) continue;
+      body.setTranslation({ x: target.x, y: target.y, z: target.z }, true);
+      body.setLinvel({ x: 0, y: 0, z: 0 }, false);
+      body.setAngvel({ x: 0, y: 0, z: 0 }, false);
+    }
+    this.pendingTeleports.clear();
+  }
+  /**
+   * Set a kinematic body's next position from ECS transform.
+   */
+  setKinematicPosition(entity, pos) {
+    const record = this.entityMap.get(entity);
+    if (!record) return;
+    const body = this.raw.bodies.get(record.bodyHandle);
+    if (!body) return;
+    body.setNextKinematicTranslation({ x: pos.x, y: pos.y, z: pos.z });
+  }
+  /**
+   * Write Rapier dynamic body poses back.
+   */
+  writebackDynamicBodies() {
+    const results = [];
+    for (const [entity, record] of this.entityMap) {
+      const body = this.raw.bodies.get(record.bodyHandle);
+      if (!body) continue;
+      if (body.bodyType() !== this.rapierModule.RigidBodyType.Dynamic) continue;
+      const translation = body.translation();
+      const rotation = body.rotation();
+      results.push({
+        entity,
+        pos: { x: translation.x, y: translation.y, z: translation.z },
+        rotation: { x: rotation.x, y: rotation.y, z: rotation.z, w: rotation.w }
+      });
+    }
+    return results;
+  }
+  /**
+   * Remove a Rapier body and its colliders when the ECS entity is despawned.
+   */
+  removeEntity(entity) {
+    const record = this.entityMap.get(entity);
+    if (!record) return;
+    const ownPairs = [...this.collisionPairs.get(entity) ?? []];
+    for (const other of ownPairs) {
+      if (this.removePair(entity, other)) {
+        this.pushCollisionEvent({ type: "stopped", entityA: entity, entityB: other });
+      }
+    }
+    this.removeKccController(entity);
+    this.raw.removeRigidBody({ handle: record.bodyHandle });
+    this.entityMap.delete(entity);
+    const own = this.collisionPairs.get(entity);
+    if (own) {
+      for (const other of own) this.collisionPairs.get(other)?.delete(entity);
+      this.collisionPairs.delete(entity);
+    }
+  }
+};
+function createRapier3DPhysicsWorld(rapier) {
+  return new RapierPhysicsWorld3D(rapier);
+}
+function hasReadableWorldPose(world) {
+  return world !== void 0 && world.length >= 16;
+}
+var PHYSICS_DT_MAX = 0.1;
+var poseScratchPosition = vec3.create();
+var poseScratchRotation = quat.create();
+var poseScratchScale = vec3.create();
+var poseScratchWorld = new Float32Array(16);
+function physicsRowIsStatic(row) {
+  if (!row.has(RigidBody)) return true;
+  const rigidBody = row.get(RigidBody);
+  return rigidBody !== void 0 && rigidBodyTypeFromF32(rigidBody.type) === "static";
+}
+function readPhysicsSyncDescriptor(row, transformComponent) {
+  const transformData = row.get(transformComponent);
+  const colliderData = row.get(Collider);
+  if (transformData === void 0 || colliderData === void 0) return void 0;
+  const useWorldPose = row.has(ChildOf) && hasReadableWorldPose(transformData.world);
+  if (useWorldPose) {
+    poseScratchWorld.set(transformData.world.subarray(0, 16));
+    mat4.decompose(poseScratchPosition, poseScratchRotation, poseScratchScale, poseScratchWorld);
+  } else {
+    poseScratchPosition[0] = transformData.pos[0] ?? 0;
+    poseScratchPosition[1] = transformData.pos[1] ?? 0;
+    poseScratchPosition[2] = transformData.pos[2] ?? 0;
+    poseScratchRotation[0] = transformData.quat[0] ?? 0;
+    poseScratchRotation[1] = transformData.quat[1] ?? 0;
+    poseScratchRotation[2] = transformData.quat[2] ?? 0;
+    poseScratchRotation[3] = transformData.quat[3] ?? 1;
+    poseScratchScale[0] = transformData.scale[0] ?? 1;
+    poseScratchScale[1] = transformData.scale[1] ?? 1;
+    poseScratchScale[2] = transformData.scale[2] ?? 1;
+  }
+  const rigidBodyData = row.has(RigidBody) ? row.get(RigidBody) : void 0;
+  const characterControllerData = row.has(CharacterController) ? row.get(CharacterController) : void 0;
+  return {
+    entity: row.entity,
+    transform: {
+      position: {
+        x: poseScratchPosition[0] ?? 0,
+        y: poseScratchPosition[1] ?? 0,
+        z: poseScratchPosition[2] ?? 0
+      },
+      rotation: {
+        x: poseScratchRotation[0] ?? 0,
+        y: poseScratchRotation[1] ?? 0,
+        z: poseScratchRotation[2] ?? 0,
+        w: poseScratchRotation[3] ?? 1
+      },
+      scale: {
+        x: poseScratchScale[0] ?? 1,
+        y: poseScratchScale[1] ?? 1,
+        z: poseScratchScale[2] ?? 1
+      }
+    },
+    rigidBody: rigidBodyData === void 0 ? {
+      type: RIGID_BODY_TYPE_STATIC,
+      mass: 0,
+      linearDamping: 0,
+      angularDamping: 0,
+      gravityScale: 1,
+      ccdEnabled: 0
+    } : {
+      type: rigidBodyData.type,
+      mass: rigidBodyData.mass,
+      linearDamping: rigidBodyData.linearDamping,
+      angularDamping: rigidBodyData.angularDamping,
+      gravityScale: rigidBodyData.gravityScale,
+      ccdEnabled: Number(rigidBodyData.ccdEnabled)
+    },
+    collider: {
+      shape: colliderData.shape,
+      halfExtents: [
+        colliderData.halfExtents[0] ?? 0,
+        colliderData.halfExtents[1] ?? 0,
+        colliderData.halfExtents[2] ?? 0
+      ],
+      radius: colliderData.radius,
+      halfHeight: colliderData.halfHeight,
+      friction: colliderData.friction,
+      restitution: colliderData.restitution,
+      density: colliderData.density,
+      isSensor: Number(colliderData.isSensor),
+      collisionGroups: colliderData.collisionGroups,
+      solverGroups: colliderData.solverGroups
+    },
+    hasCharacterController: row.has(CharacterController),
+    characterControllerOffset: characterControllerData?.offset
+  };
+}
+var PHYSICS_SYNC_BACKEND = "physicsSyncBackend";
+var PHYSICS_STEP_SIMULATION = "physicsStepSimulation";
+var PHYSICS_WRITEBACK = "physicsWriteback";
+var PHYSICS_COLLISION_SYNC = "physicsCollisionSync";
+function resolveTransform(world) {
+  return world.components.resolve("Transform");
+}
+var PhysicsSyncBackend = defineSystem({
+  name: PHYSICS_SYNC_BACKEND,
+  queries: [],
+  after: ["propagateTransformsFixed"],
+  fn: (world) => {
+    const transformComponent = resolveTransform(world);
+    if (transformComponent === void 0) return;
+    let pw;
+    try {
+      pw = world.getResource("PhysicsWorld");
+    } catch {
+      return;
+    }
+    pw.applyPendingTeleports();
+    pw._syncFromEcs(world, transformComponent);
+  }
+});
+var PhysicsStepSimulation = defineSystem({
+  name: PHYSICS_STEP_SIMULATION,
+  queries: [],
+  after: [PHYSICS_SYNC_BACKEND],
+  fn: (world) => {
+    let pw;
+    try {
+      pw = world.getResource("PhysicsWorld");
+    } catch {
+      return;
+    }
+    const dt = world.getResource(FixedTime).delta;
+    if (dt <= 0 || dt > PHYSICS_DT_MAX) return;
+    pw.step(dt);
+  }
+});
+var PhysicsWriteback = defineSystem({
+  name: PHYSICS_WRITEBACK,
+  queries: [],
+  after: [PHYSICS_STEP_SIMULATION],
+  fn: (world) => {
+    const transformComponent = resolveTransform(world);
+    if (transformComponent === void 0) return;
+    let pw;
+    try {
+      pw = world.getResource("PhysicsWorld");
+    } catch {
+      return;
+    }
+    const results = pw.writebackDynamicBodies();
+    for (const r of results) {
+      const entity = r.entity;
+      world.set(entity, transformComponent, {
+        pos: [r.pos.x, r.pos.y, r.pos.z],
+        quat: [r.rotation.x, r.rotation.y, r.rotation.z, r.rotation.w]
+      });
+    }
+  }
+});
+var PhysicsCollisionSync = defineSystem({
+  name: PHYSICS_COLLISION_SYNC,
+  queries: [],
+  after: [PHYSICS_WRITEBACK],
+  fn: (world) => {
+    let pw;
+    try {
+      pw = world.getResource("PhysicsWorld");
+    } catch {
+      return;
+    }
+    pw.writebackCollidingEntities(world, CollidingEntities);
+  }
+});
+function registerPhysicsSystems(world) {
+  const releaseComponents = registerPhysicsComponents(world);
+  const transformComponent = resolveTransform(world);
+  try {
+    const pw = world.getResource("PhysicsWorld");
+    if (transformComponent !== void 0) {
+      pw.setMoveContext(world, transformComponent, CharacterController);
+    }
+  } catch {
+  }
+  world.addSystems(FixedUpdate, PhysicsSet, [
+    PhysicsSyncBackend,
+    PhysicsStepSimulation,
+    PhysicsWriteback,
+    PhysicsCollisionSync
+  ]).unwrap();
+  return () => {
+    world.removeSystem(FixedUpdate, PHYSICS_COLLISION_SYNC);
+    world.removeSystem(FixedUpdate, PHYSICS_WRITEBACK);
+    world.removeSystem(FixedUpdate, PHYSICS_STEP_SIMULATION);
+    world.removeSystem(FixedUpdate, PHYSICS_SYNC_BACKEND);
+    try {
+      world.getResource("PhysicsWorld").clearEcsContext(world);
+    } catch {
+    }
+    releaseComponents();
+  };
+}
+var rapierInstance = null;
+var loadingPromise = null;
+async function loadRapier3D() {
+  if (rapierInstance !== null) return rapierInstance;
+  if (loadingPromise !== null) return loadingPromise;
+  loadingPromise = _doLoad();
+  return loadingPromise;
+}
+async function _doLoad() {
+  try {
+    const RAPIER = await import('@dimforge/rapier3d-compat');
+    await RAPIER.default.init();
+    rapierInstance = RAPIER.default;
+    loadingPromise = null;
+    return RAPIER.default;
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    loadingPromise = null;
+    return new PhysicsError$1({
+      code: "wasm-load-failed",
+      expected: "successful dynamic import and init of @dimforge/rapier3d-compat",
+      hint: `dynamic import or init() failed: ${reason}. Check network, file path, and that @dimforge/rapier3d-compat is installed.`,
+      detail: { code: "wasm-load-failed", reason }
+    });
+  }
+}
+
+export { RapierPhysicsWorld3D, createRapier3DPhysicsWorld, loadRapier3D, registerPhysicsSystems };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map