@volter/threejs-runtime 0.5.65

package/src/ecs/scene-query.ts

@@ -0,0 +1,43 @@
+import type * as THREE from 'three';
+import { getUserData } from './user-data';
+
+/**
+ * Runtime queries over a loaded THREE scene graph (P1.6d).
+ *
+ * These helpers walk a THREE.Object3D graph and read entity metadata off
+ * `userData`, so gameplay code can find objects by tag or name without
+ * bookkeeping its own indexes.
+ *
+ * Canonical metadata locations:
+ *   - tags:       `userData['tags']` (string[])
+ *   - name:       `Object3D.name`
+ *
+ * These are one-shot walks that notify nobody. For a repeated query, or for a
+ * signal when the answer changes, use the LIVE index instead —
+ * `ctx.sceneIndex` (`./scene-index.ts`): it reads the same `userData['tags']`
+ * storage, answers without traversing, and dispatches `entityadded`/
+ * `entityremoved`/`tagadded`/`tagremoved` on an `EventTarget`.
+ */
+
+function getTags(obj: THREE.Object3D): string[] {
+  const direct = getUserData(obj, 'tags');
+  return Array.isArray(direct) ? direct : [];
+}
+
+/** All objects in the graph carrying the given tag (depth-first, document order). */
+export function queryByTag(root: THREE.Object3D, tag: string): THREE.Object3D[] {
+  const matches: THREE.Object3D[] = [];
+  root.traverse((obj) => {
+    if (getTags(obj).includes(tag)) matches.push(obj);
+  });
+  return matches;
+}
+
+/** All objects in the graph with the given name (depth-first, document order). */
+export function queryByName(root: THREE.Object3D, name: string): THREE.Object3D[] {
+  const matches: THREE.Object3D[] = [];
+  root.traverse((obj) => {
+    if (obj.name === name) matches.push(obj);
+  });
+  return matches;
+}

package/src/ecs/user-data.ts

@@ -0,0 +1,272 @@
+/**
+ * Typed registry for `Object3D.userData` keys used by the engine and editor.
+ *
+ * Three.js lets any code stash arbitrary values on `object.userData`, and over
+ * time the engine + editor accumulated ~20 stringly-typed keys that together
+ * form a *parallel object model* — meaning carried entirely in undocumented
+ * string literals. This module is the ONE documented place that lists every
+ * such key, its value type, and what it means. All engine/editor-internal
+ * `userData` access for these keys must go through {@link getUserData} /
+ * {@link setUserData} / {@link hasUserData} / {@link deleteUserData} so the key
+ * strings live in exactly one place and are type-checked at every call site.
+ * Structural readers may use the narrow `object-marks` accessors instead;
+ * this registry includes that module's canonical keys and value schema.
+ *
+ * NOTE: This covers engine/editor *internal* keys only. User game code in the
+ * example template may stash its own ad-hoc keys; those are out of scope.
+ *
+ * ## Key reference
+ *
+ * Serialization / identity (load-bearing — editor identity):
+ * - `entityId`            — the entity's stable string id. Presence also marks an
+ *                           Object3D as a "real" entity (vs editor helper/env object).
+ *
+ * Runtime scene-query metadata (read by `scene-query.ts` and `scene-index.ts`):
+ * - `tags`                — string[] tags for `queryByTag` and the live index.
+ * - `attributes`          — per-object `Record<string, string|number|boolean>`
+ *                           of game-defined attributes (P2 `observe`). Written
+ *                           through `SceneIndex.setAttribute`, which emits an
+ *                           `attributechanged` signal; JSON-simple values only,
+ *                           so an attribute survives serialization unchanged.
+ *
+ * Runtime gameplay metadata:
+ * - `forward`             — `[x,y,z]` model-space visual forward exported as
+ *                           ordinary glTF extras for asset-facing validation.
+ * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
+ * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
+ * - `splineCurve`         — resolved THREE curve for a spline-following object.
+ * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
+ * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
+ * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
+ *                           inspector facts, bounds, and deterministic disposal.
+ *
+ * Animation (load-bearing — ED5 disposal contract):
+ * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
+ * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF (E5 —
+ *                           lets game code build its own XState-driven
+ *                           binding via `bindXStateAnimation` over the SAME
+ *                           mixer; see xstate-animation-binding.ts).
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF
+ *                           (inspector dropdown; same names as `_animClips`' keys).
+ * - `_animationRuntime`   — format-neutral live native mixer/action inspection.
+ * - `_xstateBehavior`     — optional live XState behavior actor inspection.
+ * - `_xstateAnimation`    — compatibility handle for the optional XState→Three
+ *                           bridge; animation UI never discovers through it.
+ *
+ * Disposal contract:
+ * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
+ *                           NOT be disposed by per-object cleanup (P0.2 contract).
+ *
+ * Editor shading overrides (editor-only, see `scene-sync.ts`):
+ * - `__shadeOrig`         — original material(s) stashed before a shading override.
+ * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
+ *
+ * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
+ * - `__ingest`            — `true` on every Object3D minted by ingestion; routes
+ *                           edits to live mutation.
+ * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
+ *                           root so re-reflects keep minting unique ids.
+ *
+ * Editor scene-graph tagging (editor-only):
+ * - `engineInternal`      — `true` on engine-owned infrastructure in the game scene
+ *                           (particle BatchedRenderer, debug-draw + its subtree).
+ *                           The editor's play-mode hierarchy skips these so they
+ *                           don't show up as selectable "entities".
+ * - `authoringRoot`       — explicit opt-in for a runtime descendant to become
+ *                           its own authoring object instead of a part of the
+ *                           nearest ancestor owner.
+ * - `authoringInstance`   — source OID of the custom-component callsite that
+ *                           rendered this existing Object3D. Used to group
+ *                           implementation parts without adding wrappers.
+ * - `authoringLabel`      — authored literal name (or component tag fallback)
+ *                           for that source-backed component instance.
+ * - `authoringComponent`  — exact source component identity for portable-CSF
+ *                           association; unlike the label, never user-facing copy.
+ * - `authoringDocument`   — generic reference to the project-tool document
+ *                           that owns this scene instance's authored asset.
+ * - `authoringHierarchyId`, `authoringHierarchyParentId`,
+ *   `authoringHierarchyOrder` — source-owned semantic identity, parent identity,
+ *                           and sibling ordinal shared across native surfaces.
+ * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ *
+ * Hierarchy-presentation convention (written by GAME code, read by the editor —
+ * see `../adapter/hierarchy-marks.ts`, which is the ONLY place these two are
+ * read/written from; the `vgai` prefix marks them as the HOST's namespace on a
+ * node a game owns, unlike every other key above, which the engine/editor also
+ * write):
+ * - `vgaiComponentRoot`   — display name of the component instance this subtree
+ *                           IS. The node renders as one collapsed, expandable
+ *                           row named for it.
+ * - `vgaiBuiltInternal`   — `true` on the ROOT of a subtree runtime code
+ *                           CONSTRUCTED rather than authored (skeleton bones,
+ *                           particle renderers). Subtree-scoped: everything
+ *                           below a marked node is built-internal too.
+ * - `vgaiBodyOwner`       — the rigid body that OWNS this node's pose, written
+ *                           by the code that attaches the body (see
+ *                           `../adapter/body-marks.ts`, the only reader/writer).
+ *                           A transform edit on such a node must be applied to
+ *                           the BODY, or the next physics step writes the node
+ *                           straight back.
+ * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
+ * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
+ * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
+ * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `reflectionProbe`     — live project-owned reflection probe projected from
+ *                           JSX props for renderer/editor integration.
+ * - `triggerVolume`       — plain `{ radius }` a GAME writes on the node that IS
+ *                           a trigger volume, so the editor can draw its ring
+ *                           (see `../adapter/trigger-volume.ts`).
+ * - `constraints`         — live project-owned spatial constraints projected
+ *                           into the shared Inspector and viewport.
+ * - `authoringSubject`    — transient identity/inspection for an ecosystem-native
+ *                           subject represented by an Object3D proxy.
+ * - `splineControlPoint`  — index of a spline control-point drag handle.
+ * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
+ */
+
+import type * as THREE from 'three';
+import type { ParticleSystem } from 'three.quarks';
+import type { ConstraintMark } from '../adapter/constraint';
+import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
+import type { RapierEditableBody } from '../adapter/rapier-physics-adapter';
+import type { ReflectionProbeMark } from '../adapter/reflection-probe';
+import type { TriggerVolumeMark } from '../adapter/trigger-volume';
+import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
+import type { XStateAnimationBinding } from '../animation/xstate-animation-binding';
+import type { XStateBehaviorInspection } from '../behavior/xstate-inspection';
+import { ObjectMarkKeys, type ObjectMarkSchema } from './object-marks';
+
+export type { EditorHelperType } from './object-marks';
+
+/**
+ * Maps each canonical accessor name to its value type. This is the single
+ * source of truth for what every known `userData` key holds.
+ */
+export interface UserDataSchema extends ObjectMarkSchema {
+  entityId: string;
+  forward: [number, number, number];
+  tags: string[];
+  attributes: Record<string, string | number | boolean>;
+  navRole: 'walkable' | 'obstacle';
+  pivot: [number, number, number];
+  splineCurve: THREE.Curve<THREE.Vector3>;
+  splineControlPoint: number;
+  _camera: THREE.Camera;
+  _particleSystem: ParticleSystem;
+  gaussianSplat: { src: string; numSplats: number };
+  _animMixer: THREE.AnimationMixer;
+  _animClips: Map<string, THREE.AnimationClip>;
+  _availableClips: string[];
+  _animationRuntime: AnimationRuntimeInspection;
+  _xstateBehavior: XStateBehaviorInspection;
+  _xstateAnimation: XStateAnimationBinding;
+  __sharedGeometry: boolean;
+  __shadeOrig: THREE.Material | THREE.Material[];
+  __shadeUnlit: THREE.Material[];
+  __ingest: boolean;
+  __ingestNextId: number;
+  authoringRoot: boolean;
+  authoringInstance: string;
+  authoringLabel: string;
+  vgaiBodyOwner: RapierEditableBody;
+  authoringComponent: string;
+  authoringDocument: {
+    readonly kind: 'project-tool';
+    readonly name: string;
+    readonly title: string;
+  };
+  /** Project-owned identity used to join authored hierarchy rows across adapter roots. */
+  authoringHierarchyId: string;
+  /** Project-owned parent identity when the authored parent can live on another surface. */
+  authoringHierarchyParentId: string;
+  /** Source-owned sibling ordinal used when hierarchy rows cross native roots. */
+  authoringHierarchyOrder: number;
+  editorIcon: boolean;
+  envObject: boolean;
+  constraints: readonly ConstraintMark[];
+  authoringSubject: Object3DAuthoringSubjectMark;
+  reflectionProbe: ReflectionProbeMark;
+  triggerVolume: TriggerVolumeMark;
+  vcDirIdx: number;
+}
+
+/** Any key in the typed registry. */
+export type UserDataKey = keyof UserDataSchema;
+
+/**
+ * Canonical name → literal `userData` string key. The accessor names match the
+ * raw string keys 1:1 (this is the documented set referenced by the AC), so the
+ * literal strings are owned here or by the included structural mark registry.
+ */
+export const UserDataKeys = {
+  ...ObjectMarkKeys,
+  entityId: 'entityId',
+  forward: 'forward',
+  tags: 'tags',
+  attributes: 'attributes',
+  navRole: 'navRole',
+  pivot: 'pivot',
+  splineCurve: 'splineCurve',
+  splineControlPoint: 'splineControlPoint',
+  _camera: '_camera',
+  _particleSystem: '_particleSystem',
+  gaussianSplat: 'gaussianSplat',
+  _animMixer: '_animMixer',
+  _animClips: '_animClips',
+  _availableClips: '_availableClips',
+  _animationRuntime: '_animationRuntime',
+  _xstateBehavior: '_xstateBehavior',
+  _xstateAnimation: '_xstateAnimation',
+  __sharedGeometry: '__sharedGeometry',
+  __shadeOrig: '__shadeOrig',
+  __shadeUnlit: '__shadeUnlit',
+  __ingest: '__ingest',
+  __ingestNextId: '__ingestNextId',
+  authoringRoot: 'authoringRoot',
+  authoringInstance: 'authoringInstance',
+  authoringLabel: 'authoringLabel',
+  vgaiBodyOwner: 'vgaiBodyOwner',
+  authoringComponent: 'authoringComponent',
+  authoringDocument: 'authoringDocument',
+  authoringHierarchyId: 'authoringHierarchyId',
+  authoringHierarchyParentId: 'authoringHierarchyParentId',
+  authoringHierarchyOrder: 'authoringHierarchyOrder',
+  editorIcon: 'editorIcon',
+  envObject: 'envObject',
+  constraints: 'constraints',
+  authoringSubject: 'authoringSubject',
+  reflectionProbe: 'reflectionProbe',
+  triggerVolume: 'triggerVolume',
+  vcDirIdx: 'vcDirIdx',
+} as const satisfies Record<UserDataKey, string>;
+
+/**
+ * Read a typed `userData` value. Returns `undefined` when the key is unset or
+ * when `obj` is nullish (so call sites can pass an optionally-resolved object).
+ */
+export function getUserData<K extends UserDataKey>(
+  obj: THREE.Object3D | null | undefined,
+  key: K,
+): UserDataSchema[K] | undefined {
+  return obj ? (obj.userData[UserDataKeys[key]] as UserDataSchema[K] | undefined) : undefined;
+}
+
+/** Write a typed `userData` value. */
+export function setUserData<K extends UserDataKey>(
+  obj: THREE.Object3D,
+  key: K,
+  value: UserDataSchema[K],
+): void {
+  obj.userData[UserDataKeys[key]] = value;
+}
+
+/** True when `key` is set (not `undefined`) on the object's `userData`. */
+export function hasUserData(obj: THREE.Object3D | null | undefined, key: UserDataKey): boolean {
+  return obj ? obj.userData[UserDataKeys[key]] !== undefined : false;
+}
+
+/** Remove a `userData` key. */
+export function deleteUserData(obj: THREE.Object3D, key: UserDataKey): void {
+  delete obj.userData[UserDataKeys[key]];
+}

package/src/loader.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared asset loading infrastructure.
+ *
+ * Provides a single LoadingManager (for Three.js loaders) and resolveUrl()
+ * (for raw fetch calls) so that all engine asset requests go through one
+ * configurable URL prefix. Call setAssetPrefix() once at runtime startup.
+ *
+ * Three.js loaders constructed with `loadingManager` automatically rewrite
+ * URLs via setURLModifier(). For raw fetch() calls, wrap the URL with
+ * resolveUrl() to apply the same prefix.
+ */
+
+import * as THREE from 'three';
+import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+
+let _prefix = '/';
+
+function rewriteUrl(url: string): string {
+  if (
+    url.startsWith('/') ||
+    url.startsWith('http') ||
+    url.startsWith('data:') ||
+    url.startsWith('blob:')
+  ) {
+    return url;
+  }
+  return _prefix + url;
+}
+
+/** Shared Three.js LoadingManager — all engine loaders should use this. */
+export const loadingManager = new THREE.LoadingManager();
+loadingManager.setURLModifier(rewriteUrl);
+
+/** Pre-configured TextureLoader using the shared manager. */
+export const textureLoader = new THREE.TextureLoader(loadingManager);
+
+/**
+ * Shared DRACOLoader for decoding DRACO-compressed GLTF/GLB meshes.
+ *
+ * The decoder wasm/js is vendored under
+ * packages/editor/template/public/jsm/libs/draco/gltf/ and served at the
+ * absolute runtime path '/jsm/libs/draco/gltf/' (DRACOLoader appends
+ * draco_wasm_wrapper.js / draco_decoder.wasm to this path). This is an
+ * absolute path, so it deliberately does NOT go through the asset prefix —
+ * the decoder is engine infrastructure, not a scene asset.
+ */
+export const dracoLoader = new DRACOLoader(loadingManager);
+dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
+
+/**
+ * Shared KTX2Loader for decoding KHR_texture_basisu (KTX2/Basis) textures.
+ *
+ * Vendored and served EXACTLY like the DRACO decoder above — the Basis
+ * transcoder js/wasm live in repo-root `public/jsm/libs/basis/` (the editor)
+ * and `packages/editor/template/public/jsm/libs/basis/` (a scaffolded game's
+ * own build), pinned in `vendor/upstream-assets.lock.json`, and KTX2Loader
+ * appends `basis_transcoder.js` / `.wasm` to this absolute path.
+ *
+ * Without this wiring, the Asset Budget's "Compress textures · KTX2" output
+ * is a GLB nothing in the engine can load — which is why the op and this
+ * loader landed together.
+ */
+export const ktx2Loader = new KTX2Loader(loadingManager);
+ktx2Loader.setTranscoderPath('/jsm/libs/basis/');
+
+let ktx2SupportDetected = false;
+
+/**
+ * Teach the shared KTX2Loader which compressed formats THIS GPU accepts.
+ *
+ * KTX2Loader refuses to transcode until it has seen a renderer, and the
+ * answer is a property of the page's GPU rather than of any one renderer —
+ * so the FIRST renderer to exist supplies it and every later one is a no-op.
+ * Called by the engine's own renderer setup (`setup/setup-renderer.ts`) and
+ * by the editor's viewport, which between them cover every surface that
+ * parses a GLB.
+ *
+ * This sits on the MOUNT path, so it must never throw for a renderer it
+ * cannot question. `detectSupport` reads `renderer.extensions.has/get` (or
+ * `renderer.hasFeature` on a WebGPU renderer) — surface a headless stand-in
+ * (the test harnesses' fake renderers, any non-WebGL host) does not have.
+ * Such a renderer is skipped WITHOUT latching, so the first renderer that
+ * can actually answer still configures the loader for the whole page.
+ */
+export function detectKtx2Support(renderer: THREE.WebGLRenderer): void {
+  if (ktx2SupportDetected) return;
+  const probe = renderer as unknown as
+    | {
+        isWebGPURenderer?: boolean;
+        hasFeature?: unknown;
+        extensions?: { has?: unknown; get?: unknown };
+      }
+    | null
+    | undefined;
+  const canAnswer =
+    probe != null &&
+    (probe.isWebGPURenderer === true
+      ? typeof probe.hasFeature === 'function'
+      : typeof probe.extensions?.has === 'function' && typeof probe.extensions?.get === 'function');
+  if (!canAnswer) return;
+  ktx2Loader.detectSupport(renderer);
+  ktx2SupportDetected = true;
+}
+
+/** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
+export const gltfLoader = new GLTFLoader(loadingManager);
+gltfLoader.setDRACOLoader(dracoLoader);
+gltfLoader.setKTX2Loader(ktx2Loader);
+// EXT_meshopt_compression decoding (three's own bundled decoder — inline
+// wasm, no fetch). Without this, a meshopt-compressed GLB — including the
+// output of the editor's Asset Budget "Compress · meshopt" action (W4a M3) —
+// throws at load time in every runtime and the editor viewport. Symmetric
+// with the DRACO wiring above (CB2): the ONE shared loader owns codec setup.
+gltfLoader.setMeshoptDecoder(MeshoptDecoder);
+
+/**
+ * Set the URL prefix prepended to relative asset paths.
+ * Called once by createGameRuntime(). Defaults to '/'.
+ */
+export function setAssetPrefix(prefix: string): void {
+  _prefix = prefix.endsWith('/') ? prefix : prefix ? `${prefix}/` : '/';
+}
+
+/**
+ * Resolve a relative asset URL using the current prefix.
+ * Use this for raw fetch() calls — Three.js loaders using
+ * `loadingManager` handle this automatically.
+ */
+export function resolveUrl(url: string): string {
+  return rewriteUrl(url);
+}

package/src/physics/collider-dimensions.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared world-scale collider dimension math (T1.2).
+ *
+ * Rapier colliders have no notion of a parent Object3D's `scale` — a body's
+ * shape is defined in absolute world units at creation time. Three.js meshes,
+ * by contrast, scale visually for free via the normal Object3D hierarchy. To
+ * keep the physical collider matching what's on screen, the LOADER must bake
+ * the entity's composed WORLD scale (self × every transformed ancestor) into
+ * the collider's dimensions at creation time.
+ *
+ * This is the ONE place that does that math, so every caller — the physics
+ * body creation path and the editor's collider gizmo alike — agrees on
+ * exactly the same numbers. Two copies silently agree by coincidence for
+ * uniform scale and disagree for everything else.
+ *
+ * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
+ * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
+ * round collider's round axes throws a loud error naming the entity, rather
+ * than silently simulating (or rendering) the wrong shape.
+ */
+
+import type { ColliderDescriptor } from '../asset-formats/collider';
+import { DEFAULTS } from '../defaults';
+
+/** Axes are considered "uniform enough" within this tolerance (float error only). */
+const UNIFORM_SCALE_EPSILON = 1e-4;
+
+export interface ColliderWorldDimensions {
+  /** cuboid only: per-axis half-extents, world scale applied. */
+  halfExtents?: [number, number, number];
+  /** ball/capsule only: radius, world scale applied (uniform axes required). */
+  radius?: number;
+  /** capsule only: half-height along the capsule's axis, world scale applied. */
+  halfHeight?: number;
+}
+
+/**
+ * Compute a collider's WORLD-space dimensions given the entity's composed
+ * world scale (self × ancestors, per-axis, in the entity's own local frame,
+ * in X/Y/Z order).
+ *
+ * @param collider - the entity's authored (unscaled) collider definition.
+ * @param worldScale - composed world scale `[x, y, z]`.
+ * @param entityLabel - human-readable entity identifier, used only in thrown
+ *   error messages (loud-failure naming, never silently wrong).
+ * @throws if a ball/capsule collider's round cross-section axes have a
+ *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
+ */
+export function computeColliderWorldDimensions(
+  collider: ColliderDescriptor,
+  worldScale: readonly [number, number, number],
+  entityLabel: string,
+): ColliderWorldDimensions {
+  const [sx, sy, sz] = worldScale;
+
+  switch (collider.type) {
+    case 'cuboid': {
+      const he = collider.halfExtents ?? DEFAULTS.collider.cuboid.halfExtents;
+      return { halfExtents: [he[0]! * sx, he[1]! * sy, he[2]! * sz] };
+    }
+    case 'ball': {
+      if (
+        Math.abs(sx - sy) > UNIFORM_SCALE_EPSILON ||
+        Math.abs(sy - sz) > UNIFORM_SCALE_EPSILON ||
+        Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON
+      ) {
+        throw new Error(
+          `Entity "${entityLabel}" has a "ball" collider under a non-uniform world scale ` +
+            `[${sx}, ${sy}, ${sz}]. Rapier ball colliders are always perfect spheres — a ` +
+            `non-uniform scale cannot be represented and would silently simulate the wrong ` +
+            `shape. Use a uniform scale on this entity (and every transformed ancestor), or ` +
+            `switch to a "cuboid" collider.`,
+        );
+      }
+      const radius = collider.radius ?? DEFAULTS.collider.ball.radius;
+      return { radius: radius * sx };
+    }
+    case 'capsule': {
+      // Rapier capsules run their half-height along the local Y axis, with a
+      // circular cross-section in the XZ plane — so only X/Z need to match.
+      if (Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON) {
+        throw new Error(
+          `Entity "${entityLabel}" has a "capsule" collider whose X/Z world scale differs ` +
+            `(x=${sx}, z=${sz}). Rapier capsule colliders have a circular cross-section — a ` +
+            `non-uniform X/Z scale cannot be represented and would silently simulate the ` +
+            `wrong shape. Use a uniform X/Z scale on this entity (and every transformed ` +
+            `ancestor), or switch to a "cuboid" collider.`,
+        );
+      }
+      const radius = collider.radius ?? DEFAULTS.collider.capsule.radius;
+      const halfHeight = collider.halfHeight ?? DEFAULTS.collider.capsule.halfHeight;
+      return { radius: radius * sx, halfHeight: halfHeight * sy };
+    }
+    default:
+      return {};
+  }
+}
+
+/**
+ * Compute a collider's WORLD-scaled translation offset (sibling to
+ * {@link computeColliderWorldDimensions}, same input contract).
+ *
+ * Rapier's `ColliderDesc.setTranslation` is a raw physics-engine offset with no
+ * notion of a parent Object3D's scale — like dimensions, an authored `offset`
+ * (in the entity's own local units) must be scaled per-axis by the entity's
+ * composed world scale before being handed to Rapier, or the collider's center
+ * silently drifts away from its visual anchor point under any non-1 scale.
+ * Applies to every collider type (including trimesh, which is otherwise not
+ * handled by {@link computeColliderWorldDimensions}).
+ *
+ * Returns `undefined` when no offset is authored, mirroring the `if (col.offset)`
+ * guard call sites already use.
+ */
+export function computeColliderWorldOffset(
+  offset: readonly [number, number, number] | undefined,
+  worldScale: readonly [number, number, number],
+): [number, number, number] | undefined {
+  if (!offset) return undefined;
+  const [sx, sy, sz] = worldScale;
+  return [offset[0] * sx, offset[1] * sy, offset[2] * sz];
+}

package/src/physics/collision-system.ts

@@ -0,0 +1,76 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+
+/**
+ * Collision event handler.
+ * Called with the two collider handles and whether contact started or stopped.
+ */
+export type CollisionHandler = (handleA: number, handleB: number, started: boolean) => void;
+
+/**
+ * Drains the Rapier event queue each frame and dispatches collision events.
+ *
+ * Usage:
+ *   const collisions = createCollisionSystem(rapierWorld, eventQueue);
+ *   collisions.onCollision((a, b, started) => { ... });
+ *   // In physics phase: rapierWorld.step(eventQueue);
+ *   // In postPhysics: collisions.drain();
+ */
+export function createCollisionSystem(rapierWorld: RAPIER.World, eventQueue: RAPIER.EventQueue) {
+  const handlers: CollisionHandler[] = [];
+
+  return {
+    /** Register a collision handler. */
+    onCollision(handler: CollisionHandler) {
+      handlers.push(handler);
+    },
+
+    /** Remove a collision handler. */
+    offCollision(handler: CollisionHandler) {
+      const idx = handlers.indexOf(handler);
+      if (idx !== -1) handlers.splice(idx, 1);
+    },
+
+    /**
+     * Drain the event queue and dispatch collision events.
+     * Call this in POST_PHYSICS phase, after rapierWorld.step(eventQueue).
+     *
+     * Events are buffered first, then handlers run *after* the drain callback
+     * returns. This is required: a handler that calls back into the Rapier world
+     * (e.g. trigger dispatch resolving a collider, or an `onTriggerEnter` that
+     * spawns/removes a body) would otherwise re-enter Rapier while it is still
+     * borrowed by `drainCollisionEvents`, throwing "recursive use of an object
+     * ... unsafe aliasing in rust".
+     */
+    drain() {
+      const events: Array<[number, number, boolean]> = [];
+      eventQueue.drainCollisionEvents((handle1, handle2, started) => {
+        events.push([handle1, handle2, started]);
+      });
+      eventQueue.drainContactForceEvents((_event) => {
+        // Contact force events available for advanced use.
+        // Game code can subscribe to these by extending this system.
+      });
+
+      for (const [handle1, handle2, started] of events) {
+        for (let i = 0; i < handlers.length; i++) {
+          handlers[i]!(handle1, handle2, started);
+        }
+      }
+    },
+
+    /**
+     * Look up the rigid body handle that owns a collider handle.
+     * To resolve a collider directly to its Object3D entity, use the physics
+     * registry's `getByColliderHandle` reverse index instead.
+     */
+    getBodyHandleFromCollider(colliderHandle: number): number | undefined {
+      const collider = rapierWorld.getCollider(colliderHandle);
+      if (!collider) return undefined;
+      const body = collider.parent();
+      if (!body) return undefined;
+      return body.handle;
+    },
+  };
+}
+
+export type CollisionSystem = ReturnType<typeof createCollisionSystem>;