@aura3d/physics 1.4.0 → 1.4.1

package/src/PlatformerFixtures.ts

@@ -1,205 +0,0 @@
-export type PlatformerAnimationState =
-  | "idle"
-  | "walk"
-  | "run"
-  | "jump"
-  | "fall"
-  | "doubleJump"
-  | "wallSlide"
-  | "land";
-
-export type PlatformerPlatformKind = "static" | "moving" | "rotating" | "falling" | "bouncy" | "disappearing";
-export type PlatformerCollectibleKind = "coin" | "gem" | "power-up";
-
-export interface PlatformerFixtureOptions {
-  readonly seed?: number;
-  readonly elapsedSeconds?: number;
-}
-
-export interface PlatformerPlatformSummary {
-  readonly kind: PlatformerPlatformKind;
-  readonly count: number;
-}
-
-export interface PlatformerCollectibleSummary {
-  readonly kind: PlatformerCollectibleKind;
-  readonly count: number;
-  readonly scoreValue: number;
-}
-
-export interface PlatformerControllerFixture {
-  readonly id: "external-parity-old-branch-platformer-controller-fixture";
-  readonly source: "origin-master-platformer-controller-adapted";
-  readonly config: {
-    readonly walkSpeed: number;
-    readonly runSpeed: number;
-    readonly jumpForce: number;
-    readonly doubleJumpForce: number;
-    readonly wallJumpForce: number;
-    readonly airControl: number;
-    readonly coyoteTimeSeconds: number;
-    readonly jumpBufferSeconds: number;
-    readonly maxFallSpeed: number;
-  };
-  readonly controller: {
-    readonly grounded: boolean;
-    readonly coyoteJumpAccepted: boolean;
-    readonly bufferedJumpAccepted: boolean;
-    readonly doubleJumpAccepted: boolean;
-    readonly wallJumpAccepted: boolean;
-    readonly horizontalSpeed: number;
-    readonly verticalVelocity: number;
-    readonly stateSequence: readonly PlatformerAnimationState[];
-    readonly finalState: PlatformerAnimationState;
-  };
-  readonly camera: {
-    readonly distance: number;
-    readonly minDistance: number;
-    readonly maxDistance: number;
-    readonly height: number;
-    readonly followSpeed: number;
-    readonly verticalAngle: number;
-    readonly collisionAdjustedDistance: number;
-    readonly shakeAmount: number;
-    readonly lockOnSupported: boolean;
-  };
-  readonly level: {
-    readonly startPosition: readonly [number, number, number];
-    readonly goalPosition: readonly [number, number, number];
-    readonly platformSummaries: readonly PlatformerPlatformSummary[];
-    readonly collectibleSummaries: readonly PlatformerCollectibleSummary[];
-    readonly checkpointCount: number;
-    readonly hazardCount: number;
-    readonly movingPlatformPathCount: number;
-    readonly totalPlatforms: number;
-    readonly totalCollectibles: number;
-    readonly totalScoreValue: number;
-    readonly goalDistance: number;
-  };
-  readonly hash: string;
-  readonly claimBoundary: string;
-}
-
-const platformSummaries: readonly PlatformerPlatformSummary[] = [
-  { kind: "static", count: 6 },
-  { kind: "moving", count: 1 },
-  { kind: "rotating", count: 1 },
-  { kind: "falling", count: 3 },
-  { kind: "bouncy", count: 1 },
-  { kind: "disappearing", count: 2 }
-];
-
-const collectibleSummaries: readonly PlatformerCollectibleSummary[] = [
-  { kind: "coin", count: 5, scoreValue: 100 },
-  { kind: "gem", count: 2, scoreValue: 500 },
-  { kind: "power-up", count: 1, scoreValue: 1000 }
-];
-
-export function samplePlatformerControllerFixture(options: PlatformerFixtureOptions = {}): PlatformerControllerFixture {
-  const seed = integer(options.seed ?? 0x3d2025, "seed");
-  const elapsedSeconds = finiteNonNegative(options.elapsedSeconds ?? 0.32, "elapsedSeconds");
-  const coyoteTimeSeconds = 0.15;
-  const jumpBufferSeconds = 0.1;
-  const timeSinceGrounded = 0.08 + hash01(seed, 1) * 0.03;
-  const timeSinceJumpPressed = 0.04 + hash01(seed, 2) * 0.02;
-  const coyoteJumpAccepted = timeSinceGrounded <= coyoteTimeSeconds;
-  const bufferedJumpAccepted = timeSinceJumpPressed <= jumpBufferSeconds;
-  const doubleJumpAccepted = coyoteJumpAccepted && bufferedJumpAccepted;
-  const wallJumpAccepted = hash01(seed, 3) > 0.25;
-  const horizontalSpeed = Number((5 + hash01(seed, 4) * 3).toFixed(4));
-  const verticalVelocity = Number((12 - elapsedSeconds * 9.8).toFixed(4));
-  const stateSequence: readonly PlatformerAnimationState[] = [
-    "idle",
-    horizontalSpeed > 6.5 ? "run" : "walk",
-    "jump",
-    doubleJumpAccepted ? "doubleJump" : "fall",
-    wallJumpAccepted ? "wallSlide" : "fall",
-    "land"
-  ];
-  const totalPlatforms = platformSummaries.reduce((sum, entry) => sum + entry.count, 0);
-  const totalCollectibles = collectibleSummaries.reduce((sum, entry) => sum + entry.count, 0);
-  const totalScoreValue = collectibleSummaries.reduce((sum, entry) => sum + entry.count * entry.scoreValue, 0);
-  const startPosition = [0, 2, 0] as const;
-  const goalPosition = [56, 9, 0] as const;
-  const goalDistance = Number(Math.hypot(goalPosition[0] - startPosition[0], goalPosition[1] - startPosition[1], goalPosition[2] - startPosition[2]).toFixed(4));
-  return {
-    id: "external-parity-old-branch-platformer-controller-fixture",
-    source: "origin-master-platformer-controller-adapted",
-    config: {
-      walkSpeed: 5,
-      runSpeed: 8,
-      jumpForce: 12,
-      doubleJumpForce: 10,
-      wallJumpForce: 14,
-      airControl: 0.3,
-      coyoteTimeSeconds,
-      jumpBufferSeconds,
-      maxFallSpeed: 30
-    },
-    controller: {
-      grounded: false,
-      coyoteJumpAccepted,
-      bufferedJumpAccepted,
-      doubleJumpAccepted,
-      wallJumpAccepted,
-      horizontalSpeed,
-      verticalVelocity,
-      stateSequence,
-      finalState: "land"
-    },
-    camera: {
-      distance: 8,
-      minDistance: 3,
-      maxDistance: 15,
-      height: 2,
-      followSpeed: 8,
-      verticalAngle: Number((0.3 + hash01(seed, 5) * 0.1).toFixed(4)),
-      collisionAdjustedDistance: Number((8 - hash01(seed, 6) * 1.5).toFixed(4)),
-      shakeAmount: Number((0.18 * Math.pow(0.95, elapsedSeconds * 60)).toFixed(4)),
-      lockOnSupported: true
-    },
-    level: {
-      startPosition,
-      goalPosition,
-      platformSummaries,
-      collectibleSummaries,
-      checkpointCount: 2,
-      hazardCount: 3,
-      movingPlatformPathCount: 2,
-      totalPlatforms,
-      totalCollectibles,
-      totalScoreValue,
-      goalDistance
-    },
-    hash: hashPlatformer(seed, elapsedSeconds, horizontalSpeed, verticalVelocity, totalPlatforms, totalCollectibles, goalDistance),
-    claimBoundary: "Deterministic platformer controller, third-person camera, and level-layout telemetry adapted from the old platformer example; this is not a full character controller replacement, collision solver, camera occlusion system, or Unity/Unreal controller parity claim."
-  };
-}
-
-function hashPlatformer(...values: readonly number[]): string {
-  let hash = 0x811c9dc5;
-  for (const value of values) {
-    const scaled = Math.round(value * 10_000);
-    hash ^= scaled & 0xff;
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-    hash ^= (scaled >>> 8) & 0xff;
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, "0");
-}
-
-function hash01(seed: number, salt: number): number {
-  let value = Math.imul(seed + salt * 1013904223, 1664525) + 1013904223;
-  value = Math.imul(value ^ (value >>> 13), 1274126177);
-  return ((value ^ (value >>> 16)) >>> 0) / 4294967296;
-}
-
-function finiteNonNegative(value: number, label: string): number {
-  if (!Number.isFinite(value) || value < 0) throw new RangeError(`Platformer fixture ${label} must be finite and non-negative.`);
-  return value;
-}
-
-function integer(value: number, label: string): number {
-  if (!Number.isInteger(value)) throw new RangeError(`Platformer fixture ${label} must be an integer.`);
-  return value;
-}

package/src/Raycast.ts

@@ -1,345 +0,0 @@
-import { addVec3, dotVec3, scaleVec3, subVec3, type Vec3 } from "./Shape.js";
-import type { Collider } from "./Collider.js";
-import type { RigidBody } from "./RigidBody.js";
-
-export type RaycastOptions = {
-  readonly maxDistance?: number;
-  readonly mask?: number;
-  readonly includeSensors?: boolean;
-  readonly includeBackfaces?: boolean;
-};
-
-export type RaycastHit = {
-  readonly colliderId: number;
-  readonly bodyId: number;
-  readonly point: Vec3;
-  readonly normal: Vec3;
-  readonly distance: number;
-};
-
-export type SphereCastHit = RaycastHit & {
-  readonly castCenter: Vec3;
-  readonly castRadius: number;
-};
-
-/** Ground query result consumed by the animation foot-IK rig (matches its `GroundSample` shape). */
-export type GroundHeightSample = {
-  readonly point: Vec3;
-  readonly normal: Vec3;
-  readonly distance: number;
-};
-
-/** Structural downward-ground query the `@aura3d/animation` foot-IK rig accepts. */
-export type GroundHeightRaycaster = {
-  raycastDown(origin: Vec3, maxDistance: number): GroundHeightSample | undefined;
-};
-
-/**
- * Adapt any downward raycast into the ground query the foot-IK rig needs. `cast` should perform a
- * straight-down ray (typically a `PhysicsWorld.raycast` bound to a ground layer mask) and return
- * the first hit. This is a thin adapter, not a new solver — it just casts `[0,-1,0]` from the
- * given origin and reports the hit point/normal/distance.
- */
-export function groundHeightRaycaster(
-  cast: (origin: Vec3, direction: Vec3, maxDistance: number) => RaycastHit | undefined
-): GroundHeightRaycaster {
-  return {
-    raycastDown(origin: Vec3, maxDistance: number): GroundHeightSample | undefined {
-      const hit = cast(origin, [0, -1, 0], maxDistance);
-      if (!hit) return undefined;
-      return { point: hit.point, normal: hit.normal, distance: hit.distance };
-    }
-  };
-}
-
-export function raycastCollider(origin: Vec3, direction: Vec3, collider: Collider, body: RigidBody, options: RaycastOptions = {}): RaycastHit | undefined {
-  const maxDistance = options.maxDistance ?? Number.POSITIVE_INFINITY;
-  if (collider.sensor && options.includeSensors !== true) {
-    return undefined;
-  }
-  if (options.mask !== undefined && (collider.filter.layer & options.mask) === 0) {
-    return undefined;
-  }
-  switch (collider.shape.kind) {
-    case "sphere":
-      return raycastSphere(origin, direction, body.position, collider.shape.radius, collider, maxDistance);
-    case "box":
-    case "capsule":
-      return raycastAabb(origin, direction, collider.bounds(body.position), collider, body.id, maxDistance);
-    case "plane":
-      return raycastPlane(origin, direction, collider.shape.normal, collider.shape.constant, collider, body.id, maxDistance);
-    case "mesh":
-      return raycastMesh(origin, direction, collider, body, maxDistance, options.includeBackfaces === true);
-  }
-}
-
-export function sphereCastCollider(origin: Vec3, radius: number, direction: Vec3, collider: Collider, body: RigidBody, options: RaycastOptions = {}): SphereCastHit | undefined {
-  if (!Number.isFinite(radius) || radius <= 0) {
-    throw new Error("sphereCast radius must be a finite positive number.");
-  }
-  const maxDistance = options.maxDistance ?? Number.POSITIVE_INFINITY;
-  if (collider.sensor && options.includeSensors !== true) {
-    return undefined;
-  }
-  if (options.mask !== undefined && (collider.filter.layer & options.mask) === 0) {
-    return undefined;
-  }
-  switch (collider.shape.kind) {
-    case "sphere":
-      return sphereCastSphere(origin, radius, direction, body.position, collider.shape.radius, collider, maxDistance);
-    case "box":
-    case "capsule": {
-      const bounds = collider.bounds(body.position);
-      const expanded = {
-        min: [bounds.min[0] - radius, bounds.min[1] - radius, bounds.min[2] - radius] as Vec3,
-        max: [bounds.max[0] + radius, bounds.max[1] + radius, bounds.max[2] + radius] as Vec3
-      };
-      const hit = raycastAabb(origin, direction, expanded, collider, body.id, maxDistance);
-      return hit ? toSphereCastHit(hit, origin, direction, radius) : undefined;
-    }
-    case "plane":
-      return sphereCastPlane(origin, radius, direction, collider.shape.normal, collider.shape.constant, body.position, collider, body.id, maxDistance);
-    case "mesh": {
-      const hit = raycastMesh(origin, direction, collider, body, maxDistance, options.includeBackfaces === true);
-      return hit ? toSphereCastHit(hit, origin, direction, radius) : undefined;
-    }
-  }
-}
-
-function raycastSphere(origin: Vec3, direction: Vec3, center: Vec3, radius: number, collider: Collider, maxDistance: number): RaycastHit | undefined {
-  const oc = subVec3(origin, center);
-  const b = dotVec3(oc, direction);
-  const c = dotVec3(oc, oc) - radius * radius;
-  const discriminant = b * b - c;
-  if (discriminant < 0) {
-    return undefined;
-  }
-  const sqrt = Math.sqrt(discriminant);
-  const insideDistance = c <= 0 ? 0 : undefined;
-  const distance = insideDistance ?? -b - sqrt;
-  if (distance < 0 || distance > maxDistance) {
-    return undefined;
-  }
-  const point = [origin[0] + direction[0] * distance, origin[1] + direction[1] * distance, origin[2] + direction[2] * distance] as Vec3;
-  const normal = c <= 0 ? scaleVec3(direction, -1) : scaleVec3(subVec3(point, center), 1 / radius);
-  return { colliderId: collider.id, bodyId: collider.bodyId, point, normal, distance };
-}
-
-function sphereCastSphere(origin: Vec3, castRadius: number, direction: Vec3, center: Vec3, targetRadius: number, collider: Collider, maxDistance: number): SphereCastHit | undefined {
-  const expandedRadius = castRadius + targetRadius;
-  const expandedHit = raycastSphere(origin, direction, center, expandedRadius, collider, maxDistance);
-  if (!expandedHit) {
-    return undefined;
-  }
-  const castCenter = pointAlongRay(origin, direction, expandedHit.distance);
-  const normal = expandedHit.distance === 0
-    ? scaleVec3(direction, -1)
-    : stableVec3(scaleVec3(subVec3(castCenter, center), 1 / Math.max(1e-9, Math.hypot(castCenter[0] - center[0], castCenter[1] - center[1], castCenter[2] - center[2]))));
-  return {
-    colliderId: collider.id,
-    bodyId: collider.bodyId,
-    point: stableVec3(subVec3(castCenter, scaleVec3(normal, castRadius))),
-    normal,
-    distance: expandedHit.distance,
-    castCenter,
-    castRadius
-  };
-}
-
-function raycastAabb(origin: Vec3, direction: Vec3, bounds: { readonly min: Vec3; readonly max: Vec3 }, collider: Collider, bodyId: number, maxDistance: number): RaycastHit | undefined {
-  let tmin = 0;
-  let tmax = maxDistance;
-  let axis = 0;
-  let sign = -1;
-  const originInside = pointInsideAabb(origin, bounds);
-  for (let i = 0; i < 3; i += 1) {
-    const ray = direction[i]!;
-    if (Math.abs(ray) < 1e-9) {
-      if (origin[i]! < bounds.min[i]! || origin[i]! > bounds.max[i]!) {
-        return undefined;
-      }
-      continue;
-    }
-    const inv = 1 / ray;
-    let t1 = (bounds.min[i]! - origin[i]!) * inv;
-    let t2 = (bounds.max[i]! - origin[i]!) * inv;
-    let localSign = -Math.sign(ray);
-    if (t1 > t2) {
-      const temp = t1;
-      t1 = t2;
-      t2 = temp;
-      localSign = Math.sign(ray);
-    }
-    if (t1 > tmin) {
-      tmin = t1;
-      axis = i;
-      sign = localSign;
-    }
-    tmax = Math.min(tmax, t2);
-    if (tmin > tmax) {
-      return undefined;
-    }
-  }
-  const point = [origin[0] + direction[0] * tmin, origin[1] + direction[1] * tmin, origin[2] + direction[2] * tmin] as Vec3;
-  const normal: [number, number, number] = [0, 0, 0];
-  if (originInside && tmin === 0) {
-    normal[dominantAxis(direction)] = -Math.sign(direction[dominantAxis(direction)] || 1);
-  } else {
-    normal[axis] = sign;
-  }
-  return { colliderId: collider.id, bodyId, point, normal, distance: tmin };
-}
-
-function raycastPlane(origin: Vec3, direction: Vec3, normal: Vec3, constant: number, collider: Collider, bodyId: number, maxDistance: number): RaycastHit | undefined {
-  const denom = dotVec3(normal, direction);
-  if (Math.abs(denom) < 1e-9) {
-    return undefined;
-  }
-  const distance = -(dotVec3(normal, origin) + constant) / denom;
-  if (distance < 0 || distance > maxDistance) {
-    return undefined;
-  }
-  const point = [origin[0] + direction[0] * distance, origin[1] + direction[1] * distance, origin[2] + direction[2] * distance] as Vec3;
-  return { colliderId: collider.id, bodyId, point, normal, distance };
-}
-
-function sphereCastPlane(origin: Vec3, radius: number, direction: Vec3, normal: Vec3, constant: number, planePosition: Vec3, collider: Collider, bodyId: number, maxDistance: number): SphereCastHit | undefined {
-  const signedDistance = dotVec3(normal, origin) + constant + dotVec3(normal, planePosition);
-  if (signedDistance <= radius) {
-    const castCenter = origin;
-    return {
-      colliderId: collider.id,
-      bodyId,
-      point: stableVec3(subVec3(castCenter, scaleVec3(normal, radius))),
-      normal,
-      distance: 0,
-      castCenter,
-      castRadius: radius
-    };
-  }
-  const denom = dotVec3(normal, direction);
-  if (denom >= -1e-9) {
-    return undefined;
-  }
-  const distance = (radius - signedDistance) / denom;
-  if (distance < 0 || distance > maxDistance) {
-    return undefined;
-  }
-  const castCenter = pointAlongRay(origin, direction, distance);
-  return {
-    colliderId: collider.id,
-    bodyId,
-    point: stableVec3(subVec3(castCenter, scaleVec3(normal, radius))),
-    normal,
-    distance,
-    castCenter,
-    castRadius: radius
-  };
-}
-
-function raycastMesh(origin: Vec3, direction: Vec3, collider: Collider, body: RigidBody, maxDistance: number, includeBackfaces: boolean): RaycastHit | undefined {
-  if (collider.shape.kind !== "mesh") {
-    return undefined;
-  }
-  let closest: RaycastHit | undefined;
-  const { vertices, indices } = collider.shape;
-  for (let index = 0; index < indices.length; index += 3) {
-    const a = addVec3(body.position, vertices[indices[index]!]!);
-    const b = addVec3(body.position, vertices[indices[index + 1]!]!);
-    const c = addVec3(body.position, vertices[indices[index + 2]!]!);
-    const hit = raycastTriangle(origin, direction, a, b, c, collider, body.id, maxDistance, includeBackfaces);
-    if (hit && (!closest || hit.distance < closest.distance)) {
-      closest = hit;
-    }
-  }
-  return closest;
-}
-
-function raycastTriangle(
-  origin: Vec3,
-  direction: Vec3,
-  a: Vec3,
-  b: Vec3,
-  c: Vec3,
-  collider: Collider,
-  bodyId: number,
-  maxDistance: number,
-  includeBackfaces: boolean
-): RaycastHit | undefined {
-  const edge1 = subVec3(b, a);
-  const edge2 = subVec3(c, a);
-  const p = crossVec3(direction, edge2);
-  const det = dotVec3(edge1, p);
-  if (includeBackfaces ? Math.abs(det) < 1e-9 : det < 1e-9) {
-    return undefined;
-  }
-  const invDet = 1 / det;
-  const t = subVec3(origin, a);
-  const u = dotVec3(t, p) * invDet;
-  if (u < 0 || u > 1) {
-    return undefined;
-  }
-  const q = crossVec3(t, edge1);
-  const v = dotVec3(direction, q) * invDet;
-  if (v < 0 || u + v > 1) {
-    return undefined;
-  }
-  const distance = dotVec3(edge2, q) * invDet;
-  if (distance < 0 || distance > maxDistance) {
-    return undefined;
-  }
-  const normal = normalizeForRay(crossVec3(edge1, edge2), direction);
-  const point = [origin[0] + direction[0] * distance, origin[1] + direction[1] * distance, origin[2] + direction[2] * distance] as Vec3;
-  return { colliderId: collider.id, bodyId, point, normal, distance };
-}
-
-function crossVec3(a: Vec3, b: Vec3): [number, number, number] {
-  return [
-    a[1] * b[2] - a[2] * b[1],
-    a[2] * b[0] - a[0] * b[2],
-    a[0] * b[1] - a[1] * b[0]
-  ];
-}
-
-function normalizeForRay(normal: Vec3, direction: Vec3): Vec3 {
-  const length = Math.hypot(normal[0], normal[1], normal[2]);
-  const normalized = length <= 1e-9 ? [0, 1, 0] as Vec3 : stableVec3(scaleVec3(normal, 1 / length));
-  return dotVec3(normalized, direction) > 0 ? stableVec3(scaleVec3(normalized, -1)) : normalized;
-}
-
-function pointAlongRay(origin: Vec3, direction: Vec3, distance: number): Vec3 {
-  return [
-    origin[0] + direction[0] * distance,
-    origin[1] + direction[1] * distance,
-    origin[2] + direction[2] * distance
-  ];
-}
-
-function pointInsideAabb(point: Vec3, bounds: { readonly min: Vec3; readonly max: Vec3 }): boolean {
-  return point[0] >= bounds.min[0] && point[0] <= bounds.max[0] &&
-    point[1] >= bounds.min[1] && point[1] <= bounds.max[1] &&
-    point[2] >= bounds.min[2] && point[2] <= bounds.max[2];
-}
-
-function dominantAxis(direction: Vec3): 0 | 1 | 2 {
-  const ax = Math.abs(direction[0]);
-  const ay = Math.abs(direction[1]);
-  const az = Math.abs(direction[2]);
-  if (ay >= ax && ay >= az) return 1;
-  if (az >= ax && az >= ay) return 2;
-  return 0;
-}
-
-function toSphereCastHit(hit: RaycastHit, origin: Vec3, direction: Vec3, radius: number): SphereCastHit {
-  const castCenter = pointAlongRay(origin, direction, hit.distance);
-  return {
-    ...hit,
-    point: stableVec3(subVec3(castCenter, scaleVec3(hit.normal, radius))),
-    castCenter,
-    castRadius: radius
-  };
-}
-
-function stableVec3(value: Vec3): Vec3 {
-  return value.map((component) => Object.is(component, -0) ? 0 : component) as unknown as Vec3;
-}