@aura3d/physics 1.3.3 → 1.4.1

package/src/Collider.ts

@@ -1,67 +0,0 @@
-import { Shape, type Bounds, type PhysicsShape, type Vec3 } from "./Shape.js";
-
-export type CollisionFilter = {
-  readonly layer: number;
-  readonly mask: number;
-};
-
-export type ColliderMaterial = {
-  readonly restitution: number;
-  readonly friction: number;
-};
-
-export type ColliderDescriptor = {
-  readonly shape: PhysicsShape;
-  readonly sensor?: boolean;
-  readonly filter?: Partial<CollisionFilter>;
-  readonly material?: Partial<ColliderMaterial>;
-};
-
-export class Collider {
-  readonly id: number;
-  readonly bodyId: number;
-  readonly shape: PhysicsShape;
-  readonly sensor: boolean;
-  readonly filter: CollisionFilter;
-  readonly material: ColliderMaterial;
-
-  constructor(id: number, bodyId: number, descriptor: ColliderDescriptor) {
-    if (!Number.isInteger(id) || id <= 0) {
-      throw new Error("Collider id must be a positive integer.");
-    }
-    if (!Number.isInteger(bodyId) || bodyId <= 0) {
-      throw new Error("Collider body id must be a positive integer.");
-    }
-    this.id = id;
-    this.bodyId = bodyId;
-    this.shape = descriptor.shape;
-    this.sensor = descriptor.sensor ?? false;
-    this.filter = {
-      layer: descriptor.filter?.layer ?? 1,
-      mask: descriptor.filter?.mask ?? 0xffffffff
-    };
-    this.material = {
-      restitution: descriptor.material?.restitution ?? 0,
-      friction: descriptor.material?.friction ?? 0.5
-    };
-    if (this.filter.layer < 0 || this.filter.mask < 0) {
-      throw new Error("Collider filter layer and mask must be non-negative bit masks.");
-    }
-    if (
-      !Number.isFinite(this.material.restitution) ||
-      !Number.isFinite(this.material.friction) ||
-      this.material.restitution < 0 ||
-      this.material.friction < 0
-    ) {
-      throw new Error("Collider material values must be finite and non-negative.");
-    }
-  }
-
-  canCollideWith(other: Collider): boolean {
-    return (this.filter.mask & other.filter.layer) !== 0 && (other.filter.mask & this.filter.layer) !== 0;
-  }
-
-  bounds(position: Vec3): Bounds {
-    return Shape.bounds(this.shape, position);
-  }
-}

package/src/CollisionEvents.ts

@@ -1,70 +0,0 @@
-import type { Vec3 } from "./Shape.js";
-
-export type Contact = {
-  readonly colliderA: number;
-  readonly colliderB: number;
-  readonly bodyA: number;
-  readonly bodyB: number;
-  readonly normal: Vec3;
-  readonly penetration: number;
-  readonly sensor: boolean;
-};
-
-export type CollisionEventType = "begin" | "stay" | "end";
-
-export type CollisionEvent = {
-  readonly type: CollisionEventType;
-  readonly pairKey: string;
-  readonly contact: Contact;
-};
-
-export function contactPairKey(colliderA: number, colliderB: number): string {
-  return colliderA < colliderB ? `${colliderA}:${colliderB}` : `${colliderB}:${colliderA}`;
-}
-
-export class CollisionEventQueue {
-  private previousContacts = new Map<string, Contact>();
-  private events: CollisionEvent[] = [];
-
-  update(currentContacts: readonly Contact[]): readonly CollisionEvent[] {
-    const next = new Map<string, Contact>();
-    const events: CollisionEvent[] = [];
-    for (const contact of currentContacts) {
-      const pairKey = contactPairKey(contact.colliderA, contact.colliderB);
-      next.set(pairKey, contact);
-      events.push({ type: this.previousContacts.has(pairKey) ? "stay" : "begin", pairKey, contact });
-    }
-    for (const [pairKey, contact] of this.previousContacts) {
-      if (!next.has(pairKey)) {
-        events.push({ type: "end", pairKey, contact });
-      }
-    }
-    events.sort((a, b) => a.pairKey.localeCompare(b.pairKey) || a.type.localeCompare(b.type));
-    this.previousContacts = next;
-    this.events = events;
-    return this.drain();
-  }
-
-  removeCollider(colliderId: number): readonly CollisionEvent[] {
-    const removedEvents: CollisionEvent[] = [];
-    for (const [pairKey, contact] of this.previousContacts) {
-      if (contact.colliderA === colliderId || contact.colliderB === colliderId) {
-        const event = { type: "end" as const, pairKey, contact };
-        this.events.push(event);
-        removedEvents.push(event);
-        this.previousContacts.delete(pairKey);
-      }
-    }
-    return removedEvents;
-  }
-
-  drain(): readonly CollisionEvent[] {
-    const events = this.events;
-    this.events = [];
-    return events;
-  }
-
-  snapshotContacts(): readonly Contact[] {
-    return Array.from(this.previousContacts.values());
-  }
-}

package/src/CollisionVolumes.ts

@@ -1,303 +0,0 @@
-import { cloneVec3, validateFiniteVec3, type Bounds, type Vec3 } from "./Shape.js";
-
-export type CombatFacing = -1 | 1;
-export type CollisionOwnerId = string | number;
-export type CollisionVolumeKind = "hitbox" | "hurtbox" | "pushbox" | "guardbox";
-
-export type CollisionVolumeDescriptor = {
-  readonly id?: string;
-  readonly ownerId?: CollisionOwnerId;
-  readonly offset?: Vec3;
-  readonly halfExtents: Vec3;
-  readonly enabled?: boolean;
-  readonly tags?: readonly string[];
-  readonly debug?: boolean | CollisionVolumeDebugOptions;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-};
-
-export type CollisionVolumeDebugOptions = {
-  readonly enabled?: boolean;
-  readonly color?: string;
-  readonly opacity?: number;
-  readonly label?: string;
-};
-
-export type CollisionVolumeDebugMetadata = {
-  readonly enabled: boolean;
-  readonly visibleInNormalPass: false;
-  readonly color: string;
-  readonly opacity: number;
-  readonly label?: string;
-};
-
-export type CollisionVolume = {
-  readonly id: string;
-  readonly kind: CollisionVolumeKind;
-  readonly offset: Vec3;
-  readonly halfExtents: Vec3;
-  readonly enabled: boolean;
-  readonly tags: readonly string[];
-  readonly debug: CollisionVolumeDebugMetadata;
-  readonly ownerId?: CollisionOwnerId;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-};
-
-export type ResolvedCollisionVolume = CollisionVolume & {
-  readonly center: Vec3;
-  readonly facing: CombatFacing;
-  readonly bounds: Bounds;
-};
-
-export type CollisionPenetration = {
-  readonly normal: Vec3;
-  readonly depth: number;
-  readonly axis: 0 | 1 | 2;
-  readonly overlap: Vec3;
-};
-
-export type CollisionVolumeDebugDrawOptions = {
-  readonly enabled?: boolean;
-};
-
-export type CollisionVolumeDebugDrawDescriptor = {
-  readonly id: string;
-  readonly kind: CollisionVolumeKind;
-  readonly center: Vec3;
-  readonly halfExtents: Vec3;
-  readonly color: string;
-  readonly opacity: number;
-  readonly label: string;
-};
-
-export function collisionVolume(kind: CollisionVolumeKind, descriptor: CollisionVolumeDescriptor): CollisionVolume {
-  validateHalfExtents(descriptor.halfExtents, `${kind} halfExtents`);
-  const volume = {
-    id: descriptor.id ?? kind,
-    kind,
-    offset: cloneVec3(descriptor.offset ?? [0, 0, 0]),
-    halfExtents: cloneVec3(descriptor.halfExtents),
-    enabled: descriptor.enabled ?? true,
-    tags: [...(descriptor.tags ?? [])],
-    debug: normalizeCollisionVolumeDebug(kind, descriptor.id ?? kind, descriptor.debug),
-    ...(descriptor.ownerId === undefined ? {} : { ownerId: descriptor.ownerId }),
-    ...(descriptor.metadata === undefined ? {} : { metadata: { ...descriptor.metadata } })
-  };
-  validateFiniteVec3(volume.offset, `${kind} offset`);
-  return volume;
-}
-
-export function hitbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
-  return collisionVolume("hitbox", descriptor);
-}
-
-export function hurtbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
-  return collisionVolume("hurtbox", descriptor);
-}
-
-export function pushbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
-  return collisionVolume("pushbox", descriptor);
-}
-
-export function guardbox(descriptor: CollisionVolumeDescriptor): CollisionVolume {
-  return collisionVolume("guardbox", descriptor);
-}
-
-export const createHitbox = hitbox;
-export const createHurtbox = hurtbox;
-export const createPushbox = pushbox;
-export const createGuardbox = guardbox;
-export const createGuardBox = guardbox;
-
-export function cloneCollisionVolume(volume: CollisionVolume): CollisionVolume {
-  return {
-    id: volume.id,
-    kind: volume.kind,
-    offset: cloneVec3(volume.offset),
-    halfExtents: cloneVec3(volume.halfExtents),
-    enabled: volume.enabled,
-    tags: [...volume.tags],
-    debug: { ...volume.debug },
-    ...(volume.ownerId === undefined ? {} : { ownerId: volume.ownerId }),
-    ...(volume.metadata === undefined ? {} : { metadata: { ...volume.metadata } })
-  };
-}
-
-export function withVolumeOwner(volume: CollisionVolume, ownerId: CollisionOwnerId): CollisionVolume {
-  return {
-    ...cloneCollisionVolume(volume),
-    ownerId
-  };
-}
-
-export function resolveCollisionVolume(volume: CollisionVolume, ownerPosition: Vec3, facing: CombatFacing = 1): ResolvedCollisionVolume {
-  validateFiniteVec3(ownerPosition, "volume owner position");
-  const resolvedFacing = normalizeFacing(facing);
-  const center: Vec3 = [
-    ownerPosition[0] + volume.offset[0] * resolvedFacing,
-    ownerPosition[1] + volume.offset[1],
-    ownerPosition[2] + volume.offset[2]
-  ];
-  return {
-    ...cloneCollisionVolume(volume),
-    center,
-    facing: resolvedFacing,
-    bounds: aabbFromCenter(center, volume.halfExtents)
-  };
-}
-
-export function collisionVolumeDebugDrawDescriptors(
-  volumes: readonly ResolvedCollisionVolume[],
-  options: CollisionVolumeDebugDrawOptions = {}
-): readonly CollisionVolumeDebugDrawDescriptor[] {
-  if (options.enabled !== true) {
-    return [];
-  }
-  return volumes
-    .filter((volume) => volume.enabled && volume.debug.enabled)
-    .map((volume) => ({
-      id: volume.id,
-      kind: volume.kind,
-      center: cloneVec3(volume.center),
-      halfExtents: cloneVec3(volume.halfExtents),
-      color: volume.debug.color,
-      opacity: volume.debug.opacity,
-      label: volume.debug.label ?? `${volume.kind}:${volume.id}`
-    }));
-}
-
-export function collisionVolumeVisibleInNormalPass(volume: CollisionVolume): false {
-  return volume.debug.visibleInNormalPass;
-}
-
-export function aabbFromCenter(center: Vec3, halfExtents: Vec3): Bounds {
-  validateFiniteVec3(center, "aabb center");
-  validateHalfExtents(halfExtents, "aabb halfExtents");
-  return {
-    min: [center[0] - halfExtents[0], center[1] - halfExtents[1], center[2] - halfExtents[2]],
-    max: [center[0] + halfExtents[0], center[1] + halfExtents[1], center[2] + halfExtents[2]]
-  };
-}
-
-export function boundsCenter(bounds: Bounds): Vec3 {
-  validateBounds(bounds, "bounds");
-  return [
-    (bounds.min[0] + bounds.max[0]) * 0.5,
-    (bounds.min[1] + bounds.max[1]) * 0.5,
-    (bounds.min[2] + bounds.max[2]) * 0.5
-  ];
-}
-
-export function boundsHalfExtents(bounds: Bounds): Vec3 {
-  validateBounds(bounds, "bounds");
-  return [
-    (bounds.max[0] - bounds.min[0]) * 0.5,
-    (bounds.max[1] - bounds.min[1]) * 0.5,
-    (bounds.max[2] - bounds.min[2]) * 0.5
-  ];
-}
-
-export function overlapsAabb(a: Bounds, b: Bounds): boolean {
-  validateBounds(a, "a bounds");
-  validateBounds(b, "b bounds");
-  return (
-    a.min[0] < b.max[0] &&
-    a.max[0] > b.min[0] &&
-    a.min[1] < b.max[1] &&
-    a.max[1] > b.min[1] &&
-    a.min[2] < b.max[2] &&
-    a.max[2] > b.min[2]
-  );
-}
-
-export function overlapsVolume(a: ResolvedCollisionVolume, b: ResolvedCollisionVolume): boolean {
-  if (!a.enabled || !b.enabled) {
-    return false;
-  }
-  return overlapsAabb(a.bounds, b.bounds);
-}
-
-export function aabbPenetration(a: Bounds, b: Bounds): CollisionPenetration | null {
-  if (!overlapsAabb(a, b)) {
-    return null;
-  }
-  const overlap: Vec3 = [
-    Math.min(a.max[0] - b.min[0], b.max[0] - a.min[0]),
-    Math.min(a.max[1] - b.min[1], b.max[1] - a.min[1]),
-    Math.min(a.max[2] - b.min[2], b.max[2] - a.min[2])
-  ];
-  let axis: 0 | 1 | 2 = 0;
-  if (overlap[1] < overlap[axis]) {
-    axis = 1;
-  }
-  if (overlap[2] < overlap[axis]) {
-    axis = 2;
-  }
-  const centerA = boundsCenter(a);
-  const centerB = boundsCenter(b);
-  const normal: [number, number, number] = [0, 0, 0];
-  normal[axis] = centerA[axis] <= centerB[axis] ? -1 : 1;
-  return {
-    normal,
-    depth: overlap[axis],
-    axis,
-    overlap
-  };
-}
-
-export function volumePairKey(a: CollisionVolume | ResolvedCollisionVolume, b: CollisionVolume | ResolvedCollisionVolume): string {
-  const keyA = volumeKey(a);
-  const keyB = volumeKey(b);
-  return keyA < keyB ? `${keyA}:${keyB}` : `${keyB}:${keyA}`;
-}
-
-export function normalizeFacing(value: number): CombatFacing {
-  return value < 0 ? -1 : 1;
-}
-
-export function validateBounds(bounds: Bounds, name: string): void {
-  validateFiniteVec3(bounds.min, `${name} min`);
-  validateFiniteVec3(bounds.max, `${name} max`);
-  if (bounds.min[0] > bounds.max[0] || bounds.min[1] > bounds.max[1] || bounds.min[2] > bounds.max[2]) {
-    throw new Error(`${name} min values must be less than or equal to max values.`);
-  }
-}
-
-function validateHalfExtents(value: Vec3, name: string): void {
-  validateFiniteVec3(value, name);
-  if (value[0] <= 0 || value[1] <= 0 || value[2] <= 0) {
-    throw new Error(`${name} must contain finite positive values.`);
-  }
-}
-
-function normalizeCollisionVolumeDebug(
-  kind: CollisionVolumeKind,
-  id: string,
-  debug: boolean | CollisionVolumeDebugOptions | undefined
-): CollisionVolumeDebugMetadata {
-  const options: CollisionVolumeDebugOptions = typeof debug === "object" && debug !== null ? debug : {};
-  return {
-    enabled: typeof debug === "boolean" ? debug : options.enabled ?? false,
-    visibleInNormalPass: false,
-    color: options.color ?? defaultDebugColor(kind),
-    opacity: options.opacity ?? 0.28,
-    label: options.label ?? `${kind}:${id}`
-  };
-}
-
-function defaultDebugColor(kind: CollisionVolumeKind): string {
-  switch (kind) {
-    case "hitbox":
-      return "#ef4444";
-    case "hurtbox":
-      return "#22c55e";
-    case "guardbox":
-      return "#38bdf8";
-    case "pushbox":
-      return "#facc15";
-  }
-}
-
-function volumeKey(volume: CollisionVolume | ResolvedCollisionVolume): string {
-  const owner = volume.ownerId === undefined ? "none" : String(volume.ownerId);
-  return `${owner}/${volume.kind}/${volume.id}`;
-}

package/src/Constraint.ts

@@ -1,120 +0,0 @@
-import { addVec3, dotVec3, normalizeVec3, rotateVec3ByQuat, scaleVec3, subVec3, validateFiniteVec3, type Vec3 } from "./Shape.js";
-import type { RigidBody } from "./RigidBody.js";
-
-export type ConstraintType = "fixed" | "hinge" | "slider" | "spring";
-
-export type ConstraintDescriptor = {
-  readonly type: ConstraintType;
-  readonly bodyA: RigidBody;
-  readonly bodyB: RigidBody;
-  readonly localAnchorA?: Vec3;
-  readonly localAnchorB?: Vec3;
-  readonly restLength?: number;
-  readonly stiffness?: number;
-  readonly axis?: Vec3;
-};
-
-export class Constraint {
-  readonly type: ConstraintType;
-  readonly bodyA: RigidBody;
-  readonly bodyB: RigidBody;
-  readonly localAnchorA: Vec3;
-  readonly localAnchorB: Vec3;
-  readonly restOffset: Vec3;
-  readonly restLength: number;
-  readonly stiffness: number;
-  readonly axis: Vec3;
-
-  constructor(descriptor: ConstraintDescriptor) {
-    if (descriptor.bodyA.id === descriptor.bodyB.id) {
-      throw new Error("Constraint requires two different bodies.");
-    }
-    this.localAnchorA = descriptor.localAnchorA ?? [0, 0, 0];
-    this.localAnchorB = descriptor.localAnchorB ?? [0, 0, 0];
-    validateFiniteVec3(this.localAnchorA, "constraint localAnchorA");
-    validateFiniteVec3(this.localAnchorB, "constraint localAnchorB");
-    this.axis = normalizeVec3(descriptor.axis ?? [1, 0, 0]);
-    this.type = descriptor.type;
-    this.bodyA = descriptor.bodyA;
-    this.bodyB = descriptor.bodyB;
-    const anchorA = this.anchorAWorld();
-    const anchorB = this.anchorBWorld();
-    this.restOffset = subVec3(anchorB, anchorA);
-    this.restLength = descriptor.restLength ?? Math.hypot(this.restOffset[0], this.restOffset[1], this.restOffset[2]);
-    this.stiffness = descriptor.stiffness ?? 1;
-    if (!Number.isFinite(this.restLength) || this.restLength < 0) {
-      throw new Error("Constraint restLength must be finite and non-negative.");
-    }
-    if (!Number.isFinite(this.stiffness) || this.stiffness < 0 || this.stiffness > 1) {
-      throw new Error("Constraint stiffness must be in the [0, 1] range.");
-    }
-  }
-
-  solve(): void {
-    if (this.stiffness === 0) {
-      return;
-    }
-    if (this.type === "fixed") {
-      const currentOffset = subVec3(this.anchorBWorld(), this.anchorAWorld());
-      this.applyError(subVec3(currentOffset, this.restOffset));
-      this.applyVelocityError(subVec3(this.bodyB.velocity, this.bodyA.velocity));
-    } else if (this.type === "hinge") {
-      this.applyError(subVec3(this.anchorBWorld(), this.anchorAWorld()));
-      this.applyVelocityError(subVec3(this.bodyB.velocity, this.bodyA.velocity));
-    } else if (this.type === "slider") {
-      const currentOffset = subVec3(this.anchorBWorld(), this.anchorAWorld());
-      const projected = scaleVec3(this.axis, dotVec3(currentOffset, this.axis));
-      this.applyError(subVec3(currentOffset, projected));
-      const relativeVelocity = subVec3(this.bodyB.velocity, this.bodyA.velocity);
-      const projectedVelocity = scaleVec3(this.axis, dotVec3(relativeVelocity, this.axis));
-      this.applyVelocityError(subVec3(relativeVelocity, projectedVelocity));
-    } else if (this.type === "spring") {
-      const currentOffset = subVec3(this.anchorBWorld(), this.anchorAWorld());
-      const currentLength = Math.hypot(currentOffset[0], currentOffset[1], currentOffset[2]);
-      if (currentLength <= 1e-9) {
-        return;
-      }
-      const lengthError = currentLength - this.restLength;
-      this.applyError(scaleVec3(currentOffset, lengthError / currentLength));
-      const relativeVelocity = subVec3(this.bodyB.velocity, this.bodyA.velocity);
-      const axis = scaleVec3(currentOffset, 1 / currentLength);
-      this.applyVelocityError(scaleVec3(axis, dotVec3(relativeVelocity, axis) * Math.min(1, this.stiffness)));
-    }
-  }
-
-  private anchorAWorld(): Vec3 {
-    return addVec3(this.bodyA.position, rotateVec3ByQuat(this.localAnchorA, this.bodyA.rotation));
-  }
-
-  private anchorBWorld(): Vec3 {
-    return addVec3(this.bodyB.position, rotateVec3ByQuat(this.localAnchorB, this.bodyB.rotation));
-  }
-
-  private applyError(error: Vec3): void {
-    const inverseMassSum = this.bodyA.inverseMass + this.bodyB.inverseMass;
-    if (inverseMassSum <= 0) {
-      return;
-    }
-    const weightedError = scaleVec3(error, this.stiffness);
-    if (this.bodyA.inverseMass > 0) {
-      this.bodyA.setPosition(addVec3(this.bodyA.position, scaleVec3(weightedError, this.bodyA.inverseMass / inverseMassSum)));
-    }
-    if (this.bodyB.inverseMass > 0) {
-      this.bodyB.setPosition(subVec3(this.bodyB.position, scaleVec3(weightedError, this.bodyB.inverseMass / inverseMassSum)));
-    }
-  }
-
-  private applyVelocityError(errorVelocity: Vec3): void {
-    const inverseMassSum = this.bodyA.inverseMass + this.bodyB.inverseMass;
-    if (inverseMassSum <= 0) {
-      return;
-    }
-    const correctionImpulse = scaleVec3(errorVelocity, -this.stiffness / inverseMassSum);
-    if (this.bodyA.inverseMass > 0) {
-      this.bodyA.applyImpulse(scaleVec3(correctionImpulse, -1));
-    }
-    if (this.bodyB.inverseMass > 0) {
-      this.bodyB.applyImpulse(correctionImpulse);
-    }
-  }
-}

package/src/Constraints.ts

@@ -1 +0,0 @@
-export * from "./Constraint.js";