@relu-interactives/spatial-ecs 0.2.21 → 0.2.23

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-me3iAcMF.cjs';
-export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-me3iAcMF.cjs';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-CYWZ_Zx5.cjs';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-CYWZ_Zx5.cjs';
 import * as THREE from 'three';
-import { O as Object3DRef } from './Video-U9hAnf9y.cjs';
-export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-U9hAnf9y.cjs';
-export { i as CoreComponents } from './index-CZo5I5Gs.cjs';
-export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, ScriptBehaviourSystem, SelectionContext, VideoSystem } from './systems/index.cjs';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
+import { O as Object3DRef } from './Video-ppAXaKt0.cjs';
+export { a6 as AnimationStateCallbacks, a7 as AnimationStateMachine, a8 as AnimationStateManager, a9 as StateMachine } from './Video-ppAXaKt0.cjs';
+export { i as CoreComponents } from './index-Cu2Pt7wN.cjs';
+export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ModuleLoader, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObjectSystem, SelectionContext, VideoSystem } from './systems/index.cjs';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import '@dimforge/rapier3d-compat';
 
@@ -25,15 +25,10 @@ interface CustomEcsSystem extends EcsSystem {
  * Override {@link Behaviour.onUpdate} for per-frame logic — never override
  * {@link Behaviour.update}, which is the engine-managed entry point.
  *
- * **Editor scripts**: By default, `Behaviour` subclasses do not run inside the
- * editor. Set `executeInEditor: true` on the script entry in the inspector to
- * enable the full lifecycle (`init` → `onUpdate` → `dispose`) while the editor
- * is open. This gives direct access to the Three.js scene, camera, and renderer
- * via {@link World.getScene}, {@link World.getCamera}, and
- * {@link World.getRenderer} — useful for custom shaders, procedural geometry,
- * grass, and any Three.js feature the editor's object palette does not expose.
- * Avoid mutating ECS component state every frame in editor mode, as it creates
- * undo history entries on every tick.
+ * **Editor vs runtime**: `Behaviour` subclasses run ONLY at preview/runtime —
+ * they never execute in the editor. For a visual that must render and animate
+ * inside the editor (custom shaders, procedural geometry, grass, anything the
+ * object palette can't produce), use {@link ScriptObject} instead.
  *
  * The runtime recognizes a script by its **default export** plus the
  * inherited static marker `__reluBehaviourClass`. Do not override the marker.
@@ -248,21 +243,13 @@ declare class Behaviour implements CustomEcsSystem {
     /**
      * 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.
      */
     protected init(): void;
     /**
      * 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).
      */
     protected onUpdate(): void;
     /** Called when the editor selects this entity. Optional UX hook. */
@@ -285,6 +272,105 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+/**
+ * Base class for **script objects** — entities whose THREE.js visual is built
+ * entirely by user code (procedural geometry, shaders, particle systems,
+ * anything the editor can't author natively).
+ *
+ * The critical difference from {@link Behaviour}: a `ScriptObject` runs in the
+ * **editor AND at runtime** — `build()` and `update()` execute identically in
+ * both. `ScriptObjectSystem` loads the module, instantiates the class, calls
+ * `build()` to get the visual, attaches it under the entity's Object3D, and
+ * ticks `update()` every frame. **Do NOT gate anything on
+ * `world.isEditorMode()`** — running everywhere is the whole point. Use
+ * {@link Behaviour} for gameplay logic that must NOT run in the editor.
+ *
+ * Subclasses are resolved by the inherited static marker
+ * `__reluScriptObjectClass` (survives bundler identity splits). Do not override
+ * the marker.
+ *
+ * @example
+ * ```ts
+ * import { ScriptObject, type ColorInput } from "@relu-interactives/spatial-ecs";
+ * import * as THREE from "three";
+ *
+ * export default class GlowOrb extends ScriptObject {
+ *   declare data: { color: ColorInput };
+ *   private mat!: THREE.MeshStandardMaterial;
+ *
+ *   build(): THREE.Object3D {
+ *     this.data.color ??= { type: "color", value: "#66ccff" };
+ *     this.mat = new THREE.MeshStandardMaterial({
+ *       color: this.data.color.value,
+ *       emissive: this.data.color.value,
+ *     });
+ *     return new THREE.Mesh(new THREE.SphereGeometry(0.5, 32, 32), this.mat);
+ *   }
+ *
+ *   update(dt: number): void {
+ *     this.mat.emissiveIntensity = 0.5 + 0.5 * Math.sin(performance.now() * 0.002);
+ *   }
+ *
+ *   dispose(): void {
+ *     this.mat.dispose();
+ *   }
+ * }
+ * ```
+ *
+ * @category Scripting
+ */
+declare class 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.
+     */
+    static readonly __reluScriptObjectClass: true;
+    /**
+     * 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.
+     */
+    data: Record<string, unknown>;
+    /** The owning ECS world. */
+    world: World;
+    /** The entity this script object is bound to. */
+    entityId: number;
+    /**
+     * The Object3D returned by {@link ScriptObject.build}. Assigned by
+     * `ScriptObjectSystem` after `build()` runs; `null` until then.
+     */
+    root: THREE.Object3D | null;
+    /**
+     * 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: World, entityId: number, data?: Record<string, unknown>);
+    /**
+     * 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(): THREE.Object3D;
+    /**
+     * OPTIONAL — per-frame hook. Runs in the editor AND at runtime (e.g. advance
+     * a shader time uniform, procedural animation). Keep per-frame work on local
+     * THREE state / uniforms — do NOT write ECS components every frame (that
+     * churns the editor's undo history).
+     */
+    update?(deltaTime: number): void;
+    /**
+     * OPTIONAL — free any GPU resources this script created (geometries,
+     * materials, textures, render targets). Called by `ScriptObjectSystem` when
+     * the object is removed, disabled, or reloaded. THREE `dispose()` is
+     * idempotent, so double-dispose is safe.
+     */
+    dispose?(): void;
+}
+
 type ComponentValueMaps = {
     object3DRefValues: Map<number, unknown>;
     nameValues: Map<number, unknown>;
@@ -306,6 +392,7 @@ type ComponentValueMaps = {
     animationValues: Map<number, unknown>;
     imageTargetAnchorValues: Map<number, unknown>;
     scriptValues: Map<number, unknown>;
+    scriptObjectValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
     prefabNodeValues: Map<number, unknown>;
@@ -540,6 +627,8 @@ declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, M
  * - entity-id fields → `{$node}` (internal) or raw id (external)
  * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
  *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - ScriptObjectComponent keeps only `{scriptUrl, className, enabled, data}`
+ *   (runtimeState/runtimeMessage are per-instance transients)
  * - Object3DRef keeps only `{visibility}` (the rest is a live object ref)
  *
  * Keep the id-bearing field list in sync with `snapshotIdUtils.ts`.
@@ -617,4 +706,4 @@ declare function serializeEntitySubtree(world: World, rootId: EntityId, options?
     maxDepth?: number;
 }): SerializeEntitySubtreeResult;
 
-export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };
+export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, ScriptObject, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-me3iAcMF.js';
-export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-me3iAcMF.js';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-CYWZ_Zx5.js';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-CYWZ_Zx5.js';
 import * as THREE from 'three';
-import { O as Object3DRef } from './Video-DHnxjGhW.js';
-export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-DHnxjGhW.js';
-export { i as CoreComponents } from './index-D7FSg0Au.js';
-export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, ScriptBehaviourSystem, SelectionContext, VideoSystem } from './systems/index.js';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
+import { O as Object3DRef } from './Video-C1IOat7L.js';
+export { a6 as AnimationStateCallbacks, a7 as AnimationStateMachine, a8 as AnimationStateManager, a9 as StateMachine } from './Video-C1IOat7L.js';
+export { i as CoreComponents } from './index-DdiWu1b6.js';
+export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ModuleLoader, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObjectSystem, SelectionContext, VideoSystem } from './systems/index.js';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import '@dimforge/rapier3d-compat';
 
@@ -25,15 +25,10 @@ interface CustomEcsSystem extends EcsSystem {
  * Override {@link Behaviour.onUpdate} for per-frame logic — never override
  * {@link Behaviour.update}, which is the engine-managed entry point.
  *
- * **Editor scripts**: By default, `Behaviour` subclasses do not run inside the
- * editor. Set `executeInEditor: true` on the script entry in the inspector to
- * enable the full lifecycle (`init` → `onUpdate` → `dispose`) while the editor
- * is open. This gives direct access to the Three.js scene, camera, and renderer
- * via {@link World.getScene}, {@link World.getCamera}, and
- * {@link World.getRenderer} — useful for custom shaders, procedural geometry,
- * grass, and any Three.js feature the editor's object palette does not expose.
- * Avoid mutating ECS component state every frame in editor mode, as it creates
- * undo history entries on every tick.
+ * **Editor vs runtime**: `Behaviour` subclasses run ONLY at preview/runtime —
+ * they never execute in the editor. For a visual that must render and animate
+ * inside the editor (custom shaders, procedural geometry, grass, anything the
+ * object palette can't produce), use {@link ScriptObject} instead.
  *
  * The runtime recognizes a script by its **default export** plus the
  * inherited static marker `__reluBehaviourClass`. Do not override the marker.
@@ -248,21 +243,13 @@ declare class Behaviour implements CustomEcsSystem {
     /**
      * 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.
      */
     protected init(): void;
     /**
      * 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).
      */
     protected onUpdate(): void;
     /** Called when the editor selects this entity. Optional UX hook. */
@@ -285,6 +272,105 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+/**
+ * Base class for **script objects** — entities whose THREE.js visual is built
+ * entirely by user code (procedural geometry, shaders, particle systems,
+ * anything the editor can't author natively).
+ *
+ * The critical difference from {@link Behaviour}: a `ScriptObject` runs in the
+ * **editor AND at runtime** — `build()` and `update()` execute identically in
+ * both. `ScriptObjectSystem` loads the module, instantiates the class, calls
+ * `build()` to get the visual, attaches it under the entity's Object3D, and
+ * ticks `update()` every frame. **Do NOT gate anything on
+ * `world.isEditorMode()`** — running everywhere is the whole point. Use
+ * {@link Behaviour} for gameplay logic that must NOT run in the editor.
+ *
+ * Subclasses are resolved by the inherited static marker
+ * `__reluScriptObjectClass` (survives bundler identity splits). Do not override
+ * the marker.
+ *
+ * @example
+ * ```ts
+ * import { ScriptObject, type ColorInput } from "@relu-interactives/spatial-ecs";
+ * import * as THREE from "three";
+ *
+ * export default class GlowOrb extends ScriptObject {
+ *   declare data: { color: ColorInput };
+ *   private mat!: THREE.MeshStandardMaterial;
+ *
+ *   build(): THREE.Object3D {
+ *     this.data.color ??= { type: "color", value: "#66ccff" };
+ *     this.mat = new THREE.MeshStandardMaterial({
+ *       color: this.data.color.value,
+ *       emissive: this.data.color.value,
+ *     });
+ *     return new THREE.Mesh(new THREE.SphereGeometry(0.5, 32, 32), this.mat);
+ *   }
+ *
+ *   update(dt: number): void {
+ *     this.mat.emissiveIntensity = 0.5 + 0.5 * Math.sin(performance.now() * 0.002);
+ *   }
+ *
+ *   dispose(): void {
+ *     this.mat.dispose();
+ *   }
+ * }
+ * ```
+ *
+ * @category Scripting
+ */
+declare class 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.
+     */
+    static readonly __reluScriptObjectClass: true;
+    /**
+     * 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.
+     */
+    data: Record<string, unknown>;
+    /** The owning ECS world. */
+    world: World;
+    /** The entity this script object is bound to. */
+    entityId: number;
+    /**
+     * The Object3D returned by {@link ScriptObject.build}. Assigned by
+     * `ScriptObjectSystem` after `build()` runs; `null` until then.
+     */
+    root: THREE.Object3D | null;
+    /**
+     * 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: World, entityId: number, data?: Record<string, unknown>);
+    /**
+     * 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(): THREE.Object3D;
+    /**
+     * OPTIONAL — per-frame hook. Runs in the editor AND at runtime (e.g. advance
+     * a shader time uniform, procedural animation). Keep per-frame work on local
+     * THREE state / uniforms — do NOT write ECS components every frame (that
+     * churns the editor's undo history).
+     */
+    update?(deltaTime: number): void;
+    /**
+     * OPTIONAL — free any GPU resources this script created (geometries,
+     * materials, textures, render targets). Called by `ScriptObjectSystem` when
+     * the object is removed, disabled, or reloaded. THREE `dispose()` is
+     * idempotent, so double-dispose is safe.
+     */
+    dispose?(): void;
+}
+
 type ComponentValueMaps = {
     object3DRefValues: Map<number, unknown>;
     nameValues: Map<number, unknown>;
@@ -306,6 +392,7 @@ type ComponentValueMaps = {
     animationValues: Map<number, unknown>;
     imageTargetAnchorValues: Map<number, unknown>;
     scriptValues: Map<number, unknown>;
+    scriptObjectValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
     prefabNodeValues: Map<number, unknown>;
@@ -540,6 +627,8 @@ declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, M
  * - entity-id fields → `{$node}` (internal) or raw id (external)
  * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
  *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - ScriptObjectComponent keeps only `{scriptUrl, className, enabled, data}`
+ *   (runtimeState/runtimeMessage are per-instance transients)
  * - Object3DRef keeps only `{visibility}` (the rest is a live object ref)
  *
  * Keep the id-bearing field list in sync with `snapshotIdUtils.ts`.
@@ -617,4 +706,4 @@ declare function serializeEntitySubtree(world: World, rootId: EntityId, options?
     maxDepth?: number;
 }): SerializeEntitySubtreeResult;
 
-export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };
+export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, ScriptObject, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };

package/dist/index.js

@@ -1,11 +1,11 @@
-import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-5U3YS4JD.js';
-export { ADDED_NODE_MARKER_COMPONENT, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, ScriptBehaviourSystem, TransformSyncSystem, VideoSystem, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-5U3YS4JD.js';
-import { registerDefaultFactories } from './chunk-K6KMKKJ6.js';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-K6KMKKJ6.js';
-import { ObjectManagementSystem } from './chunk-AXRCGF63.js';
-export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-AXRCGF63.js';
-import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-V7BNVTJW.js';
-export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents } from './chunk-V7BNVTJW.js';
+import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-7BEZBIVB.js';
+export { ADDED_NODE_MARKER_COMPONENT, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, TransformSyncSystem, VideoSystem, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-7BEZBIVB.js';
+import { registerDefaultFactories } from './chunk-52CHDPRQ.js';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-52CHDPRQ.js';
+import { ObjectManagementSystem } from './chunk-WKGCC7YL.js';
+export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-WKGCC7YL.js';
+import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-JHCPRVBC.js';
+export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents } from './chunk-JHCPRVBC.js';
 import './chunk-QHILSPT4.js';
 import { normalizeDebugValue, DEBUG_CHANGE_IGNORED_SYSTEMS, cloneHistoryValue } from './chunk-ZXGHKX7N.js';
 import { __name } from './chunk-OY7ZODZP.js';
@@ -1037,6 +1037,11 @@ function remapSnapshotEntityIds(snapshot, idMap, options) {
             };
           });
         }
+      } else if (block.component === "ScriptObjectComponent" && record) {
+        const data = asRecord(record.data);
+        if (data) {
+          record.data = remapScriptData(data, idMap, nullExternal, warn);
+        }
       } else if (block.component === "InstancedMeshComponent" && record) {
         if (Array.isArray(record.instanceEntityIds)) {
           const remapped = [];