@gg-web-engine/core 0.0.58 → 0.0.59

package/dist/base/blueprint/blueprint-node.d.ts

@@ -0,0 +1,75 @@
+import { Observable } from 'rxjs';
+import { GgWorld, GgWorldTypeDocRepo } from '../gg-world';
+/**
+ * Whether a {@link BlueprintNode} pin carries an execution pulse ("do this now", no meaningful
+ * payload - e.g. Unreal's white exec pins) or a data value ("here's a value", not itself a
+ * trigger - e.g. Unreal's colored data pins). Purely descriptive for now (introspection/future
+ * editor tooling) - {@link BlueprintNode.trigger} treats every input pin the same way at runtime,
+ * since a node is free to both react to and read a value from the same pin (see
+ * {@link RemoveEntityBlueprintNode}, whose single `"entity"` pin is a data pin that also triggers
+ * the node when fed a value - the same way an Unreal event node's payload pins double as the
+ * thing that fires the node).
+ */
+export type BlueprintPinKind = 'exec' | 'data';
+/**
+ * Declares one named pin a {@link BlueprintNode} exposes - either an input (fed a value via
+ * {@link BlueprintNode.trigger}) or an output (fired via {@link BlueprintNode.output}).
+ */
+export interface BlueprintPinDefinition {
+    name: string;
+    kind: BlueprintPinKind;
+}
+/**
+ * One node in a {@link Blueprint} graph - the engine's analogue of a single Unreal Blueprint graph
+ * node: a small unit of behavior with named input pins that trigger it, named output pins it can
+ * fire in response, and a `settings` bag of static (non-pin) configuration baked in from its
+ * {@link BlueprintNodeJson} (e.g. `RemoveEntity`'s `dispose` flag). Register a concrete subclass's
+ * factory against a type alias via `LevelLoader.registerBlueprintNode` so `Blueprint` can
+ * instantiate it from JSON, the same way `LevelLoader.registerClass` works for entity classes.
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export declare abstract class BlueprintNode<D = any, R = any, TypeDoc extends GgWorldTypeDocRepo<D, R> = GgWorldTypeDocRepo<D, R>> {
+    protected readonly world: GgWorld<D, R, TypeDoc>;
+    protected readonly settings: Record<string, any>;
+    /**
+     * This node's input pins - see {@link trigger} for how they're fed.
+     */
+    abstract readonly inputs: readonly BlueprintPinDefinition[];
+    /**
+     * This node's output pins - see {@link output} for how to observe them.
+     */
+    abstract readonly outputs: readonly BlueprintPinDefinition[];
+    private readonly outputSubjects;
+    constructor(world: GgWorld<D, R, TypeDoc>, settings: Record<string, any>);
+    private subjectFor;
+    /**
+     * Observe one of this node's output pins firing - what a {@link BlueprintLinkJson} subscribes
+     * to in order to feed a downstream node's input, or what an embedding `Blueprint`'s own
+     * `outputs` entry bubbles up to whatever triggered the blueprint.
+     * @param name - The output pin's name, per {@link outputs}
+     */
+    output(name: string): Observable<unknown>;
+    /**
+     * Fire one of this node's output pins - call from within {@link trigger} once the node has done
+     * whatever that output represents. A no-op if nothing is subscribed.
+     * @param name - The output pin's name, per {@link outputs}
+     * @param value - Payload for a data output pin; omit for a bare exec pulse
+     */
+    protected emit(name: string, value?: unknown): void;
+    /**
+     * Feed a value/pulse into one of this node's input pins (per {@link inputs}), running whatever
+     * behavior that pin represents. Called by `Blueprint` both for external triggers (via its own
+     * `inputs` aliasing) and for links from another node's output pin.
+     * @param inputName - The input pin's name, per {@link inputs}
+     * @param value - Payload carried in on a data pin, if any
+     */
+    abstract trigger(inputName: string, value?: unknown): void;
+    /**
+     * Release anything this node set up outside of its output subjects (timers, subscriptions,
+     * etc). Default no-op - override when a node needs it. `Blueprint.dispose` calls this on every
+     * node in its graph.
+     */
+    dispose(): void;
+}

package/dist/base/blueprint/blueprint-node.js

@@ -0,0 +1,51 @@
+import { Subject } from 'rxjs';
+/**
+ * One node in a {@link Blueprint} graph - the engine's analogue of a single Unreal Blueprint graph
+ * node: a small unit of behavior with named input pins that trigger it, named output pins it can
+ * fire in response, and a `settings` bag of static (non-pin) configuration baked in from its
+ * {@link BlueprintNodeJson} (e.g. `RemoveEntity`'s `dispose` flag). Register a concrete subclass's
+ * factory against a type alias via `LevelLoader.registerBlueprintNode` so `Blueprint` can
+ * instantiate it from JSON, the same way `LevelLoader.registerClass` works for entity classes.
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export class BlueprintNode {
+    constructor(world, settings) {
+        this.world = world;
+        this.settings = settings;
+        this.outputSubjects = new Map();
+    }
+    subjectFor(name) {
+        let subject = this.outputSubjects.get(name);
+        if (!subject) {
+            subject = new Subject();
+            this.outputSubjects.set(name, subject);
+        }
+        return subject;
+    }
+    /**
+     * Observe one of this node's output pins firing - what a {@link BlueprintLinkJson} subscribes
+     * to in order to feed a downstream node's input, or what an embedding `Blueprint`'s own
+     * `outputs` entry bubbles up to whatever triggered the blueprint.
+     * @param name - The output pin's name, per {@link outputs}
+     */
+    output(name) {
+        return this.subjectFor(name).asObservable();
+    }
+    /**
+     * Fire one of this node's output pins - call from within {@link trigger} once the node has done
+     * whatever that output represents. A no-op if nothing is subscribed.
+     * @param name - The output pin's name, per {@link outputs}
+     * @param value - Payload for a data output pin; omit for a bare exec pulse
+     */
+    emit(name, value) {
+        this.subjectFor(name).next(value);
+    }
+    /**
+     * Release anything this node set up outside of its output subjects (timers, subscriptions,
+     * etc). Default no-op - override when a node needs it. `Blueprint.dispose` calls this on every
+     * node in its graph.
+     */
+    dispose() { }
+}

package/dist/base/blueprint/blueprint.d.ts

@@ -0,0 +1,123 @@
+import { Observable } from 'rxjs';
+import { GgWorld, GgWorldTypeDocRepo } from '../gg-world';
+import { BlueprintNode } from './blueprint-node';
+/**
+ * A function that builds a {@link BlueprintNode} instance from its baked-in settings. Registered
+ * against a node type alias via `LevelLoader.registerBlueprintNode`, the same way
+ * {@link EntityGenerator} is registered against an entity class alias via `registerClass`.
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export type BlueprintNodeFactory<D, R, TypeDoc extends GgWorldTypeDocRepo<D, R>> = (world: GgWorld<D, R, TypeDoc>, settings: Record<string, any>) => BlueprintNode<D, R, TypeDoc>;
+/**
+ * A reference to one named pin on one node within a {@link BlueprintJson} graph - either end of a
+ * {@link BlueprintLinkJson}, or what a graph's own `inputs`/`outputs` entry aliases.
+ */
+export interface BlueprintPinRef {
+    /**
+     * `id` of the node within the same `BlueprintJson.nodes` array
+     */
+    node: string;
+    /**
+     * Pin name on that node, per its `BlueprintNode.inputs`/`outputs`
+     */
+    pin: string;
+}
+/**
+ * JSON description of a single node instance within a {@link BlueprintJson} graph.
+ */
+export interface BlueprintNodeJson {
+    /**
+     * Identifier for this node instance, unique within the same graph - referenced by
+     * `BlueprintLinkJson`/`BlueprintJson.inputs`/`BlueprintJson.outputs`.
+     */
+    id: string;
+    /**
+     * Node type alias, matching a type registered via `LevelLoader.registerBlueprintNode` (e.g. the
+     * built-in `"RemoveEntity"`).
+     */
+    type: string;
+    /**
+     * Static settings baked into the node (e.g. `RemoveEntity`'s `dispose` flag) - not wired at
+     * runtime, unlike a pin.
+     */
+    settings?: Record<string, any>;
+}
+/**
+ * JSON description of one wire connecting one node's output pin to another node's input pin
+ * within the same {@link BlueprintJson} graph. Whenever `from` fires, `to` is triggered with
+ * whatever value (if any) `from` fired with.
+ */
+export interface BlueprintLinkJson {
+    from: BlueprintPinRef;
+    to: BlueprintPinRef;
+}
+/**
+ * A blueprint graph, serializable as a single JSON document - the engine's analogue of an Unreal
+ * Blueprint event graph. `nodes` are node instances (see {@link BlueprintNodeJson}), `links` wire
+ * one node's output pin to another's input pin, and `inputs`/`outputs` expose named entry/exit
+ * points at the graph's own boundary - each aliasing one node's pin - so embedding code (or, in
+ * the future, another blueprint nesting this one) doesn't need to know internal node ids. A level
+ * JSON references a `BlueprintJson` by name via its top-level `blueprints` map and an entity's
+ * `events` mapping - see `gg-engine-level-json`.
+ */
+export interface BlueprintJson {
+    /**
+     * Node instances in this graph
+     */
+    nodes: BlueprintNodeJson[];
+    /**
+     * Wires wiring one node's output pin to another node's input pin
+     */
+    links?: BlueprintLinkJson[];
+    /**
+     * Named entry points into this graph, each aliasing one node's input pin - e.g.
+     * `{ "in": { "node": "n1", "pin": "entity" } }` lets external code trigger `"n1"`'s `"entity"`
+     * pin by calling `blueprint.trigger("in", value)` without knowing the internal node id. A
+     * blueprint bound to a level JSON entity event is always triggered through the entry named
+     * `"in"` - see `gg-engine-level-json`.
+     */
+    inputs?: Record<string, BlueprintPinRef>;
+    /**
+     * Named exit points out of this graph, each aliasing one node's output pin - for a future
+     * blueprint nested inside a larger graph to bubble one of its own nodes' outputs back out.
+     */
+    outputs?: Record<string, BlueprintPinRef>;
+}
+/**
+ * Runtime instance of a {@link BlueprintJson} graph: builds one {@link BlueprintNode} per
+ * `nodes` entry (via the node type registry passed in), wires every `links` entry as a live
+ * subscription from the source node's output pin to the target node's input pin, and exposes the
+ * graph's own `inputs`/`outputs` boundary. Each binding of a blueprint (e.g. one level JSON entity
+ * event) gets its own `Blueprint` instance - and therefore its own node instances - even when
+ * multiple bindings reference the same `BlueprintJson` by name, so per-node state (a future timer
+ * node's countdown, etc) is never accidentally shared between unrelated bindings.
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export declare class Blueprint<D = any, R = any, TypeDoc extends GgWorldTypeDocRepo<D, R> = GgWorldTypeDocRepo<D, R>> {
+    private readonly json;
+    private readonly nodes;
+    private readonly linkSubscriptions;
+    constructor(world: GgWorld<D, R, TypeDoc>, json: BlueprintJson, registry: ReadonlyMap<string, BlueprintNodeFactory<D, R, TypeDoc>>);
+    /**
+     * Feed a value/pulse into one of this graph's named entry points (per `BlueprintJson.inputs`).
+     * A no-op (with a console warning) if no such input, or the node it aliases failed to build.
+     * @param inputName - Entry point name, per `BlueprintJson.inputs`
+     * @param value - Payload to hand to the aliased node's input pin, if any
+     */
+    trigger(inputName: string, value?: unknown): void;
+    /**
+     * Observe one of this graph's named exit points (per `BlueprintJson.outputs`) firing.
+     * @param outputName - Exit point name, per `BlueprintJson.outputs`
+     * @throws if no such output is declared, or the node it aliases failed to build
+     */
+    output(outputName: string): Observable<unknown>;
+    /**
+     * Unwire every link and dispose every node in this graph. Idempotent-ish - safe to call once
+     * per `Blueprint` instance, same lifetime contract as `IEntity.dispose`.
+     */
+    dispose(): void;
+}

package/dist/base/blueprint/blueprint.js

@@ -0,0 +1,86 @@
+/**
+ * Runtime instance of a {@link BlueprintJson} graph: builds one {@link BlueprintNode} per
+ * `nodes` entry (via the node type registry passed in), wires every `links` entry as a live
+ * subscription from the source node's output pin to the target node's input pin, and exposes the
+ * graph's own `inputs`/`outputs` boundary. Each binding of a blueprint (e.g. one level JSON entity
+ * event) gets its own `Blueprint` instance - and therefore its own node instances - even when
+ * multiple bindings reference the same `BlueprintJson` by name, so per-node state (a future timer
+ * node's countdown, etc) is never accidentally shared between unrelated bindings.
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export class Blueprint {
+    constructor(world, json, registry) {
+        var _a, _b;
+        this.json = json;
+        this.nodes = new Map();
+        this.linkSubscriptions = [];
+        for (const nodeJson of json.nodes) {
+            const factory = registry.get(nodeJson.type);
+            if (!factory) {
+                console.warn(`No blueprint node type registered for "${nodeJson.type}" - skipping node "${nodeJson.id}"`);
+                continue;
+            }
+            this.nodes.set(nodeJson.id, factory(world, (_a = nodeJson.settings) !== null && _a !== void 0 ? _a : {}));
+        }
+        for (const link of (_b = json.links) !== null && _b !== void 0 ? _b : []) {
+            const source = this.nodes.get(link.from.node);
+            const target = this.nodes.get(link.to.node);
+            if (!source || !target) {
+                console.warn(`Blueprint link references an unknown node ("${link.from.node}" -> "${link.to.node}") - skipping`);
+                continue;
+            }
+            this.linkSubscriptions.push(source.output(link.from.pin).subscribe(value => target.trigger(link.to.pin, value)));
+        }
+    }
+    /**
+     * Feed a value/pulse into one of this graph's named entry points (per `BlueprintJson.inputs`).
+     * A no-op (with a console warning) if no such input, or the node it aliases failed to build.
+     * @param inputName - Entry point name, per `BlueprintJson.inputs`
+     * @param value - Payload to hand to the aliased node's input pin, if any
+     */
+    trigger(inputName, value) {
+        var _a;
+        const ref = (_a = this.json.inputs) === null || _a === void 0 ? void 0 : _a[inputName];
+        if (!ref) {
+            console.warn(`Blueprint has no declared input named "${inputName}" - ignoring trigger`);
+            return;
+        }
+        const node = this.nodes.get(ref.node);
+        if (!node) {
+            return;
+        }
+        node.trigger(ref.pin, value);
+    }
+    /**
+     * Observe one of this graph's named exit points (per `BlueprintJson.outputs`) firing.
+     * @param outputName - Exit point name, per `BlueprintJson.outputs`
+     * @throws if no such output is declared, or the node it aliases failed to build
+     */
+    output(outputName) {
+        var _a;
+        const ref = (_a = this.json.outputs) === null || _a === void 0 ? void 0 : _a[outputName];
+        if (!ref) {
+            throw new Error(`Blueprint has no declared output named "${outputName}"`);
+        }
+        const node = this.nodes.get(ref.node);
+        if (!node) {
+            throw new Error(`Blueprint output "${outputName}" references unknown node "${ref.node}"`);
+        }
+        return node.output(ref.pin);
+    }
+    /**
+     * Unwire every link and dispose every node in this graph. Idempotent-ish - safe to call once
+     * per `Blueprint` instance, same lifetime contract as `IEntity.dispose`.
+     */
+    dispose() {
+        for (const sub of this.linkSubscriptions) {
+            sub.unsubscribe();
+        }
+        this.linkSubscriptions.splice(0, this.linkSubscriptions.length);
+        for (const node of this.nodes.values()) {
+            node.dispose();
+        }
+    }
+}

package/dist/base/blueprint/nodes/remove-entity.node.d.ts

@@ -0,0 +1,26 @@
+import { GgWorldTypeDocRepo } from '../../gg-world';
+import { BlueprintNode, BlueprintPinDefinition } from '../blueprint-node';
+/**
+ * Settings for the built-in `"RemoveEntity"` blueprint node - baked in from its
+ * {@link BlueprintNodeJson.settings}, not wired at runtime.
+ */
+export interface RemoveEntityNodeSettings {
+    /**
+     * Whether to dispose the entity (release its components/children) as well as remove it from
+     * the world, same as the `dispose` argument of `GgWorld.removeEntity`. Defaults to `false`.
+     */
+    dispose?: boolean;
+}
+/**
+ * Built-in blueprint node: removes an entity from the world - the blueprint analogue of calling
+ * `world.removeEntity(entity, dispose)` directly. Has one input pin, `"entity"` (a data pin that
+ * also acts as this node's trigger - feeding it a value runs the node, same as an Unreal event
+ * node's payload pin doubling as its exec pulse) and no output pins. Whether the removal also
+ * disposes the entity is controlled by the static `dispose` setting, not a pin - see
+ * {@link RemoveEntityNodeSettings}.
+ */
+export declare class RemoveEntityBlueprintNode<D = any, R = any, TypeDoc extends GgWorldTypeDocRepo<D, R> = GgWorldTypeDocRepo<D, R>> extends BlueprintNode<D, R, TypeDoc> {
+    readonly inputs: readonly BlueprintPinDefinition[];
+    readonly outputs: readonly BlueprintPinDefinition[];
+    trigger(inputName: string, value?: unknown): void;
+}

package/dist/base/blueprint/nodes/remove-entity.node.js

@@ -0,0 +1,29 @@
+import { IEntity } from '../../entities/i-entity';
+import { BlueprintNode } from '../blueprint-node';
+/**
+ * Built-in blueprint node: removes an entity from the world - the blueprint analogue of calling
+ * `world.removeEntity(entity, dispose)` directly. Has one input pin, `"entity"` (a data pin that
+ * also acts as this node's trigger - feeding it a value runs the node, same as an Unreal event
+ * node's payload pin doubling as its exec pulse) and no output pins. Whether the removal also
+ * disposes the entity is controlled by the static `dispose` setting, not a pin - see
+ * {@link RemoveEntityNodeSettings}.
+ */
+export class RemoveEntityBlueprintNode extends BlueprintNode {
+    constructor() {
+        super(...arguments);
+        this.inputs = [{ name: 'entity', kind: 'data' }];
+        this.outputs = [];
+    }
+    trigger(inputName, value) {
+        var _a;
+        if (inputName !== 'entity') {
+            return;
+        }
+        if (!(value instanceof IEntity)) {
+            console.warn('RemoveEntity blueprint node triggered without a valid entity reference - ignoring');
+            return;
+        }
+        const settings = this.settings;
+        this.world.removeEntity(value, (_a = settings.dispose) !== null && _a !== void 0 ? _a : false);
+    }
+}

package/dist/base/components/rendering/i-renderer.component.d.ts

@@ -24,6 +24,7 @@ export declare abstract class IRendererComponent<D, R, VTypeDoc extends VisualTy
     readonly scene: IVisualSceneComponent<D, R, VTypeDoc>;
     readonly canvas?: HTMLCanvasElement | undefined;
     entity: IEntity | null;
+    abstract camera: VTypeDoc['camera'];
     /** Specifies the options for the renderer. */
     readonly rendererOptions: RendererOptions & Partial<VTypeDoc['rendererExtraOpts']>;
     /** get flag whether renderer shows physics debugger view */

package/dist/base/components/rendering/i-visual-scene.component.d.ts

@@ -1,6 +1,8 @@
 import { IComponent } from '../i-component';
 import { VisualTypeDocRepo } from '../../gg-world';
+import { RendererOptions } from './i-renderer.component';
 export interface IVisualSceneComponent<D, R, VTypeDoc extends VisualTypeDocRepo<D, R> = VisualTypeDocRepo<D, R>> extends IComponent {
     readonly factory: VTypeDoc['factory'];
     init(): Promise<void>;
+    createRenderer(camera: VTypeDoc['camera'], canvas?: HTMLCanvasElement, rendererOptions?: Partial<RendererOptions & VTypeDoc['rendererExtraOpts']>): VTypeDoc['renderer'];
 }

package/dist/base/entities/group.entity.d.ts

@@ -0,0 +1,17 @@
+import { GgWorldTypeDocRepo } from '../gg-world';
+import { IEntity, TickOrder } from './i-entity';
+/**
+ * A trivial entity with no rendering/physics of its own: it exists purely as a parent/grouping
+ * node. `LevelLoader.loadLevel`/`loadLevelFromUrl` hand one back for every loaded level - every
+ * entity the level's JSON produced is added as one of its children (see `IEntity.addChildren`),
+ * so the whole level can be torn down in a single call:
+ * `world.removeEntity(level, true)` cascades removal + disposal to every child
+ * (see `IEntity.onRemoved`/`dispose`). Also used internally to group the several entities a single
+ * multi-piece GLB load can produce under one name (see the built-in `"Glb"` level entity class).
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export declare class GroupEntity<D = any, R = any, TypeDoc extends GgWorldTypeDocRepo<D, R> = GgWorldTypeDocRepo<D, R>> extends IEntity<D, R, TypeDoc> {
+    readonly tickOrder = TickOrder.OBJECTS_BINDING;
+}

package/dist/base/entities/group.entity.js

@@ -0,0 +1,19 @@
+import { IEntity, TickOrder } from './i-entity';
+/**
+ * A trivial entity with no rendering/physics of its own: it exists purely as a parent/grouping
+ * node. `LevelLoader.loadLevel`/`loadLevelFromUrl` hand one back for every loaded level - every
+ * entity the level's JSON produced is added as one of its children (see `IEntity.addChildren`),
+ * so the whole level can be torn down in a single call:
+ * `world.removeEntity(level, true)` cascades removal + disposal to every child
+ * (see `IEntity.onRemoved`/`dispose`). Also used internally to group the several entities a single
+ * multi-piece GLB load can produce under one name (see the built-in `"Glb"` level entity class).
+ * @template D - The position type
+ * @template R - The rotation type
+ * @template TypeDoc - The type document repository
+ */
+export class GroupEntity extends IEntity {
+    constructor() {
+        super(...arguments);
+        this.tickOrder = TickOrder.OBJECTS_BINDING;
+    }
+}

package/dist/base/entities/i-entity.d.ts

@@ -42,6 +42,17 @@ export declare abstract class IEntity<D = any, R = any, TypeDoc extends GgWorldT
     get children(): IEntity[];
     addChildren(...entities: IEntity[]): void;
     removeChildren(entities: IEntity[], dispose?: boolean): void;
+    /**
+     * Find a descendant entity by name, searching this entity's own children and their children
+     * recursively (depth-first) - not the whole world, just this entity's subtree. Useful e.g. to
+     * pull a specific entity back out of a `GroupEntity` a `LevelLoader` handed back:
+     * `level.getChildEntityByName('KillFloor')`.
+     * @param name - The descendant entity's `name`
+     * @returns The matching descendant
+     * @throws if no descendant has that name
+     */
+    getChildEntityByName<T extends IEntity = IEntity>(name: string): T;
+    private findChildEntityByName;
     private _components;
     get components(): IWorldComponent<D, R, TypeDoc>[];
     addComponents(...components: IWorldComponent<D, R, TypeDoc>[]): void;

package/dist/base/entities/i-entity.js

@@ -74,6 +74,34 @@ export class IEntity {
             }
         }
     }
+    /**
+     * Find a descendant entity by name, searching this entity's own children and their children
+     * recursively (depth-first) - not the whole world, just this entity's subtree. Useful e.g. to
+     * pull a specific entity back out of a `GroupEntity` a `LevelLoader` handed back:
+     * `level.getChildEntityByName('KillFloor')`.
+     * @param name - The descendant entity's `name`
+     * @returns The matching descendant
+     * @throws if no descendant has that name
+     */
+    getChildEntityByName(name) {
+        const found = this.findChildEntityByName(name);
+        if (!found) {
+            throw new Error(`No child entity named "${name}" found under "${this.name}"`);
+        }
+        return found;
+    }
+    findChildEntityByName(name) {
+        for (const child of this._children) {
+            if (child.name === name) {
+                return child;
+            }
+            const found = child.findChildEntityByName(name);
+            if (found) {
+                return found;
+            }
+        }
+        return undefined;
+    }
     get components() {
         return [...this._components];
     }

package/dist/base/entities/i-renderer.entity.d.ts

@@ -3,11 +3,12 @@ import { GgWorld, GgWorldTypeDocVPatch, VisualTypeDocRepo } from '../gg-world';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { Point2 } from '../models/points';
 import { RendererOptions } from '../components/rendering/i-renderer.component';
+import { IPositionable } from '../interfaces/i-positionable';
 /**
  * Represents a base class for a renderer entity.
  * @class
  */
-export declare abstract class IRendererEntity<D, R, VTypeDoc extends VisualTypeDocRepo<D, R> = VisualTypeDocRepo<D, R>> extends IEntity<D, R, GgWorldTypeDocVPatch<D, R, VTypeDoc>> {
+export declare abstract class IRendererEntity<D, R, VTypeDoc extends VisualTypeDocRepo<D, R> = VisualTypeDocRepo<D, R>> extends IEntity<D, R, GgWorldTypeDocVPatch<D, R, VTypeDoc>> implements IPositionable<D, R> {
     readonly renderer: VTypeDoc['renderer'];
     readonly tickOrder = TickOrder.RENDERING;
     /** Represents the current size of the renderer. */
@@ -23,6 +24,11 @@ export declare abstract class IRendererEntity<D, R, VTypeDoc extends VisualTypeD
      */
     get rendererSize(): Point2 | null;
     get rendererOptions(): RendererOptions;
+    get camera(): VTypeDoc['camera'];
+    get position(): D;
+    set position(value: D);
+    get rotation(): R;
+    set rotation(value: R);
     /** get flag whether renderer shows physics debugger view */
     get physicsDebugViewActive(): boolean;
     /** turns on/off physics debugger view for this renderer */

package/dist/base/entities/i-renderer.entity.js

@@ -23,6 +23,21 @@ export class IRendererEntity extends IEntity {
     get rendererOptions() {
         return this.renderer.rendererOptions;
     }
+    get camera() {
+        return this.renderer.camera;
+    }
+    get position() {
+        return this.camera.position;
+    }
+    set position(value) {
+        this.renderer.camera.position = value;
+    }
+    get rotation() {
+        return this.renderer.camera.rotation;
+    }
+    set rotation(value) {
+        this.renderer.camera.rotation = value;
+    }
     /** get flag whether renderer shows physics debugger view */
     get physicsDebugViewActive() {
         return this.renderer.physicsDebugViewActive;

package/dist/base/gg-world.d.ts

@@ -6,6 +6,7 @@ export type VisualTypeDocRepo<D, R> = {
     displayObject: IDisplayObjectComponent<D, R>;
     renderer: IRendererComponent<D, R>;
     rendererExtraOpts: {};
+    camera: IPositionable<D, R>;
 };
 export type PhysicsTypeDocRepo<D, R> = {
     factory: unknown;
@@ -32,6 +33,8 @@ export type GgWorldSceneTypeDocVPatch<D, R, VTypeDoc extends VisualTypeDocRepo2D
 export type GgWorldSceneTypeDocPPatch<D, R, PTypeDoc extends PhysicsTypeDocRepo<D, R>, PW extends IPhysicsWorldComponent<D, R, PTypeDoc> | null> = Omit<GgWorldSceneTypeRepo<D, R>, 'physicsWorld'> & {
     physicsWorld: PW;
 };
+export type TypeDocOf<W extends GgWorld<any, any>> = W extends GgWorld<infer D, infer R, infer TypeDoc> ? TypeDoc : never;
+export type SceneTypeDocOf<W extends GgWorld<any, any>> = W extends GgWorld<infer D, infer R, infer TypeDoc, infer SceneTypeDoc> ? SceneTypeDoc : never;
 export declare abstract class GgWorld<D, R, TypeDoc extends GgWorldTypeDocRepo<D, R> = GgWorldTypeDocRepo<D, R>, SceneTypeDoc extends GgWorldSceneTypeRepo<D, R, TypeDoc> = GgWorldSceneTypeRepo<D, R, TypeDoc>> {
     private static default_name_counter;
     private static _documentWorlds;
@@ -67,6 +70,16 @@ export declare abstract class GgWorld<D, R, TypeDoc extends GgWorldTypeDocRepo<D
     position?: D, rotation?: R, material?: unknown): IPositionable<D, R> & IRenderableEntity<D, R, TypeDoc>;
     addEntity(entity: IEntity): void;
     removeEntity(entity: IEntity, dispose?: boolean): void;
+    /**
+     * Find an entity anywhere in the world by name. `children` is a flat list of every entity ever
+     * added via `addEntity` (nested entities included - `addChildren`/`onSpawned` cascade into it
+     * too), so this is a plain linear scan, not a tree walk; to search inside one particular
+     * entity's own subtree instead, use `IEntity.getChildEntityByName`.
+     * @param name - The entity's `name`
+     * @returns The first entity found with that name (insertion order), if more than one shares it
+     * @throws if no entity in the world has that name
+     */
+    getEntityByName<T extends IEntity = IEntity>(name: string): T;
     private onGgStaticInitialized;
     protected registerConsoleCommands(ggstatic: {
         registerConsoleCommand: (world: GgWorld<any, any> | null, command: string, handler: (...args: string[]) => Promise<string>, doc?: string) => void;

package/dist/base/gg-world.js

@@ -134,7 +134,13 @@ export class GgWorld {
         this.disposed$.complete();
     }
     addEntity(entity) {
-        if (!!entity.world) {
+        if (entity.world === this) {
+            // Already a member of this world - e.g. reparented (via addChildren) after having been
+            // added directly, as level-loaded entities are. Not an error: just a no-op, since
+            // addChildren already updated the parent/children bookkeeping before calling back in here.
+            return;
+        }
+        if (entity.world) {
             console.warn('Trying to spawn entity, which is already spawned');
             return;
         }
@@ -156,6 +162,22 @@ export class GgWorld {
             entity.dispose();
         }
     }
+    /**
+     * Find an entity anywhere in the world by name. `children` is a flat list of every entity ever
+     * added via `addEntity` (nested entities included - `addChildren`/`onSpawned` cascade into it
+     * too), so this is a plain linear scan, not a tree walk; to search inside one particular
+     * entity's own subtree instead, use `IEntity.getChildEntityByName`.
+     * @param name - The entity's `name`
+     * @returns The first entity found with that name (insertion order), if more than one shares it
+     * @throws if no entity in the world has that name
+     */
+    getEntityByName(name) {
+        const found = this.children.find(e => e.name === name);
+        if (!found) {
+            throw new Error(`No entity named "${name}" found in the world`);
+        }
+        return found;
+    }
     onGgStaticInitialized() {
         window.removeEventListener('ggstatic_added', this.onGgStaticInitialized);
         this.registerConsoleCommands(window.ggstatic);

package/dist/base/index.d.ts

@@ -1,3 +1,6 @@
+export * from './blueprint/blueprint';
+export * from './blueprint/blueprint-node';
+export * from './blueprint/nodes/remove-entity.node';
 export * from './clock/global-clock';
 export * from './clock/i-clock';
 export * from './clock/pausable-clock';
@@ -14,6 +17,7 @@ export * from './data-structures/bitmask';
 export * from './data-structures/graph';
 export * from './entities/controllers/animation-mixer';
 export * from './entities/controllers/inline-controller';
+export * from './entities/group.entity';
 export * from './entities/i-entity';
 export * from './entities/i-renderer.entity';
 export * from './entities/i-renderable.entity';
@@ -36,3 +40,4 @@ export * from './math/matrix4';
 export * from './math/splines';
 export * from './pipes/gg-elastic.pipe';
 export * from './gg-world';
+export * from './level-loader';