@relu-interactives/spatial-ecs 0.2.22 → 0.2.24

package/dist/docs/guide/authoring-a-script-object.md

@@ -14,18 +14,20 @@ import { ScriptObject, type ColorInput } from "@relu-interactives/spatial-ecs";
 import * as THREE from "three";
 
 export default class WavePlane extends ScriptObject {
-  // Typed data → inspector fields (same envelopes as Behaviours).
-  declare data: { color: ColorInput };
+  // Inspector fields: an INLINE `data = { … }` literal (same envelopes as
+  // Behaviours). NEVER `declare data` — that is a type-only annotation with no
+  // runtime object, so the editor can't discover your fields and the inspector
+  // shows nothing to edit.
+  data = { color: "#3aa0ff" as ColorInput };
 
   private mat!: THREE.ShaderMaterial;
 
   // REQUIRED — build and return the visual root.
   build(): THREE.Object3D {
-    this.data.color ??= { type: "color", value: "#3aa0ff" };
     this.mat = new THREE.ShaderMaterial({
       uniforms: {
         uTime: { value: 0 },
-        uColor: { value: new THREE.Color(this.data.color.value) },
+        uColor: { value: new THREE.Color(this.data.color) },
       },
       vertexShader: /* glsl */ `
         uniform float uTime;
@@ -66,22 +68,33 @@ export default class WavePlane extends ScriptObject {
 | --- | --- | --- |
 | `this.world` | `World` | The owning ECS world. |
 | `this.entityId` | `number` | The entity this script is bound to. |
-| `this.data` | `Record<string, unknown>` | Inspector-bound payload. Declare a shape with `declare data: MyShape`. |
+| `this.data` | `Record<string, unknown>` | Inspector-bound payload. Declare it with an INLINE literal (`data = { … }`) — never `declare data` (a type-only annotation with no runtime object → no inspector fields). |
 | `this.root` | `THREE.Object3D \| null` | The object `build()` returned (set after build). |
 
 ## Data fields (inspector)
 
-Type `data` fields with the same input envelopes as Behaviours to get inspector controls:
+Declare `data` as an **inline literal** (`data = { … }`) with the same input envelopes as Behaviours. **Never use `declare data`** — it is a type-only annotation that produces no runtime object, so the editor can't discover the fields and the inspector shows nothing to edit. (Likewise, don't set defaults with `this.data.x ??= …` inside `build()` — put the default in the literal.)
+
+Simple scalars take a value plus an `as <Input>` cast and are read directly:
+
+```ts
+data = {
+  color: "#3aa0ff" as ColorInput,  // color swatch → this.data.color
+  speed: 1.0 as FloatInput,        // number field → this.data.speed
+  enabled: true as ToggleInput,    // toggle       → this.data.enabled
+};
+```
+
+Rich inputs that carry metadata are authored as inline objects and read via `.value` (or the resolved view for entity/component pickers):
 
 ```ts
-declare data: {
-  color: ColorInput;      // color swatch
-  amplitude: SliderInput; // slider
-  target: EntityInput;    // entity picker
+data = {
+  amplitude: { type: "slider", min: 0, max: 1, value: 0.5 }, // → this.data.amplitude.value
+  target: { type: "entity", value: null },                   // → this.data.target.value
 };
 ```
 
-Read a field's value as `this.data.color.value`. See [Data binding](./behaviour-data-binding/) for the full envelope catalog. Edits made in the inspector are pushed to the live instance's `this.data` between frames.
+See [Data binding](./behaviour-data-binding/) for the full envelope catalog. Edits made in the inspector are pushed to the live instance's `this.data` between frames.
 
 ## Rules
 

package/dist/docs/guide/systems/physics-sync-system.md

@@ -45,7 +45,7 @@ Initializes and manages the Rapier physics world, creates rigid bodies and colli
 ## Behavior notes
 
 - **Async init** — the Rapier WASM module is loaded once on the first `update()` call. Physics simulation does not start until the module is ready; entities created before init are processed on the first frame after init completes.
-- **Trimesh** — `trimesh` colliders extract vertex/index data from the entity's `THREE.BufferGeometry`. The extracted data is cached per entity by a geometry signature.
+- **Trimesh** — `trimesh` colliders merge the vertex/index data of **every mesh** under the entity (multi-primitive GLBs are fully covered) with the entity's **world scale baked into the vertices** — Rapier bodies carry no scale, so scaling the entity is how you resize a trimesh; the collider rebuilds automatically when the scale or geometry changes. The extracted data is cached per entity by a geometry+scale signature, and the heavy vertex merge runs only when that signature changes.
 - **Sensor colliders** — setting `values.collider.isSensor = true` creates a Rapier sensor collider. Sensor contacts do not generate forces but can be used for overlap/trigger queries.
 - **Gravity** — the global gravity vector is read from the `Environment` component (`gravity` field, default `{ x: 0, y: -9.81, z: 0 }`) and applied to the Rapier world gravity setting each frame.
 - **Preview only** — the system is typically constructed with `{ isEditor: false }` for preview. In the editor the physics world step is skipped so objects don't fall during authoring.

package/dist/index.cjs

@@ -6789,82 +6789,108 @@ function createColliderDesc(RAPIER, values, triMeshData) {
   return desc;
 }
 __name(createColliderDesc, "createColliderDesc");
-function findFirstMeshWithGeometry(object) {
-  if (object instanceof THREE36__namespace.Mesh && object.geometry) {
-    return object;
+function collectTriMeshParts(object) {
+  if (!object) {
+    return null;
   }
-  let found = null;
+  object.updateWorldMatrix(true, true);
+  const worldScale = new THREE36__namespace.Vector3();
+  object.getWorldScale(worldScale);
+  const scale = {
+    x: Math.abs(worldScale.x) || 1,
+    y: Math.abs(worldScale.y) || 1,
+    z: Math.abs(worldScale.z) || 1
+  };
+  const worldToObject = new THREE36__namespace.Matrix4().copy(object.matrixWorld).invert();
+  const parts = [];
   object.traverse((child) => {
-    if (found) {
+    if (!(child instanceof THREE36__namespace.Mesh) || !child.geometry) {
       return;
     }
-    if (child instanceof THREE36__namespace.Mesh && child.geometry) {
-      found = child;
+    const geometry = child.geometry;
+    const positionAttribute = geometry.getAttribute("position");
+    if (!positionAttribute || positionAttribute.itemSize < 3) {
+      return;
     }
+    const positionCount = positionAttribute.count;
+    if (positionCount < 3) {
+      return;
+    }
+    const indexAttribute = geometry.getIndex();
+    const indexCount = indexAttribute ? indexAttribute.count : Math.floor(positionCount / 3) * 3;
+    if (indexCount < 3) {
+      return;
+    }
+    const relativeMatrix = new THREE36__namespace.Matrix4().multiplyMatrices(
+      worldToObject,
+      child.matrixWorld
+    );
+    const matrixSignature = relativeMatrix.elements.map((value) => value.toFixed(5)).join(",");
+    parts.push({
+      positionAttribute,
+      indexAttribute,
+      positionCount,
+      indexCount,
+      relativeMatrix,
+      signature: `${child.uuid}:${geometry.uuid}:${positionCount}:${indexCount}:${matrixSignature}`
+    });
   });
-  return found;
-}
-__name(findFirstMeshWithGeometry, "findFirstMeshWithGeometry");
-function createTriMeshData(object) {
-  if (!object) {
+  if (parts.length === 0) {
     return null;
   }
-  const mesh = findFirstMeshWithGeometry(object);
-  if (!mesh) {
+  const scaleSignature = `${scale.x.toFixed(5)},${scale.y.toFixed(5)},${scale.z.toFixed(5)}`;
+  return {
+    parts,
+    scale,
+    signature: `${scaleSignature}|${parts.map((p) => p.signature).join("|")}`
+  };
+}
+__name(collectTriMeshParts, "collectTriMeshParts");
+function createTriMeshData(collected) {
+  if (!collected) {
     return null;
   }
-  const geometry = mesh.geometry;
-  const positionAttribute = geometry.getAttribute("position");
-  if (!positionAttribute || positionAttribute.itemSize < 3) {
-    return null;
+  const { parts, scale } = collected;
+  let vertexTotal = 0;
+  let indexTotal = 0;
+  for (const part of parts) {
+    vertexTotal += part.positionCount;
+    indexTotal += part.indexCount;
   }
-  const positionCount = positionAttribute.count;
-  if (positionCount < 3) {
+  if (vertexTotal < 3 || indexTotal < 3) {
     return null;
   }
-  object.updateWorldMatrix(true, true);
-  mesh.updateWorldMatrix(true, true);
-  const worldToObject = new THREE36__namespace.Matrix4().copy(object.matrixWorld).invert();
-  const relativeMatrix = new THREE36__namespace.Matrix4().multiplyMatrices(
-    worldToObject,
-    mesh.matrixWorld
-  );
-  const vertices = new Float32Array(positionCount * 3);
+  const vertices = new Float32Array(vertexTotal * 3);
+  const indices = new Uint32Array(indexTotal);
   const point = new THREE36__namespace.Vector3();
-  for (let index = 0; index < positionCount; index += 1) {
-    point.set(
-      positionAttribute.getX(index),
-      positionAttribute.getY(index),
-      positionAttribute.getZ(index)
-    ).applyMatrix4(relativeMatrix);
-    const outputIndex = index * 3;
-    vertices[outputIndex] = point.x;
-    vertices[outputIndex + 1] = point.y;
-    vertices[outputIndex + 2] = point.z;
-  }
-  const indexAttribute = geometry.getIndex();
-  let indices;
-  if (indexAttribute) {
-    indices = new Uint32Array(indexAttribute.count);
-    for (let index = 0; index < indexAttribute.count; index += 1) {
-      indices[index] = indexAttribute.getX(index);
-    }
-  } else {
-    const triangleIndexCount = Math.floor(positionCount / 3) * 3;
-    if (triangleIndexCount < 3) {
-      return null;
-    }
-    indices = new Uint32Array(triangleIndexCount);
-    for (let index = 0; index < triangleIndexCount; index += 1) {
-      indices[index] = index;
+  let vertexOffset = 0;
+  let indexOffset = 0;
+  for (const part of parts) {
+    const { positionAttribute, indexAttribute, relativeMatrix } = part;
+    for (let index = 0; index < part.positionCount; index += 1) {
+      point.set(
+        positionAttribute.getX(index),
+        positionAttribute.getY(index),
+        positionAttribute.getZ(index)
+      ).applyMatrix4(relativeMatrix);
+      const outputIndex = (vertexOffset + index) * 3;
+      vertices[outputIndex] = point.x * scale.x;
+      vertices[outputIndex + 1] = point.y * scale.y;
+      vertices[outputIndex + 2] = point.z * scale.z;
+    }
+    if (indexAttribute) {
+      for (let index = 0; index < part.indexCount; index += 1) {
+        indices[indexOffset + index] = vertexOffset + indexAttribute.getX(index);
+      }
+    } else {
+      for (let index = 0; index < part.indexCount; index += 1) {
+        indices[indexOffset + index] = vertexOffset + index;
+      }
     }
+    vertexOffset += part.positionCount;
+    indexOffset += part.indexCount;
   }
-  const matrixSignature = relativeMatrix.elements.map((value) => value.toFixed(5)).join(",");
-  return {
-    vertices,
-    indices,
-    signature: `${mesh.uuid}:${geometry.uuid}:${positionCount}:${indices.length}:${matrixSignature}`
-  };
+  return { vertices, indices, signature: collected.signature };
 }
 __name(createTriMeshData, "createTriMeshData");
 function syncBodyFromTransform(body, transform) {
@@ -7041,7 +7067,7 @@ var _PhysicsSyncSystem = class _PhysicsSyncSystem {
         syncBodyFromTransform(body, transform);
       }
       const effectiveCollider = computeColliderState(physics.values.collider, object);
-      const triMeshData = effectiveCollider.shape === "trimesh" ? createTriMeshData(object) : null;
+      const triMeshParts = effectiveCollider.shape === "trimesh" ? collectTriMeshParts(object) : null;
       if (!effectiveCollider || !effectiveCollider.enabled) {
         const colliderHandle = this.colliderHandles.get(entityId);
         if (typeof colliderHandle === "number") {
@@ -7055,7 +7081,7 @@ var _PhysicsSyncSystem = class _PhysicsSyncSystem {
         physics.collider = null;
         continue;
       }
-      const colliderSignature = `${JSON.stringify(effectiveCollider)}:${triMeshData?.signature ?? ""}`;
+      const colliderSignature = `${JSON.stringify(effectiveCollider)}:${triMeshParts?.signature ?? ""}`;
       const previousColliderSignature = this.colliderSignatures.get(entityId);
       if (!this.colliderHandles.has(entityId) || previousColliderSignature !== colliderSignature) {
         const previousColliderHandle = this.colliderHandles.get(entityId);
@@ -7068,7 +7094,7 @@ var _PhysicsSyncSystem = class _PhysicsSyncSystem {
         const colliderDesc = createColliderDesc(
           this.rapier,
           effectiveCollider,
-          triMeshData
+          createTriMeshData(triMeshParts)
         );
         const createdCollider = physicsWorld.createCollider(colliderDesc, body);
         this.colliderHandles.set(entityId, createdCollider.handle);
@@ -9419,9 +9445,9 @@ var _ScriptObjectSystem = class _ScriptObjectSystem {
     } catch {
       instance = new ctor(world, entityId, currentData);
     }
-    const defaults = normalizeScriptData(instance.data);
-    const merged = mergeDataByCurrentDefaults(defaults, currentData);
-    instance.data = resolveInputData(world, merged);
+    const literalDefaults = normalizeScriptData(instance.data);
+    const seed = Object.keys(literalDefaults).length > 0 ? mergeDataByCurrentDefaults(literalDefaults, currentData) : { ...currentData };
+    instance.data = resolveInputData(world, seed);
     const parent = world.getComponent(entityId, Object3DRef)?.object;
     if (!parent) {
       throw new Error("Script object entity has no Object3D to attach to.");
@@ -9451,6 +9477,13 @@ var _ScriptObjectSystem = class _ScriptObjectSystem {
     built.userData[SCRIPT_OBJECT_ROOT_FLAG] = true;
     parent.add(built);
     instance.root = built;
+    const postBuildData = normalizeScriptData(instance.data);
+    const schemaDefaults = { ...literalDefaults };
+    for (const [key2, value] of Object.entries(postBuildData)) {
+      if (!(key2 in schemaDefaults)) schemaDefaults[key2] = value;
+    }
+    const merged = mergeDataByCurrentDefaults(schemaDefaults, currentData);
+    instance.data = resolveInputData(world, merged);
     const stored = serializeDataForStorage(merged, merged);
     component.data = stored;
     component.runtimeState = "ready";