@relu-interactives/spatial-ecs 0.2.16 → 0.2.20

package/dist/docs/guide/components/entity-type.md

@@ -59,11 +59,11 @@ Iterate all entities in the scene and apply logic only to those of a specific ty
 
 ```typescript
 import { Behaviour, EntityType, TransformComponent } from "@relu-interactives/spatial-ecs";
-import type { StringInput, FloatInput } from "@relu-interactives/spatial-ecs";
+import type { TextInput, FloatInput } from "@relu-interactives/spatial-ecs";
 
 export default class TypeFilter extends Behaviour {
   data = {
-    targetKind: "cube" as StringInput,
+    targetKind: "cube" as TextInput,
     spinSpeed: 1 as FloatInput,
   };
 

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

@@ -70,11 +70,11 @@ Drive the quad's visibility from the inspector or from game logic via `Object3DR
 
 ```typescript
 import { Behaviour, ImageComponent, Object3DRef } from "@relu-interactives/spatial-ecs";
-import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class ImageVisibility extends Behaviour {
   data = {
-    visible: true as BooleanInput,
+    visible: true as ToggleInput,
   };
 
   protected onUpdate() {

package/dist/docs/guide/components/instanced-mesh.md

@@ -63,12 +63,12 @@ export default class InstanceCounter extends Behaviour {
 
 ```typescript
 import { Behaviour, InstancedMeshComponent } from "@relu-interactives/spatial-ecs";
-import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class ToggleShadows extends Behaviour {
   data = {
-    castShadow: true as BooleanInput,
-    receiveShadow: true as BooleanInput,
+    castShadow: true as ToggleInput,
+    receiveShadow: true as ToggleInput,
   };
 
   protected init() {

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/mesh-geometry.md

@@ -44,12 +44,12 @@ Let the inspector or game logic control whether the mesh casts and receives shad
 
 ```typescript
 import { Behaviour, MeshGeometryComponent } from "@relu-interactives/spatial-ecs";
-import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class ShadowDriver extends Behaviour {
   data = {
-    castShadow: true as BooleanInput,
-    receiveShadow: true as BooleanInput,
+    castShadow: true as ToggleInput,
+    receiveShadow: true as ToggleInput,
   };
 
   protected onUpdate() {

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

@@ -40,12 +40,12 @@ Walk the mesh hierarchy and enable or disable shadow casting based on a boolean
 
 ```typescript
 import { Behaviour, MeshComponent } from "@relu-interactives/spatial-ecs";
-import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class ShadowToggle extends Behaviour {
   data = {
-    castShadow: true as BooleanInput,
-    receiveShadow: true as BooleanInput,
+    castShadow: true as ToggleInput,
+    receiveShadow: true as ToggleInput,
   };
 
   protected onUpdate() {

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

@@ -73,11 +73,11 @@ Show or hide the loaded model at runtime using the `Object3DRef` visibility flag
 
 ```typescript
 import { Behaviour, ModelComponent, Object3DRef } from "@relu-interactives/spatial-ecs";
-import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class ModelVisibility extends Behaviour {
   data = {
-    visible: true as BooleanInput,
+    visible: true as ToggleInput,
   };
 
   protected onUpdate() {

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

@@ -40,11 +40,11 @@ Rename the entity at runtime from an inspector string field. Useful for dynamic
 
 ```typescript
 import { Behaviour, Name } from "@relu-interactives/spatial-ecs";
-import type { StringInput } from "@relu-interactives/spatial-ecs";
+import type { TextInput } from "@relu-interactives/spatial-ecs";
 
 export default class EntityRenamer extends Behaviour {
   data = {
-    displayName: "My Entity" as StringInput,
+    displayName: "My Entity" as TextInput,
   };
 
   protected onUpdate() {
@@ -62,11 +62,11 @@ Query all `Name` components to locate a sibling entity and read its position.
 
 ```typescript
 import { Behaviour, Name, TransformComponent } from "@relu-interactives/spatial-ecs";
-import type { StringInput } from "@relu-interactives/spatial-ecs";
+import type { TextInput } from "@relu-interactives/spatial-ecs";
 
 export default class LookAtTarget extends Behaviour {
   data = {
-    targetName: "Target" as StringInput,
+    targetName: "Target" as TextInput,
   };
 
   protected onUpdate() {

package/dist/docs/guide/components/object3d-ref.md

@@ -39,11 +39,11 @@ Expose a boolean that shows or hides the entity's scene object at runtime.
 
 ```typescript
 import { Behaviour, Object3DRef } from "@relu-interactives/spatial-ecs";
-import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class VisibilityDriver extends Behaviour {
   data = {
-    visible: true as BooleanInput,
+    visible: true as ToggleInput,
   };
 
   protected onUpdate() {

package/dist/docs/guide/components/parent-id.md

@@ -54,11 +54,11 @@ Assign a new parent entity ID to move the entity (and its children) under a diff
 
 ```typescript
 import { Behaviour, ParentId, Name, KeyboardKeys } from "@relu-interactives/spatial-ecs";
-import type { StringInput } from "@relu-interactives/spatial-ecs";
+import type { TextInput } from "@relu-interactives/spatial-ecs";
 
 export default class Reparenter extends Behaviour {
   data = {
-    newParentName: "Holder" as StringInput,
+    newParentName: "Holder" as TextInput,
   };
 
   protected onUpdate() {

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/components/video.md

@@ -73,12 +73,12 @@ Expose volume and loop settings as inspector fields so they can be tuned without
 
 ```typescript
 import { Behaviour, VideoComponent } from "@relu-interactives/spatial-ecs";
-import type { FloatInput, BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { FloatInput, ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class VideoSettings extends Behaviour {
   data = {
     volume: 1 as FloatInput,
-    loop: true as BooleanInput,
+    loop: true as ToggleInput,
   };
 
   protected onUpdate() {

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,133 @@
+# 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.
+
+v1 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 part of v1).
+- "Unpack" in the inspector detaches an instance permanently — it becomes
+  ordinary objects with no link.
+- Nested prefabs (a prefab inside another prefab) are not supported in v1.
+
+## 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

@@ -283,7 +283,8 @@ intersected mesh sorted by distance. Each hit carries the owning `entityId`
 so you can drive game logic from the result.
 
 ```ts
-import { Behaviour, NameComponent } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { Name } from "@relu-interactives/spatial-ecs/components";
 import * as THREE from "three";
 
 export default class ClickToInspect extends Behaviour {
@@ -299,7 +300,7 @@ export default class ClickToInspect extends Behaviour {
     const first = hits.find((hit) => hit.entityId !== null);
     if (!first || first.entityId === null) return;
 
-    const name = this.world.getComponent(first.entityId, NameComponent);
+    const name = this.world.getComponent(first.entityId, Name);
     console.log(
       "clicked",
       name?.value ?? first.entityId,
@@ -429,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) {