@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/i18n/message.js

@@ -0,0 +1,369 @@
+/**
+ * ICU-style message syntax: a parser that runs once per string when a table loads, and a
+ * formatter that walks the resulting AST and builds only the output string.
+ *
+ * Supported forms:
+ * - `{name}`: an argument. Numbers go through `Intl.NumberFormat`, dates through
+ *   `Intl.DateTimeFormat`, everything else through `String`.
+ * - `{n, number}`, `{n, number, integer | percent}`; `{d, date}`, `{d, date, short | medium |
+ *   long | full}`; `{d, time}`, `{d, time, short | medium | long | full}`.
+ * - `{count, plural, offset:1 =0 {none} one {# item} other {# items}}`: `Intl.PluralRules`
+ *   cardinal categories (`zero one two few many other`), exact `=N` forms checked first, `#` the
+ *   number minus the offset, formatted for the locale. `selectordinal` uses ordinal rules.
+ * - `{g, select, male {he} female {she} other {they}}`.
+ * - `'{'` quotes a special character (`{ } #`), `''` is one apostrophe; any other apostrophe is
+ *   literal.
+ *
+ * Every error names the key and the 1-based column where parsing stopped.
+ */
+export class MessageSyntaxError extends Error {
+    key;
+    /** 1-based column in the message where parsing stopped. */
+    column;
+    constructor(key, column, detail) {
+        super(`i18n: "${key}" column ${column}: ${detail}`);
+        this.name = 'MessageSyntaxError';
+        this.key = key;
+        this.column = column;
+    }
+}
+const SPECIAL = new Set(['{', '}', '#']);
+const IDENT = /[A-Za-z0-9_]/;
+const WS = /\s/;
+class Parser {
+    src;
+    key;
+    pos = 0;
+    constructor(src, key) {
+        this.src = src;
+        this.key = key;
+    }
+    fail(detail, at = this.pos) {
+        throw new MessageSyntaxError(this.key, Math.min(at, this.src.length) + 1, detail);
+    }
+    skipWs() {
+        while (this.pos < this.src.length && WS.test(this.src[this.pos]))
+            this.pos++;
+    }
+    ident(what) {
+        const start = this.pos;
+        while (this.pos < this.src.length && IDENT.test(this.src[this.pos]))
+            this.pos++;
+        if (this.pos === start)
+            this.fail(`expected ${what}`);
+        return this.src.slice(start, this.pos);
+    }
+    expect(ch) {
+        if (this.src[this.pos] !== ch) {
+            this.fail(this.pos >= this.src.length ? `unexpected end, expected '${ch}'` : `expected '${ch}'`);
+        }
+        this.pos++;
+    }
+    /** Parses up to `}` (nested) or the end (top level). */
+    sequence(nested, inPlural) {
+        const out = [];
+        let text = '';
+        const flush = () => {
+            if (text)
+                out.push(text);
+            text = '';
+        };
+        const s = this.src;
+        while (this.pos < s.length) {
+            const c = s[this.pos];
+            if (c === "'") {
+                const next = s[this.pos + 1];
+                if (next === "'") {
+                    text += "'";
+                    this.pos += 2;
+                }
+                else if (next !== undefined && SPECIAL.has(next)) {
+                    // Quoted literal to the next lone apostrophe (or the end, as ICU does).
+                    this.pos++;
+                    while (this.pos < s.length) {
+                        if (s[this.pos] === "'") {
+                            if (s[this.pos + 1] === "'") {
+                                text += "'";
+                                this.pos += 2;
+                                continue;
+                            }
+                            this.pos++;
+                            break;
+                        }
+                        text += s[this.pos++];
+                    }
+                }
+                else {
+                    text += c;
+                    this.pos++;
+                }
+            }
+            else if (c === '{') {
+                flush();
+                out.push(this.argument(inPlural));
+            }
+            else if (c === '}') {
+                if (!nested)
+                    this.fail("unmatched '}'");
+                flush();
+                return out;
+            }
+            else if (c === '#' && inPlural) {
+                flush();
+                out.push({ kind: 'hash' });
+                this.pos++;
+            }
+            else {
+                text += c;
+                this.pos++;
+            }
+        }
+        if (nested)
+            this.fail("unexpected end, expected '}'");
+        flush();
+        return out;
+    }
+    argument(inPlural) {
+        this.expect('{');
+        this.skipWs();
+        const name = this.ident('an argument name');
+        this.skipWs();
+        if (this.src[this.pos] === '}') {
+            this.pos++;
+            return { kind: 'arg', name };
+        }
+        if (this.src[this.pos] !== ',') {
+            this.fail(this.pos >= this.src.length ? "unexpected end, expected '}' or ','" : "expected '}' or ','");
+        }
+        this.pos++;
+        this.skipWs();
+        const typeAt = this.pos;
+        const type = this.ident('an argument type');
+        this.skipWs();
+        switch (type) {
+            case 'number':
+            case 'date':
+            case 'time': {
+                let style = null;
+                if (this.src[this.pos] === ',') {
+                    this.pos++;
+                    this.skipWs();
+                    style = this.ident('a style');
+                    this.skipWs();
+                }
+                this.expect('}');
+                return { kind: type, name, style };
+            }
+            case 'plural':
+            case 'selectordinal':
+                this.expect(',');
+                return this.plural(name, type === 'selectordinal');
+            case 'select':
+                this.expect(',');
+                return this.select(name, inPlural);
+            default:
+                this.fail(`unknown argument type '${type}'`, typeAt);
+        }
+    }
+    plural(name, ordinal) {
+        const exact = new Map();
+        const categories = new Map();
+        let other = null;
+        let offset = 0;
+        this.skipWs();
+        if (this.src.startsWith('offset:', this.pos)) {
+            this.pos += 'offset:'.length;
+            this.skipWs();
+            const at = this.pos;
+            const digits = this.ident('an offset');
+            offset = Number(digits);
+            if (!Number.isInteger(offset))
+                this.fail(`bad offset '${digits}'`, at);
+            this.skipWs();
+        }
+        for (;;) {
+            this.skipWs();
+            if (this.src[this.pos] === '}')
+                break;
+            if (this.pos >= this.src.length)
+                this.fail("unexpected end, expected '}'");
+            const at = this.pos;
+            if (this.src[this.pos] === '=') {
+                this.pos++;
+                const digits = this.ident('a number after =');
+                const n = Number(digits);
+                if (!Number.isFinite(n))
+                    this.fail(`bad exact form '=${digits}'`, at);
+                exact.set(n, this.caseBody(true));
+                continue;
+            }
+            const selector = this.ident('a plural category');
+            if (selector === 'other')
+                other = this.caseBody(true);
+            else if (CATEGORIES.has(selector))
+                categories.set(selector, this.caseBody(true));
+            else
+                this.fail(`unknown plural category '${selector}'`, at);
+        }
+        if (!other)
+            this.fail("plural needs an 'other' case");
+        this.pos++;
+        return { kind: 'plural', name, ordinal, offset, exact, categories, other };
+    }
+    select(name, inPlural) {
+        const cases = new Map();
+        let other = null;
+        for (;;) {
+            this.skipWs();
+            if (this.src[this.pos] === '}')
+                break;
+            if (this.pos >= this.src.length)
+                this.fail("unexpected end, expected '}'");
+            const selector = this.ident('a select case');
+            const body = this.caseBody(inPlural);
+            if (selector === 'other')
+                other = body;
+            else
+                cases.set(selector, body);
+        }
+        if (!other)
+            this.fail("select needs an 'other' case");
+        this.pos++;
+        return { kind: 'select', name, cases, other };
+    }
+    caseBody(inPlural) {
+        this.skipWs();
+        this.expect('{');
+        const body = this.sequence(true, inPlural);
+        this.expect('}');
+        return body;
+    }
+}
+const CATEGORIES = new Set(['zero', 'one', 'two', 'few', 'many']);
+/** Parses one message. Throws `MessageSyntaxError` naming `key` and the column. */
+export function parseMessage(source, key = 'message') {
+    return new Parser(source, key).sequence(false, false);
+}
+const DATE_STYLES = new Set(['short', 'medium', 'long', 'full']);
+export function createIntlCache() {
+    const plurals = new Map();
+    const numbers = new Map();
+    const dates = new Map();
+    return {
+        plural(locale, ordinal) {
+            const k = `${locale}|${ordinal ? 'o' : 'c'}`;
+            let r = plurals.get(k);
+            if (!r) {
+                r = new Intl.PluralRules(locale, { type: ordinal ? 'ordinal' : 'cardinal' });
+                plurals.set(k, r);
+            }
+            return r;
+        },
+        number(locale, style) {
+            const k = `${locale}|${style ?? ''}`;
+            let f = numbers.get(k);
+            if (!f) {
+                const opts = style === 'integer'
+                    ? { maximumFractionDigits: 0 }
+                    : style === 'percent'
+                        ? { style: 'percent' }
+                        : {};
+                f = new Intl.NumberFormat(locale, opts);
+                numbers.set(k, f);
+            }
+            return f;
+        },
+        date(locale, kind, style) {
+            const k = `${locale}|${kind}|${style ?? ''}`;
+            let f = dates.get(k);
+            if (!f) {
+                const s = style && DATE_STYLES.has(style)
+                    ? style
+                    : undefined;
+                const opts = kind === 'date' ? { dateStyle: s ?? 'medium' } : { timeStyle: s ?? 'short' };
+                f = new Intl.DateTimeFormat(locale, opts);
+                dates.set(k, f);
+            }
+            return f;
+        },
+    };
+}
+/**
+ * Formats a parsed message for `locale`. A missing argument renders as `{name}` so the UI never
+ * shows an empty string. Allocates only the output string.
+ */
+export function formatMessage(ast, args, locale, intl) {
+    return walk(ast, args, locale, intl, null);
+}
+function walk(ast, args, locale, intl, hash) {
+    let out = '';
+    for (let i = 0; i < ast.length; i++) {
+        const node = ast[i];
+        if (typeof node === 'string') {
+            out += node;
+            continue;
+        }
+        switch (node.kind) {
+            case 'hash':
+                if (hash === null)
+                    out += '#';
+                else if (typeof hash === 'number')
+                    out += intl.number(locale, null).format(hash);
+                else
+                    out += hash;
+                break;
+            case 'arg': {
+                const v = args?.[node.name];
+                if (v === undefined)
+                    out += `{${node.name}}`;
+                else if (typeof v === 'number')
+                    out += intl.number(locale, null).format(v);
+                else if (v instanceof Date)
+                    out += intl.date(locale, 'date', null).format(v);
+                else
+                    out += String(v);
+                break;
+            }
+            case 'number': {
+                const v = args?.[node.name];
+                if (typeof v === 'number')
+                    out += intl.number(locale, node.style).format(v);
+                else
+                    out += v === undefined ? `{${node.name}}` : String(v);
+                break;
+            }
+            case 'date':
+            case 'time': {
+                const v = args?.[node.name];
+                if (v instanceof Date || typeof v === 'number')
+                    out += intl.date(locale, node.kind, node.style).format(v);
+                else
+                    out += v === undefined ? `{${node.name}}` : String(v);
+                break;
+            }
+            case 'plural': {
+                const v = args?.[node.name];
+                if (typeof v !== 'number') {
+                    // Not a number: `other`, with `#` printing the argument (or its placeholder) as text.
+                    const text = v === undefined ? `{${node.name}}` : String(v);
+                    out += walk(node.other, args, locale, intl, text);
+                    break;
+                }
+                const inner = v - node.offset;
+                const exact = node.exact.get(v);
+                const branch = exact ??
+                    node.categories.get(intl.plural(locale, node.ordinal).select(inner)) ??
+                    node.other;
+                out += walk(branch, args, locale, intl, inner);
+                break;
+            }
+            case 'select': {
+                const v = args?.[node.name];
+                const branch = (v === undefined ? undefined : node.cases.get(String(v))) ?? node.other;
+                out += walk(branch, args, locale, intl, hash);
+                break;
+            }
+        }
+    }
+    return out;
+}

package/dist/i18n/negotiate.d.ts

@@ -0,0 +1,17 @@
+/** Locale matching and text direction. No `Intl.Locale` needed: BCP 47 tags split on `-`. */
+export type TextDirection = 'ltr' | 'rtl';
+/** Language subtags written right to left. Scripts are not consulted: `ar-Latn` is rare in games. */
+export declare const RTL_LANGUAGES: ReadonlySet<string>;
+/** The language subtag of a BCP 47 tag, lower case: `pt-BR` → `pt`. */
+export declare function languageOf(locale: string): string;
+/** `'rtl'` when the language subtag is in `RTL_LANGUAGES`, else `'ltr'`. */
+export declare function directionOf(locale: string): TextDirection;
+/** What the browser asks for, most preferred first; empty outside a browser. */
+export declare function requestedLocales(): readonly string[];
+/**
+ * Picks the locale from `available` that best matches `requested` (most preferred first,
+ * `navigator.languages` by default). For each requested tag in order: an exact match
+ * (case-insensitive), else the first available tag sharing its language subtag (`en-US` → `en`
+ * or `en-GB`). When nothing matches, `fallback` (the first entry of `available`).
+ */
+export declare function negotiateLocale(available: readonly string[], requested?: readonly string[], fallback?: string): string;

package/dist/i18n/negotiate.js

@@ -0,0 +1,58 @@
+/** Locale matching and text direction. No `Intl.Locale` needed: BCP 47 tags split on `-`. */
+/** Language subtags written right to left. Scripts are not consulted: `ar-Latn` is rare in games. */
+export const RTL_LANGUAGES = new Set([
+    'ar',
+    'arc',
+    'ckb',
+    'dv',
+    'fa',
+    'ha',
+    'he',
+    'iw',
+    'khw',
+    'ks',
+    'ku',
+    'ps',
+    'sd',
+    'syr',
+    'ug',
+    'ur',
+    'yi',
+]);
+/** The language subtag of a BCP 47 tag, lower case: `pt-BR` → `pt`. */
+export function languageOf(locale) {
+    return locale.split(/[-_]/, 1)[0].toLowerCase();
+}
+/** `'rtl'` when the language subtag is in `RTL_LANGUAGES`, else `'ltr'`. */
+export function directionOf(locale) {
+    return RTL_LANGUAGES.has(languageOf(locale)) ? 'rtl' : 'ltr';
+}
+/** What the browser asks for, most preferred first; empty outside a browser. */
+export function requestedLocales() {
+    if (typeof navigator === 'undefined')
+        return [];
+    if (navigator.languages?.length)
+        return navigator.languages;
+    return navigator.language ? [navigator.language] : [];
+}
+/**
+ * Picks the locale from `available` that best matches `requested` (most preferred first,
+ * `navigator.languages` by default). For each requested tag in order: an exact match
+ * (case-insensitive), else the first available tag sharing its language subtag (`en-US` → `en`
+ * or `en-GB`). When nothing matches, `fallback` (the first entry of `available`).
+ */
+export function negotiateLocale(available, requested = requestedLocales(), fallback = available[0]) {
+    if (available.length === 0)
+        return fallback;
+    for (const want of requested) {
+        const w = want.toLowerCase();
+        const exact = available.find((a) => a.toLowerCase() === w);
+        if (exact !== undefined)
+            return exact;
+        const lang = languageOf(want);
+        const partial = available.find((a) => languageOf(a) === lang);
+        if (partial !== undefined)
+            return partial;
+    }
+    return fallback;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@thunderclap-engine/engine`: the top layer a game touches (D-041). `createGame()` boots the platform
+ * and wires every noun-free system into one ctx. The modules under it stay reachable through
+ * their own subpaths (`@thunderclap-engine/engine/<module>`).
+ */
+export type { CreateGameOptions, EngineCtx, FlushableSave, GameHooks, GameReplay, HideReason, ReplayOptions, ShowReason, SimOption, XrControl, XrOptions, } from './core/game.js';
+export { createGame } from './core/game.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createGame } from './core/game.js';

package/dist/input/bindings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Saving, loading and checking bindings maps (ws/input-3). `serializeBindings` writes the map a
+ * game got from `Input.bindings()` as JSON; `parseBindings` reads it back against the game's
+ * defaults (unknown actions dropped with a warning, missing ones filled in, malformed bindings
+ * dropped); `findConflicts` lists inputs bound to more than one action.
+ */
+import type { Binding, Bindings } from './types.js';
+/** Plain JSON of a bindings map, for saving. */
+export declare function serializeBindings<A extends string>(map: Bindings<A>): string;
+/**
+ * Read a bindings map saved by `serializeBindings` (text or an already-parsed object). Every
+ * action in `defaults` is present in the result: from `text` when it has a well-formed list
+ * there, else from `defaults`. Actions not in `defaults` are dropped with one `console.warn`
+ * naming them; malformed bindings are dropped the same way. Unparseable text yields `defaults`.
+ */
+export declare function parseBindings<A extends string>(text: string | unknown, defaults: Bindings<A>): Bindings<A>;
+/** One input bound to several actions. */
+export interface BindingConflict {
+    /** The binding (its first occurrence). */
+    binding: Binding;
+    /** The actions sharing it, in map order. */
+    actions: string[];
+}
+/**
+ * Inputs bound to more than one action. Two bindings conflict when their input and trigger
+ * fields are equal (a `hold` and a `press` on the same key do not); chords conflict only with
+ * identical chords.
+ */
+export declare function findConflicts<A extends string>(map: Bindings<A>): BindingConflict[];
+/** Structural check of one binding (its input shape and optional trigger fields). */
+export declare function isBinding(v: unknown): v is Binding;

package/dist/input/bindings.js

@@ -0,0 +1,141 @@
+const GESTURES = new Set(['tap', 'doubleTap', 'longPress', 'pan', 'drag', 'pinch']);
+const POINTER_BUTTONS = new Set(['select', 'secondary']);
+const XR_BUTTONS = new Set(['trigger', 'squeeze', 'pinch']);
+const TRIGGERS = new Set(['press', 'hold', 'doubleTap']);
+/** Plain JSON of a bindings map, for saving. */
+export function serializeBindings(map) {
+    return JSON.stringify(map);
+}
+/**
+ * Read a bindings map saved by `serializeBindings` (text or an already-parsed object). Every
+ * action in `defaults` is present in the result: from `text` when it has a well-formed list
+ * there, else from `defaults`. Actions not in `defaults` are dropped with one `console.warn`
+ * naming them; malformed bindings are dropped the same way. Unparseable text yields `defaults`.
+ */
+export function parseBindings(text, defaults) {
+    let raw;
+    if (typeof text === 'string') {
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            console.warn('[input] bindings: not JSON; using defaults');
+            return defaults;
+        }
+    }
+    else
+        raw = text;
+    if (!isObject(raw)) {
+        console.warn('[input] bindings: not an object; using defaults');
+        return defaults;
+    }
+    const out = {};
+    const unknown = [];
+    const malformed = [];
+    for (const action of Object.keys(raw)) {
+        if (!(action in defaults))
+            unknown.push(action);
+    }
+    for (const action of Object.keys(defaults)) {
+        const list = raw[action];
+        if (list === undefined) {
+            out[action] = defaults[action];
+            continue;
+        }
+        if (!Array.isArray(list)) {
+            malformed.push(action);
+            out[action] = defaults[action];
+            continue;
+        }
+        const good = [];
+        for (const b of list) {
+            if (isBinding(b))
+                good.push(b);
+            else
+                malformed.push(action);
+        }
+        out[action] = good;
+    }
+    if (unknown.length)
+        console.warn(`[input] bindings: unknown actions dropped: ${unknown.join(', ')}`);
+    if (malformed.length) {
+        console.warn(`[input] bindings: malformed bindings dropped in: ${[...new Set(malformed)].join(', ')}`);
+    }
+    return out;
+}
+/**
+ * Inputs bound to more than one action. Two bindings conflict when their input and trigger
+ * fields are equal (a `hold` and a `press` on the same key do not); chords conflict only with
+ * identical chords.
+ */
+export function findConflicts(map) {
+    const seen = new Map();
+    for (const action of Object.keys(map)) {
+        for (const b of map[action]) {
+            const key = canonical(b);
+            const c = seen.get(key);
+            if (c) {
+                if (!c.actions.includes(action))
+                    c.actions.push(action);
+            }
+            else
+                seen.set(key, { binding: b, actions: [action] });
+        }
+    }
+    const out = [];
+    for (const c of seen.values())
+        if (c.actions.length > 1)
+            out.push(c);
+    return out;
+}
+/** A stable key for a binding: its fields sorted, defaults made explicit. */
+function canonical(b) {
+    const o = { ...b };
+    if (o.trigger === 'press')
+        delete o.trigger;
+    if ('chord' in b)
+        o.chord = b.chord.map(canonical);
+    return JSON.stringify(o, Object.keys(o).sort());
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isNum(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+/** Structural check of one binding (its input shape and optional trigger fields). */
+export function isBinding(v) {
+    if (!isObject(v))
+        return false;
+    if (v.trigger !== undefined && !TRIGGERS.has(v.trigger))
+        return false;
+    if (v.holdMs !== undefined && !isNum(v.holdMs))
+        return false;
+    if (v.doubleTapMs !== undefined && !isNum(v.doubleTapMs))
+        return false;
+    if ('key' in v)
+        return typeof v.key === 'string';
+    if ('mouse' in v)
+        return isNum(v.mouse);
+    if ('wheel' in v)
+        return v.wheel === 1 || v.wheel === -1;
+    if ('padButton' in v)
+        return isNum(v.padButton) && optNum(v.pad) && optNum(v.threshold);
+    if ('padAxis' in v) {
+        return (isNum(v.padAxis) && (v.dir === 1 || v.dir === -1) && optNum(v.pad) && optNum(v.threshold));
+    }
+    if ('gesture' in v)
+        return GESTURES.has(v.gesture);
+    if ('pointer' in v)
+        return POINTER_BUTTONS.has(v.pointer);
+    if ('xr' in v) {
+        return (XR_BUTTONS.has(v.xr) &&
+            (v.hand === undefined || v.hand === 'left' || v.hand === 'right'));
+    }
+    if ('chord' in v)
+        return Array.isArray(v.chord) && v.chord.every(isBinding);
+    return false;
+}
+function optNum(v) {
+    return v === undefined || isNum(v);
+}

package/dist/input/clock.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The clock gestures and look are timed on (ws/input-8). By default that is `performance.now()`
+ * (wall time). A game with a fixed step passes one `createTickClock()` to both and advances it
+ * from the step, so long-presses, double taps, look acceleration and `Look.onTap` run on game
+ * time, and a recording replays the same gestures on the same tick indices however far apart
+ * the replay's ticks are in wall time.
+ */
+/** A clock in ms. Only differences between readings matter; it should never go backwards. */
+export interface InputClock {
+    now(): number;
+}
+/** A clock that moves only when told: `advance(ms)` once per fixed step. */
+export interface TickClock extends InputClock {
+    /** Move the clock forward by `ms`. Negative and non-finite values are ignored. */
+    advance(ms: number): void;
+}
+/** `performance.now()` (or `Date.now()` where there is no `performance`): the default clock. */
+export declare const wallClock: InputClock;
+/**
+ * A game-time clock for gestures and look. Call `advance(stepMs)` from the fixed step, before
+ * `input.update()`, and pass the same clock to `createGestures({ clock })` and
+ * `createLook({ clock })` so the two share one time base. `start` is the first reading
+ * (default 0).
+ *
+ * ```ts
+ * const clock = createTickClock();
+ * const input = new Input(bindings, {
+ *   gestures: createGestures({ clock }),
+ *   look: createLook({ clock }),
+ * });
+ * // GameLoop `update(dt)`, in fixed steps of `dt` seconds:
+ * clock.advance(dt * 1000);
+ * input.update();
+ * ```
+ */
+export declare function createTickClock(start?: number): TickClock;
+/**
+ * The clock options gestures and look accept resolved to one clock and its bound `now`:
+ * `clock` wins over the older `now` function, and with neither it is `wallClock`.
+ */
+export declare function resolveClock(clock: InputClock | undefined, now: (() => number) | undefined): {
+    clock: InputClock;
+    now: () => number;
+};