@relu-interactives/spatial-ecs 0.2.22 → 0.2.23

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/index.cjs

@@ -9419,9 +9419,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 +9451,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";