@jgengine/core 0.7.0 → 0.8.0

package/dist/devtools/devtools.js

@@ -0,0 +1,484 @@
+import { createChangeSignal } from "../store/changeSignal.js";
+const FRAME_CAPACITY = 240;
+const RECENT_FRAMES = 60;
+const LONG_FRAME_MS = 33.4;
+const LATENCY_CAPACITY = 120;
+const LOG_CAPACITY = 200;
+const LOG_MESSAGE_MAX = 400;
+const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function nowMs() {
+    const perf = globalThis.performance;
+    return perf !== undefined ? perf.now() : Date.now();
+}
+function inferKind(initial, hasOptions) {
+    if (hasOptions)
+        return "select";
+    if (typeof initial === "number")
+        return "slider";
+    if (typeof initial === "boolean")
+        return "toggle";
+    if (typeof initial === "string" && COLOR_PATTERN.test(initial))
+        return "color";
+    return "text";
+}
+function sliderBounds(initial, options) {
+    const min = options?.min ?? (initial < 0 ? initial * 2 : 0);
+    const max = options?.max ?? (initial > 0 ? initial * 2 : initial < 0 ? 0 : 1);
+    const step = options?.step ?? (max - min) / 100;
+    return { min, max, step };
+}
+function formatLogArg(arg) {
+    if (typeof arg === "string")
+        return arg;
+    if (arg instanceof Error)
+        return `${arg.name}: ${arg.message}`;
+    try {
+        return JSON.stringify(arg) ?? String(arg);
+    }
+    catch {
+        return String(arg);
+    }
+}
+export function formatLogMessage(args) {
+    const message = args.map(formatLogArg).join(" ");
+    return message.length > LOG_MESSAGE_MAX ? `${message.slice(0, LOG_MESSAGE_MAX)}…` : message;
+}
+function percentile(sorted, fraction) {
+    if (sorted.length === 0)
+        return 0;
+    const index = Math.min(sorted.length - 1, Math.floor(sorted.length * fraction));
+    return sorted[index];
+}
+const MAX_TABLE_ENTRIES = 64;
+function discoverableKind(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return "slider";
+    if (typeof value === "boolean")
+        return "toggle";
+    if (typeof value === "string" && COLOR_PATTERN.test(value))
+        return "color";
+    return null;
+}
+function discoverableEntries(candidate) {
+    if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate))
+        return [];
+    const proto = Object.getPrototypeOf(candidate);
+    if (proto !== Object.prototype && proto !== null)
+        return [];
+    const entries = [];
+    for (const [key, value] of Object.entries(candidate)) {
+        const kind = discoverableKind(value);
+        if (kind !== null)
+            entries.push([key, kind]);
+        if (entries.length > MAX_TABLE_ENTRIES)
+            return [];
+    }
+    return entries;
+}
+export function createDevtools() {
+    const signal = createChangeSignal();
+    const frameMsBuffer = new Float64Array(FRAME_CAPACITY);
+    const simMsBuffer = new Float64Array(FRAME_CAPACITY);
+    let frameIndex = 0;
+    let frameCount = 0;
+    let renderSample = null;
+    const logEntries = [];
+    let consoleCaptured = false;
+    const latencySamples = [];
+    const controlRecords = new Map();
+    const discoveredRecords = new Map();
+    const probeReaders = new Map();
+    const readProbes = () => {
+        const values = {};
+        for (const [name, read] of probeReaders) {
+            try {
+                values[name] = read();
+            }
+            catch (error) {
+                values[name] = `probe failed: ${formatLogArg(error)}`;
+            }
+        }
+        return values;
+    };
+    const pushLog = (level, message) => {
+        logEntries.push({ at: Date.now(), level, message });
+        if (logEntries.length > LOG_CAPACITY)
+            logEntries.splice(0, logEntries.length - LOG_CAPACITY);
+    };
+    const frameStats = () => {
+        if (frameCount === 0)
+            return null;
+        const size = Math.min(frameCount, FRAME_CAPACITY);
+        const frames = [];
+        const sims = [];
+        for (let offset = 0; offset < size; offset += 1) {
+            const at = (frameIndex - size + offset + FRAME_CAPACITY) % FRAME_CAPACITY;
+            frames.push(frameMsBuffer[at]);
+            sims.push(simMsBuffer[at]);
+        }
+        const recent = frames.slice(-RECENT_FRAMES);
+        const recentAvg = recent.reduce((sum, ms) => sum + ms, 0) / recent.length;
+        const sorted = [...frames].sort((a, b) => a - b);
+        return {
+            fps: recentAvg > 0 ? 1000 / recentAvg : 0,
+            avgFrameMs: frames.reduce((sum, ms) => sum + ms, 0) / frames.length,
+            p95FrameMs: percentile(sorted, 0.95),
+            maxFrameMs: sorted[sorted.length - 1],
+            avgSimMs: sims.reduce((sum, ms) => sum + ms, 0) / sims.length,
+            maxSimMs: sims.reduce((max, ms) => Math.max(max, ms), 0),
+            longFrames: frames.filter((ms) => ms > LONG_FRAME_MS).length,
+            samples: size,
+            recentFrameMs: recent,
+        };
+    };
+    const latencyStats = () => {
+        if (latencySamples.length === 0)
+            return null;
+        let min = Number.POSITIVE_INFINITY;
+        let max = 0;
+        let sum = 0;
+        for (const ms of latencySamples) {
+            min = Math.min(min, ms);
+            max = Math.max(max, ms);
+            sum += ms;
+        }
+        return {
+            lastMs: latencySamples[latencySamples.length - 1],
+            avgMs: sum / latencySamples.length,
+            minMs: min,
+            maxMs: max,
+            samples: latencySamples.length,
+        };
+    };
+    const toControl = (record) => ({
+        name: record.name,
+        kind: record.kind,
+        label: record.label,
+        group: record.group,
+        initial: record.initial,
+        min: record.min,
+        max: record.max,
+        step: record.step,
+        options: record.options,
+        read: () => record.value,
+        write: (value) => writeControl(record, value),
+        reset: () => writeControl(record, record.initial),
+    });
+    const writeControl = (record, raw) => {
+        let next = raw;
+        if (record.kind === "slider" && typeof next === "number") {
+            if (record.min !== undefined)
+                next = Math.max(record.min, next);
+            if (record.max !== undefined)
+                next = Math.min(record.max, next);
+        }
+        if (Object.is(record.value, next))
+            return;
+        record.value = next;
+        for (const listener of record.listeners)
+            listener(next);
+        signal.notify();
+    };
+    const register = (name, initial, options) => {
+        const kind = inferKind(initial, options?.options !== undefined);
+        const existing = controlRecords.get(name);
+        const slashIndex = name.indexOf("/");
+        const derivedGroup = slashIndex > 0 ? name.slice(0, slashIndex) : "general";
+        const derivedLabel = slashIndex > 0 ? name.slice(slashIndex + 1) : name;
+        const bounds = kind === "slider" ? sliderBounds(initial, options) : undefined;
+        const record = existing !== undefined && existing.kind === kind
+            ? existing
+            : {
+                name,
+                kind,
+                label: "",
+                group: "",
+                initial,
+                value: initial,
+                listeners: new Set(),
+            };
+        record.label = options?.label ?? derivedLabel;
+        record.group = options?.group ?? derivedGroup;
+        record.initial = initial;
+        record.min = bounds?.min;
+        record.max = bounds?.max;
+        record.step = bounds?.step;
+        record.options = options?.options;
+        if (options?.onChange !== undefined)
+            record.listeners.add(options.onChange);
+        controlRecords.set(name, record);
+        signal.notify();
+        return {
+            name,
+            kind,
+            initial,
+            get value() {
+                return record.value;
+            },
+            set: (value) => writeControl(record, value),
+            reset: () => writeControl(record, record.initial),
+            subscribe: (listener) => {
+                record.listeners.add(listener);
+                return () => record.listeners.delete(listener);
+            },
+        };
+    };
+    const bindDiscovered = (table, key, kind, accessor, source) => {
+        const id = `${table}/${key}`;
+        const existing = discoveredRecords.get(id);
+        if (existing === undefined) {
+            discoveredRecords.set(id, {
+                id,
+                table,
+                key,
+                kind,
+                initial: accessor.initial,
+                enabled: false,
+                source,
+                get: accessor.get,
+                set: accessor.set,
+            });
+            return true;
+        }
+        if (source !== null && existing.source === source)
+            return false;
+        existing.source = source;
+        existing.get = accessor.get;
+        existing.set = accessor.set;
+        const control = controlRecords.get(id);
+        if (existing.enabled && control !== undefined)
+            accessor.set(control.value);
+        return true;
+    };
+    const scanTable = (table, candidate) => {
+        const entries = discoverableEntries(candidate);
+        if (entries.length === 0)
+            return 0;
+        const target = candidate;
+        let changed = false;
+        for (const [key, kind] of entries) {
+            const accessor = {
+                initial: target[key],
+                get: () => target[key],
+                set: (value) => {
+                    target[key] = value;
+                },
+            };
+            if (bindDiscovered(table, key, kind, accessor, target))
+                changed = true;
+        }
+        if (changed)
+            signal.notify();
+        return entries.length;
+    };
+    const enableDiscovered = (id) => {
+        const record = discoveredRecords.get(id);
+        if (record === undefined || record.enabled)
+            return;
+        record.enabled = true;
+        const current = record.get();
+        const handle = register(id, record.initial, { group: record.table, label: record.key });
+        handle.subscribe((value) => record.set(value));
+        if (!Object.is(current, record.initial))
+            handle.set(current);
+    };
+    return {
+        frame: {
+            record({ frameMs, simMs }) {
+                frameMsBuffer[frameIndex] = frameMs;
+                simMsBuffer[frameIndex] = simMs;
+                frameIndex = (frameIndex + 1) % FRAME_CAPACITY;
+                frameCount += 1;
+            },
+            stats: frameStats,
+        },
+        render: {
+            record(sample) {
+                renderSample = sample;
+            },
+            latest: () => renderSample,
+        },
+        logs: {
+            push: pushLog,
+            captureConsole() {
+                if (consoleCaptured)
+                    return;
+                const globalConsole = globalThis.console;
+                if (globalConsole === undefined)
+                    return;
+                consoleCaptured = true;
+                const levels = ["log", "info", "warn", "error"];
+                for (const level of levels) {
+                    const original = globalConsole[level].bind(globalConsole);
+                    globalConsole[level] = (...args) => {
+                        pushLog(level, formatLogMessage(args));
+                        original(...args);
+                    };
+                }
+            },
+            list: () => logEntries,
+            clear() {
+                logEntries.length = 0;
+                signal.notify();
+            },
+        },
+        latency: {
+            record(ms) {
+                latencySamples.push(ms);
+                if (latencySamples.length > LATENCY_CAPACITY)
+                    latencySamples.splice(0, latencySamples.length - LATENCY_CAPACITY);
+            },
+            stats: latencyStats,
+        },
+        controls: {
+            register,
+            list: () => [...controlRecords.values()].map(toControl),
+            get: (name) => {
+                const record = controlRecords.get(name);
+                return record === undefined ? null : toControl(record);
+            },
+            remove(name) {
+                if (controlRecords.delete(name))
+                    signal.notify();
+            },
+            resetAll() {
+                for (const record of controlRecords.values())
+                    writeControl(record, record.initial);
+            },
+        },
+        discover: {
+            bind(table, key, accessor) {
+                const kind = discoverableKind(accessor.initial);
+                if (kind === null)
+                    return;
+                if (bindDiscovered(table, key, kind, accessor, null))
+                    signal.notify();
+            },
+            scanTable,
+            scanModule(exports) {
+                let total = 0;
+                for (const [name, value] of Object.entries(exports)) {
+                    total += scanTable(name, value);
+                }
+                return total;
+            },
+            list: () => [...discoveredRecords.values()].map((record) => ({
+                id: record.id,
+                table: record.table,
+                key: record.key,
+                kind: record.kind,
+                initial: record.initial,
+                enabled: record.enabled,
+                read: () => record.get(),
+            })),
+            enable(id) {
+                enableDiscovered(id);
+                signal.notify();
+            },
+            disable(id) {
+                const record = discoveredRecords.get(id);
+                if (record === undefined || !record.enabled)
+                    return;
+                record.enabled = false;
+                record.set(record.initial);
+                controlRecords.delete(id);
+                signal.notify();
+            },
+            clear() {
+                for (const record of discoveredRecords.values()) {
+                    if (record.enabled) {
+                        record.set(record.initial);
+                        controlRecords.delete(record.id);
+                    }
+                }
+                discoveredRecords.clear();
+                signal.notify();
+            },
+        },
+        overrides: {
+            export() {
+                const enabled = [...discoveredRecords.values()].filter((r) => r.enabled).map((r) => r.id);
+                const values = {};
+                for (const record of controlRecords.values()) {
+                    if (!Object.is(record.value, record.initial))
+                        values[record.name] = record.value;
+                }
+                return { enabled, values };
+            },
+            apply(overrides) {
+                for (const id of overrides.enabled)
+                    enableDiscovered(id);
+                for (const [name, value] of Object.entries(overrides.values)) {
+                    const record = controlRecords.get(name);
+                    if (record !== undefined)
+                        writeControl(record, value);
+                }
+                signal.notify();
+            },
+        },
+        probes: {
+            register(name, read) {
+                probeReaders.set(name, read);
+                signal.notify();
+                return () => {
+                    probeReaders.delete(name);
+                    signal.notify();
+                };
+            },
+            read: readProbes,
+        },
+        signal,
+        snapshot() {
+            return {
+                at: Date.now(),
+                frame: frameStats(),
+                render: renderSample,
+                latency: latencyStats(),
+                logs: [...logEntries],
+                probes: readProbes(),
+                controls: [...controlRecords.values()].map((record) => ({
+                    name: record.name,
+                    kind: record.kind,
+                    value: record.value,
+                    initial: record.initial,
+                })),
+                discovered: [...discoveredRecords.values()].map((record) => ({
+                    id: record.id,
+                    kind: record.kind,
+                    value: record.get(),
+                    enabled: record.enabled,
+                })),
+            };
+        },
+    };
+}
+export const devtools = createDevtools();
+export function tunable(name, initial, options) {
+    return devtools.controls.register(name, initial, options);
+}
+export function snapshotDevtools() {
+    return devtools.snapshot();
+}
+export function instrumentLatency(target, methods, record = devtools.latency.record) {
+    const wrapped = { ...target };
+    for (const method of methods) {
+        const fn = target[method];
+        if (typeof fn !== "function")
+            continue;
+        wrapped[method] = ((...args) => {
+            const start = nowMs();
+            const result = fn.call(target, ...args);
+            if (result instanceof Promise) {
+                return result.then((value) => {
+                    record(nowMs() - start);
+                    return value;
+                }, (error) => {
+                    record(nowMs() - start);
+                    throw error;
+                });
+            }
+            return result;
+        });
+    }
+    return wrapped;
+}

package/dist/devtools/transformTunables.d.ts

@@ -0,0 +1,14 @@
+export interface TunableTransformResult {
+    code: string;
+    bound: string[];
+}
+export declare function transformTunableExports(code: string, table: string): TunableTransformResult;
+export declare function tunableModuleTable(id: string): string | null;
+export declare function tunableDiscoveryPlugin(): {
+    name: string;
+    enforce: "pre";
+    transform(code: string, id: string): {
+        code: string;
+        map: null;
+    } | null;
+};

package/dist/devtools/transformTunables.js

@@ -0,0 +1,38 @@
+const TUNABLE_EXPORT_PATTERN = /^export const ([A-Za-z_$][\w$]*)\s*=\s*(-?\d+(?:\.\d+)?|true|false|"#(?:[0-9a-fA-F]{3,8})"|'#(?:[0-9a-fA-F]{3,8})')\s*;[ \t]*$/gm;
+export function transformTunableExports(code, table) {
+    const bound = [];
+    const rewritten = code.replace(TUNABLE_EXPORT_PATTERN, (_match, name, literal) => {
+        bound.push(name);
+        return `export let ${name} = ${literal};`;
+    });
+    if (bound.length === 0)
+        return { code, bound };
+    const bindings = bound
+        .map((name) => `__jg_devtools.discover.bind(${JSON.stringify(table)}, ${JSON.stringify(name)}, { initial: ${name}, get: () => ${name}, set: (__jg_value) => { ${name} = __jg_value as never; } });`)
+        .join("\n");
+    return {
+        code: `${rewritten}\nimport { devtools as __jg_devtools } from "@jgengine/core/devtools/devtools";\n${bindings}\n`,
+        bound,
+    };
+}
+const GAME_MODULE_PATTERN = /[/\\]Games[/\\][^/\\]+[/\\]src[/\\](.+)\.(ts|tsx)$/;
+const SKIP_MODULE_PATTERN = /(\.test\.|[/\\]main\.tsx$)/;
+export function tunableModuleTable(id) {
+    if (SKIP_MODULE_PATTERN.test(id))
+        return null;
+    const match = GAME_MODULE_PATTERN.exec(id);
+    return match === null ? null : match[1].replace(/\\/g, "/");
+}
+export function tunableDiscoveryPlugin() {
+    return {
+        name: "jgengine-tunable-discovery",
+        enforce: "pre",
+        transform(code, id) {
+            const table = tunableModuleTable(id);
+            if (table === null)
+                return null;
+            const result = transformTunableExports(code, table);
+            return result.bound.length === 0 ? null : { code: result.code, map: null };
+        },
+    };
+}

package/dist/game/chat.d.ts

@@ -0,0 +1,66 @@
+import type { GameEvents } from "./events.js";
+import type { EmotesDeps } from "./social.js";
+export type ChatChannelKind = "global" | "party" | "proximity";
+export interface ChatRateLimit {
+    count: number;
+    perMs: number;
+}
+export interface ChatChannelDef {
+    id: string;
+    kind: ChatChannelKind;
+    radius?: number;
+    historyLimit?: number;
+    rateLimit?: ChatRateLimit;
+}
+export interface ChatMessage {
+    id: string;
+    channelId: string;
+    fromUserId: string;
+    body: string;
+    at: number;
+}
+export type ChatRecipients = readonly string[] | "all";
+export type ChatSendResult = {
+    message: ChatMessage;
+    recipients: ChatRecipients;
+} | {
+    reason: string;
+};
+export interface ChatSnapshot {
+    messages: Record<string, ChatMessage[]>;
+    counter: number;
+}
+export interface Chat {
+    register(def: ChatChannelDef): void;
+    channels(): ChatChannelDef[];
+    send(fromUserId: string, channelId: string, body: string): ChatSendResult;
+    whisper(fromUserId: string, toUserId: string, body: string): ChatSendResult;
+    history(channelId: string, options?: {
+        limit?: number;
+        viewerUserId?: string;
+    }): ChatMessage[];
+    snapshot(): ChatSnapshot;
+    hydrate(data: ChatSnapshot): void;
+}
+export interface ChatDeps {
+    events: GameEvents;
+    now?: () => number;
+    party?: {
+        membersOf(userId: string): string[];
+    };
+    proximity?: EmotesDeps;
+    blockedBy?: (userId: string) => readonly string[];
+    maxBodyLength?: number;
+    defaultRateLimit?: ChatRateLimit;
+}
+export declare const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit;
+export declare const DEFAULT_CHAT_HISTORY_LIMIT = 100;
+export declare const DEFAULT_CHAT_BODY_LENGTH = 500;
+export declare const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
+export declare const WHISPER_CHANNEL_PREFIX = "whisper:";
+export declare function whisperChannelId(a: string, b: string): string;
+export interface ChatRateLimiter {
+    allow(key: string, atMs: number): boolean;
+}
+export declare function createChatRateLimiter(limit: ChatRateLimit): ChatRateLimiter;
+export declare function createChat(deps: ChatDeps): Chat;