@relu-interactives/spatial-ecs 0.2.21 → 0.2.23

package/dist/systems/index.cjs

@@ -1891,7 +1891,6 @@ var _ScriptComponent = class _ScriptComponent extends Component {
       className: typeof entry.className === "string" ? entry.className : "",
       scriptUrl: typeof entry.scriptUrl === "string" ? entry.scriptUrl : "",
       enabled: typeof entry.enabled === "boolean" ? entry.enabled : true,
-      executeInEditor: typeof entry.executeInEditor === "boolean" ? entry.executeInEditor : false,
       data: entry.data && typeof entry.data === "object" && !Array.isArray(entry.data) ? entry.data : {},
       runtimeState: entry.runtimeState,
       runtimeMessage: typeof entry.runtimeMessage === "string" ? entry.runtimeMessage : void 0
@@ -1913,6 +1912,27 @@ var _ScriptComponent = class _ScriptComponent extends Component {
 __name(_ScriptComponent, "ScriptComponent");
 var ScriptComponent = _ScriptComponent;
 
+// core/components/ScriptObjectComponent.ts
+var _ScriptObjectComponent = class _ScriptObjectComponent extends Component {
+  constructor(input = {}) {
+    super();
+    this.scriptUrl = typeof input.scriptUrl === "string" && input.scriptUrl.length > 0 ? input.scriptUrl : null;
+    this.className = typeof input.className === "string" && input.className.length > 0 ? input.className : null;
+    this.enabled = typeof input.enabled === "boolean" ? input.enabled : true;
+    this.data = input.data && typeof input.data === "object" && !Array.isArray(input.data) ? input.data : {};
+    this.runtimeState = input.runtimeState === "idle" || input.runtimeState === "loading" || input.runtimeState === "ready" || input.runtimeState === "error" ? input.runtimeState : "idle";
+    this.runtimeMessage = typeof input.runtimeMessage === "string" ? input.runtimeMessage : void 0;
+    Object.defineProperty(this, "instance", {
+      value: null,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+  }
+};
+__name(_ScriptObjectComponent, "ScriptObjectComponent");
+var ScriptObjectComponent = _ScriptObjectComponent;
+
 // core/components/Selectable.ts
 var _Selectable = class _Selectable extends Component {
   constructor(enabled = true) {
@@ -4760,6 +4780,10 @@ function buildComponentValueMaps(snapshot) {
     animationValues: readByComponent(snapshot.components, "AnimationComponent"),
     imageTargetAnchorValues: readByComponent(snapshot.components, "ImageTargetAnchor"),
     scriptValues: readByComponent(snapshot.components, "ScriptComponent"),
+    scriptObjectValues: readByComponent(
+      snapshot.components,
+      "ScriptObjectComponent"
+    ),
     instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent"),
     instanceSlotValues: readByComponent(snapshot.components, "InstanceSlotComponent"),
     prefabNodeValues: readByComponent(snapshot.components, "PrefabNode"),
@@ -4877,6 +4901,14 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       new ScriptComponent(entries)
     );
   }
+  const sourceScriptObject = asRecord3(values.scriptObjectValues.get(sourceEntityId));
+  if (sourceScriptObject) {
+    const soc = world.getComponent(targetEntityId, ScriptObjectComponent);
+    const data = asRecord3(sourceScriptObject.data);
+    if (soc && data) {
+      soc.data = remapEntityRefsInScriptData(data, idMap);
+    }
+  }
   {
     const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
     if (imComponent && imComponent.instanceEntityIds.length > 0) {
@@ -5463,7 +5495,8 @@ var HYDRATABLE_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "spotLight",
   "areaLight",
   "instancedMesh",
-  "instanceSlot"
+  "instanceSlot",
+  "scriptObject"
 ]);
 
 // core/hydration/hydrateWorld.ts
@@ -5565,6 +5598,16 @@ function buildEntityCreationPayload(sourceEntityId, kind, componentValues) {
       };
     }
   }
+  if (kind === "scriptObject") {
+    const so = asRecord3(componentValues.scriptObjectValues.get(sourceEntityId));
+    if (so) {
+      payload.options = {
+        scriptUrl: typeof so.scriptUrl === "string" ? so.scriptUrl : null,
+        className: typeof so.className === "string" ? so.className : null,
+        enabled: typeof so.enabled === "boolean" ? so.enabled : true
+      };
+    }
+  }
   return payload;
 }
 __name(buildEntityCreationPayload, "buildEntityCreationPayload");
@@ -6124,22 +6167,14 @@ var _Behaviour = class _Behaviour {
   /**
    * Called once before the first {@link Behaviour.onUpdate}. Override to
    * default and validate {@link Behaviour.data}, cache references, or set
-   * initial state.
-   *
-   * @remarks
-   * Also called in editor mode when `executeInEditor` is `true` on the script
-   * entry.
+   * initial state. Runs at preview/runtime only — never in the editor.
    */
   init() {
   }
   /**
    * Called every frame while the script is enabled. Override with the
-   * script's main per-frame logic.
-   *
-   * @remarks
-   * Also called every frame in editor mode when `executeInEditor` is `true`.
-   * Access the Three.js scene with `this.world.getScene()` for editor-only
-   * rendering work such as custom shaders or procedural geometry.
+   * script's main per-frame logic. Runs at preview/runtime only — never in the
+   * editor (use {@link ScriptObject} for editor-visible visuals).
    */
   onUpdate() {
   }
@@ -6178,7 +6213,14 @@ __name(_Behaviour, "Behaviour");
 _Behaviour.__reluBehaviourClass = true;
 var Behaviour = _Behaviour;
 
-// core/systems/ScriptBehaviourSystem.ts
+// core/systems/scriptShared.ts
+async function defaultModuleLoader(scriptUrl) {
+  return await import(
+    /* webpackIgnore: true */
+    scriptUrl
+  );
+}
+__name(defaultModuleLoader, "defaultModuleLoader");
 function toErrorMessage(error) {
   const sanitize = /* @__PURE__ */ __name((value) => value.replace(/localasset:\/\/[^/]+\//g, "localasset://").replace(/\/Users\/[^\s)]+/g, "[local path]"), "sanitize");
   if (error instanceof Error && error.message) {
@@ -6190,26 +6232,22 @@ function toErrorMessage(error) {
   return "Unknown script error.";
 }
 __name(toErrorMessage, "toErrorMessage");
-function buildInstanceKey(entityId, scriptUrl, className) {
-  return `${entityId}:${scriptUrl}:${className}`;
-}
-__name(buildInstanceKey, "buildInstanceKey");
-function resolveBehaviourCtor(moduleValue, className) {
+function resolveScriptCtor(moduleValue, className, options) {
   const named = moduleValue[className];
   const fallback = moduleValue.default;
   const candidate = typeof named === "function" ? named : typeof fallback === "function" ? fallback : null;
   if (!candidate) {
     return null;
   }
-  if (!(candidate.prototype instanceof Behaviour)) {
-    const isBehaviourSubclass = !!candidate.__reluBehaviourClass;
-    if (!isBehaviourSubclass) {
+  if (!(candidate.prototype instanceof options.baseClass)) {
+    const marker = candidate[options.markerKey];
+    if (!marker) {
       return null;
     }
   }
   return candidate;
 }
-__name(resolveBehaviourCtor, "resolveBehaviourCtor");
+__name(resolveScriptCtor, "resolveScriptCtor");
 function normalizeScriptData(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -6291,8 +6329,8 @@ function resolveInputData(world, rawData) {
   return resolved;
 }
 __name(resolveInputData, "resolveInputData");
-function serializeDataForStorage(rawData, behaviourData) {
-  const result = { ...behaviourData };
+function serializeDataForStorage(rawData, instanceData) {
+  const result = { ...instanceData };
   for (const [key, rawValue] of Object.entries(rawData)) {
     if (isRawEntityInput(rawValue) || isRawComponentInput(rawValue)) {
       result[key] = rawValue;
@@ -6301,13 +6339,25 @@ function serializeDataForStorage(rawData, behaviourData) {
   return result;
 }
 __name(serializeDataForStorage, "serializeDataForStorage");
+
+// core/systems/ScriptBehaviourSystem.ts
+function buildInstanceKey(entityId, scriptUrl, className) {
+  return `${entityId}:${scriptUrl}:${className}`;
+}
+__name(buildInstanceKey, "buildInstanceKey");
+function resolveBehaviourCtor(moduleValue, className) {
+  return resolveScriptCtor(moduleValue, className, {
+    baseClass: Behaviour,
+    markerKey: "__reluBehaviourClass"
+  });
+}
+__name(resolveBehaviourCtor, "resolveBehaviourCtor");
 function normalizeEntry(value, fallbackEntityId) {
   return {
     entityId: typeof value?.entityId === "number" ? value.entityId : fallbackEntityId,
     className: typeof value?.className === "string" ? value.className : "",
     scriptUrl: typeof value?.scriptUrl === "string" ? value.scriptUrl : "",
     enabled: typeof value?.enabled === "boolean" ? value.enabled : true,
-    executeInEditor: typeof value?.executeInEditor === "boolean" ? value.executeInEditor : false,
     data: normalizeScriptData(value?.data),
     runtimeState: value?.runtimeState === "idle" || value?.runtimeState === "loading" || value?.runtimeState === "ready" || value?.runtimeState === "error" ? value.runtimeState : void 0,
     runtimeMessage: typeof value?.runtimeMessage === "string" ? value.runtimeMessage : void 0
@@ -6330,13 +6380,6 @@ function writeScriptEntries(component, entries) {
   }
 }
 __name(writeScriptEntries, "writeScriptEntries");
-async function defaultModuleLoader(scriptUrl) {
-  return await import(
-    /* webpackIgnore: true */
-    scriptUrl
-  );
-}
-__name(defaultModuleLoader, "defaultModuleLoader");
 var _ScriptBehaviourSystem = class _ScriptBehaviourSystem {
   constructor(moduleLoader, selectionContext) {
     this.instances = /* @__PURE__ */ new Map();
@@ -6452,11 +6495,11 @@ var _ScriptBehaviourSystem = class _ScriptBehaviourSystem {
       let hasEnabledScript = false;
       for (let entryIndex = 0; entryIndex < nextEntries.length; entryIndex += 1) {
         const entry = nextEntries[entryIndex];
-        const skipInEditor = world.isEditorMode() && !entry.executeInEditor;
+        const skipInEditor = world.isEditorMode();
         if (!entry.enabled || !entry.scriptUrl || skipInEditor) {
           nextEntries[entryIndex] = {
             ...entry,
-            runtimeState: skipInEditor ? "idle" : "idle",
+            runtimeState: "idle",
             runtimeMessage: void 0
           };
           continue;
@@ -6643,7 +6686,7 @@ var _ScriptBehaviourSystem = class _ScriptBehaviourSystem {
     const mergedData = mergeDataByCurrentDefaults(defaults, currentData);
     const resolvedData = resolveInputData(world, mergedData);
     behaviour.data = resolvedData;
-    if (!world.isEditorMode() || liveEntry.executeInEditor === true) {
+    if (!world.isEditorMode()) {
       behaviour.init();
     }
     liveEntries[entryIndex] = {
@@ -6671,6 +6714,335 @@ __name(_ScriptBehaviourSystem, "ScriptBehaviourSystem");
 _ScriptBehaviourSystem.CLICK_THRESHOLD = 6;
 var ScriptBehaviourSystem = _ScriptBehaviourSystem;
 
+// core/ScriptObject.ts
+var _ScriptObject = class _ScriptObject {
+  /**
+   * Engine-managed constructor. `ScriptObjectSystem` instantiates subclasses
+   * with the owning world, the entity id, and the component's `data`. User code
+   * should not call this directly.
+   */
+  constructor(world, entityId, data) {
+    /**
+     * The script's data payload (the `ScriptObjectComponent.data`). Declare a
+     * concrete shape on subclasses with `declare data: MyShape` for type safety.
+     * Use the same typed input envelopes as Behaviours (`ColorInput`,
+     * `SliderInput`, `EntityInput`, …) to get inspector fields.
+     */
+    this.data = {};
+    /**
+     * The Object3D returned by {@link ScriptObject.build}. Assigned by
+     * `ScriptObjectSystem` after `build()` runs; `null` until then.
+     */
+    this.root = null;
+    this.world = world;
+    this.entityId = entityId;
+    if (data) this.data = data;
+  }
+  /**
+   * REQUIRED — build and return the visual root. Called once by
+   * `ScriptObjectSystem` after construction. The returned object is attached
+   * under the entity's Object3D (so it inherits the entity transform, selection
+   * and visibility). Subclasses MUST override.
+   */
+  build() {
+    throw new Error("ScriptObject subclasses must implement build()");
+  }
+};
+__name(_ScriptObject, "ScriptObject");
+/**
+ * Static marker used by `ScriptObjectSystem` to detect `ScriptObject`
+ * subclasses even when a bundler ships a second copy of the package into the
+ * script blob (breaking `instanceof`). Do NOT override.
+ */
+_ScriptObject.__reluScriptObjectClass = true;
+var ScriptObject = _ScriptObject;
+
+// core/systems/ScriptObjectSystem.ts
+var SCRIPT_OBJECT_ROOT_FLAG = "__scriptObjectRoot";
+function setInstanceRef(component, value) {
+  Object.defineProperty(component, "instance", {
+    value,
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+}
+__name(setInstanceRef, "setInstanceRef");
+function disposeBuiltObject(root) {
+  root.parent?.remove(root);
+  root.traverse((node) => {
+    const mesh = node;
+    const geometry = mesh.geometry;
+    if (geometry?.dispose && !geometry.userData?.[SHARED_MODEL_RESOURCE_FLAG]) {
+      geometry.dispose();
+    }
+    const material = mesh.material;
+    const materials = Array.isArray(material) ? material : material ? [material] : [];
+    for (const mat of materials) {
+      if (mat.userData?.[SHARED_MODEL_RESOURCE_FLAG]) continue;
+      for (const value of Object.values(mat)) {
+        if (value instanceof THREE14__namespace.Texture) value.dispose();
+      }
+      mat.dispose?.();
+    }
+  });
+}
+__name(disposeBuiltObject, "disposeBuiltObject");
+var _ScriptObjectSystem = class _ScriptObjectSystem {
+  constructor(moduleLoader) {
+    this.instances = /* @__PURE__ */ new Map();
+    this.loading = /* @__PURE__ */ new Map();
+    /** Bumped by invalidate*() so in-flight loads that predate it are discarded. */
+    this.epoch = 0;
+    this.moduleLoader = moduleLoader ?? defaultModuleLoader;
+  }
+  update(world, deltaTime) {
+    const active = /* @__PURE__ */ new Map();
+    for (const entityId of world.query(ScriptObjectComponent)) {
+      const component = world.getComponent(entityId, ScriptObjectComponent);
+      if (!component) continue;
+      const wantsRun = component.enabled && typeof component.scriptUrl === "string" && typeof component.className === "string";
+      if (!wantsRun) {
+        const record = this.instances.get(entityId);
+        if (record) this.teardownRecord(world, entityId, record, false);
+        this.loading.delete(entityId);
+        if (component.runtimeState !== "idle") {
+          component.runtimeState = "idle";
+          component.runtimeMessage = void 0;
+        }
+        continue;
+      }
+      active.set(entityId, component);
+    }
+    for (const [entityId, record] of this.instances) {
+      const component = active.get(entityId);
+      const identityChanged = !component || record.scriptUrl !== component.scriptUrl || record.className !== component.className;
+      if (!world.hasEntity(entityId) || identityChanged) {
+        this.teardownRecord(world, entityId, record, false);
+      }
+    }
+    for (const [entityId, component] of active) {
+      const record = this.instances.get(entityId);
+      if (!record || record.status !== "ready" || !record.instance) continue;
+      if (!world.isEntityVisible(entityId)) continue;
+      if (component.data !== record.lastWrittenData) {
+        try {
+          const merged = mergeDataByCurrentDefaults(
+            record.rawData,
+            normalizeScriptData(component.data)
+          );
+          record.rawData = merged;
+          record.instance.data = resolveInputData(world, merged);
+          const stored = serializeDataForStorage(merged, merged);
+          component.data = stored;
+          record.lastWrittenData = stored;
+        } catch (error) {
+          this.markError(world, entityId, component, error);
+          continue;
+        }
+      }
+      try {
+        record.instance.update?.(deltaTime);
+      } catch (error) {
+        this.markError(world, entityId, component, error);
+      }
+    }
+    for (const [entityId, component] of active) {
+      if (this.instances.has(entityId) || this.loading.has(entityId)) continue;
+      const scriptUrl = component.scriptUrl;
+      const className = component.className;
+      if (component.runtimeState !== "loading") {
+        component.runtimeState = "loading";
+        component.runtimeMessage = void 0;
+      }
+      const epochAtStart = this.epoch;
+      const key = `${epochAtStart}:${scriptUrl}:${className}`;
+      const promise = this.loadScriptObject(
+        world,
+        entityId,
+        scriptUrl,
+        className,
+        key,
+        epochAtStart
+      ).catch((error) => {
+        this.markError(world, entityId, void 0, error);
+        console.error(
+          `[ScriptObjectSystem] Failed loading ${className} (${scriptUrl})`,
+          error
+        );
+      }).finally(() => {
+        if (this.loading.get(entityId)?.key === key) {
+          this.loading.delete(entityId);
+        }
+      });
+      this.loading.set(entityId, { key, promise });
+    }
+    for (const entityId of this.loading.keys()) {
+      if (!active.has(entityId)) this.loading.delete(entityId);
+    }
+  }
+  async loadScriptObject(world, entityId, scriptUrl, className, key, epochAtStart) {
+    const moduleValue = await this.moduleLoader(scriptUrl);
+    if (this.loading.get(entityId)?.key !== key || epochAtStart !== this.epoch || !world.hasEntity(entityId)) {
+      return;
+    }
+    const component = world.getComponent(entityId, ScriptObjectComponent);
+    if (!component || !component.enabled || component.scriptUrl !== scriptUrl || component.className !== className) {
+      return;
+    }
+    const ctor = resolveScriptCtor(moduleValue, className, {
+      baseClass: ScriptObject,
+      markerKey: "__reluScriptObjectClass"
+    });
+    if (!ctor) {
+      throw new Error(
+        `Missing ScriptObject export '${className}' in ${scriptUrl}`
+      );
+    }
+    const currentData = normalizeScriptData(component.data);
+    let instance;
+    try {
+      instance = new ctor(world, entityId, void 0);
+    } catch {
+      instance = new ctor(world, entityId, currentData);
+    }
+    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.");
+    }
+    for (const child of [...parent.children]) {
+      if (child.userData?.[SCRIPT_OBJECT_ROOT_FLAG]) {
+        disposeBuiltObject(child);
+      }
+    }
+    let built;
+    try {
+      built = instance.build();
+    } catch (error) {
+      try {
+        instance.dispose?.();
+      } catch {
+      }
+      throw error;
+    }
+    if (!built || built.isObject3D !== true) {
+      try {
+        instance.dispose?.();
+      } catch {
+      }
+      throw new Error("build() must return a THREE.Object3D.");
+    }
+    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";
+    component.runtimeMessage = void 0;
+    setInstanceRef(component, instance);
+    this.instances.set(entityId, {
+      entityId,
+      scriptUrl,
+      className,
+      status: "ready",
+      instance,
+      root: built,
+      rawData: merged,
+      lastWrittenData: stored
+    });
+  }
+  /** Dispose a record's instance + built subtree. `keepTombstone` leaves an error marker. */
+  teardownRecord(world, entityId, record, keepTombstone) {
+    try {
+      record.instance?.dispose?.();
+    } catch {
+    }
+    if (record.root) disposeBuiltObject(record.root);
+    const component = world.getComponent(entityId, ScriptObjectComponent);
+    if (component) setInstanceRef(component, null);
+    if (keepTombstone) {
+      this.instances.set(entityId, {
+        ...record,
+        status: "error",
+        instance: null,
+        root: null
+      });
+    } else {
+      this.instances.delete(entityId);
+    }
+  }
+  markError(world, entityId, component, error) {
+    const comp = component ?? world.getComponent(entityId, ScriptObjectComponent) ?? null;
+    if (comp) {
+      comp.runtimeState = "error";
+      comp.runtimeMessage = toErrorMessage(error);
+    }
+    const record = this.instances.get(entityId);
+    if (record) {
+      this.teardownRecord(world, entityId, record, true);
+    } else {
+      this.instances.set(entityId, {
+        entityId,
+        scriptUrl: comp?.scriptUrl ?? "",
+        className: comp?.className ?? "",
+        status: "error",
+        instance: null,
+        root: null,
+        rawData: {},
+        lastWrittenData: null
+      });
+    }
+  }
+  /** Dispose all live instances so the next update() reloads with fresh modules. */
+  invalidateAll() {
+    this.epoch += 1;
+    for (const [entityId, record] of [...this.instances]) {
+      try {
+        record.instance?.dispose?.();
+      } catch {
+      }
+      if (record.root) disposeBuiltObject(record.root);
+      this.instances.delete(entityId);
+    }
+    this.loading.clear();
+  }
+  /** Invalidate only the entities whose script matches `scriptUrl`. */
+  invalidate(scriptUrl) {
+    this.epoch += 1;
+    for (const [entityId, record] of [...this.instances]) {
+      if (record.scriptUrl !== scriptUrl) continue;
+      try {
+        record.instance?.dispose?.();
+      } catch {
+      }
+      if (record.root) disposeBuiltObject(record.root);
+      this.instances.delete(entityId);
+    }
+    for (const [entityId, entry] of [...this.loading]) {
+      if (entry.key.includes(`:${scriptUrl}:`)) this.loading.delete(entityId);
+    }
+  }
+  dispose(world) {
+    for (const [entityId, record] of [...this.instances]) {
+      this.teardownRecord(world, entityId, record, false);
+    }
+    this.instances.clear();
+    this.loading.clear();
+  }
+};
+__name(_ScriptObjectSystem, "ScriptObjectSystem");
+var ScriptObjectSystem = _ScriptObjectSystem;
+
 // core/systems/TransformSyncSystem.ts
 var _TransformSyncSystem = class _TransformSyncSystem {
   update(world) {
@@ -6947,7 +7319,9 @@ exports.ObjectVisibilitySystem = ObjectVisibilitySystem;
 exports.PhysicsSyncSystem = PhysicsSyncSystem;
 exports.PostprocessingSyncSystem = PostprocessingSyncSystem;
 exports.RenderSystem = RenderSystem;
+exports.SCRIPT_OBJECT_ROOT_FLAG = SCRIPT_OBJECT_ROOT_FLAG;
 exports.ScriptBehaviourSystem = ScriptBehaviourSystem;
+exports.ScriptObjectSystem = ScriptObjectSystem;
 exports.TransformSyncSystem = TransformSyncSystem;
 exports.VideoSystem = VideoSystem;
 //# sourceMappingURL=index.cjs.map