@gg-web-engine/core 0.0.58 → 0.0.60

package/dist/3d/level-loader.d.ts

@@ -0,0 +1,300 @@
+import { LevelLoader } from '../base/level-loader';
+import { Gg3dWorld, Gg3dWorldTypeDocRepo } from './gg-3d-world';
+import { AxisDirection3, Point3, Point4 } from '../base';
+import { DisplayObject3dOpts } from './factories';
+import { Body3DOptions } from './models/body-options';
+import { Shape3DDescriptor } from './models/shapes';
+import { GgCarProperties } from './entities/gg-car/gg-car.entity';
+import { RVEntityAxleOptions, RVEntitySharedWheelOptions } from './entities/raycast-vehicle-3d.entity';
+import { MapGraphNodeType } from './entities/map-graph-3d.entity';
+/**
+ * Shape names accepted by the built-in `"Primitive"` entity class in a 3D level JSON, via the
+ * sibling `shape` field on the entity (e.g. `{ class: "Primitive", shape: "BOX" }`) - the same
+ * `Shape3DDescriptor['shape']` values used at the engine API level, so no translation is needed
+ * between a level JSON and `Gg3dWorld.addPrimitiveRigidBody`.
+ */
+export type Primitive3DShapeName = Shape3DDescriptor['shape'];
+/**
+ * Settings shared by every primitive entity (Box, Sphere, Plane, Capsule, Cylinder, Cone)
+ */
+export interface Primitive3DSettings {
+    /**
+     * Which primitive shape to construct
+     */
+    shape: Primitive3DShapeName;
+    /**
+     * Position of the primitive
+     */
+    position?: Point3;
+    /**
+     * Rotation of the primitive
+     */
+    rotation?: Point4;
+    /**
+     * Dimensions of the primitive (for Box)
+     */
+    dimensions?: Point3;
+    /**
+     * Radius of the primitive (for Sphere, Capsule, Cylinder, Cone)
+     */
+    radius?: number;
+    /**
+     * Height of the primitive (for Cylinder, Cone)
+     */
+    height?: number;
+    /**
+     * Centers distance of the primitive (for Capsule)
+     */
+    centersDistance?: number;
+    /**
+     * Material options for the primitive
+     */
+    material?: DisplayObject3dOpts<any>;
+    /**
+     * Physics body options, merged over sensible defaults
+     */
+    body?: Partial<Body3DOptions>;
+}
+/**
+ * Settings for a trigger entity
+ */
+export interface Trigger3DSettings {
+    /**
+     * Position of the trigger
+     */
+    position?: Point3;
+    /**
+     * Rotation of the trigger
+     */
+    rotation?: Point4;
+    /**
+     * Dimensions of the trigger
+     */
+    dimensions: Point3;
+}
+/**
+ * Settings for a camera entity
+ */
+export interface Camera3DSettings {
+    /**
+     * Position of the camera
+     */
+    position?: Point3;
+    /**
+     * Rotation of the camera
+     */
+    rotation?: Point4;
+    /**
+     * Field of view in degrees
+     */
+    fov?: number;
+    /**
+     * Aspect ratio (width / height)
+     */
+    aspectRatio?: number;
+    /**
+     * Near and far frustum planes
+     */
+    frustrum?: {
+        near: number;
+        far: number;
+    };
+}
+/**
+ * Settings for a `"GgCar"` wheel's optional visual mesh. A level JSON has no way to reference an
+ * existing display object component (unlike programmatic `RVEntityProperties`, whose
+ * `WheelDisplayOptions.displayObject` takes one directly) - instead, supplying `display` at all
+ * makes the `"GgCar"` generator build one itself via `visualScene.factory.createCylinder`, sized
+ * to that wheel's own (or its axle/shared settings') `tyreRadius`/`tyreWidth`. Omit `display`
+ * entirely (on both the wheel and whatever it inherits from) to leave that wheel invisible
+ * (physics-only), same as omitting `WheelDisplayOptions.displayObject` does programmatically.
+ */
+export interface GgCarWheelDisplaySettings {
+    material?: DisplayObject3dOpts<any>;
+    wheelObjectDirection?: AxisDirection3;
+}
+/**
+ * JSON-friendly counterpart of `RVEntitySharedWheelOptions`: identical except `display` is a
+ * {@link GgCarWheelDisplaySettings} descriptor instead of a ready-made `WheelDisplayOptions`.
+ */
+export type GgCarSharedWheelSettings = Omit<RVEntitySharedWheelOptions, 'display'> & {
+    display?: GgCarWheelDisplaySettings;
+};
+/**
+ * JSON-friendly counterpart of `RVEntityAxleOptions`, for the `"GgCar"` class's `wheelBase.front`/
+ * `wheelBase.rear`.
+ */
+export type GgCarAxleSettings = Pick<RVEntityAxleOptions, 'halfAxleWidth' | 'axlePosition' | 'axleHeight'> & GgCarSharedWheelSettings;
+/**
+ * JSON-friendly counterpart of one `RVEntityProperties['wheelOptions']` element, for the
+ * `"GgCar"` class's `wheelOptions` array.
+ */
+export type GgCarWheelSettings = GgCarSharedWheelSettings & {
+    isLeft: boolean;
+    isFront: boolean;
+    position: Point3;
+};
+/**
+ * Fields of `GgCarProperties` that don't vary between its `wheelBase`/`wheelOptions` shapes -
+ * carried over into {@link GgCar3DSettings} as-is (already plain JSON-serializable data).
+ */
+export interface GgCar3DCommonSettings {
+    suspension: GgCarProperties['suspension'];
+    tractionBias: GgCarProperties['tractionBias'];
+    mpsToRpmFactor?: GgCarProperties['mpsToRpmFactor'];
+    engine: GgCarProperties['engine'];
+    brake: GgCarProperties['brake'];
+    transmission: GgCarProperties['transmission'];
+    maxSteerAngle: GgCarProperties['maxSteerAngle'];
+}
+/**
+ * Settings for the built-in `"GgCar"` entity class (3D only): builds a box-shaped chassis rigid
+ * body (+ optional matching display box) and a full `GgCarEntity` on top of it - the procedural
+ * counterpart of the GLB-driven car construction apps do by hand (see `examples/fly-city-three-ammo`'s
+ * `GameFactory.generateCar`), for a car whose chassis/wheels are plain primitives rather than
+ * loaded meshes.
+ */
+export type GgCar3DSettings = GgCar3DCommonSettings & {
+    position?: Point3;
+    rotation?: Point4;
+    /**
+     * The chassis's box collider/mesh. `body` is merged over a default dynamic body (same shape as
+     * `Primitive3DSettings.body`, but with `mass: 800` instead of `1`, since a `mass: 1` chassis is
+     * unrealistically light for a car).
+     */
+    chassis: {
+        dimensions: Point3;
+        material?: DisplayObject3dOpts<any>;
+        body?: Partial<Body3DOptions>;
+    };
+} & ({
+    wheelBase: {
+        shared?: GgCarSharedWheelSettings;
+        front: GgCarAxleSettings;
+        rear: GgCarAxleSettings;
+    };
+    wheelOptions?: undefined;
+    sharedWheelOptions?: undefined;
+} | {
+    wheelOptions: GgCarWheelSettings[];
+    sharedWheelOptions?: GgCarSharedWheelSettings;
+    wheelBase?: undefined;
+});
+/**
+ * JSON-friendly counterpart of `MapGraphNodeType`: identical except `loadOptions` may be omitted
+ * (defaulting to `{}`) rather than required, since most nodes need none of it.
+ */
+export type MapGraphNodeJson = Omit<MapGraphNodeType, 'loadOptions'> & {
+    loadOptions?: MapGraphNodeType['loadOptions'];
+};
+/**
+ * Settings for the built-in `"MapGraph"` entity class (3D only): builds a `MapGraph` from plain
+ * node data and wraps it in a ready-to-use `MapGraph3dEntity`. `graph` mirrors the two
+ * `MapGraph` factory methods - a flat (optionally closed-loop) path via `nodes`, or a rectangular
+ * `grid` - since both already take plain-data node arrays. The resulting entity doesn't implement
+ * `IPositionable3d` (each node carries its own absolute `position`/`rotation`), so there's no
+ * `position`/`rotation` field here - and its `loaderCursor$` still needs to be driven at runtime
+ * from whatever entity's position should determine which nodes are loaded (see
+ * `gg-engine-level-json` skill's "MapGraph" section).
+ */
+export interface MapGraph3DSettings {
+    graph: {
+        type?: 'array';
+        nodes: MapGraphNodeJson[];
+        closed?: boolean;
+    } | {
+        type: 'grid';
+        grid: MapGraphNodeJson[][];
+    };
+    /** Depth in the graph to load - see `Gg3dMapGraphEntityOptions.loadDepth` (default `5`) */
+    loadDepth?: number;
+    /** Extra unload-delay depth - see `Gg3dMapGraphEntityOptions.inertia` (default `0`) */
+    inertia?: number;
+    /** Max nodes loaded per tick - see `Gg3dMapGraphEntityOptions.maxNodesLoadingPerTick` (default `1`) */
+    maxNodesLoadingPerTick?: number;
+    /** Ticks/second of the internal load-scheduling clock - see `MapGraph3dEntity.loadRateLimit` (default `1`) */
+    loadRateLimit?: number;
+}
+/**
+ * 3D level loader: registers the built-in primitive/trigger/camera/car/map-graph entity classes
+ * and dispatches `LevelJson` entities to them (or to custom classes registered via
+ * `registerClass`).
+ * @template TypeDoc - The type document repository
+ */
+export declare class Gg3dLevelLoader<TypeDoc extends Gg3dWorldTypeDocRepo = Gg3dWorldTypeDocRepo> extends LevelLoader<Point3, Point4, TypeDoc> {
+    protected readonly world: Gg3dWorld<TypeDoc>;
+    constructor(world: Gg3dWorld<TypeDoc>);
+    /**
+     * Register the built-in classes for primitives, triggers, and cameras
+     */
+    private registerDefaultClasses;
+    /**
+     * Turn a `Primitive3DSettings` (`shape` plus shape-specific fields) into the `Shape3DDescriptor`
+     * consumed by `Gg3dWorld.addPrimitiveRigidBody`.
+     * @param settings - The primitive settings, as parsed from a `"Primitive"` entity's `shape` +
+     * `config`
+     * @returns The shape descriptor
+     */
+    private buildShapeDescriptor;
+    /**
+     * Create a primitive entity (both display object and physics body) from a shape descriptor.
+     * `Shape3DDescriptor` (no mesh-only segment options) is used for both the visual and the
+     * physics representation, same as `Gg3dWorld.addPrimitiveRigidBody`'s own shortcut methods.
+     * @param world - The world instance
+     * @param shape - The shape descriptor
+     * @param settings - Position/rotation/material/body settings shared by all primitives
+     * @returns The created entity
+     */
+    private createPrimitive;
+    /**
+     * Create a trigger entity: a `Trigger3dEntity` wrapping the raw physics trigger component, so
+     * the app can subscribe to `onEntityEntered`/`onEntityLeft` without any extra wiring - see the
+     * base `LevelLoader` docs for how it's parented for level-lifecycle cleanup.
+     * @param world - The world instance
+     * @param settings - The trigger settings
+     * @returns The created trigger entity
+     */
+    private createTrigger;
+    /**
+     * Create a camera entity: a `Camera3dEntity` wrapping the raw camera component, not attached to
+     * any renderer/canvas (a level JSON has no notion of one - `world.addRenderer(entity.camera,
+     * canvas)` once the app has a canvas). Parented under the level's group entity, so it's torn
+     * down along with the rest of the level - put a camera meant to outlive a level swap in a
+     * separate, never-unloaded level instead (see `gg-engine-level-json`'s "Camera" section).
+     * @param world - The world instance
+     * @param settings - The camera settings
+     * @returns The created camera entity
+     */
+    private createCamera;
+    /**
+     * Build a `WheelDisplayOptions` for one `"GgCar"` wheel/axle from its (already shared-merged)
+     * settings, via `visualScene.factory.createCylinder`. Returns `undefined` (no visual wheel,
+     * physics-only) if `display` wasn't specified at all, or there's no visual scene to build one
+     * against.
+     * @param world - The world instance
+     * @param wheelSettings - The wheel's own settings, already merged over whatever it inherits
+     * from `wheelBase.shared`/`sharedWheelOptions`
+     * @returns The resolved display options, or `undefined`
+     */
+    private resolveWheelDisplay;
+    /**
+     * Create a `"GgCar"` entity: a box chassis rigid body (+ optional matching display box) wrapped
+     * in a full `GgCarEntity`, with each wheel's optional visual mesh built from its settings (see
+     * {@link resolveWheelDisplay}) rather than referencing an existing display object component,
+     * which a level JSON has no way to do.
+     * @param world - The world instance
+     * @param settings - The car settings
+     * @returns The created car entity
+     */
+    private createGgCar;
+    /**
+     * Create a `"MapGraph"` entity: a `MapGraph` built from plain node data (a flat/looped path or
+     * a rectangular grid, see {@link MapGraph3DSettings}), wrapped in a ready-to-use
+     * `MapGraph3dEntity`. The app still has to drive `loaderCursor$` itself once the level is
+     * loaded - see `gg-engine-level-json`'s "MapGraph" section.
+     * @param world - The world instance
+     * @param settings - The map graph settings
+     * @returns The created map graph entity
+     */
+    private createMapGraph;
+}

package/dist/3d/level-loader.js

@@ -0,0 +1,267 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { LevelLoader } from '../base/level-loader';
+import { Trigger3dEntity } from './entities/trigger-3d.entity';
+import { Camera3dEntity } from './entities/camera-3d.entity';
+import { GgCarEntity } from './entities/gg-car/gg-car.entity';
+import { MapGraph, MapGraph3dEntity, } from './entities/map-graph-3d.entity';
+const defaultBodyOptions = {
+    dynamic: true,
+    mass: 1,
+    restitution: 0.2,
+    friction: 0.5,
+    ownCollisionGroups: 'all',
+    interactWithCollisionGroups: 'all',
+};
+const defaultCarChassisBodyOptions = Object.assign(Object.assign({}, defaultBodyOptions), { mass: 800 });
+/** Fallback tyre size used only to size a `"GgCar"` wheel's auto-generated cylinder mesh when
+ * neither the wheel nor its shared wheel settings specify one - independent of the physics
+ * wheel's own default (`RaycastVehicle3dEntity`'s internal `wheeelDefaults`) applied when a
+ * wheel's `tyreRadius`/`tyreWidth` is left unset entirely. */
+const defaultWheelDisplaySize = { tyreRadius: 0.4, tyreWidth: 0.3 };
+/**
+ * 3D level loader: registers the built-in primitive/trigger/camera/car/map-graph entity classes
+ * and dispatches `LevelJson` entities to them (or to custom classes registered via
+ * `registerClass`).
+ * @template TypeDoc - The type document repository
+ */
+export class Gg3dLevelLoader extends LevelLoader {
+    constructor(world) {
+        super(world);
+        this.world = world;
+        this.registerDefaultClasses();
+    }
+    /**
+     * Register the built-in classes for primitives, triggers, and cameras
+     */
+    registerDefaultClasses() {
+        this.registerClass('Primitive', (world, settings) => this.createPrimitive(world, this.buildShapeDescriptor(settings), settings));
+        this.registerClass('Trigger', this.createTrigger.bind(this));
+        this.registerClass('Camera', this.createCamera.bind(this));
+        this.registerClass('GgCar', this.createGgCar.bind(this));
+        this.registerClass('MapGraph', this.createMapGraph.bind(this));
+    }
+    /**
+     * Turn a `Primitive3DSettings` (`shape` plus shape-specific fields) into the `Shape3DDescriptor`
+     * consumed by `Gg3dWorld.addPrimitiveRigidBody`.
+     * @param settings - The primitive settings, as parsed from a `"Primitive"` entity's `shape` +
+     * `config`
+     * @returns The shape descriptor
+     */
+    buildShapeDescriptor(settings) {
+        switch (settings.shape) {
+            case 'BOX':
+                if (!settings.dimensions) {
+                    throw new Error('Dimensions are required for BOX primitive');
+                }
+                return { shape: 'BOX', dimensions: settings.dimensions };
+            case 'SPHERE':
+                if (settings.radius === undefined) {
+                    throw new Error('Radius is required for SPHERE primitive');
+                }
+                return { shape: 'SPHERE', radius: settings.radius };
+            case 'PLANE':
+                return { shape: 'PLANE' };
+            case 'CAPSULE':
+                if (settings.radius === undefined) {
+                    throw new Error('Radius is required for CAPSULE primitive');
+                }
+                if (settings.centersDistance === undefined) {
+                    throw new Error('Centers distance is required for CAPSULE primitive');
+                }
+                return { shape: 'CAPSULE', radius: settings.radius, centersDistance: settings.centersDistance };
+            case 'CYLINDER':
+                if (settings.radius === undefined) {
+                    throw new Error('Radius is required for CYLINDER primitive');
+                }
+                if (settings.height === undefined) {
+                    throw new Error('Height is required for CYLINDER primitive');
+                }
+                return { shape: 'CYLINDER', radius: settings.radius, height: settings.height };
+            case 'CONE':
+                if (settings.radius === undefined) {
+                    throw new Error('Radius is required for CONE primitive');
+                }
+                if (settings.height === undefined) {
+                    throw new Error('Height is required for CONE primitive');
+                }
+                return { shape: 'CONE', radius: settings.radius, height: settings.height };
+            default:
+                throw new Error(`Unknown primitive shape "${settings.shape}"`);
+        }
+    }
+    /**
+     * Create a primitive entity (both display object and physics body) from a shape descriptor.
+     * `Shape3DDescriptor` (no mesh-only segment options) is used for both the visual and the
+     * physics representation, same as `Gg3dWorld.addPrimitiveRigidBody`'s own shortcut methods.
+     * @param world - The world instance
+     * @param shape - The shape descriptor
+     * @param settings - Position/rotation/material/body settings shared by all primitives
+     * @returns The created entity
+     */
+    createPrimitive(world, shape, settings) {
+        const { position, rotation, material, body } = settings;
+        return world.addPrimitiveRigidBody({ shape, body: Object.assign(Object.assign({}, defaultBodyOptions), body) }, position, rotation, material);
+    }
+    /**
+     * Create a trigger entity: a `Trigger3dEntity` wrapping the raw physics trigger component, so
+     * the app can subscribe to `onEntityEntered`/`onEntityLeft` without any extra wiring - see the
+     * base `LevelLoader` docs for how it's parented for level-lifecycle cleanup.
+     * @param world - The world instance
+     * @param settings - The trigger settings
+     * @returns The created trigger entity
+     */
+    createTrigger(world, settings) {
+        var _a;
+        const { position, rotation, dimensions } = settings;
+        const shape = { shape: 'BOX', dimensions };
+        const trigger = (_a = world.physicsWorld) === null || _a === void 0 ? void 0 : _a.factory.createTrigger(shape, { position, rotation });
+        if (!trigger) {
+            return undefined;
+        }
+        const entity = new Trigger3dEntity(trigger);
+        if (position) {
+            entity.position = position;
+        }
+        if (rotation) {
+            entity.rotation = rotation;
+        }
+        return entity;
+    }
+    /**
+     * Create a camera entity: a `Camera3dEntity` wrapping the raw camera component, not attached to
+     * any renderer/canvas (a level JSON has no notion of one - `world.addRenderer(entity.camera,
+     * canvas)` once the app has a canvas). Parented under the level's group entity, so it's torn
+     * down along with the rest of the level - put a camera meant to outlive a level swap in a
+     * separate, never-unloaded level instead (see `gg-engine-level-json`'s "Camera" section).
+     * @param world - The world instance
+     * @param settings - The camera settings
+     * @returns The created camera entity
+     */
+    createCamera(world, settings) {
+        var _a;
+        const { position, rotation, fov, aspectRatio, frustrum } = settings;
+        const camera = (_a = world.visualScene) === null || _a === void 0 ? void 0 : _a.factory.createPerspectiveCamera({ fov, aspectRatio, frustrum });
+        if (!camera) {
+            return undefined;
+        }
+        const entity = new Camera3dEntity(camera);
+        if (position) {
+            entity.position = position;
+        }
+        if (rotation) {
+            entity.rotation = rotation;
+        }
+        return entity;
+    }
+    /**
+     * Build a `WheelDisplayOptions` for one `"GgCar"` wheel/axle from its (already shared-merged)
+     * settings, via `visualScene.factory.createCylinder`. Returns `undefined` (no visual wheel,
+     * physics-only) if `display` wasn't specified at all, or there's no visual scene to build one
+     * against.
+     * @param world - The world instance
+     * @param wheelSettings - The wheel's own settings, already merged over whatever it inherits
+     * from `wheelBase.shared`/`sharedWheelOptions`
+     * @returns The resolved display options, or `undefined`
+     */
+    resolveWheelDisplay(world, wheelSettings) {
+        var _a, _b;
+        if (!wheelSettings.display || !world.visualScene) {
+            return undefined;
+        }
+        const { tyreRadius = defaultWheelDisplaySize.tyreRadius, tyreWidth = defaultWheelDisplaySize.tyreWidth } = wheelSettings;
+        return {
+            displayObject: world.visualScene.factory.createCylinder(tyreRadius, tyreWidth, (_a = wheelSettings.display.material) !== null && _a !== void 0 ? _a : {}),
+            wheelObjectDirection: (_b = wheelSettings.display.wheelObjectDirection) !== null && _b !== void 0 ? _b : 'x',
+        };
+    }
+    /**
+     * Create a `"GgCar"` entity: a box chassis rigid body (+ optional matching display box) wrapped
+     * in a full `GgCarEntity`, with each wheel's optional visual mesh built from its settings (see
+     * {@link resolveWheelDisplay}) rather than referencing an existing display object component,
+     * which a level JSON has no way to do.
+     * @param world - The world instance
+     * @param settings - The car settings
+     * @returns The created car entity
+     */
+    createGgCar(world, settings) {
+        var _a, _b, _c;
+        if (!world.physicsWorld) {
+            return undefined;
+        }
+        const { position, rotation, chassis, wheelBase, wheelOptions, sharedWheelOptions } = settings, rest = __rest(settings, ["position", "rotation", "chassis", "wheelBase", "wheelOptions", "sharedWheelOptions"]);
+        if (!(chassis === null || chassis === void 0 ? void 0 : chassis.dimensions)) {
+            throw new Error('Chassis dimensions are required for GgCar class');
+        }
+        if (!wheelBase && !wheelOptions) {
+            throw new Error('Either "wheelBase" or "wheelOptions" is required for GgCar class');
+        }
+        const chassisBody = world.physicsWorld.factory.createRigidBody({
+            shape: { shape: 'BOX', dimensions: chassis.dimensions },
+            body: Object.assign(Object.assign({}, defaultCarChassisBodyOptions), chassis.body),
+        });
+        const chassis3D = (_c = (_a = world.visualScene) === null || _a === void 0 ? void 0 : _a.factory.createBox(chassis.dimensions, (_b = chassis.material) !== null && _b !== void 0 ? _b : {})) !== null && _c !== void 0 ? _c : null;
+        const carProperties = wheelBase
+            ? Object.assign(Object.assign({}, rest), { wheelBase: {
+                    shared: Object.assign(Object.assign({}, wheelBase.shared), { display: undefined }),
+                    front: Object.assign(Object.assign({}, wheelBase.front), { display: this.resolveWheelDisplay(world, Object.assign(Object.assign({}, wheelBase.shared), wheelBase.front)) }),
+                    rear: Object.assign(Object.assign({}, wheelBase.rear), { display: this.resolveWheelDisplay(world, Object.assign(Object.assign({}, wheelBase.shared), wheelBase.rear)) }),
+                } }) : Object.assign(Object.assign({}, rest), { wheelOptions: wheelOptions.map(wheel => (Object.assign(Object.assign({}, wheel), { display: this.resolveWheelDisplay(world, Object.assign(Object.assign({}, sharedWheelOptions), wheel)) }))), sharedWheelOptions: sharedWheelOptions && Object.assign(Object.assign({}, sharedWheelOptions), { display: undefined }) });
+        const entity = new GgCarEntity(carProperties, chassis3D, world.physicsWorld.factory.createRaycastVehicle(chassisBody));
+        if (position) {
+            entity.position = position;
+        }
+        if (rotation) {
+            entity.rotation = rotation;
+        }
+        return entity;
+    }
+    /**
+     * Create a `"MapGraph"` entity: a `MapGraph` built from plain node data (a flat/looped path or
+     * a rectangular grid, see {@link MapGraph3DSettings}), wrapped in a ready-to-use
+     * `MapGraph3dEntity`. The app still has to drive `loaderCursor$` itself once the level is
+     * loaded - see `gg-engine-level-json`'s "MapGraph" section.
+     * @param world - The world instance
+     * @param settings - The map graph settings
+     * @returns The created map graph entity
+     */
+    createMapGraph(world, settings) {
+        var _a, _b, _c;
+        const { graph, loadDepth, inertia, maxNodesLoadingPerTick, loadRateLimit } = settings;
+        if (!graph) {
+            throw new Error('"graph" is required for MapGraph class');
+        }
+        const normalizeNode = (node) => {
+            var _a;
+            return (Object.assign(Object.assign({}, node), { loadOptions: (_a = node.loadOptions) !== null && _a !== void 0 ? _a : {} }));
+        };
+        let mapGraph;
+        if (graph.type === 'grid') {
+            if (!((_a = graph.grid) === null || _a === void 0 ? void 0 : _a.length)) {
+                throw new Error('"graph.grid" must be a non-empty grid for MapGraph class');
+            }
+            mapGraph = MapGraph.fromMapSquareGrid(graph.grid.map(row => row.map(normalizeNode)));
+        }
+        else {
+            if (!((_b = graph.nodes) === null || _b === void 0 ? void 0 : _b.length)) {
+                throw new Error('"graph.nodes" must be a non-empty array for MapGraph class');
+            }
+            mapGraph = MapGraph.fromMapArray(graph.nodes.map(normalizeNode), (_c = graph.closed) !== null && _c !== void 0 ? _c : false);
+        }
+        const options = Object.assign(Object.assign(Object.assign({}, (loadDepth !== undefined ? { loadDepth } : {})), (inertia !== undefined ? { inertia } : {})), (maxNodesLoadingPerTick !== undefined ? { maxNodesLoadingPerTick } : {}));
+        const entity = new MapGraph3dEntity(mapGraph, options);
+        if (loadRateLimit !== undefined) {
+            entity.loadRateLimit = loadRateLimit;
+        }
+        return entity;
+    }
+}

package/dist/3d/loader.d.ts

@@ -2,6 +2,7 @@ import { Gg3dWorld, Gg3dWorldTypeDocRepo } from './gg-3d-world';
 import { GgMeta } from './models/gg-meta';
 import { Entity3d } from './entities/entity-3d';
 import { Point3, Point4 } from '../base';
+import { Gg3dLevelLoader } from './level-loader';
 export declare enum CachingStrategy {
     Nothing = 0,
     Files = 1,
@@ -28,11 +29,51 @@ export type LoadResult<TypeDoc extends Gg3dWorldTypeDocRepo = Gg3dWorldTypeDocRe
 export type LoadResultWithProps<TypeDoc extends Gg3dWorldTypeDocRepo = Gg3dWorldTypeDocRepo> = LoadResult<TypeDoc> & {
     props?: LoadResult<TypeDoc>[];
 };
-export declare class Gg3dLoader<TypeDoc extends Gg3dWorldTypeDocRepo = Gg3dWorldTypeDocRepo> {
-    protected readonly world: Gg3dWorld;
+/**
+ * Settings for the built-in `"Glb"` level entity class (3D only): loads a GG GLB+meta pair via
+ * `Gg3dLoader.loadGgGlb` and returns every entity it produces (the model itself, plus any nested
+ * props/scenes) grouped under one `GroupEntity`.
+ */
+export interface Glb3DSettings {
+    /**
+     * Path (URL or path prefix, without extension) to the `.glb`/`.meta` pair - passed straight
+     * through to `loadGgGlb`
+     */
+    path: string;
+    /**
+     * Position of the loaded model
+     */
+    position?: Point3;
+    /**
+     * Rotation of the loaded model
+     */
+    rotation?: Point4;
+    /**
+     * Caching strategy, see `CachingStrategy`. Defaults to `CachingStrategy.Nothing`, same as
+     * `loadGgGlb` itself.
+     */
+    cachingStrategy?: CachingStrategy;
+    /**
+     * Whether to also load dummies flagged as props/scenes. Defaults to `true`, same as `loadGgGlb`.
+     */
+    loadProps?: boolean;
+    /**
+     * Path where to find prop scenes, if different from `path`'s own directory
+     */
+    propsPath?: string;
+}
+/**
+ * Full 3D loader exposed as `Gg3dWorld.loader`: GLB+meta asset loading (`loadGgGlb` and friends)
+ * layered on top of `Gg3dLevelLoader`, so `registerClass`/`loadLevel`/`loadLevelFromUrl`/
+ * `getEntityByName` are all available directly on `world.loader`. Also registers a `"Glb"` level
+ * entity class (see `Glb3DSettings`) so a level JSON can place a GLB model declaratively, the same
+ * way it places primitives/triggers/cameras.
+ * @template TypeDoc - The type document repository
+ */
+export declare class Gg3dLoader<TypeDoc extends Gg3dWorldTypeDocRepo = Gg3dWorldTypeDocRepo> extends Gg3dLevelLoader<TypeDoc> {
     readonly filesCache: Map<string, [ArrayBuffer, GgMeta] | Promise<[ArrayBuffer, GgMeta]>>;
     readonly loadResultCache: Map<string, LoadResourcesResult<TypeDoc> | Promise<LoadResourcesResult<TypeDoc>>>;
-    constructor(world: Gg3dWorld);
+    constructor(world: Gg3dWorld<TypeDoc>);
     loadGgGlbFiles(path: string, useCache?: boolean): Promise<[ArrayBuffer, GgMeta]>;
     loadGgGlbResources(path: string, cachingStrategy?: CachingStrategy): Promise<LoadResourcesResult<TypeDoc>>;
     loadGgGlb(path: string, options?: Partial<LoadOptions>): Promise<LoadResultWithProps<TypeDoc>>;