@vgai/engine 0.5.0 → 0.5.2

package/dist/render/render-batch-system.js

@@ -1,230 +0,0 @@
-import * as THREE from 'three';
-import { getUserData } from '../scene/user-data';
-// Structural signature — groups meshes that are VALUE-identical, not object-identical.
-// The engine scene-loader instantiates a fresh geometry+material per entity (no dedup),
-// so keying on .uuid would never batch a real scene. Keying on geometry type+parameters
-// and material type+key-props groups identical authored primitives (e.g. 10k boxes of
-// the same size+color → one batch). Non-primitive geometry (GLTF, no `.parameters`)
-// falls back to uuid → it simply won't group, which is the safe default.
-const geoKey = (g) => {
-    const params = g.parameters;
-    return params ? `${g.type}:${JSON.stringify(params)}` : `uuid:${g.uuid}`;
-};
-const matKey = (m) => {
-    const s = m;
-    const col = s.color?.getHexString?.() ?? '';
-    const map = s.map?.uuid ?? '';
-    return `${m.type}:${col}:${s.roughness ?? ''}:${s.metalness ?? ''}:${map}:${m.side}:${m.transparent}:${m.vertexColors}`;
-};
-const SIG = (m) => 
-// include shadow flags: meshes with different cast/receive must not share a batch
-// (the InstancedMesh carries one flag for the whole group).
-`${geoKey(m.geometry)}|${matKey(m.material)}|${m.castShadow ? 1 : 0}${m.receiveShadow ? 1 : 0}`;
-/** Nearest self/ancestor entity descriptor, if any. */
-function nearestEntity(obj) {
-    let cur = obj;
-    while (cur) {
-        const entity = getUserData(cur, 'entity');
-        if (entity)
-            return entity;
-        cur = cur.parent;
-    }
-    return undefined;
-}
-/** Explicit per-entity opt-out (`render.autoBatch === false`). */
-function entityOptOut(obj) {
-    return nearestEntity(obj)?.render?.autoBatch === false;
-}
-/**
- * Static-batching eligibility: only entities that won't move are safe to freeze
- * and instance. An entity with physics, behavior components, or its own animation
- * is a likely mover → left as an ordinary draw. Plain scenery (no def, or a def
- * with none of those) is eligible. This is the safe, transparent default; a future
- * dynamic-batch path (markMoved-driven) can include movers.
- */
-function isLikelyStatic(obj) {
-    const e = nearestEntity(obj);
-    if (!e)
-        return true; // un-tagged scenery
-    if (e.physics)
-        return false;
-    if (e.animation)
-        return false;
-    if (e.components && Object.keys(e.components).length > 0)
-        return false;
-    return true;
-}
-export class RenderBatchSystem {
-    scene;
-    settings;
-    root = new THREE.Group();
-    groups = [];
-    dynamicGroups = []; // subset needing per-frame sync
-    // Original parent of each detached (static) source, to re-attach on teardown.
-    parentOf = new WeakMap();
-    // instanceId mapping for raycast: which group + slot an InstancedMesh belongs to.
-    membersOf = new WeakMap();
-    constructor(scene, settings) {
-        this.scene = scene;
-        this.settings = settings;
-        this.root.name = 'RenderBatchSystem';
-        this.root.matrixAutoUpdate = false; // instances carry world matrices directly
-    }
-    /** Scan the scene and build instanced groups. Idempotent (rebuilds). */
-    build() {
-        this.teardown();
-        this.scene.add(this.root);
-        this.scene.updateMatrixWorld(true);
-        // collect eligible candidates, grouped by (geometry, material)
-        const buckets = new Map();
-        this.scene.traverse((obj) => {
-            const m = obj;
-            if (!m.isMesh)
-                return;
-            if (m.isInstancedMesh)
-                return;
-            if (m.isSkinnedMesh)
-                return;
-            if (m.isBatchedMesh)
-                return;
-            if (!m.visible)
-                return;
-            if (!m.geometry || !m.material || Array.isArray(m.material))
-                return;
-            if (m.material.transparent)
-                return;
-            if (this.root === m.parent)
-                return; // our own instances
-            if (entityOptOut(m))
-                return;
-            const key = SIG(m);
-            const arr = buckets.get(key) ?? [];
-            arr.push(m);
-            buckets.set(key, arr);
-        });
-        // Each signature bucket is partitioned into STATIC (detached, zero-cost) and
-        // DYNAMIC (kept in-place, dirty-synced) members, each ≥2 forming its own batch.
-        for (const bucket of buckets.values()) {
-            const staticMembers = [];
-            const dynamicMembers = [];
-            for (const m of bucket)
-                (isLikelyStatic(m) ? staticMembers : dynamicMembers).push(m);
-            if (staticMembers.length >= 2)
-                this.makeGroup(staticMembers, false);
-            if (dynamicMembers.length >= 2)
-                this.makeGroup(dynamicMembers, true);
-        }
-    }
-    makeGroup(sources, dynamic) {
-        const frustum = this.settings['frustumCulling'] !== false;
-        const tmp = new THREE.Matrix4();
-        const proto = sources[0];
-        const inst = new THREE.InstancedMesh(proto.geometry, proto.material, sources.length);
-        inst.frustumCulled = frustum && !dynamic; // moving batches can leave the padded sphere
-        // Inherit shadow flags from the prototype so batched objects still cast/receive
-        // shadows (otherwise detaching the sources would silently drop them from shadows).
-        inst.castShadow = proto.castShadow;
-        inst.receiveShadow = proto.receiveShadow;
-        const cache = dynamic ? new Float32Array(sources.length * 16) : undefined;
-        for (let i = 0; i < sources.length; i++) {
-            const s = sources[i];
-            tmp.copy(s.matrixWorld);
-            inst.setMatrixAt(i, tmp);
-            if (dynamic) {
-                // keep the source in the graph (physics/animation still updates its matrixWorld),
-                // just hide its own draw; we copy its world matrix into the instance each frame.
-                cache.set(tmp.elements, i * 16);
-                s.visible = false;
-            }
-            else if (s.parent) {
-                // static: detach entirely so the renderer never walks it (zero per-frame cost)
-                this.parentOf.set(s, s.parent);
-                s.parent.remove(s);
-            }
-        }
-        inst.instanceMatrix.needsUpdate = true;
-        if (frustum && !dynamic)
-            inst.computeBoundingSphere();
-        this.membersOf.set(inst, sources);
-        this.root.add(inst);
-        const group = cache
-            ? { instanced: inst, sources, dynamic, cache }
-            : { instanced: inst, sources, dynamic };
-        this.groups.push(group);
-        if (dynamic)
-            this.dynamicGroups.push(group);
-    }
-    /**
-     * Per-frame sync for DYNAMIC groups only (static are detached & immutable → free).
-     * Called in the preRender phase. Refreshes world matrices once (the engine's movers
-     * set matrixWorldNeedsUpdate via physics/animation), then re-writes only the instances
-     * whose source moved (element-wise cache compare). No-op when there are no movers.
-     */
-    update() {
-        if (this.dynamicGroups.length === 0)
-            return;
-        this.scene.updateMatrixWorld(false); // refresh moved subtrees (force=false → cheap)
-        for (const g of this.dynamicGroups) {
-            const cache = g.cache;
-            let dirty = false;
-            for (let i = 0; i < g.sources.length; i++) {
-                const el = g.sources[i].matrixWorld.elements;
-                const off = i * 16;
-                let changed = false;
-                for (let k = 0; k < 16; k++) {
-                    if (el[k] !== cache[off + k]) {
-                        changed = true;
-                        break;
-                    }
-                }
-                if (!changed)
-                    continue;
-                g.instanced.setMatrixAt(i, g.sources[i].matrixWorld);
-                cache.set(el, off);
-                dirty = true;
-            }
-            if (dirty)
-                g.instanced.instanceMatrix.needsUpdate = true;
-        }
-    }
-    /**
-     * Raycast against the batched instances, mapping a hit back to the logical source
-     * Object3D (so editor/gameplay picking still resolves a detached entity).
-     */
-    raycast(raycaster) {
-        const hits = raycaster.intersectObject(this.root, true);
-        for (const h of hits) {
-            const members = this.membersOf.get(h.object);
-            if (members && h.instanceId != null)
-                return members[h.instanceId] ?? null;
-        }
-        return null;
-    }
-    /** Number of draw calls the batcher contributes (1 per group). */
-    get drawCalls() {
-        return this.groups.length;
-    }
-    /** How many source meshes were collapsed into instances. */
-    get batchedCount() {
-        return this.groups.reduce((n, g) => n + g.sources.length, 0);
-    }
-    teardown() {
-        for (const g of this.groups) {
-            for (const s of g.sources) {
-                if (g.dynamic)
-                    s.visible = true; // dynamic sources stayed in-graph, hidden
-                else {
-                    const parent = this.parentOf.get(s); // static sources were detached — re-attach
-                    if (parent)
-                        parent.add(s);
-                }
-            }
-            g.instanced.dispose();
-            this.root.remove(g.instanced);
-        }
-        this.groups = [];
-        this.dynamicGroups = [];
-        if (this.root.parent)
-            this.root.parent.remove(this.root);
-    }
-}

package/dist/render/render-features.d.ts

@@ -1,47 +0,0 @@
-import { z } from 'zod';
-/**
- * The render-feature registry — single source of truth for every togglable render
- * setting. The scene schema (`SceneEnvironment.rendering`, `SceneEntity.render`),
- * the cascade resolver (`resolveRenderSettings`), the editor UI, and the stats
- * overlay are all derived from this list, so "everything togglable" stays
- * consistent by construction (same posture as the component/material/instancer
- * registries). Adding a feature here gives it a schema field + cascade entry for
- * free. See docs/research/RENDER-SETTINGS-UX.md.
- */
-export type RenderFeatureValue = boolean | number | string;
-export interface RenderFeature {
-    /** Stable key used in schema, cascade, and UI. */
-    key: string;
-    /** Editor display label. */
-    label: string;
-    /** Schema `.describe()` text (powers JSON Schema / inspector docs). */
-    description: string;
-    /** Control shape. */
-    kind: 'toggle' | 'number' | 'enum';
-    /** Engine default — the "fast by default" baseline. */
-    default: RenderFeatureValue;
-    /**
-     * `live` re-applies on change; `reload` needs a renderer re-init (e.g. backend,
-     * antialias). The editor badges `reload` features and re-inits the viewport.
-     */
-    apply: 'live' | 'reload';
-    /** Whether this feature may be overridden per-entity (the entity cascade layer). */
-    perEntity: boolean;
-    /** Allowed values for `enum` kind. */
-    options?: readonly string[];
-    /** [min, max] for `number` kind. */
-    range?: readonly [number, number];
-}
-export declare const RENDER_FEATURES: readonly RenderFeature[];
-/** Map for O(1) lookup by key. */
-export declare const RENDER_FEATURE_BY_KEY: ReadonlyMap<string, RenderFeature>;
-/**
- * Build a Zod object for the render settings, derived from the registry so the
- * schema can never drift from the feature list. All fields optional — absence
- * means "inherit" in the cascade. `perEntityOnly` builds the per-entity override
- * schema (only features whose `perEntity` is true).
- */
-export declare function buildRenderingZod(opts?: {
-    perEntityOnly?: boolean;
-}): z.ZodTypeAny;
-//# sourceMappingURL=render-features.d.ts.map

package/dist/render/render-features.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render-features.d.ts","sourceRoot":"","sources":["../../src/render/render-features.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnC,uDAAuD;IACvD,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EA6EnD,CAAC;AAEF,kCAAkC;AAClC,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAEpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CAAC,CAAC,UAAU,CAiBtF"}

package/dist/render/render-features.js

@@ -1,105 +0,0 @@
-import { z } from 'zod';
-export const RENDER_FEATURES = [
-    {
-        key: 'autoBatch',
-        label: 'Auto-batching',
-        description: 'Automatically batch entities sharing geometry+material into one draw call (InstancedMesh/BatchedMesh) while keeping each Object3D as the handle. The headline perf win; opt out per-entity for custom-shader/skinned meshes.',
-        kind: 'toggle',
-        default: true,
-        apply: 'live',
-        perEntity: true,
-    },
-    {
-        key: 'frustumCulling',
-        label: 'Frustum culling',
-        description: 'Per-instance frustum culling for batched content.',
-        kind: 'toggle',
-        default: true,
-        apply: 'live',
-        perEntity: true,
-    },
-    {
-        key: 'lod',
-        label: 'Level of detail',
-        description: 'Distance-based geometry swap (LOD) for eligible entities.',
-        kind: 'toggle',
-        default: true,
-        apply: 'live',
-        perEntity: true,
-    },
-    {
-        key: 'shadows',
-        label: 'Shadows',
-        description: 'Enable the shadow map. Per-entity cast/receive still applies.',
-        kind: 'toggle',
-        default: true,
-        apply: 'live',
-        perEntity: true,
-    },
-    {
-        key: 'postProcessing',
-        label: 'Post-processing',
-        description: 'Master switch for the post-processing stack (individual effects nest beneath it).',
-        kind: 'toggle',
-        default: true,
-        apply: 'live',
-        perEntity: false,
-    },
-    {
-        key: 'resolutionScale',
-        label: 'Resolution scale',
-        description: 'Device-pixel-ratio multiplier (1.0 = native). The cheapest perf dial.',
-        kind: 'number',
-        default: 1,
-        apply: 'live',
-        perEntity: false,
-        range: [0.25, 2],
-    },
-    {
-        key: 'antialias',
-        label: 'Antialiasing',
-        description: 'MSAA via renderer construction. Applies on reload (renderer re-init).',
-        kind: 'toggle',
-        default: true,
-        apply: 'reload',
-        perEntity: false,
-    },
-    {
-        key: 'backend',
-        label: 'Renderer backend',
-        description: 'GPU backend: auto picks WebGPU when available, else WebGL2. Applies on reload.',
-        kind: 'enum',
-        default: 'auto',
-        apply: 'reload',
-        perEntity: false,
-        options: ['auto', 'webgl', 'webgpu'],
-    },
-];
-/** Map for O(1) lookup by key. */
-export const RENDER_FEATURE_BY_KEY = new Map(RENDER_FEATURES.map((f) => [f.key, f]));
-/**
- * Build a Zod object for the render settings, derived from the registry so the
- * schema can never drift from the feature list. All fields optional — absence
- * means "inherit" in the cascade. `perEntityOnly` builds the per-entity override
- * schema (only features whose `perEntity` is true).
- */
-export function buildRenderingZod(opts = {}) {
-    const shape = {};
-    for (const f of RENDER_FEATURES) {
-        if (opts.perEntityOnly && !f.perEntity)
-            continue;
-        let base;
-        if (f.kind === 'toggle')
-            base = z.boolean();
-        else if (f.kind === 'number')
-            base = z.number();
-        else
-            base = z.enum(f.options);
-        shape[f.key] = base.optional().describe(f.description);
-    }
-    return z
-        .object(shape)
-        .describe(opts.perEntityOnly
-        ? 'Per-entity render overrides (omit a field to inherit from the scene/engine default)'
-        : 'Scene render settings (omit a field to inherit the engine default)');
-}

package/dist/render/render-settings.d.ts

@@ -1,36 +0,0 @@
-import { type RenderFeatureValue } from './render-features';
-/**
- * Cascade resolution for render settings: engine default → scene → entity, with
- * tri-state inherit (an absent value inherits from the next level up). See
- * docs/research/RENDER-SETTINGS-UX.md.
- */
-/** A partial override map (scene-level or entity-level). Absent key = inherit. */
-export type RenderScope = Partial<Record<string, RenderFeatureValue>>;
-/** Fully-resolved settings: every registry key present. */
-export type ResolvedRenderSettings = Record<string, RenderFeatureValue>;
-/**
- * Resolve effective settings. `entity` overrides only apply to features whose
- * `perEntity` flag is set; non-per-entity features resolve across engine→scene
- * only. `??` walks up the chain on `undefined` (inherit) but lets an explicit
- * `false`/`0` override (they are not nullish).
- */
-export declare function resolveRenderSettings(scene?: RenderScope, entity?: RenderScope): ResolvedRenderSettings;
-/**
- * A small observable holding the live scene-level resolved settings. Live
- * features re-apply when a value changes (subscribers are notified with the
- * changed key). This is the seam a future player-facing graphics menu would
- * drive — for now it backs the editor toggles + the runtime systems.
- */
-export declare class RenderSettings {
-    private values;
-    private listeners;
-    constructor(scene?: RenderScope);
-    get(key: string): RenderFeatureValue;
-    /** Set a scene-level value; notifies subscribers if it changed. */
-    set(key: string, value: RenderFeatureValue): void;
-    /** Resolve the effective value for an entity (entity override → scene → default). */
-    forEntity(key: string, entity?: RenderScope): RenderFeatureValue;
-    subscribe(fn: (key: string, value: RenderFeatureValue) => void): () => void;
-    snapshot(): ResolvedRenderSettings;
-}
-//# sourceMappingURL=render-settings.d.ts.map

package/dist/render/render-settings.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render-settings.d.ts","sourceRoot":"","sources":["../../src/render/render-settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE7E;;;;GAIG;AAEH,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEtE,2DAA2D;AAC3D,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,sBAAsB,CAOxB;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,SAAS,CAA+D;gBAEpE,KAAK,CAAC,EAAE,WAAW;IAI/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB;IAIpC,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAMjD,qFAAqF;IACrF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,kBAAkB;IAKhE,SAAS,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI;IAK3E,QAAQ,IAAI,sBAAsB;CAGnC"}

package/dist/render/render-settings.js

@@ -1,51 +0,0 @@
-import { RENDER_FEATURES } from './render-features';
-/**
- * Resolve effective settings. `entity` overrides only apply to features whose
- * `perEntity` flag is set; non-per-entity features resolve across engine→scene
- * only. `??` walks up the chain on `undefined` (inherit) but lets an explicit
- * `false`/`0` override (they are not nullish).
- */
-export function resolveRenderSettings(scene, entity) {
-    const out = {};
-    for (const f of RENDER_FEATURES) {
-        const entityVal = f.perEntity ? entity?.[f.key] : undefined;
-        out[f.key] = entityVal ?? scene?.[f.key] ?? f.default;
-    }
-    return out;
-}
-/**
- * A small observable holding the live scene-level resolved settings. Live
- * features re-apply when a value changes (subscribers are notified with the
- * changed key). This is the seam a future player-facing graphics menu would
- * drive — for now it backs the editor toggles + the runtime systems.
- */
-export class RenderSettings {
-    values;
-    listeners = new Set();
-    constructor(scene) {
-        this.values = resolveRenderSettings(scene);
-    }
-    get(key) {
-        return this.values[key];
-    }
-    /** Set a scene-level value; notifies subscribers if it changed. */
-    set(key, value) {
-        if (this.values[key] === value)
-            return;
-        this.values[key] = value;
-        for (const fn of this.listeners)
-            fn(key, value);
-    }
-    /** Resolve the effective value for an entity (entity override → scene → default). */
-    forEntity(key, entity) {
-        const f = entity?.[key];
-        return f ?? this.values[key];
-    }
-    subscribe(fn) {
-        this.listeners.add(fn);
-        return () => this.listeners.delete(fn);
-    }
-    snapshot() {
-        return { ...this.values };
-    }
-}