auto-git:

[add] src/geometry/model-instance-collider-generation.ts
 [add] src/runtime-three/rapier-collision-world.ts
 [change] AGENTS.md
 [change] CHAT_CONTEXT.md
 [change] architecture.md
 [change] package.json
 [change] prompts-lite.txt
 [change] prompts.txt
 [change] roadmap.md
 [change] src/assets/model-instances.ts
 [change] src/document/migrate-scene-document.ts
 [change] src/document/scene-document-validation.ts
 [change] src/document/scene-document.ts
 [change] src/runtime-three/first-person-navigation-controller.ts
 [change] src/runtime-three/navigation-controller.ts
 [change] src/runtime-three/runtime-host.ts
 [change] src/runtime-three/runtime-scene-build.ts
 [change] src/runtime-three/runtime-scene-validation.ts
 [change] src/viewport-three/viewport-host.ts
 [change] testing.md

src/assets/model-instances.ts

@@ -2,6 +2,15 @@ import { createOpaqueId } from "../core/ids";
 import type { Vec3 } from "../core/vector";
 import type { ModelAssetRecord } from "./project-assets";
 
+export const MODEL_INSTANCE_COLLISION_MODES = ["none", "terrain", "static", "dynamic", "simple"] as const;
+
+export type ModelInstanceCollisionMode = (typeof MODEL_INSTANCE_COLLISION_MODES)[number];
+
+export interface ModelInstanceCollisionSettings {
+  mode: ModelInstanceCollisionMode;
+  visible: boolean;
+}
+
 export interface ModelInstance {
   id: string;
   kind: "modelInstance";
@@ -10,6 +19,7 @@ export interface ModelInstance {
   position: Vec3;
   rotationDegrees: Vec3;
   scale: Vec3;
+  collision: ModelInstanceCollisionSettings;
   animationClipName?: string;
   animationAutoplay?: boolean;
 }
@@ -32,6 +42,11 @@ export const DEFAULT_MODEL_INSTANCE_SCALE: Vec3 = {
   z: 1
 };
 
+export const DEFAULT_MODEL_INSTANCE_COLLISION_SETTINGS: ModelInstanceCollisionSettings = {
+  mode: "none",
+  visible: false
+};
+
 function cloneVec3(vector: Vec3): Vec3 {
   return {
     x: vector.x,
@@ -44,6 +59,39 @@ function areVec3Equal(left: Vec3, right: Vec3): boolean {
   return left.x === right.x && left.y === right.y && left.z === right.z;
 }
 
+export function isModelInstanceCollisionMode(value: unknown): value is ModelInstanceCollisionMode {
+  return MODEL_INSTANCE_COLLISION_MODES.includes(value as ModelInstanceCollisionMode);
+}
+
+export function createModelInstanceCollisionSettings(
+  overrides: Partial<ModelInstanceCollisionSettings> = {}
+): ModelInstanceCollisionSettings {
+  const mode = overrides.mode ?? DEFAULT_MODEL_INSTANCE_COLLISION_SETTINGS.mode;
+
+  if (!isModelInstanceCollisionMode(mode)) {
+    throw new Error("Model instance collision mode must be a supported value.");
+  }
+
+  const visible = overrides.visible ?? DEFAULT_MODEL_INSTANCE_COLLISION_SETTINGS.visible;
+
+  if (typeof visible !== "boolean") {
+    throw new Error("Model instance collision visibility must be a boolean.");
+  }
+
+  return {
+    mode,
+    visible
+  };
+}
+
+export function cloneModelInstanceCollisionSettings(settings: ModelInstanceCollisionSettings): ModelInstanceCollisionSettings {
+  return createModelInstanceCollisionSettings(settings);
+}
+
+export function areModelInstanceCollisionSettingsEqual(left: ModelInstanceCollisionSettings, right: ModelInstanceCollisionSettings): boolean {
+  return left.mode === right.mode && left.visible === right.visible;
+}
+
 export function normalizeModelInstanceName(name: string | null | undefined): string | undefined {
   if (name === undefined || name === null) {
     return undefined;
@@ -68,11 +116,15 @@ function assertPositiveFiniteVec3(vector: Vec3, label: string) {
 }
 
 export function createModelInstance(
-  overrides: Partial<Pick<ModelInstance, "id" | "name" | "position" | "rotationDegrees" | "scale" | "animationClipName" | "animationAutoplay">> & Pick<ModelInstance, "assetId">
+  overrides: Partial<
+    Pick<ModelInstance, "id" | "name" | "position" | "rotationDegrees" | "scale" | "collision" | "animationClipName" | "animationAutoplay">
+  > &
+    Pick<ModelInstance, "assetId">
 ): ModelInstance {
   const position = cloneVec3(overrides.position ?? DEFAULT_MODEL_INSTANCE_POSITION);
   const rotationDegrees = cloneVec3(overrides.rotationDegrees ?? DEFAULT_MODEL_INSTANCE_ROTATION_DEGREES);
   const scale = cloneVec3(overrides.scale ?? DEFAULT_MODEL_INSTANCE_SCALE);
+  const collision = cloneModelInstanceCollisionSettings(overrides.collision ?? DEFAULT_MODEL_INSTANCE_COLLISION_SETTINGS);
 
   if (overrides.assetId.trim().length === 0) {
     throw new Error("Model instance assetId must be a non-empty string.");
@@ -90,6 +142,7 @@ export function createModelInstance(
     position,
     rotationDegrees,
     scale,
+    collision,
     animationClipName: overrides.animationClipName,
     animationAutoplay: overrides.animationAutoplay
   };
@@ -128,6 +181,7 @@ export function areModelInstancesEqual(left: ModelInstance, right: ModelInstance
     areVec3Equal(left.position, right.position) &&
     areVec3Equal(left.rotationDegrees, right.rotationDegrees) &&
     areVec3Equal(left.scale, right.scale) &&
+    areModelInstanceCollisionSettingsEqual(left.collision, right.collision) &&
     left.animationClipName === right.animationClipName &&
     left.animationAutoplay === right.animationAutoplay
   );