@scenoco-three/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SceNoCo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @scenoco-three/core
+
+The **runtime** of [SceNoCo](https://github.com/) — a component-based scene framework for
+[Three.js](https://threejs.org). Scene · Node · Component, Unity/Cocos-shaped, with the
+scene compiled to a compact bundle the runtime loads. **No XML parser or validator ships
+here** — that lives in `@scenoco-three/compiler` (build time only).
+
+```ts
+import { Engine, Component, component, property } from '@scenoco-three/core';
+import sceneBundle from './scene.bundle.json'; // produced at build time
+
+@component({ name: 'Rotator', description: 'Spins the host around Y' })
+export class Rotator extends Component {
+  @property({ type: 'float', default: 1 }) speed = 1;
+  override update(dt: number) { this.node.rotation.y += this.speed * dt; }
+}
+
+const engine = new Engine({ canvas });
+engine.loadScene(sceneBundle);
+```
+
+## What's in here
+
+- `Engine` — owns the `THREE.Scene`, the render loop, component lifecycles, the `System`
+  seam, prefab instantiation, and the bundle deserializer.
+- `Component` — typed host nodes, typed `@property` references, lifecycle hooks.
+- `PrefabRef` — what a `@property({ type: 'prefab' })` field receives; `spawn()` instantiates
+  a build-time-embedded prefab.
+- The extensible node/attachment registry and the bundle wire format.
+
+`three` is a peer dependency. See the [repository](../../README.md) and
+[ARCHITECTURE.md](../../ARCHITECTURE.md) for the full design.
+
+## License
+
+[MIT](./LICENSE)

package/dist/components/Follow.d.ts

@@ -0,0 +1,15 @@
+import { Vector3 } from 'three';
+import { Component } from '../core/Component.js';
+import { Oscillator } from './Oscillator.js';
+/**
+ * Moves the host along an axis by another Oscillator's current offset —
+ * a typed component-to-component reference (Unity/Cocos style).
+ */
+export declare class Follow extends Component {
+    source: Oscillator | null;
+    axis: Vector3;
+    scale: number;
+    private readonly origin;
+    onLoad(): void;
+    update(): void;
+}

package/dist/components/Follow.js

@@ -0,0 +1,41 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Vector3 } from 'three';
+import { Component } from '../core/Component.js';
+import { component, property } from '../core/decorators.js';
+import { Oscillator } from './Oscillator.js';
+/**
+ * Moves the host along an axis by another Oscillator's current offset —
+ * a typed component-to-component reference (Unity/Cocos style).
+ */
+let Follow = class Follow extends Component {
+    source = null;
+    axis = new Vector3(0, 1, 0);
+    scale = 1;
+    origin = new Vector3();
+    onLoad() {
+        this.origin.copy(this.node.position);
+    }
+    update() {
+        if (!this.source)
+            return;
+        this.node.position.copy(this.origin).addScaledVector(this.axis, this.source.offset * this.scale);
+    }
+};
+__decorate([
+    property(Oscillator)
+], Follow.prototype, "source", void 0);
+__decorate([
+    property({ type: 'vec3', default: '0 1 0', description: 'Direction the offset is applied along' })
+], Follow.prototype, "axis", void 0);
+__decorate([
+    property({ type: 'float', default: 1, description: 'Multiplier on the source offset' })
+], Follow.prototype, "scale", void 0);
+Follow = __decorate([
+    component({ name: 'Follow', description: "Offsets the host along an axis by another Oscillator's value" })
+], Follow);
+export { Follow };

package/dist/components/LookAt.d.ts

@@ -0,0 +1,11 @@
+import type { Object3D } from 'three';
+import { Component } from '../core/Component.js';
+/**
+ * Orients the host so its -Z axis points at a target Object3D — a typed
+ * `node` reference, resolved from another node's name in XML.
+ */
+export declare class LookAt extends Component {
+    target: Object3D | null;
+    private readonly worldPos;
+    update(): void;
+}

package/dist/components/LookAt.js

@@ -0,0 +1,30 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Vector3 } from 'three';
+import { Component } from '../core/Component.js';
+import { component, property } from '../core/decorators.js';
+/**
+ * Orients the host so its -Z axis points at a target Object3D — a typed
+ * `node` reference, resolved from another node's name in XML.
+ */
+let LookAt = class LookAt extends Component {
+    target = null;
+    worldPos = new Vector3();
+    update() {
+        if (!this.target)
+            return;
+        this.target.getWorldPosition(this.worldPos);
+        this.node.lookAt(this.worldPos);
+    }
+};
+__decorate([
+    property({ type: 'node', description: 'Node to face' })
+], LookAt.prototype, "target", void 0);
+LookAt = __decorate([
+    component({ name: 'LookAt', description: 'Rotates the host to face a target Object3D each frame' })
+], LookAt);
+export { LookAt };

package/dist/components/Oscillator.d.ts

@@ -0,0 +1,13 @@
+import { Vector3 } from 'three';
+import { Component } from '../core/Component.js';
+export declare class Oscillator extends Component {
+    axis: Vector3;
+    amplitude: number;
+    frequency: number;
+    /** Current offset along the axis — read this via a typed reference. */
+    offset: number;
+    private elapsed;
+    private readonly origin;
+    onLoad(): void;
+    update(dt: number): void;
+}

package/dist/components/Oscillator.js

@@ -0,0 +1,42 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Vector3 } from 'three';
+import { Component } from '../core/Component.js';
+import { component, property } from '../core/decorators.js';
+let Oscillator = class Oscillator extends Component {
+    axis = new Vector3(0, 1, 0);
+    amplitude = 1;
+    frequency = 1;
+    /** Current offset along the axis — read this via a typed reference. */
+    offset = 0;
+    elapsed = 0;
+    origin = new Vector3();
+    onLoad() {
+        this.origin.copy(this.node.position);
+    }
+    update(dt) {
+        this.elapsed += dt;
+        this.offset = Math.sin(this.elapsed * this.frequency * Math.PI * 2) * this.amplitude;
+        this.node.position.copy(this.origin).addScaledVector(this.axis, this.offset);
+    }
+};
+__decorate([
+    property({ type: 'vec3', default: '0 1 0', description: 'Movement axis in local space' })
+], Oscillator.prototype, "axis", void 0);
+__decorate([
+    property({ type: 'float', default: 1, description: 'Peak offset distance from the start position' })
+], Oscillator.prototype, "amplitude", void 0);
+__decorate([
+    property({ type: 'float', default: 1, description: 'Oscillations per second' })
+], Oscillator.prototype, "frequency", void 0);
+Oscillator = __decorate([
+    component({
+        name: 'Oscillator',
+        description: 'Moves the host node back and forth along an axis as a sine wave',
+    })
+], Oscillator);
+export { Oscillator };

package/dist/components/Rotator.d.ts

@@ -0,0 +1,5 @@
+import { Component } from '../core/Component.js';
+export declare class Rotator extends Component {
+    speed: number;
+    update(dt: number): void;
+}

package/dist/components/Rotator.js

@@ -0,0 +1,21 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Component } from '../core/Component.js';
+import { component, property } from '../core/decorators.js';
+let Rotator = class Rotator extends Component {
+    speed = 1;
+    update(dt) {
+        this.node.rotation.y += this.speed * dt;
+    }
+};
+__decorate([
+    property({ type: 'float', default: 1, description: 'Rotation speed in radians per second' })
+], Rotator.prototype, "speed", void 0);
+Rotator = __decorate([
+    component({ name: 'Rotator', description: 'Rotates the host node around its Y axis over time' })
+], Rotator);
+export { Rotator };

package/dist/core/Component.d.ts

@@ -0,0 +1,60 @@
+import type { Object3D } from 'three';
+import type { Engine } from './Engine.js';
+/**
+ * Base class for all SceNoCo components (Cocos Creator / Unity MonoBehaviour style).
+ *
+ * Lifecycle, driven by the Engine:
+ *   onLoad    — once, immediately when the component is attached
+ *   onEnable  — when the component becomes enabled (incl. right after onLoad)
+ *   start     — once, on the first update tick while enabled
+ *   update    — every tick while enabled
+ *   onDisable — when the component becomes disabled
+ *   onDestroy — once, when the component is removed or the engine is disposed
+ *
+ * Components share data through typed references — a field declared with
+ * `@property(SomeComponent)` holds a live instance of that component — not
+ * through any global bus.
+ *
+ * `TNode` types the host node. A component attached to a specific kind of node
+ * declares it and gets typed access with no casts:
+ *
+ *   class CameraRig extends Component<PerspectiveCamera> {
+ *     override start() { this.node.fov = 60; this.node.updateProjectionMatrix(); }
+ *   }
+ *
+ * The default `Object3D` keeps every plain component source-compatible.
+ */
+export declare abstract class Component<TNode extends Object3D = Object3D> {
+    /** Host node (typed by `TNode`). Assigned by the engine before onLoad. */
+    node: TNode;
+    /** Owning engine. Assigned by the engine before onLoad. */
+    engine: Engine;
+    /** Author-assigned scene id, if any (from `id="…"` in XML). Used by `engine.findComponent`. */
+    id?: string;
+    /** @internal set by the engine after onLoad has run */
+    _loaded: boolean;
+    /** @internal set by the engine when start has run */
+    _started: boolean;
+    private _enabled;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /** First component of the given type on the same node, or null (Unity/Cocos style). */
+    getComponent<T extends Component>(type: abstract new () => T): T | null;
+    /** Remove this component from the engine, running onDisable/onDestroy (Cocos style). */
+    destroy(): void;
+    onLoad?(): void;
+    onEnable?(): void;
+    start?(): void;
+    /** Variable-rate tick, once per frame (dt = real seconds since last frame). */
+    update?(dt: number): void;
+    /**
+     * Fixed-rate tick, for physics and anything that needs a deterministic step.
+     * Called zero or more times per frame at `engine.fixedTimeStep` before
+     * `update`. Runs after each physics-subsystem fixed step (see EngineSystem).
+     */
+    fixedUpdate?(fixedDt: number): void;
+    /** Runs after every component's `update` in the same frame (camera follow, etc.). */
+    lateUpdate?(dt: number): void;
+    onDisable?(): void;
+    onDestroy?(): void;
+}

package/dist/core/Component.js

@@ -0,0 +1,63 @@
+/**
+ * Base class for all SceNoCo components (Cocos Creator / Unity MonoBehaviour style).
+ *
+ * Lifecycle, driven by the Engine:
+ *   onLoad    — once, immediately when the component is attached
+ *   onEnable  — when the component becomes enabled (incl. right after onLoad)
+ *   start     — once, on the first update tick while enabled
+ *   update    — every tick while enabled
+ *   onDisable — when the component becomes disabled
+ *   onDestroy — once, when the component is removed or the engine is disposed
+ *
+ * Components share data through typed references — a field declared with
+ * `@property(SomeComponent)` holds a live instance of that component — not
+ * through any global bus.
+ *
+ * `TNode` types the host node. A component attached to a specific kind of node
+ * declares it and gets typed access with no casts:
+ *
+ *   class CameraRig extends Component<PerspectiveCamera> {
+ *     override start() { this.node.fov = 60; this.node.updateProjectionMatrix(); }
+ *   }
+ *
+ * The default `Object3D` keeps every plain component source-compatible.
+ */
+export class Component {
+    /** Host node (typed by `TNode`). Assigned by the engine before onLoad. */
+    node;
+    /** Owning engine. Assigned by the engine before onLoad. */
+    engine;
+    /** Author-assigned scene id, if any (from `id="…"` in XML). Used by `engine.findComponent`. */
+    id;
+    /** @internal set by the engine after onLoad has run */
+    _loaded = false;
+    /** @internal set by the engine when start has run */
+    _started = false;
+    _enabled = true;
+    get enabled() {
+        return this._enabled;
+    }
+    set enabled(value) {
+        if (value === this._enabled)
+            return;
+        this._enabled = value;
+        if (this._loaded) {
+            if (value)
+                this.onEnable?.();
+            else
+                this.onDisable?.();
+        }
+    }
+    /** First component of the given type on the same node, or null (Unity/Cocos style). */
+    getComponent(type) {
+        for (const c of this.engine.getComponents(this.node)) {
+            if (c instanceof type)
+                return c;
+        }
+        return null;
+    }
+    /** Remove this component from the engine, running onDisable/onDestroy (Cocos style). */
+    destroy() {
+        this.engine.removeComponent(this);
+    }
+}

package/dist/core/Engine.d.ts

@@ -0,0 +1,169 @@
+import { type Camera, PerspectiveCamera, Scene, WebGLRenderer } from 'three';
+import type { Object3D } from 'three';
+import type { Component } from './Component.js';
+import type { System } from './System.js';
+import { type Bundle } from '../dsl/bundle-format.js';
+import type { CompiledScene } from '../dsl/compiled.js';
+import { type AttachmentInstance } from '../dsl/nodes.js';
+export interface EngineOptions {
+    /** Render target. Omit for headless use (tests, CLI tooling, validation). */
+    canvas?: HTMLCanvasElement;
+    /** Start the render loop immediately when a canvas is given. Default true. */
+    autoStart?: boolean;
+    /** Seconds per fixed step (physics + `fixedUpdate`). Default 1/60. */
+    fixedTimeStep?: number;
+}
+/**
+ * A spawned prefab/subtree (from `engine.instantiate`). Hold onto it to remove
+ * the subtree later — Unity/Cocos `Instantiate` → `Destroy`.
+ */
+export interface SceneInstance {
+    /** Root Object3D of the spawned subtree. */
+    readonly root: Object3D;
+    /** Remove the subtree, destroy its components, and free its GPU resources. */
+    destroy(): void;
+}
+/**
+ * Core runtime: owns the Three.js scene graph, the render loop, and the
+ * lifecycles of all attached components.
+ *
+ * Without a canvas the engine runs headless — `tick(dt)` advances the
+ * simulation manually, which is how tests and CLI tooling drive it.
+ */
+export declare class Engine {
+    readonly scene: Scene<import("three").Object3DEventMap>;
+    /** The engine's built-in fallback camera, used until a scene supplies one. */
+    readonly camera: PerspectiveCamera;
+    readonly renderer?: WebGLRenderer;
+    /** Camera the renderer currently draws through (defaults to `camera`). */
+    private activeCamera;
+    private readonly components;
+    private readonly byNode;
+    private readonly byId;
+    private readonly systems;
+    /** Each running system → the component type its `components` query is kept in sync with. */
+    private readonly systemQueries;
+    private readonly rendererSize;
+    /** Seconds per fixed step; accumulator carries leftover frame time. */
+    private readonly fixedTimeStep;
+    private fixedAccumulator;
+    private rafId?;
+    private lastFrameTime?;
+    /** Root object of the currently loaded scene (from loadScene), if any. */
+    private sceneRoot?;
+    /** Components owned by the loaded scene — the only ones disposeScene removes. */
+    private sceneComponents;
+    /** Systems auto-run for the loaded scene — removed on unload. */
+    private sceneSystems;
+    /** Live attachment instances of the loaded scene (retained for findAttachment). */
+    private sceneAttachments;
+    /** Live spawned subtrees (from instantiate), so dispose() can clean them up. */
+    private readonly instances;
+    constructor(options?: EngineOptions);
+    /**
+     * Attach a component to a node, by constructor or by registered name.
+     * Runs onLoad (and onEnable if enabled); start runs on the next tick.
+     */
+    addComponent<T extends Component>(node: Object3D, type: new () => T, props?: Partial<T>): T;
+    addComponent(node: Object3D, type: string, props?: Record<string, unknown>): Component;
+    /** Bookkeeping only: track the instance without running any lifecycle hook. */
+    private registerComponent;
+    /** Run onLoad + onEnable for an already-registered instance. */
+    private initComponent;
+    /** Detach a component, running onDisable (if enabled) and onDestroy. */
+    removeComponent(instance: Component): void;
+    getComponents(node: Object3D): readonly Component[];
+    /**
+     * Register an engine subsystem instance. Injects `system.engine`, seeds its
+     * `components` query (from its `@system(Type)` registration), and runs
+     * `onAttach`. Usually the engine does this for you (a registered `@system`
+     * auto-runs when its component type appears); call it directly for manual use.
+     */
+    addSystem<T extends System>(system: T): T;
+    /** The first running system assignable to `type` (Unity GetComponent style). */
+    getSystem<T extends System>(type: abstract new (...args: never[]) => T): T | undefined;
+    /** Remove a subsystem, running its `onDetach`. */
+    removeSystem(system: System): void;
+    /**
+     * The live instance of an attachment type in the loaded scene (e.g. a system
+     * reads `engine.findAttachment(Physics)?.gravity`). Singleton config attachments
+     * are the typical use.
+     */
+    findAttachment<T extends AttachmentInstance>(type: abstract new (...args: never[]) => T): T | undefined;
+    /**
+     * Find an Object3D by its scene `id` (e.g. `findObject('Turbine_01')`, or a
+     * scoped prefab-instance internal `findObject('t1/blade')`). Searches the whole
+     * loaded scene and any spawned instances; returns the first match.
+     */
+    findObject(id: string): Object3D | undefined;
+    /**
+     * Find a component by id — mirroring the `#id` references used in XML. Resolves
+     * a component's own id first; failing that, treats `id` as a node id and returns
+     * the (first) component on that node, optionally narrowed to `type`.
+     *
+     * `type` may be a class reference OR a registered component name string (e.g.
+     * `'GameManager'`). The string form avoids the `import type` footgun: a type-only
+     * import is erased at runtime, making the class reference undefined.
+     */
+    findComponent<T extends Component = Component>(id: string, type?: (abstract new () => T) | string): T | undefined;
+    /** The camera the renderer draws through (a scene camera if one is active). */
+    get renderCamera(): Camera;
+    /**
+     * Render through a specific camera — e.g. one defined in the scene
+     * (`engine.setActiveCamera(engine.findObject('Main')!)`). `loadScene` already
+     * auto-selects the first camera it finds; this is for switching afterwards.
+     * Pass nothing to revert to the engine's built-in camera.
+     */
+    setActiveCamera(camera?: Camera): void;
+    /**
+     * Load a scene from a pre-built bundle (or a CompiledScene), replacing any
+     * current one. Bundles are produced at build time by `scenoco/compiler`; the
+     * runtime never parses or validates XML. All components are instantiated and
+     * their references wired before any onLoad runs, so cross-component refs are
+     * valid from the first lifecycle hook.
+     *
+     * If the scene defines a camera, it becomes the active render camera; the
+     * engine's built-in camera is the fallback when it doesn't.
+     */
+    loadScene(source: Bundle | CompiledScene): void;
+    /** Instantiate + run each registered @system whose component type is present. */
+    private runSceneSystems;
+    /**
+     * Spawn a prefab (or any bundle/CompiledScene) as a subtree under `parent`
+     * (the scene root by default), at runtime — Unity/Cocos `Instantiate`.
+     * Returns a handle whose `destroy()` removes just this subtree; the loaded
+     * scene and other instances are untouched. References inside the prefab are
+     * already wired by index, so spawning the same prefab many times is safe.
+     */
+    instantiate(source: Bundle | CompiledScene, parent?: Object3D): SceneInstance;
+    /**
+     * Context for `instantiateScene`: the live scene/renderer (for attachments)
+     * and how a `prefab` prop spawns — `engine.instantiate`, so spawned subtrees
+     * are tracked and torn down by `dispose()`.
+     */
+    private instantiateContext;
+    /** Register + run onLoad/onEnable for a freshly instantiated subtree. */
+    private initLive;
+    /**
+     * Remove the loaded scene: destroy its components (only those owned by the
+     * scene — manually attached ones and spawned instances survive) and release
+     * its GPU resources.
+     */
+    disposeScene(): void;
+    /**
+     * Advance the simulation by dt seconds, then render if a renderer exists.
+     * Phases, in order: fixed steps (`fixedUpdate` + subsystem `fixedStep`,
+     * repeated to drain the accumulator) → `start`/`update` → `lateUpdate` →
+     * subsystem `step` → render. Variable `update` still runs exactly once per
+     * tick, so existing components are unaffected.
+     */
+    tick(dt: number): void;
+    /** One fixed step: components' fixedUpdate (apply forces/read), then subsystems step. */
+    private fixedStep;
+    /** Start the requestAnimationFrame loop (no-op when already running or headless). */
+    start(): void;
+    stop(): void;
+    /** Stop the loop, destroy all components/instances/subsystems, free GPU resources. */
+    dispose(): void;
+    private resizeToCanvas;
+}