@vgai/engine 0.5.0 → 0.5.1

package/dist/dev/performance-profiler.js

@@ -1,181 +0,0 @@
-const now = () => globalThis.performance?.now() ?? Date.now();
-function percentile(values, fraction) {
-    if (values.length === 0)
-        return 0;
-    const sorted = [...values].sort((a, b) => a - b);
-    return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))] ?? 0;
-}
-/** Game-owned, bounded external store for browser-native performance diagnostics. */
-export function createPerformanceProfiler(initiallyEnabled = false) {
-    const listeners = new Set();
-    const frames = [];
-    const currentPhases = new Map();
-    const currentSystems = new Map();
-    const currentComponents = new Map();
-    let enabled = initiallyEnabled;
-    let recording = false;
-    let frameId = 0;
-    let frameStart = 0;
-    let lastFrameStart = 0;
-    let phaseStart = 0;
-    let systemStart = 0;
-    let componentStart = 0;
-    let render = {
-        gpuMs: null,
-        drawCalls: 0,
-        triangles: 0,
-        geometries: 0,
-        textures: 0,
-    };
-    let snapshot = {
-        enabled,
-        recording,
-        fps: 0,
-        cpuMs: 0,
-        p95Ms: 0,
-        p99Ms: 0,
-        frames,
-        phases: [],
-        systems: [],
-        components: [],
-        render,
-    };
-    function publish() {
-        const latest = frames.at(-1);
-        const intervals = frames.map((frame) => frame.intervalMs).filter((value) => value > 0);
-        snapshot = {
-            enabled,
-            recording,
-            fps: latest?.intervalMs ? 1000 / latest.intervalMs : 0,
-            cpuMs: latest?.cpuMs ?? 0,
-            p95Ms: percentile(intervals, 0.95),
-            p99Ms: percentile(intervals, 0.99),
-            frames,
-            phases: latest?.phases ?? [],
-            systems: [...currentSystems].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
-            components: [...currentComponents]
-                .map(([name, ms]) => ({ name, ms }))
-                .sort((a, b) => b.ms - a.ms),
-            render,
-        };
-        for (const listener of listeners)
-            listener();
-    }
-    return {
-        get enabled() {
-            return enabled;
-        },
-        set enabled(value) {
-            if (enabled === value)
-                return;
-            enabled = value;
-            publish();
-        },
-        get recording() {
-            return recording;
-        },
-        startRecording() {
-            enabled = true;
-            recording = true;
-            frames.length = 0;
-            publish();
-        },
-        stopRecording() {
-            recording = false;
-            publish();
-        },
-        clear() {
-            frames.length = 0;
-            publish();
-        },
-        beginFrame() {
-            if (!enabled)
-                return;
-            currentPhases.clear();
-            currentSystems.clear();
-            currentComponents.clear();
-            render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
-            frameStart = now();
-        },
-        beginPhase() {
-            if (!enabled)
-                return;
-            phaseStart = now();
-        },
-        endPhase(name) {
-            if (!enabled)
-                return;
-            const elapsed = now() - phaseStart;
-            currentPhases.set(name, (currentPhases.get(name) ?? 0) + elapsed);
-            if (recording)
-                performance.measure(`vgai.phase.${name}`, { start: phaseStart, duration: elapsed });
-        },
-        systemObserver: {
-            beginSystem() {
-                if (!enabled)
-                    return;
-                systemStart = now();
-            },
-            endSystem(scope, phase, name) {
-                if (!enabled)
-                    return;
-                const end = now();
-                const key = `${scope} / ${phase} / ${name}`;
-                currentSystems.set(key, (currentSystems.get(key) ?? 0) + end - systemStart);
-            },
-        },
-        beginComponent() {
-            if (!recording)
-                return;
-            componentStart = now();
-        },
-        endComponent(name) {
-            if (!recording)
-                return;
-            currentComponents.set(name, (currentComponents.get(name) ?? 0) + now() - componentStart);
-        },
-        reportRender(stats) {
-            if (!enabled)
-                return;
-            render = {
-                gpuMs: stats.gpuMs ?? render.gpuMs,
-                drawCalls: render.drawCalls + stats.drawCalls,
-                triangles: render.triangles + stats.triangles,
-                geometries: render.geometries + stats.geometries,
-                textures: render.textures + stats.textures,
-            };
-        },
-        endFrame() {
-            if (!enabled)
-                return;
-            const timestamp = now();
-            const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
-            lastFrameStart = frameStart;
-            const frame = {
-                id: ++frameId,
-                timestamp,
-                intervalMs,
-                cpuMs: timestamp - frameStart,
-                phases: [...currentPhases].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
-            };
-            frames.push(frame);
-            if (frames.length > 600)
-                frames.splice(0, frames.length - 600);
-            if (recording)
-                performance.measure('vgai.frame', { start: frameStart, duration: frame.cpuMs });
-            publish();
-        },
-        subscribe(listener) {
-            listeners.add(listener);
-            return () => {
-                listeners.delete(listener);
-            };
-        },
-        getSnapshot() {
-            return snapshot;
-        },
-        exportJSON() {
-            return JSON.stringify({ version: 1, capturedAt: new Date().toISOString(), frames }, null, 2);
-        },
-    };
-}

package/dist/dev/webgl-gpu-timer.d.ts

@@ -1,8 +0,0 @@
-/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
-export declare function createWebGLGpuTimer(context: WebGLRenderingContext | WebGL2RenderingContext): {
-    begin(): void;
-    end(): void;
-    poll(): number | null;
-    dispose(): void;
-};
-//# sourceMappingURL=webgl-gpu-timer.d.ts.map

package/dist/dev/webgl-gpu-timer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"webgl-gpu-timer.d.ts","sourceRoot":"","sources":["../../src/dev/webgl-gpu-timer.ts"],"names":[],"mappings":"AAKA,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,sBAAsB;;;YAsB/E,MAAM,GAAG,IAAI;;EAwBxB"}

package/dist/dev/webgl-gpu-timer.js

@@ -1,52 +0,0 @@
-/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
-export function createWebGLGpuTimer(context) {
-    const gl = context;
-    const extension = gl.getExtension('EXT_disjoint_timer_query_webgl2');
-    const supported = extension !== null && typeof gl.createQuery === 'function';
-    const pending = [];
-    let active = null;
-    let latestMs = null;
-    return {
-        begin() {
-            if (!supported || active)
-                return;
-            active = gl.createQuery();
-            if (active)
-                gl.beginQuery(extension.TIME_ELAPSED_EXT, active);
-        },
-        end() {
-            if (!supported || !active)
-                return;
-            gl.endQuery(extension.TIME_ELAPSED_EXT);
-            pending.push(active);
-            active = null;
-        },
-        poll() {
-            if (!supported)
-                return null;
-            if (gl.getParameter(extension.GPU_DISJOINT_EXT)) {
-                for (const query of pending.splice(0))
-                    gl.deleteQuery(query);
-                return null;
-            }
-            while (pending.length > 0) {
-                const query = pending[0];
-                if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE))
-                    break;
-                pending.shift();
-                latestMs = gl.getQueryParameter(query, gl.QUERY_RESULT) / 1_000_000;
-                gl.deleteQuery(query);
-            }
-            return latestMs;
-        },
-        dispose() {
-            if (active) {
-                gl.endQuery(extension.TIME_ELAPSED_EXT);
-                gl.deleteQuery(active);
-                active = null;
-            }
-            for (const query of pending.splice(0))
-                gl.deleteQuery(query);
-        },
-    };
-}

package/dist/ecs/component-manager.d.ts

@@ -1,205 +0,0 @@
-import type { PhysicsRegistry } from '../physics/physics-registry';
-import { type AdapterSurface, type WorldInstance } from '../runtime/game';
-import type { GameContext } from '../runtime/types';
-import type { Physics2DRegistry } from '../world2d/physics2d-registry';
-import { GameComponent, type GameComponentClass, type NodeOf } from './game-component';
-/**
- * The manager's node/instance types, widened over every `AdapterSurface` (T7.2
- * slice 2, D8 §3). `NodeOf<AdapterSurface>` distributes to `THREE.Object3D |
- * PIXI.Container` (react contributes `never`, which drops out of the
- * union) — this is what lets a single manager instance be constructed for
- * ANY one kind (threejs, pixijs, or react) while still type-checking
- * `attach()` calls made with a default-kind (`GameComponent`, K =
- * 'threejs') instance, unmodified, from every existing call site.
- */
-type AnyNode = NodeOf<AdapterSurface>;
-type AnyComponent = GameComponent<AdapterSurface>;
-/**
- * Optional identity a caller of `attach()` can supply for a component instance
- * it looked up in a `ComponentRegistry`/`Component2DRegistry` (T5.4) — `key` is
- * the name the class was registered under (the swap key `hotSwap` matches on),
- * `props` is the raw, pre-`schema.parse` authored data for that instance (kept
- * so a later `hotSwap` can re-validate it against a NEW class version's
- * `static schema`). Deliberately NOT imported from `scene/component-registry.ts`
- * to avoid a cycle (that module already imports `ComponentManager` from here) —
- * this is a structural duck-type of the same shape.
- */
-export interface RegistryAttachInfo {
-    key: string;
-    props: Record<string, unknown>;
-}
-/**
- * Manages GameComponent instances attached to entities (Object3Ds).
- *
- * Tracks instances per Object3D and per phase. Registers one tick function per
- * phase via `ctx.systems.setComponentTick(phase, ...)` (T7.1 slice 2) — a
- * dedicated slot, not a bare `add()`ed system. `SystemRunner.runPhase` always
- * runs the componentTick slot after every engine-bucket system and before
- * every game-bucket system in that phase, so component updates interleave
- * correctly with engine systems BY STRUCTURE: an engine system `add()`ed
- * after this manager is constructed still runs before its tick (see
- * `test/system-runs-before-component-tick.test.ts`).
- *
- * Kind (T7.2 slice 2, D8 §3): a manager is constructed for exactly ONE
- * `AdapterSurface` (`opts.kind`, default `'threejs'` — every existing call site
- * omits it and gets the same manager slice 1 built). `attach()` enforces two
- * rules against that kind, loudly:
- *  - a `'react'`-kind manager throws on EVERY attach (react entities host no
- *    GameComponents — render from game state via the T7.4 state bridge);
- *  - any other kind throws when the component's `static declaredKind` is set
- *    and doesn't match this manager's kind (`'any'` is exempt — a
- *    kind-agnostic component may attach wherever components are legal).
- * A `'pixijs'`-kind manager wires `rigidBody`/`collider` from `opts.physics2d`
- * (a `Physics2DRegistry`) instead of the 3D `physics: PhysicsRegistry`
- * parameter — the field names match by design (`world2d/types.ts`), so this
- * is a retype of the wiring, not a new shape. `physics` is optional (T7.3
- * slice 2) — a `'pixijs'`-kind manager never reads it (`resolvePhysicsRefs`
- * below only reaches the 3D branch for a non-pixijs manager), so a caller
- * building one no longer has to construct a throwaway 3D `PhysicsRegistry`
- * just to satisfy this signature.
- */
-export declare function createComponentManager(ctx: GameContext, physics?: PhysicsRegistry, opts?: {
-    kind?: AdapterSurface;
-    physics2d?: Physics2DRegistry;
-}): {
-    /** Attach a component instance to an entity node (Object3D in a threejs
-     *  world, PIXI.Container in a pixijs world). Validates the attach rules
-     *  (§3: react-world throw, kind-mismatch throw) synchronously before any
-     *  structural change, whether or not a phase tick is currently running.
-     *  `registry` (T5.4, optional) records the `componentRegistry` name +
-     *  pre-`schema.parse` authored data a scene-authored attach looked the
-     *  class up under — `hotSwap` keys on it instead of the live
-     *  `constructor.name`. Omit it for an ad-hoc, code-attached instance (no
-     *  registry entry) — `hotSwap` falls back to matching those by class name,
-     *  unchanged from pre-T5.4 behavior. */
-    attach(node: AnyNode, instance: AnyComponent, registry?: RegistryAttachInfo): void;
-    /**
-     * Call init() on all components that haven't been initialized yet, and
-     * wait for them to resolve. Components attached since the last call are
-     * covered. Safe to call even when the automatic per-frame flush has
-     * already started some of them — `startInit` is idempotent per instance,
-     * so this awaits the same in-flight promise rather than double-invoking
-     * init(). Manual calls remain useful when subsequent code depends on an
-     * init()'s side effects having completed synchronously (the automatic
-     * flush only guarantees "ticking starts once init resolves", not
-     * "resolved by the time this function returns").
-     */
-    initAll(): Promise<void>;
-    /** Remove all components from an entity node, calling dispose. */
-    detach(node: AnyNode): void;
-    /**
-     * Backfill `instance.world` for every already-attached instance whose
-     * world is still undefined (T7.2 slice 2 — closes the KNOWN GAP
-     * documented on `resolveWorldInstance` above). A ONE-TIME wiring
-     * completion, called exactly once by `registerThreeWorld`
-     * (`create-runtime.ts`) right after this manager's `WorldInstance` is
-     * constructed — NOT a lazy getter, NOT a per-frame sync: a plain
-     * backfill pass over the existing `byEntity` bookkeeping, with no
-     * ongoing cost once it returns. Idempotent and safe to call more than
-     * once (only ever touches instances still missing a world).
-     */
-    adoptWorld(world: WorldInstance): void;
-    /** Get all component instances for an entity node. */
-    getComponents(node: AnyNode): AnyComponent[];
-    /**
-     * Get the first attached instance of a given component class on an
-     * entity node — the typed single-component sibling of `getComponents`
-     * (issue #99: `onTriggerEnter`'s `other` is a raw node; this is how a
-     * handler asks "does my trigger partner have a `Collectible` (or
-     * whatever marker) component?" instead of an untyped `getComponents`
-     * walk or a fragile `other.name === '...'` display-name check).
-     * Matches via `instanceof`, so a subclass of `cls` is returned too
-     * (same subclass handling as `queryByComponent`). Same ordering as
-     * `getComponents` (attach order for that node) and, like
-     * `getComponents`, does NOT exclude instances pending-detach this tick
-     * — a caller inside a phase tick that cares should filter itself, same
-     * as any other `getComponents` consumer. `undefined` if the node has no
-     * attached instance of `cls`.
-     */
-    getComponent<T extends AnyComponent>(node: AnyNode, cls: new () => T): T | undefined;
-    /**
-     * Query all live attached instances of a given component class within
-     * THIS manager — the per-world half of the §5 cross-world query
-     * (`docs/GAME-ROOT-DESIGN.md` §5; `Game.queryByComponent` in
-     * `runtime/game.ts` is the game-level aggregation over every world's
-     * manager).
-     *
-     * Returns instances (not nodes), `instanceof cls`, in stable attach
-     * order — walked from the existing `byEntity` bookkeeping (the same
-     * structure `hotSwap`/`clear` iterate), not a new index, so correctness
-     * tracks the manager's real attach/detach state rather than a
-     * maintained-in-parallel cache. Order note: this is attach order
-     * PER ENTITY (the order components were pushed for that Object3D),
-     * concatenated in `byEntity`'s insertion order (first-attach order of
-     * the entities themselves) — for the common case of each entity
-     * attached once this coincides with global chronological attach order;
-     * it would not for an entity re-attached to after other entities were
-     * attached in between, which this manager does not otherwise track a
-     * global order for.
-     *
-     * Excludes instances pending-detach this tick (`detachedThisTick`) —
-     * mirrors the same use-after-dispose guard the phase tick applies, so a
-     * query run mid-tick (e.g. from inside a component's `update`) never
-     * returns something already torn down this frame.
-     */
-    queryByComponent<T extends AnyComponent>(cls: new () => T): T[];
-    /**
-     * Hot-swap prototypes for every live instance registered under `name`
-     * (T5.4). State on `this` survives; method bodies update to the new
-     * class. `name` is matched against each instance's RECORDED registry key
-     * (`registryKeyOf`, set by `attach()`'s optional `registry` argument) —
-     * not the live `constructor.name`, which is fragile under minification, a
-     * class rename, or two distinct classes sharing one runtime name (a
-     * registry key is stable identity chosen at scene-author time,
-     * independent of what the class calls itself). An instance attached
-     * WITHOUT a registry key (ad-hoc/code-attached — no `ComponentRegistry`
-     * entry) has no such recorded identity, so it falls back to the legacy
-     * `constructor.name` compare — this is the ONLY place that fallback
-     * applies; a registry-keyed instance never matches by name, so two
-     * registry-keyed classes that happen to share a `constructor.name` (e.g.
-     * both minified to the same short name) swap independently.
-     *
-     * Zero matches is a loud swap-miss (`hmr-swap-report.ts`), never a silent
-     * no-op — this is "renamed class → loud miss" (docs/BACKBONE-TASKS.md's
-     * T5.4 detail note): if a dev renames a component's export, the hot
-     * update arrives keyed under the NEW name, no live instance is recorded
-     * under it yet (the registry/scene JSON hasn't been re-authored), so
-     * nothing matches and the warning fires — the OLD class stays in effect
-     * rather than the rename silently doing nothing.
-     *
-     * GameComponent-subclass guard (§7.1-5, probe7): every editor HMR call
-     * site passes any `typeof value === 'function'` module export — that used
-     * to include a plain helper function sharing a live component's registry
-     * key/name, which this method would happily `Object.setPrototypeOf` onto
-     * a live instance, leaving it with no `update()` (a caught-and-logged
-     * `TypeError` every frame, forever). `NewClass` is now required to have
-     * `GameComponent` somewhere in its prototype chain — anything else is
-     * refused OUTRIGHT, loudly, with NO instance touched. This is a second,
-     * independent line of defense behind the call-site filter
-     * (`play-mode.ts`'s HMR handlers now filter to `value.prototype
-     * instanceof GameComponent` before ever calling this) — belt AND
-     * suspenders, so a future caller that forgets to filter still can't
-     * corrupt a live instance.
-     *
-     * `opts.warnOnMiss` (default `true`, §7.1-4/probe2b): the multi-world HMR
-     * fan-out (`play-mode.ts`'s `hotSwapAcrossWorlds`) calls this once per
-     * first-party world and must not let a per-world zero-match here look
-     * like "renamed class" when the name simply lives in a DIFFERENT world's
-     * manager — the fan-out helper suppresses this method's own warning
-     * (`{ warnOnMiss: false }`) and emits the ONE real warning itself only
-     * when the total across every world is zero. Every other existing caller
-     * (`applyBrowserComponentEdit`, the dev HMR demos, every hotSwap unit
-     * test) omits `opts` and keeps today's per-call warn-on-miss behavior
-     * unchanged. Returns the number of live instances swapped, so a caller
-     * that needs to aggregate across several managers (the fan-out helper)
-     * can sum it without re-deriving it from a side-channel.
-     */
-    hotSwap(name: string, NewClass: GameComponentClass, opts?: {
-        warnOnMiss?: boolean;
-    }): number;
-    /** Dispose all components and clear all maps. */
-    clear(): void;
-};
-export type ComponentManager = ReturnType<typeof createComponentManager>;
-export {};
-//# sourceMappingURL=component-manager.d.ts.map

package/dist/ecs/component-manager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"component-manager.d.ts","sourceRoot":"","sources":["../../src/ecs/component-manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,KAAK,cAAc,EAAuB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EAEvB,KAAK,MAAM,EACZ,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;GAQG;AACH,KAAK,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AACtC,KAAK,YAAY,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAoDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,WAAW,EAChB,OAAO,CAAC,EAAE,eAAe,EACzB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,cAAc,CAAC;IAAC,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAAE;IA8Z7D;;;;;;;;;4CASwC;iBAC3B,OAAO,YAAY,YAAY,aAAa,kBAAkB;IAW3E;;;;;;;;;;OAUG;;IAMH,kEAAkE;iBACrD,OAAO;IAcpB;;;;;;;;;;OAUG;sBACe,aAAa,GAAG,IAAI;IAQtC,sDAAsD;wBAClC,OAAO,GAAG,YAAY,EAAE;IAI5C;;;;;;;;;;;;;;OAcG;iBACU,CAAC,SAAS,YAAY,QAAQ,OAAO,OAAO,UAAU,CAAC,GAAG,CAAC,GAAG,SAAS;IASpF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;qBACc,CAAC,SAAS,YAAY,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE;IAW/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;kBAEW,MAAM,YAAY,kBAAkB,SAAS;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM;IAyB5F,iDAAiD;;EA6BpD;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC"}