@datamoc/mw_games 0.7.6 → 0.7.8

package/dist/two-d/ui/markup.js

@@ -0,0 +1,370 @@
+/** the tags this parser knows; anything else is literal text, not a tag */
+const KNOWN_TAGS = new Set(['b', 'i', 'span', 'br', 'img']);
+/**
+ * Reads `source` as inline markup and returns one span per styled run.
+ *
+ * Known tags are `<b>`, `<i>`, `<span color='…' size='…'>`, `<br/>` (or `<br>`, which becomes a
+ * newline in the text) and `<img>path</img>` (or `<img src='path'/>`). Nesting works the way it
+ * reads: a `<b>` inside an `<i>` is both, and a closing tag restores exactly the style it opened
+ * over. `&lt;`, `&gt;`, `&amp;`, `&quot;` and `&apos;` are the escapes for the characters that would
+ * otherwise be syntax.
+ *
+ * Two rules are deliberate, because content written by hand meets both. An **unknown or malformed**
+ * tag - `<blink>`, a `</b>` that closes nothing, an `<img>` with no `</img>` - is kept literally in
+ * the text rather than dropped or guessed at, so the worst case is text that reads oddly instead of
+ * text that lost a piece. And a `$name` that nothing supplies is kept literally too, for the same
+ * reason.
+ *
+ * @example
+ * ```ts
+ * import { escapeHtml, markupToHtml, parseMarkup, stripMarkup } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const spans = parseMarkup("Hail, <b>$name</b>! <span color='#c0ffee'>Four</span> coins<br/>And an<img>gold.png</img>", {
+ *   variables: { name: 'Kalenz' },
+ * });
+ *
+ * console.log(spans[1]); // { text: 'Kalenz', bold: true, italic: false }
+ * console.log(spans[2]); // { text: 'Four', bold: false, italic: false, color: '#c0ffee' }
+ * console.log(spans[3].text); // '\nAnd an'
+ * console.log(spans[4].image); // 'gold.png'
+ * console.log(stripMarkup('<b>Bold</b> and <i>italic</i>')); // 'Bold and italic'
+ * console.log(markupToHtml(spans)); // escaped text with <b>/<i> around the emphasis
+ * ```
+ */
+export function parseMarkup(source, options = {}) {
+    const variables = options.variables ?? {};
+    const spans = [];
+    const stack = [];
+    let style = { bold: false, italic: false };
+    let text = '';
+    const flush = () => {
+        if (!text)
+            return;
+        const span = { text, bold: style.bold, italic: style.italic };
+        if (style.color !== undefined)
+            span.color = style.color;
+        if (style.size !== undefined)
+            span.size = style.size;
+        spans.push(span);
+        text = '';
+    };
+    for (let index = 0; index < source.length; index++) {
+        const char = source[index];
+        if (char === '&') {
+            const entity = readEntity(source, index);
+            if (entity) {
+                text += entity.text;
+                index = entity.end;
+                continue;
+            }
+        }
+        if (char === '$') {
+            const variable = readVariable(source, index);
+            const value = variable ? variables[variable.name] : undefined;
+            if (variable && value !== undefined) {
+                text += value;
+                index = variable.end;
+                continue;
+            }
+        }
+        if (char === '<') {
+            const tag = readTag(source, index);
+            if (tag && KNOWN_TAGS.has(tag.name)) {
+                if (tag.name === 'img') {
+                    const image = readImage(source, tag);
+                    if (image) {
+                        flush();
+                        spans.push({ text: '', bold: false, italic: false, image: image.src });
+                        index = image.end;
+                        continue;
+                    }
+                }
+                else if (tag.name === 'br') {
+                    text += '\n';
+                    index = tag.end;
+                    continue;
+                }
+                else if (!tag.closing) {
+                    //flush before the style moves: the text so far belongs to the style it was written
+                    //in, and accumulating across a tag would give all of it the last style seen
+                    flush();
+                    stack.push({ tag: tag.name, style });
+                    style = opened(style, tag.name, tag.body);
+                    index = tag.end;
+                    continue;
+                }
+                else {
+                    const top = stack[stack.length - 1];
+                    if (top?.tag === tag.name) {
+                        flush();
+                        style = top.style;
+                        stack.pop();
+                        index = tag.end;
+                        continue;
+                    }
+                }
+            }
+        }
+        text += char;
+    }
+    flush();
+    return spans;
+}
+/** The same text with the markup taken out, for a place that cannot render any of it. */
+export function stripMarkup(source, options = {}) {
+    return parseMarkup(source, options)
+        .map((span) => span.image ?? span.text)
+        .join('');
+}
+/**
+ * Spans as an HTML fragment for a renderer that speaks HTML text, which is what the ui's `RichLabel`
+ * is. Emphasis, colour and size all render - `HTMLText`'s dialect is real CSS, so a `color`/`size`
+ * span becomes a `<span style="...">` wrapper - and the text is escaped, so `a < b` can never turn
+ * into a tag. An image span renders as nothing here: `HTMLText` has no inline-image primitive, so a
+ * caller that wants the image drawn positions a sprite itself, at the position `layoutMarkupLines`
+ * reports for that span.
+ */
+export function markupToHtml(spans) {
+    return spans
+        .map((span) => {
+        if (span.image !== undefined)
+            return '';
+        let text = escapeHtml(span.text);
+        if (span.italic)
+            text = `<i>${text}</i>`;
+        if (span.bold)
+            text = `<b>${text}</b>`;
+        const style = [
+            span.color !== undefined ? `color:${span.color}` : undefined,
+            span.size !== undefined ? `font-size:${span.size}px` : undefined,
+        ].filter((declaration) => declaration !== undefined);
+        if (style.length > 0)
+            text = `<span style="${style.join(';')}">${text}</span>`;
+        return text;
+    })
+        .join('');
+}
+/**
+ * The plain-text projection for a place that cannot render any markup at all - a screen reader, a
+ * log line, a tooltip that only takes a string. Unlike `stripMarkup` (which keeps an image span's
+ * raw path, useful for round-tripping but not for reading aloud), an image becomes `describeImage`'s
+ * result, defaulting to `[image]` so an image is at least announced as present rather than silently
+ * dropped or read as a file path.
+ *
+ * @example
+ * ```ts
+ * import { markupAccessibilityText, parseMarkup } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const spans = parseMarkup("Pay <b>10</b> gold<img>coin.png</img>");
+ * console.log(markupAccessibilityText(spans)); // 'Pay 10 gold[image]'
+ * console.log(markupAccessibilityText(spans, { describeImage: () => ' (coin icon)' }));
+ * // 'Pay 10 gold (coin icon)'
+ * ```
+ */
+export function markupAccessibilityText(spans, options = {}) {
+    const describeImage = options.describeImage ?? (() => '[image]');
+    return spans.map((span) => (span.image !== undefined ? describeImage(span.image) : span.text)).join('');
+}
+/**
+ * Wraps already-parsed spans into lines, word by word, each word measured under its own span's
+ * style - which is the acceptance this item was missing: wrapping computed *after* styling, not
+ * before it, so a bold or larger run wraps where its own wider glyphs actually land rather than
+ * where the plain text would have. An explicit line break (`<br/>`, which `parseMarkup` turns into
+ * a literal `\n`) always starts a new line; otherwise a word moves to the next line only once it
+ * would overflow `maxWidth`, so a single word wider than `maxWidth` still renders (not clipped) as
+ * ever a caller's original design.
+ *
+ * Backend-neutral by construction: the same spans, the same `measure` function and the same
+ * `maxWidth` given to `layoutMarkupLines` decide the exact same line breaks whether the caller then
+ * draws each line through `markupToHtml`/`HTMLText` or through a canvas `Text2D` per run - which is
+ * what makes the two backends render "equivalent runs" rather than each doing its own wrapping.
+ *
+ * @example
+ * ```ts
+ * import { layoutMarkupLines, parseMarkup } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const spans = parseMarkup('Take <b>two small</b> coins');
+ * const lines = layoutMarkupLines(spans, (piece) => piece.text.length * 8, 100);
+ * console.log(lines.map((line) => line.spans.map((span) => span.text).join('')));
+ * ```
+ */
+export function layoutMarkupLines(spans, measure, maxWidth) {
+    const pieces = [];
+    for (const span of spans) {
+        if (span.image !== undefined) {
+            pieces.push({ ...span });
+            continue;
+        }
+        const parts = span.text.split('\n');
+        parts.forEach((part, index) => {
+            if (index > 0)
+                pieces.push({ text: '', bold: span.bold, italic: span.italic, hardBreak: true });
+            for (const word of part.match(/\S+|\s+/g) ?? []) {
+                pieces.push({ text: word, bold: span.bold, italic: span.italic, color: span.color, size: span.size });
+            }
+        });
+    }
+    const lines = [];
+    let current = [];
+    let width = 0;
+    const flushLine = () => {
+        //trailing whitespace never counts toward a line's own width or survives into it
+        while (current.length > 0 &&
+            current[current.length - 1].text.trim() === '' &&
+            !current[current.length - 1].image) {
+            width -= measure(current[current.length - 1]);
+            current.pop();
+        }
+        lines.push({ spans: mergeMarkupSpans(current), width: Math.max(0, width) });
+        current = [];
+        width = 0;
+    };
+    for (const piece of pieces) {
+        if (piece.hardBreak) {
+            flushLine();
+            continue;
+        }
+        const pieceWidth = measure(piece);
+        const isSpace = piece.image === undefined && piece.text.trim() === '';
+        if (width > 0 && !isSpace && width + pieceWidth > maxWidth)
+            flushLine();
+        current.push(piece);
+        width += pieceWidth;
+    }
+    if (current.length > 0 || lines.length === 0)
+        flushLine();
+    return lines;
+}
+function mergeMarkupSpans(pieces) {
+    const merged = [];
+    for (const piece of pieces) {
+        const last = merged[merged.length - 1];
+        if (last &&
+            piece.image === undefined &&
+            last.image === undefined &&
+            last.bold === piece.bold &&
+            last.italic === piece.italic &&
+            last.color === piece.color &&
+            last.size === piece.size) {
+            last.text += piece.text;
+        }
+        else {
+            merged.push({ ...piece });
+        }
+    }
+    return merged;
+}
+/**
+ * Positions already-laid-out lines into a flat list of placed runs, one per span, so a canvas
+ * backend draws each span as its own `Text2D` (or an image as its own sprite) at the reported
+ * `x`/`y`. This is the half `layoutMarkupLines` deliberately leaves out: it decides *which*
+ * spans share a line, this decides *where* on the line each one lands.
+ *
+ * Direction is what makes the two backends equivalent rather than merely identical in text: an
+ * `rtl` line places its first (logical) span at the right edge and flows left from it, while an
+ * `ltr` line flows right from the left edge, so the same spans read in the language's own order
+ * on either side. Alignment then moves the whole line within `maxWidth`, defaulting to the
+ * direction's natural edge (`'right'` for `rtl`, `'left'` for `ltr`). A line wider than
+ * `maxWidth` is not clipped - the same "a single long word still renders" rule
+ * `layoutMarkupLines` already keeps - it simply starts left of zero.
+ *
+ * @example
+ * ```ts
+ * import { layoutMarkupLines, parseMarkup, positionMarkupLines } from '@datamoc/mw_games/two-d/ui';
+ *
+ * const spans = parseMarkup('Take <b>two</b> coins<img>coin.png</img>');
+ * const measure = (piece: { text: string; image?: string }) =>
+ * 	piece.image !== undefined ? 16 : piece.text.length * 8;
+ * const lines = layoutMarkupLines(spans, measure, 120);
+ * const runs = positionMarkupLines(lines, { measure, maxWidth: 120, lineHeight: 16 });
+ * console.log(runs.map((run) => run.span.image ?? run.span.text).join(''));
+ * ```
+ */
+export function positionMarkupLines(lines, layout) {
+    const direction = layout.direction ?? 'ltr';
+    const align = layout.align ?? (direction === 'rtl' ? 'right' : 'left');
+    const placed = [];
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+        const line = lines[lineIndex];
+        const y = lineIndex * layout.lineHeight;
+        const widths = line.spans.map((span) => layout.measure(span));
+        const total = widths.reduce((sum, width) => sum + width, 0);
+        const startX = align === 'left' ? 0 : align === 'right' ? layout.maxWidth - total : (layout.maxWidth - total) / 2;
+        let cursor = direction === 'rtl' ? startX + total : startX;
+        for (let index = 0; index < line.spans.length; index++) {
+            const width = widths[index];
+            const x = direction === 'rtl' ? cursor - width : cursor;
+            cursor = direction === 'rtl' ? cursor - width : cursor + width;
+            placed.push({ span: line.spans[index], x, y, width });
+        }
+    }
+    return placed;
+}
+/** escapes the five characters that would otherwise read as syntax */
+export function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+function opened(style, name, body) {
+    if (name === 'b')
+        return { ...style, bold: true };
+    if (name === 'i')
+        return { ...style, italic: true };
+    const color = attribute(body, 'color');
+    const size = Number(attribute(body, 'size') ?? '');
+    const next = { ...style };
+    if (color)
+        next.color = color;
+    if (Number.isFinite(size) && size > 0)
+        next.size = size;
+    return next;
+}
+/** the value of one attribute, quoted or bare; `undefined` when it is not there */
+function attribute(body, name) {
+    const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`).exec(body);
+    return match ? (match[1] ?? match[2] ?? match[3]) : undefined;
+}
+function readTag(source, at) {
+    const match = /^<(\/?)([a-zA-Z]+)([^>]*)>/.exec(source.slice(at));
+    if (!match)
+        return null;
+    const body = match[3].trimEnd();
+    return {
+        name: match[2].toLowerCase(),
+        closing: match[1] === '/',
+        selfClosing: body.endsWith('/') && match[1] === '',
+        body: body.replace(/\/$/, '').trim(),
+        end: at + match[0].length - 1,
+    };
+}
+/** `<img>path</img>` or `<img src='path'/>`, whichever shape was written; null when neither is */
+function readImage(source, tag) {
+    if (tag.selfClosing) {
+        const src = attribute(tag.body, 'src');
+        return src ? { src, end: tag.end } : null;
+    }
+    const close = source.indexOf('</img>', tag.end + 1);
+    if (close < 0)
+        return null;
+    const src = source.slice(tag.end + 1, close).trim();
+    return src ? { src, end: close + '</img>'.length - 1 } : null;
+}
+function readEntity(source, at) {
+    const named = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+    const match = /^&(lt|gt|amp|quot|apos);/.exec(source.slice(at));
+    if (match)
+        return { text: named[match[1]], end: at + match[0].length - 1 };
+    const numeric = /^&#(\d+);/.exec(source.slice(at));
+    if (numeric)
+        return { text: String.fromCodePoint(Number(numeric[1])), end: at + numeric[0].length - 1 };
+    return null;
+}
+function readVariable(source, at) {
+    const match = /^\$([A-Za-z_][A-Za-z0-9_]*)/.exec(source.slice(at));
+    return match ? { name: match[1], end: at + match[0].length - 1 } : null;
+}
+//# sourceMappingURL=markup.js.map

package/dist/two-d/ui/markup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.js","sourceRoot":"","sources":["../../../src/two-d/ui/markup.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export declare const version = "0.7.6";
+export declare const version = "0.7.8";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export const version = '0.7.6';
+export const version = '0.7.8';
 //# sourceMappingURL=version.js.map

package/dist/world/SideTurns.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The turn model a strategy game counts by: sides take turns one after another, a round is
+ * every side taking one, and the time of day steps on once per round. This is deliberately
+ * distinct from `TurnClock` (timed effects on a single actor) and `simulation.Scheduler`
+ * (energy-cost turn order within a side): it is the outer loop a scenario runs on.
+ *
+ * The time schedule carries a `lawfulBonus` per entry, in percent, the number the reference
+ * game's `[time] lawful_bonus=` writes (day `25`, night `-25`, dawn/dusk `0`). A unit's
+ * alignment turns that into its own bonus, and a `TimeArea` can override the schedule for
+ * part of the map, which is what makes the bonus per-hex rather than global.
+ */
+/** how a unit's damage answers the time of day, the reference's `align=` values */
+export type Alignment = 'lawful' | 'neutral' | 'chaotic' | 'liminal';
+export interface TimeOfDay {
+    /** the time's own name: a game's content (`'morning'`, `'first_watch'`) */
+    id: string;
+    /** the schedule's own percentage a lawful unit gains and a chaotic one loses */
+    lawfulBonus: number;
+}
+/** A part of the map on its own schedule, indexed in parallel with the global one. */
+export interface TimeArea {
+    /** the schedule this area's cells use instead of the global one */
+    times: readonly TimeOfDay[];
+    contains(x: number, y: number): boolean;
+}
+export interface SideTurnsOptions {
+    /** the sides in the order they take turns within a round */
+    sides: readonly string[];
+    /** the time-of-day schedule, one entry per round, cycling */
+    schedule: readonly TimeOfDay[];
+    /** which side takes the first turn; 0 by default */
+    sideIndex?: number;
+    /** the first round, 1 by default (rounds are 1-based, as the reference's `turn` is) */
+    round?: number;
+    /** the schedule entry the first round uses; 0 by default */
+    timeIndex?: number;
+    /** per-cell schedule overrides; the first area containing a cell wins */
+    areas?: readonly TimeArea[];
+}
+export interface SideTurn {
+    side: string;
+    round: number;
+    /** true on the turn that opened a new round and advanced the time of day */
+    newRound: boolean;
+}
+/** what `SideTurns.toJSON` writes and `fromJSON` resumes from */
+export interface SideTurnState {
+    round: number;
+    sideIndex: number;
+    timeIndex: number;
+}
+/**
+ * Which side is taking its turn, which round it is, and what time of day applies - the
+ * outer scenario loop. `advance()` moves to the next side; wrapping past the last side opens
+ * a new round and steps the schedule on one entry, cycling. `timeOfDayAt(x, y)` and
+ * `lawfulBonusAt(...)` read the schedule for a cell, so a time area can give one region a
+ * different bonus without a second turn counter.
+ *
+ * @example
+ * ```ts
+ * import { SideTurns } from '@datamoc/mw_games/world';
+ *
+ * const turns = new SideTurns({
+ *   sides: ['rebels', 'undead'],
+ *   schedule: [
+ *     { id: 'day', lawfulBonus: 25 },
+ *     { id: 'night', lawfulBonus: -25 },
+ *   ],
+ * });
+ *
+ * console.log(turns.side, turns.round, turns.timeOfDay.id); // 'rebels' 1 'day'
+ * console.log(turns.lawfulBonusAt('lawful', 4, 4)); // 25 - a lawful unit in the day
+ * turns.advance(); // 'undead', still round 1
+ * turns.advance(); // 'rebels', round 2, timeOfDay is now 'night'
+ * ```
+ */
+export declare class SideTurns {
+    readonly sides: readonly string[];
+    readonly schedule: readonly TimeOfDay[];
+    private readonly areas;
+    private state;
+    constructor(options: SideTurnsOptions);
+    get round(): number;
+    /** the side whose turn it is */
+    get side(): string;
+    get timeIndex(): number;
+    /** the global time of day, before any time area overrides it */
+    get timeOfDay(): TimeOfDay;
+    get snapshot(): SideTurnState;
+    /** The time of day at a cell: the first containing time area's entry, else the global one. */
+    timeOfDayAt(x: number, y: number): TimeOfDay;
+    /** The percentage bonus `alignment` gets at a cell, through that cell's own time of day. */
+    lawfulBonusAt(alignment: Alignment, x: number, y: number): number;
+    /** Moves to the next side, opening a new round and stepping the schedule on a wrap. */
+    advance(): SideTurn;
+    toJSON(): SideTurnState;
+    /** Resumes from `toJSON`, with the same sides/schedule/areas the game was created with. */
+    static fromJSON(options: SideTurnsOptions, state: SideTurnState): SideTurns;
+}
+/**
+ * What one alignment gets out of the time of day's own `lawfulBonus`, in percent: a lawful
+ * unit takes it, a chaotic one takes its negation, and neutral and liminal units ignore the
+ * time entirely (the reference's own four `align=` values).
+ *
+ * @example
+ * ```ts
+ * import { alignmentBonus } from '@datamoc/mw_games/world';
+ *
+ * alignmentBonus('lawful', 25); // 25 - day favours a lawful unit
+ * alignmentBonus('chaotic', 25); // -25 - the same day punishes a chaotic one
+ * alignmentBonus('neutral', 25); // 0 - neutral ignores the time of day
+ * ```
+ */
+export declare function alignmentBonus(alignment: Alignment, lawfulBonus: number): number;
+//# sourceMappingURL=SideTurns.d.ts.map

package/dist/world/SideTurns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SideTurns.d.ts","sourceRoot":"","sources":["../../src/world/SideTurns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAErE,MAAM,WAAW,SAAS;IACzB,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IAEX,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACxB,mEAAmE;IACnE,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IAE5B,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAChC,4DAA4D;IAC5D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzB,6DAA6D;IAC7D,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IAE/B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,yEAAyE;IACzE,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IAEd,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,SAAS;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IAExC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,KAAK,CAAgB;IAE7B,YAAY,OAAO,EAAE,gBAAgB,EAmBpC;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,gCAAgC;IAChC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,gEAAgE;IAChE,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED,8FAA8F;IAC9F,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAM3C;IAED,4FAA4F;IAC5F,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;IAED,uFAAuF;IACvF,OAAO,IAAI,QAAQ,CAUlB;IAED,MAAM,IAAI,aAAa,CAEtB;IAED,2FAA2F;IAC3F,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,CAO1E;CACD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAShF"}

package/dist/world/SideTurns.js

@@ -0,0 +1,138 @@
+/**
+ * The turn model a strategy game counts by: sides take turns one after another, a round is
+ * every side taking one, and the time of day steps on once per round. This is deliberately
+ * distinct from `TurnClock` (timed effects on a single actor) and `simulation.Scheduler`
+ * (energy-cost turn order within a side): it is the outer loop a scenario runs on.
+ *
+ * The time schedule carries a `lawfulBonus` per entry, in percent, the number the reference
+ * game's `[time] lawful_bonus=` writes (day `25`, night `-25`, dawn/dusk `0`). A unit's
+ * alignment turns that into its own bonus, and a `TimeArea` can override the schedule for
+ * part of the map, which is what makes the bonus per-hex rather than global.
+ */
+/**
+ * Which side is taking its turn, which round it is, and what time of day applies - the
+ * outer scenario loop. `advance()` moves to the next side; wrapping past the last side opens
+ * a new round and steps the schedule on one entry, cycling. `timeOfDayAt(x, y)` and
+ * `lawfulBonusAt(...)` read the schedule for a cell, so a time area can give one region a
+ * different bonus without a second turn counter.
+ *
+ * @example
+ * ```ts
+ * import { SideTurns } from '@datamoc/mw_games/world';
+ *
+ * const turns = new SideTurns({
+ *   sides: ['rebels', 'undead'],
+ *   schedule: [
+ *     { id: 'day', lawfulBonus: 25 },
+ *     { id: 'night', lawfulBonus: -25 },
+ *   ],
+ * });
+ *
+ * console.log(turns.side, turns.round, turns.timeOfDay.id); // 'rebels' 1 'day'
+ * console.log(turns.lawfulBonusAt('lawful', 4, 4)); // 25 - a lawful unit in the day
+ * turns.advance(); // 'undead', still round 1
+ * turns.advance(); // 'rebels', round 2, timeOfDay is now 'night'
+ * ```
+ */
+export class SideTurns {
+    constructor(options) {
+        if (options.sides.length === 0)
+            throw new Error('SideTurns needs at least one side');
+        if (options.schedule.length === 0)
+            throw new Error('SideTurns needs a non-empty schedule');
+        const round = options.round ?? 1;
+        const sideIndex = options.sideIndex ?? 0;
+        const timeIndex = options.timeIndex ?? 0;
+        if (!Number.isInteger(round) || round < 1)
+            throw new Error('SideTurns round must be a positive integer');
+        if (sideIndex < 0 || sideIndex >= options.sides.length) {
+            throw new Error(`SideTurns side index ${sideIndex} is outside ${options.sides.length} sides`);
+        }
+        if (timeIndex < 0 || timeIndex >= options.schedule.length) {
+            throw new Error(`SideTurns time index ${timeIndex} is outside ${options.schedule.length} times`);
+        }
+        this.sides = [...options.sides];
+        this.schedule = [...options.schedule];
+        this.areas = options.areas ?? [];
+        this.state = { round, sideIndex, timeIndex };
+    }
+    get round() {
+        return this.state.round;
+    }
+    /** the side whose turn it is */
+    get side() {
+        return this.sides[this.state.sideIndex];
+    }
+    get timeIndex() {
+        return this.state.timeIndex;
+    }
+    /** the global time of day, before any time area overrides it */
+    get timeOfDay() {
+        return this.schedule[this.state.timeIndex];
+    }
+    get snapshot() {
+        return { ...this.state };
+    }
+    /** The time of day at a cell: the first containing time area's entry, else the global one. */
+    timeOfDayAt(x, y) {
+        for (const area of this.areas) {
+            if (!area.contains(x, y))
+                continue;
+            return area.times[this.state.timeIndex] ?? this.timeOfDay;
+        }
+        return this.timeOfDay;
+    }
+    /** The percentage bonus `alignment` gets at a cell, through that cell's own time of day. */
+    lawfulBonusAt(alignment, x, y) {
+        return alignmentBonus(alignment, this.timeOfDayAt(x, y).lawfulBonus);
+    }
+    /** Moves to the next side, opening a new round and stepping the schedule on a wrap. */
+    advance() {
+        let newRound = false;
+        this.state.sideIndex++;
+        if (this.state.sideIndex >= this.sides.length) {
+            this.state.sideIndex = 0;
+            this.state.round++;
+            this.state.timeIndex = (this.state.timeIndex + 1) % this.schedule.length;
+            newRound = true;
+        }
+        return { side: this.side, round: this.state.round, newRound };
+    }
+    toJSON() {
+        return this.snapshot;
+    }
+    /** Resumes from `toJSON`, with the same sides/schedule/areas the game was created with. */
+    static fromJSON(options, state) {
+        return new SideTurns({
+            ...options,
+            round: state.round,
+            sideIndex: state.sideIndex,
+            timeIndex: state.timeIndex,
+        });
+    }
+}
+/**
+ * What one alignment gets out of the time of day's own `lawfulBonus`, in percent: a lawful
+ * unit takes it, a chaotic one takes its negation, and neutral and liminal units ignore the
+ * time entirely (the reference's own four `align=` values).
+ *
+ * @example
+ * ```ts
+ * import { alignmentBonus } from '@datamoc/mw_games/world';
+ *
+ * alignmentBonus('lawful', 25); // 25 - day favours a lawful unit
+ * alignmentBonus('chaotic', 25); // -25 - the same day punishes a chaotic one
+ * alignmentBonus('neutral', 25); // 0 - neutral ignores the time of day
+ * ```
+ */
+export function alignmentBonus(alignment, lawfulBonus) {
+    switch (alignment) {
+        case 'lawful':
+            return lawfulBonus;
+        case 'chaotic':
+            return -lawfulBonus;
+        default:
+            return 0;
+    }
+}
+//# sourceMappingURL=SideTurns.js.map