@datamoc/mw_games 0.7.6 → 0.7.8

package/dist/actors/craft.js

@@ -1,3 +1,15 @@
+function matchesIngredient(item, ingredient) {
+    if (ingredient.matches)
+        return ingredient.matches(item);
+    if (ingredient.category !== undefined)
+        return item.category === ingredient.category;
+    if (typeof ingredient.id === 'string')
+        return item.id === ingredient.id;
+    return (ingredient.id ?? []).includes(item.id);
+}
+function ingredientHasMatcher(ingredient) {
+    return ingredient.matches !== undefined || ingredient.category !== undefined || ingredient.id !== undefined;
+}
 /**
  * Resolves a recipe against an inventory: every ingredient checked, consumed, and the
  * result added, all in one call - the same small-focused-function shape `skillCheck`
@@ -5,10 +17,15 @@
  * adds/removes what a game already hands it; nothing there turns one stack of items into a
  * different one, which is the entire gap this closes.
  *
- * All or nothing: if any ingredient is missing or too few, nothing is touched. If every
- * ingredient is present but the result would not fit (`Inventory`'s own capacity, unrelated
- * to crafting itself), the ingredients are put back exactly as they were rather than being
- * spent for nothing.
+ * An ingredient may name an exact `id` (or any of several), a `category` ("any herb", matched
+ * against the item definition's own `category`), or a `matches` predicate, and a quantity is
+ * taken from as many matching stacks as it spans.
+ *
+ * All or nothing: if any ingredient is missing or too few, nothing is touched. The allocation
+ * runs against a working copy of the stacks first, so two ingredients that could both take the
+ * same stack cannot each count it. If every ingredient is present but the result would not fit
+ * (`Inventory`'s own capacity, unrelated to crafting itself), the ingredients are put back
+ * exactly as they were rather than being spent for nothing.
  *
  * @returns whether the recipe resolved
  *
@@ -17,38 +34,53 @@
  * import { craft, Inventory, type Recipe } from '@datamoc/mw_games/actors';
  *
  * const bag = new Inventory();
- * bag.add({ id: 'wood', quantity: 3, stackable: true });
- * bag.add({ id: 'iron', quantity: 1, stackable: true });
+ * bag.add({ id: 'sage', quantity: 2, stackable: true, category: 'herb' });
+ * bag.add({ id: 'ember', quantity: 1, stackable: true, category: 'runestone' });
  *
  * const recipe: Recipe = {
- *   ingredients: [{ id: 'wood', quantity: 2 }, { id: 'iron', quantity: 1 }],
- *   result: { id: 'torch', quantity: 1 },
+ *   ingredients: [
+ *     { category: 'herb', quantity: 2 },
+ *     { category: 'runestone', quantity: 1 },
+ *   ],
+ *   result: { id: 'elixir', quantity: 1 },
  * };
  *
- * const made = craft(bag, recipe); // true - both ingredients present, consumed, torch added
+ * const made = craft(bag, recipe); // true - any herb plus any runestone becomes an elixir
  * ```
  */
 export function craft(inventory, recipe) {
-    const needed = new Map();
+    //a working copy of every stack's quantity, so an earlier ingredient consumes this allocation
+    //even when a later one matches the same category or predicate
+    const available = new Map();
+    for (const item of inventory.items)
+        available.set(item, item.quantity);
+    const taken = new Map();
     for (const ingredient of recipe.ingredients) {
-        needed.set(ingredient.id, (needed.get(ingredient.id) ?? 0) + ingredient.quantity);
-    }
-    for (const [id, quantity] of needed) {
-        const held = inventory.find(id);
-        if (!held || held.quantity < quantity)
+        if (!ingredientHasMatcher(ingredient))
+            throw new Error('recipe ingredient must name an id, a category, or a matches predicate');
+        if (!Number.isFinite(ingredient.quantity) || ingredient.quantity <= 0)
+            throw new Error('recipe ingredient quantity must be a positive number');
+        let needed = ingredient.quantity;
+        for (const item of inventory.items) {
+            if (needed <= 0)
+                break;
+            const held = available.get(item) ?? 0;
+            if (held <= 0 || !matchesIngredient(item, ingredient))
+                continue;
+            const take = Math.min(held, needed);
+            available.set(item, held - take);
+            needed -= take;
+            taken.set(item, (taken.get(item) ?? 0) + take);
+        }
+        if (needed > 0)
             return false;
     }
-    //captured before anything is removed, so a failed add below can restore exactly this
-    const consumed = recipe.ingredients.map((ingredient) => ({
-        ...inventory.find(ingredient.id),
-        quantity: ingredient.quantity,
-    }));
-    for (const ingredient of recipe.ingredients)
-        inventory.remove(ingredient.id, ingredient.quantity);
+    for (const [item, quantity] of taken)
+        inventory.remove(item.id, quantity, item.instanceId);
     if (inventory.add(recipe.result))
         return true;
-    for (const item of consumed)
-        inventory.add(item);
+    for (const [item, quantity] of taken)
+        inventory.add({ ...item, quantity });
     return false;
 }
 //# sourceMappingURL=craft.js.map

package/dist/actors/craft.js.map

@@ -1 +1 @@
-{"version":3,"file":"craft.js","sourceRoot":"","sources":["../../src/actors/craft.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,KAAK,CAAC,SAAoB,EAAE,MAAc;IACzD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QAC7C,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACnF,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,GAAG,QAAQ;YAAE,OAAO,KAAK,CAAC;IACrD,CAAC;IAED,qFAAqF;IACrF,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACxD,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAE;QACjC,QAAQ,EAAE,UAAU,CAAC,QAAQ;KAC7B,CAAC,CAAC,CAAC;IAEJ,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,WAAW;QAAE,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClG,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,KAAK,MAAM,IAAI,IAAI,QAAQ;QAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC;AACd,CAAC"}
+{"version":3,"file":"craft.js","sourceRoot":"","sources":["../../src/actors/craft.ts"],"names":[],"mappings":"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"}

package/dist/actors/index.d.ts

@@ -10,7 +10,7 @@ export type { EquippableItem, EquipmentOptions, SavedEquipment } from './Equipme
 export { Inventory } from './Inventory.ts';
 export type { InventoryItem, InventoryOptions, ItemDefinition, SavedInventory, SavedInventoryItem, } from './Inventory.ts';
 export { craft } from './craft.ts';
-export type { Recipe } from './craft.ts';
+export type { Ingredient, Recipe } from './craft.ts';
 export { applyStatusEffect } from './StatusEffect.ts';
 export type { EffectClock, StatusEffectOptions, StatusEffectHandle } from './StatusEffect.ts';
 export { identify, enchant, damageItem, repairItem } from './ItemState.ts';

package/dist/actors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actors/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACjG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACX,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,kBAAkB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC3E,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAClH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpG,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACjH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC3E,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACzG,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/ai/Heuristics.d.ts

@@ -0,0 +1,240 @@
+/** A single aspect's value: the shapes a game authors in content without inventing a type. */
+export type AspectValue = number | string | boolean | readonly string[];
+export interface AspectValues {
+    readonly [name: string]: AspectValue | undefined;
+}
+/**
+ * The named tuning knobs of a heuristic AI - Wesnoth's "aspects" - read by whatever stage is
+ * scoring candidates. `mwg` ships no values, because the numbers are game content: a side sets
+ * `aggression`, `caution`, `village_value`, `keep_away` and the rest to whatever its own balance
+ * wants, and a difficulty level overrides a few of them.
+ *
+ * Typed readers give a stage a usable number without every caller casting: a missing aspect reads
+ * as the fallback (`1` for a weight, so an unset aspect is neutral rather than zeroing a score).
+ *
+ * @example
+ * ```ts
+ * import { Aspects } from '@datamoc/mw_games/ai';
+ *
+ * const aspects = new Aspects({ aggression: 2, keep_away: 3 });
+ * console.log(aspects.number('aggression')); // 2
+ * console.log(aspects.number('caution')); // 0 - the fallback
+ * ```
+ */
+export declare class Aspects {
+    private values;
+    constructor(defaults?: AspectValues);
+    has(name: string): boolean;
+    get(name: string): AspectValue | undefined;
+    set(name: string, value: AspectValue): void;
+    /** a numeric aspect, or `fallback` when it is missing or not a number */
+    number(name: string, fallback?: number): number;
+    flag(name: string, fallback?: boolean): boolean;
+    /** a list aspect; a bare string reads as a one-entry list, anything else as empty */
+    list(name: string): readonly string[];
+    names(): string[];
+    /** a new store with `overrides` laid over this one, leaving this one untouched */
+    with(overrides: AspectValues): Aspects;
+    toJSON(): Record<string, AspectValue>;
+    static fromJSON(values: Readonly<Record<string, AspectValue>>): Aspects;
+}
+export interface DifficultyLevel {
+    id: string;
+    name?: string;
+    /** the aspects this level changes from the game's base set */
+    aspects?: AspectValues;
+}
+/**
+ * Named difficulty levels, each a set of aspect overrides - Wesnoth's native difficulty ladder,
+ * which is really "the same AI with different numbers". A level is applied on top of a base aspect
+ * set, so a game writes its normal AI once and a level only lists what it changes.
+ *
+ * @example
+ * ```ts
+ * import { Aspects, Difficulty } from '@datamoc/mw_games/ai';
+ *
+ * const difficulty = new Difficulty(
+ *   [{ id: 'hard', aspects: { aggression: 2, keep_away: 3 } }],
+ *   { aggression: 1 },
+ * );
+ * console.log(difficulty.aspectsFor('hard').number('aggression')); // 2
+ * ```
+ */
+export declare class Difficulty {
+    private readonly levels;
+    private readonly base;
+    constructor(levels?: readonly DifficultyLevel[], base?: AspectValues);
+    get ids(): string[];
+    get(id: string): DifficultyLevel | undefined;
+    /** the base aspects with a level's overrides applied; throws for an unknown level */
+    aspectsFor(id: string): Aspects;
+}
+export type GoalKind = 'attack' | 'defend' | 'retreat' | 'capture' | 'scout';
+export interface Goal {
+    unit: string;
+    kind: GoalKind;
+    /** what the goal is about: the enemy to attack, the village to hold */
+    target?: string;
+    /** a tiebreaker between goals, read by a stage's own `weigh`; defaults to 1 */
+    priority?: number;
+}
+/**
+ * Per-unit goals - "hold this village", "attack that leader" - kept as a small registry for a
+ * stage's `weigh` to read. `mwg` does not decide what a goal is worth, the same way it ships no
+ * damage formula: the registry answers *what* a unit has been told to do, and a game's weigh
+ * decides how much that matters.
+ *
+ * @example
+ * ```ts
+ * import { Goals } from '@datamoc/mw_games/ai';
+ *
+ * const goals = new Goals();
+ * goals.set({ unit: 'hero', kind: 'attack', target: 'rat', priority: 3 });
+ * console.log(goals.get('hero')?.kind); // 'attack'
+ * ```
+ */
+export declare class Goals {
+    private readonly byUnit;
+    set(goal: Goal): void;
+    clear(unit: string): void;
+    get(unit: string): Goal | undefined;
+    all(): readonly Goal[];
+    get isEmpty(): boolean;
+}
+/**
+ * The order a side recruits in - Wesnoth's `recruitment_pattern`, e.g. `scout, fighter, archer` -
+ * cycled by turn. A side with nothing left to recruit falls back to its `fallback`, and a side
+ * with neither recruits nothing.
+ *
+ * @example
+ * ```ts
+ * import { RecruitmentPattern } from '@datamoc/mw_games/ai';
+ *
+ * const pattern = new RecruitmentPattern(['scout', 'fighter'], 'fighter');
+ * console.log(pattern.at(0), pattern.at(1), pattern.at(2)); // scout fighter scout
+ * ```
+ */
+export declare class RecruitmentPattern {
+    private readonly order;
+    private readonly fallback;
+    constructor(order: readonly string[], fallback?: string | null);
+    get length(): number;
+    /** the unit type at a position in the cycle, or the fallback when the pattern is empty */
+    at(index: number): string | null;
+    /** the entry after `after` in the cycle, or the first when `after` is not in it */
+    next(after: string | null): string | null;
+}
+export interface HeuristicCandidate<A = unknown> {
+    /** an id for tracing which candidate won */
+    id: string;
+    action: A;
+    /** the unit the action belongs to, matched against `Goals` by a stage's own `weigh` */
+    unit?: string;
+    /**
+     * Aspect-named weights this candidate contributes, e.g. `{ aggression: 3, village_value: 2 }`.
+     * `distance` is special: with a `keep_away` aspect it is penalised by `keepAwayScore`.
+     */
+    factors?: Readonly<Record<string, number>>;
+    /** the acting unit's type, when the candidate carries one */
+    type?: string;
+    /** the acting unit's role/function, e.g. `leader` or `courier` */
+    role?: string;
+    /** whether the acting unit can recruit */
+    can_recruit?: boolean;
+    /** the acting unit's own name */
+    name?: string;
+}
+export interface HeuristicContext {
+    aspects: Aspects;
+    goals?: Goals;
+    turn?: number;
+}
+export interface HeuristicStage<A = unknown> {
+    id: string;
+    /** whether this stage runs at all; it always does when omitted */
+    when?: (context: HeuristicContext) => boolean;
+    /** score one candidate; higher wins. Defaults to `defaultWeigh` */
+    weigh?: (candidate: HeuristicCandidate<A>, context: HeuristicContext) => number;
+}
+export interface HeuristicDecision<A = unknown> {
+    candidate: HeuristicCandidate<A>;
+    stage: string;
+    score: number;
+}
+/**
+ * The candidate-action pipeline at the heart of a Wesnoth-style AI: stages run in order, the first
+ * one whose `when` passes scores every candidate with its `weigh`, and the highest score wins (the
+ * earlier candidate on a tie, so a decision is stable across equal scores).
+ *
+ * The default `weigh` is the aspect-weighted sum of each candidate's `factors`, which is what makes
+ * the aspects worth having: a game sets `aggression: 2` once and every candidate naming
+ * `aggression` is worth twice as much. `keep_away` is honoured through a candidate's `distance`
+ * factor. A stage that needs more - goal priorities, terrain, this turn's state - brings its own
+ * `weigh`, and `mwg` stays out of the rules.
+ *
+ * @example
+ * ```ts
+ * import { Aspects, HeuristicAI } from '@datamoc/mw_games/ai';
+ *
+ * const ai = new HeuristicAI<{ kind: string }>({ stages: [{ id: 'best' }] });
+ * const decision = ai.decide(
+ *   [
+ *     { id: 'wait', action: { kind: 'wait' }, factors: { caution: 2 } },
+ *     { id: 'charge', action: { kind: 'attack' }, factors: { aggression: 3 } },
+ *   ],
+ *   { aspects: new Aspects({ aggression: 1, caution: 1 }) },
+ * );
+ * console.log(decision?.candidate.id); // 'charge'
+ * ```
+ */
+export declare class HeuristicAI<A = unknown> {
+    private readonly stages;
+    constructor(options: {
+        stages: readonly HeuristicStage<A>[];
+    });
+    /** the first stage's best candidate, or `null` when nothing applies or no candidate is given */
+    decide(candidates: readonly HeuristicCandidate<A>[], context: HeuristicContext): HeuristicDecision<A> | null;
+}
+/**
+ * The default stage weight: each factor times the aspect of the same name (an unset aspect weighs
+ * 1, so a factor on its own is not erased), minus a `keepAwayScore` penalty for a candidate's
+ * `distance`.
+ *
+ * @example
+ * ```ts
+ * import { Aspects, defaultWeigh } from '@datamoc/mw_games/ai';
+ *
+ * const score = defaultWeigh(
+ *   { id: 'charge', action: {}, factors: { aggression: 3 } },
+ *   { aspects: new Aspects({ aggression: 2 }) },
+ * );
+ * console.log(score); // 6
+ * ```
+ */
+export declare function defaultWeigh<A>(candidate: HeuristicCandidate<A>, context: HeuristicContext): number;
+/**
+ * How much a candidate at `distance` loses for being inside a `keepAway` radius: 0 when there is no
+ * radius or the candidate is outside it, otherwise the shortfall as a negative score.
+ *
+ * @example
+ * ```ts
+ * import { keepAwayScore } from '@datamoc/mw_games/ai';
+ *
+ * console.log(keepAwayScore(1, 3)); // -2, two tiles inside the radius
+ * console.log(keepAwayScore(5, 3)); // 0, outside it
+ * ```
+ */
+export declare function keepAwayScore(distance: number, keepAway: number): number;
+/**
+ * What a stage's own weigh can add for a goal: its `priority`, or 1 when it has none.
+ *
+ * @example
+ * ```ts
+ * import { goalScore } from '@datamoc/mw_games/ai';
+ *
+ * console.log(goalScore({ unit: 'u1', kind: 'attack', priority: 3 })); // 3
+ * console.log(goalScore(undefined)); // 0, no goal at all
+ * ```
+ */
+export declare function goalScore(goal: Goal | undefined): number;
+//# sourceMappingURL=Heuristics.d.ts.map

package/dist/ai/Heuristics.d.ts.map

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