@relu-interactives/spatial-ecs 0.2.17 → 0.2.21

package/dist/components/index.d.cts

@@ -1,4 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from '../Video-D4B-z74P.cjs';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BeuJ1xt5.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-U9hAnf9y.cjs';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-me3iAcMF.cjs';
+export { P as PrefabInstance, a as PrefabNode } from '../index-CZo5I5Gs.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.d.ts

@@ -1,4 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from '../Video-Cym2C52L.js';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BeuJ1xt5.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-DHnxjGhW.js';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-me3iAcMF.js';
+export { P as PrefabInstance, a as PrefabNode } from '../index-D7FSg0Au.js';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, ScriptComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, normalizePhysicsState } from '../chunk-FTIQQK62.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState } from '../chunk-V7BNVTJW.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/docs/guide/components/material.md

@@ -2,6 +2,10 @@
 
 Material catalog for an entity. Tracks the live three.js materials (`materials`, `material`) plus serialized authoring state (`values[]`) mirrored from the inspector. Supports `standard`, `basic`, `phong`, and `physical` PBR types with optional texture map slots.  Use `setMaterials`, `updateValue`, `setMaterialType`, `setTextureFiltering`, and `setUseMipmaps` to mutate state — these keep `values[]` and the live three.js materials in sync. Texture URLs use the `localasset://` protocol inside the editor.
 
+## Shared material assets (editor)
+
+The editor can link a material slot to a **material asset** (a `.material` file in the project's asset browser) via the `assetRefs` field — one entry per slot, holding the asset's `localasset://` URL or `null` for a local material. The editor materializes the asset's values into `values[]` and re-applies them to every linked entity whenever the asset is edited. Rendering and the published runtime read only `values[]`; `assetRefs` is editor bookkeeping that persists with the project.
+
 > **Managed by:** [`MaterialSyncSystem`](../systems/material-sync-system)
 
 ## Editor inspector

package/dist/docs/guide/components/physics.md

@@ -4,6 +4,16 @@ Combined rigid body and collider component backed by Rapier. `values.rigidbody.t
 
 > **Managed by:** [`PhysicsSyncSystem`](../systems/physics-sync-system)
 
+## Collider sizing rules (read before authoring colliders)
+
+- **Primitives auto-fit on add** (v0.2.18+): adding a `PhysicsComponent` to a `plane`, `cube`, `sphere`, `capsule`, or `cylinder` derives the collider from the mesh-geometry parameters automatically — a plane gets a thin local-Z slab and a `fixed` body, a cube gets its exact box, and so on. Models and entities without mesh geometry keep the generic 1 m cuboid default and must be sized explicitly. Auto-fit runs only when no explicit values are passed; saved/duplicated components are never altered. If you resize the mesh geometry AFTER adding physics, re-author the collider — it does not track later geometry edits.
+
+- `values.collider.size` holds the cuboid's **FULL edge lengths** in meters — NOT half-extents. A 1 m cube is `size: { x: 1, y: 1, z: 1 }`.
+- Collider dimensions (`size`, `radius`, `height`) are authored in **unscaled local units**: `PhysicsSyncSystem` multiplies them by the entity's world scale when building the collider. Author the dimensions of the *unscaled* mesh; scaling the entity keeps mesh and collider matched.
+- `offsetPosition` is **not** multiplied by scale — it is applied in raw units. On a scaled entity, compute the offset in final world units.
+- The collider is axis-aligned to the entity and follows the entity's `TransformComponent` rotation (plus `offsetRotation`). A `plane` primitive is a vertical quad pre-rotated `rotation.x = -π/2` to lie flat — keep that rotation, and put a plane floor's thin cuboid axis on **local Z** (geometry is 100×100 → `size: { x: 100, y: 100, z: 0.05 }`). A flattened `cube` is usually a more robust ground.
+- Model (GLB) colliders are never auto-fitted from geometry — measure the mesh bounds and author dimensions explicitly, or use `trimesh` for complex static geometry.
+
 ## Editor inspector
 
 ![Physics inspector](/images/components/Physics.png)

package/dist/docs/guide/getting-started/editor/assets-browser.md

@@ -46,7 +46,7 @@ Folders are real directories under `assets/`. You can:
 
 ## Scripts
 
-Right-click in the asset browser and pick **New Component** to create a `Behaviour` script in place. The editor compiles it and exposes it for attachment via the inspector's **Script** panel. See [Custom Behaviours](../../authoring-a-behaviour).
+Right-click in the asset browser and pick **New Script** to create a `Behaviour` script in place. The editor compiles it and exposes it for attachment via the inspector's **Script** panel. See [Custom Behaviours](../../authoring-a-behaviour).
 
 ## Related
 

package/dist/docs/guide/prefabs.md

@@ -0,0 +1,152 @@
+# Prefabs
+
+A prefab packages a fully configured entity — its children, components,
+materials, physics, animations, and scripts — into a reusable `.prefab`
+asset. Configure something once (a third-person character, a pickup, an
+enemy), save it as a prefab, then reuse it everywhere: drag copies into the
+scene, or spawn them from scripts at runtime.
+
+## File anatomy
+
+A `.prefab` file is JSON:
+
+```jsonc
+{
+  "version": 1,
+  "name": "Enemy",
+  "snapshot": {
+    "entities": [1, 2, 3],          // ids renumbered 1..N, root first
+    "components": [                  // same columnar shape as a world snapshot
+      { "component": "PrefabNode", "entries": [ /* stable per-node uuids */ ] },
+      { "component": "TransformComponent", "entries": [ /* … */ ] }
+      // …every other serialized component
+    ]
+  }
+}
+```
+
+- Every entity carries a `PrefabNode { nodeId }` — a stable uuid used to
+  match instance entities back to the file across sessions and machines.
+- The root's `ParentId` is always `null`; entity references inside the
+  subtree (script `EntityInput`/`ComponentInput` fields, instanced-mesh
+  slots) are remapped on instantiation. References that pointed *outside*
+  the subtree are nulled when the prefab is created.
+- Scene singletons (`Environment`, `Postprocessing`) never serialize into a
+  prefab. Cameras and image targets cannot be turned into prefabs.
+
+## Creating and editing (editor)
+
+- **Create**: drag an entity from the Hierarchy into the Asset Browser. The
+  dragged entity automatically becomes the first linked *instance*.
+- **Edit**: double-click the `.prefab` tile — the editor enters **Prefab
+  Mode**, showing only the prefab's contents with the full inspector.
+  Saving writes the file; closing returns to the scene and applies the
+  changes to every instance.
+- **Instantiate**: drag the `.prefab` from the Asset Browser into the
+  viewport or onto a Hierarchy row.
+
+## Instances and per-property overrides
+
+Scene instances stay fully editable. Any property you change on an instance
+(a material color, a script field, a child's transform) becomes an
+**override**: when the prefab asset is edited later, overridden properties
+keep their per-instance values while everything else syncs from the file.
+
+Always per-instance (never synced): the instance **root's** position /
+rotation / scale, name, and place in the scene hierarchy.
+
+Rules of thumb:
+
+- Components or children you *add* to an instance are yours — prefab
+  updates never remove them.
+- Components or children you *delete* from an instance come back on the
+  next prefab apply (deletion tracking is not supported).
+- "Unpack" in the inspector detaches ONE level — the objects lose their
+  link but any nested instances inside survive as standalone instances.
+
+## Nested prefabs
+
+Prefabs can contain other prefab instances: drag a prefab into an open
+prefab (Prefab Mode), or create a prefab from a subtree that contains whole
+instances. Node identity is scoped per placement, so a prefab may nest two
+copies of the same child prefab and each keeps independent overrides.
+
+- Editing a child prefab **cascades**: every prefab file that nests it is
+  patched (overrides preserved), and every scene instance updates when you
+  close the editor — transitively through any depth of nesting.
+- A prefab can never contain itself, directly or through another prefab
+  (the editor rejects the drop).
+- Only *whole* instances nest — a partial slice of an instance can't become
+  a prefab.
+- In the scene, content can't be re-parented across a nested instance
+  boundary (its identity would change); open the host prefab to
+  restructure.
+- Runtime spawning is unaffected: files are fully materialized, so
+  `spawnPrefab` needs no resolution regardless of nesting depth.
+
+## Spawning at runtime
+
+Scripts spawn prefabs with `this.spawnPrefab(source, options?)`. Declare an
+`AssetInput` field and drag the `.prefab` onto it in the editor:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class EnemySpawner extends Behaviour {
+  data = {
+    // AssetInput — drag Enemy.prefab onto this field in the inspector
+    enemyPrefab: { path: "", type: "prefab" },
+    spawned: [] as number[],
+  };
+
+  private async spawnWave() {
+    for (let i = 0; i < 3; i++) {
+      const rootId = await this.spawnPrefab(this.data.enemyPrefab, {
+        position: { x: i * 2 - 2, y: 0, z: -6 },
+      });
+      this.data.spawned.push(rootId);
+    }
+  }
+
+  private despawnWave() {
+    for (const id of this.data.spawned) {
+      this.despawn(id); // removes the root and all of its children
+    }
+    this.data.spawned = [];
+  }
+}
+```
+
+Details:
+
+- `spawnPrefab` resolves once the entities exist. Heavy assets inside
+  (models, textures, audio) stream in reactively — repeated spawns of the
+  same prefab share geometry through the model cache, so waves are cheap.
+- `source` can be an `AssetInput` (`{ path, type }`), a URL string, or a
+  pre-loaded `PrefabAsset`.
+- Options: `{ parentId, position, rotation, scale }` — the transform applies
+  to the spawned root in its parent's local space.
+- `world.spawnPrefab(...)` / `world.despawnPrefab(id)` expose the same calls
+  outside of behaviours.
+
+## Preloading and caching
+
+Each prefab URL is fetched and parsed once per session (`loadPrefab` caches
+the parsed file; failed loads retry). Published experiences preload prefab
+files referenced by script `AssetInput` fields — plus the models and
+textures inside them — before the experience starts, so the first spawn
+does not hitch.
+
+## Custom hosts
+
+Prefab files store editor-space asset URLs. Published and preview builds
+register a resolver that maps them onto the deployed `assets/` folder:
+
+```ts
+import { setPrefabAssetUrlResolver } from "@relu-interactives/spatial-ecs";
+
+setPrefabAssetUrlResolver((url) => rewriteToMyCdn(url));
+```
+
+The standard project templates already do this — you only need it when
+embedding the runtime in a custom host.

package/dist/docs/guide/world-api.md

@@ -430,7 +430,7 @@ export default class PauseOnHit extends Behaviour {
 > [!TIP]
 > `pause()` and `resume()` affect the **entire world**. If you only want to
 > stop a subset of entities (for example, freeze enemies while a menu is open)
-> use a flag on a custom component instead and guard your `onUpdate` logic.
+> use a flag in a custom script (`Behaviour`) instead and guard your `onUpdate` logic.
 
 ## See also
 

package/dist/factories/index.cjs

@@ -929,10 +929,130 @@ var _PhysicsComponent = class _PhysicsComponent extends Component {
 };
 __name(_PhysicsComponent, "PhysicsComponent");
 var PhysicsComponent = _PhysicsComponent;
+var DEFAULT_MESH_GEOMETRY_PARAMETERS = {
+  capsule: { radius: 0.5, height: 1 },
+  cube: { width: 1, height: 1, depth: 1 },
+  cylinder: { radius: 0.5, height: 1 },
+  plane: { width: 100, height: 100 },
+  sphere: { radius: 0.5 }
+};
+var GEOMETRY_TYPE_BY_KIND = {
+  capsule: "CapsuleGeometry",
+  cube: "BoxGeometry",
+  cylinder: "CylinderGeometry",
+  model: "Model",
+  plane: "PlaneGeometry",
+  sphere: "SphereGeometry"
+};
+var _MeshGeometryComponent = class _MeshGeometryComponent extends Component {
+  constructor(kind, object, parameters, options) {
+    super();
+    this.kind = kind;
+    this.geometryType = GEOMETRY_TYPE_BY_KIND[kind];
+    this.object = object;
+    this.modelName = options?.modelName ?? "";
+    this.castShadow = options?.castShadow ?? false;
+    this.receiveShadow = options?.receiveShadow ?? false;
+    switch (kind) {
+      case "cube":
+        this.parameters = {
+          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.cube,
+          ...parameters
+        };
+        break;
+      case "plane":
+        this.parameters = {
+          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.plane,
+          ...parameters
+        };
+        break;
+      case "sphere":
+        this.parameters = {
+          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.sphere,
+          ...parameters
+        };
+        break;
+      case "cylinder":
+        this.parameters = {
+          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.cylinder,
+          ...parameters
+        };
+        break;
+      case "capsule":
+        this.parameters = {
+          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.capsule,
+          ...parameters
+        };
+        break;
+      case "model":
+        this.parameters = {};
+        break;
+    }
+  }
+};
+__name(_MeshGeometryComponent, "MeshGeometryComponent");
+var MeshGeometryComponent = _MeshGeometryComponent;
 
 // core/factories/components/PhysicsFactory.ts
+function deriveColliderFromGeometry(world, entityId) {
+  const meshGeometry = world.getComponent(entityId, MeshGeometryComponent);
+  if (!meshGeometry) {
+    return null;
+  }
+  switch (meshGeometry.kind) {
+    case "plane": {
+      const params = meshGeometry.parameters;
+      return {
+        collider: {
+          shape: "cuboid",
+          size: { x: params.width, y: params.height, z: 0.05 }
+        },
+        // An (effectively) zero-thickness sheet is only physically meaningful
+        // as static geometry — planes are floors/walls, not dynamic bodies.
+        rigidbody: { type: "fixed" }
+      };
+    }
+    case "cube": {
+      const params = meshGeometry.parameters;
+      return {
+        collider: {
+          shape: "cuboid",
+          size: { x: params.width, y: params.height, z: params.depth }
+        }
+      };
+    }
+    case "sphere": {
+      const params = meshGeometry.parameters;
+      return { collider: { shape: "ball", radius: params.radius } };
+    }
+    case "capsule": {
+      const params = meshGeometry.parameters;
+      return {
+        collider: {
+          shape: "capsule",
+          radius: params.radius,
+          height: params.height
+        }
+      };
+    }
+    case "cylinder": {
+      const params = meshGeometry.parameters;
+      return {
+        collider: {
+          shape: "cylinder",
+          radius: params.radius,
+          height: params.height
+        }
+      };
+    }
+    default:
+      return null;
+  }
+}
+__name(deriveColliderFromGeometry, "deriveColliderFromGeometry");
 function createPhysicsComponent(world, entityId, values) {
-  const component = new PhysicsComponent(values);
+  const initial = values ?? deriveColliderFromGeometry(world, entityId) ?? void 0;
+  const component = new PhysicsComponent(initial);
   world.addComponent(entityId, component);
   return component;
 }
@@ -1286,8 +1406,23 @@ var _MaterialComponent = class _MaterialComponent extends Component {
     this.materials = [];
     this.material = null;
     this.values = [];
+    this.assetRefs = [];
     this.setMaterials(materialOrMaterials);
   }
+  /** Link/unlink a slot to a material asset URL (editor bookkeeping only). */
+  setAssetRef(index, url) {
+    if (index < 0) {
+      return;
+    }
+    while (this.assetRefs.length <= index) {
+      this.assetRefs.push(null);
+    }
+    this.assetRefs[index] = url;
+  }
+  /** The material-asset URL a slot is linked to, or null when local. */
+  getAssetRef(index) {
+    return this.assetRefs[index] ?? null;
+  }
   setMaterials(materialOrMaterials = []) {
     this.materials = Array.isArray(materialOrMaterials) ? materialOrMaterials.filter(Boolean) : materialOrMaterials ? [materialOrMaterials] : [];
     this.material = this.materials[0] ?? null;
@@ -1356,69 +1491,6 @@ function createMeshComponent(world, entityId, ...args) {
   return component;
 }
 __name(createMeshComponent, "createMeshComponent");
-var DEFAULT_MESH_GEOMETRY_PARAMETERS = {
-  capsule: { radius: 0.5, height: 1 },
-  cube: { width: 1, height: 1, depth: 1 },
-  cylinder: { radius: 0.5, height: 1 },
-  plane: { width: 100, height: 100 },
-  sphere: { radius: 0.5 }
-};
-var GEOMETRY_TYPE_BY_KIND = {
-  capsule: "CapsuleGeometry",
-  cube: "BoxGeometry",
-  cylinder: "CylinderGeometry",
-  model: "Model",
-  plane: "PlaneGeometry",
-  sphere: "SphereGeometry"
-};
-var _MeshGeometryComponent = class _MeshGeometryComponent extends Component {
-  constructor(kind, object, parameters, options) {
-    super();
-    this.kind = kind;
-    this.geometryType = GEOMETRY_TYPE_BY_KIND[kind];
-    this.object = object;
-    this.modelName = options?.modelName ?? "";
-    this.castShadow = options?.castShadow ?? false;
-    this.receiveShadow = options?.receiveShadow ?? false;
-    switch (kind) {
-      case "cube":
-        this.parameters = {
-          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.cube,
-          ...parameters
-        };
-        break;
-      case "plane":
-        this.parameters = {
-          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.plane,
-          ...parameters
-        };
-        break;
-      case "sphere":
-        this.parameters = {
-          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.sphere,
-          ...parameters
-        };
-        break;
-      case "cylinder":
-        this.parameters = {
-          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.cylinder,
-          ...parameters
-        };
-        break;
-      case "capsule":
-        this.parameters = {
-          ...DEFAULT_MESH_GEOMETRY_PARAMETERS.capsule,
-          ...parameters
-        };
-        break;
-      case "model":
-        this.parameters = {};
-        break;
-    }
-  }
-};
-__name(_MeshGeometryComponent, "MeshGeometryComponent");
-var MeshGeometryComponent = _MeshGeometryComponent;
 
 // core/factories/components/MeshGeometryFactory.ts
 function createMeshGeometryComponent(world, entityId, ...args) {