hoi4-agent-tools 4.3.0 → 4.4.0

package/dist/hoi4_agent_tools/map/partition-tuning.js

@@ -0,0 +1,101 @@
+import { ServiceError } from '../core/result.js';
+/** Defaults relative to the base land area, from the vanilla spread (median 160, p10 77, p90 846). */
+export const PARTITION_DEFAULTS = {
+    fertile: 0.35,
+    hills: 1,
+    mountain: 2.2,
+    waste: 3.4,
+    seaCoastal: 0.5,
+    seaOpen: 2.4,
+    lake: 6_000,
+    barrierStrength: 20,
+    minProvincePixels: 40,
+    narrowStraitPx: 24,
+};
+/** The province count above which the wiki and the text-table limit advise against a map. */
+export const PARTITION_PROVINCE_WARNING = 14_000;
+export const PARTITION_PROVINCE_ERROR = 21_000;
+function refuse(code, message, details) {
+    throw new ServiceError(code, message, details);
+}
+function checkPixels(name, value, minimum) {
+    if (value === undefined)
+        return;
+    if (!Number.isFinite(value) || value < minimum)
+        refuse('MAP_PARTITION_AREA_BANDS_CONTRADICTORY', `partition ${name} must be a finite number of at least ${minimum} pixels`, { field: name, value, minimum });
+}
+/**
+ * Resolve and check the tuning against the request. Contradictory size bands, a map too small for
+ * the minimum province, or an ordering that cannot be met are refused before any pixel is
+ * touched, with `MAP_PARTITION_*` codes.
+ */
+export function resolvePartitionTuning(tuning, base) {
+    const minProvincePixels = tuning?.minProvincePixels ?? PARTITION_DEFAULTS.minProvincePixels;
+    checkPixels('minProvincePixels', minProvincePixels, 20);
+    const cellLimit = Math.floor(Math.min(base.width, base.height) / 14) ** 2;
+    if (minProvincePixels > cellLimit)
+        refuse('MAP_PARTITION_MAP_TOO_SMALL', `The map is too small for provinces of at least ${minProvincePixels} pixels: a province may span at most an eighth of the map, about ${cellLimit} pixels here`, { minProvincePixels, maximum: cellLimit, width: base.width, height: base.height });
+    const clamp = (value) => Math.max(minProvincePixels, Math.min(cellLimit, Math.round(value)));
+    const land = base.landProvincePixels;
+    const bands = tuning?.landArea;
+    for (const [name, value] of Object.entries(bands ?? {}))
+        checkPixels(`landArea.${name}`, value, minProvincePixels);
+    const fertile = clamp(bands?.fertile ?? land * PARTITION_DEFAULTS.fertile);
+    const hills = clamp(bands?.hills ?? land * PARTITION_DEFAULTS.hills);
+    const mountain = clamp(bands?.mountain ?? land * PARTITION_DEFAULTS.mountain);
+    const waste = clamp(bands?.waste ?? land * PARTITION_DEFAULTS.waste);
+    if (fertile > hills || hills > mountain)
+        refuse('MAP_PARTITION_AREA_BANDS_CONTRADICTORY', 'partition landArea must grow from fertile to hills to mountain (fertile <= hills <= mountain)', { fertile, hills, mountain, waste });
+    const sea = tuning?.seaArea;
+    for (const [name, value] of Object.entries(sea ?? {}))
+        checkPixels(`seaArea.${name}`, value, minProvincePixels);
+    const coastal = clamp(sea?.coastal ?? base.seaProvincePixels * PARTITION_DEFAULTS.seaCoastal);
+    const open = clamp(sea?.open ?? base.seaProvincePixels * PARTITION_DEFAULTS.seaOpen);
+    if (coastal > open)
+        refuse('MAP_PARTITION_AREA_BANDS_CONTRADICTORY', 'partition seaArea.coastal may not exceed seaArea.open', { coastal, open });
+    const perState = tuning?.provincesPerState;
+    if (perState !== undefined && perState[0] > perState[1])
+        refuse('MAP_PARTITION_STATE_SIZE_CONTRADICTORY', 'partition provincesPerState must be [smallest, largest] with smallest <= largest', { provincesPerState: perState });
+    const regionSize = tuning?.regionSize;
+    if (regionSize !== undefined && regionSize[0] > regionSize[1])
+        refuse('MAP_PARTITION_REGION_SIZE_CONTRADICTORY', 'partition regionSize must be [smallest, largest] with smallest <= largest', { regionSize });
+    const group = (range, target, low, high) => {
+        if (range !== undefined)
+            return {
+                min: range[0],
+                target: Math.max(range[0], Math.min(range[1], Math.round(Math.sqrt(range[0] * range[1])))),
+                max: range[1],
+            };
+        return {
+            min: Math.max(1, Math.round(target * low)),
+            target,
+            max: Math.max(target, Math.round(target * high)) + (target > 1 ? 1 : 0),
+        };
+    };
+    const strength = tuning?.barrierStrength ?? PARTITION_DEFAULTS.barrierStrength;
+    if (!Number.isFinite(strength) || strength < 0 || strength > 60)
+        refuse('MAP_PARTITION_STRENGTH_INVALID', 'partition barrierStrength must be from 0 to 60', {
+            barrierStrength: strength,
+        });
+    const strait = tuning?.narrowStraitPx ?? PARTITION_DEFAULTS.narrowStraitPx;
+    if (!Number.isInteger(strait) || strait < 4 || strait > 64)
+        refuse('MAP_PARTITION_STRENGTH_INVALID', 'partition narrowStraitPx must be from 4 to 64', {
+            narrowStraitPx: strait,
+        });
+    return {
+        landArea: { fertile, plains: clamp(Math.sqrt(fertile * hills)), hills, mountain, waste },
+        seaArea: { coastal, open },
+        lakeArea: clamp(PARTITION_DEFAULTS.lake),
+        states: group(perState, base.provincesPerState, 0.5, 1.6),
+        regions: group(regionSize, base.landProvincesPerRegion, 0.6, 1.5),
+        seaRegions: group(undefined, base.seaProvincesPerRegion, 0.5, 1.6),
+        barrierStrength: strength,
+        minProvincePixels,
+        narrowStraitPx: strait,
+        maxProvincePixels: cellLimit,
+        normalizeLand: bands === undefined || Object.keys(bands).length === 0,
+        normalizeSea: sea === undefined || Object.keys(sea).length === 0,
+        landBase: land,
+        seaBase: base.seaProvincePixels,
+    };
+}

package/dist/hoi4_agent_tools/map/partition-watershed.js

@@ -0,0 +1,252 @@
+import { ServiceError } from '../core/result.js';
+/**
+ * The two engines of the feature-aware province partition (ADR 0058): variable-radius dart
+ * throwing for seeds and a marker-controlled watershed (multi-source Dijkstra with integer costs
+ * in a bucket queue) for borders. Both are deterministic: hashed priorities, no random state, no
+ * floating-point function beyond `+ - * /` and `sqrt`.
+ */
+export function hash32(seed, a, b = 0) {
+    let n = Math.imul(seed ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul(a + 0x7f4a7c15, 0xc2b2ae35);
+    n = Math.imul(n ^ (n >>> 15), 0x2c1b3c6d) ^ Math.imul(b + 0x165667b1, 0x297a2d39);
+    n = Math.imul(n ^ (n >>> 12), 0x85ebca6b);
+    n = Math.imul(n ^ (n >>> 15), 0xc2b2ae35);
+    return (n ^ (n >>> 16)) >>> 0;
+}
+export function unit32(value) {
+    return value / 4_294_967_296;
+}
+/**
+ * Candidates per final seed. Random sequential adsorption reaches about 94% of the jamming
+ * density after ten attempts per disc, which fills the map without visible gaps.
+ */
+const OVERSAMPLE = 40;
+/** Dart-throwing spacing over the square root of the planned area (jamming gives 0.834). */
+export const SEED_SPACING = 0.8;
+/**
+ * Variable-radius Poisson-disc seeds: candidates are drawn per lattice cell with a probability
+ * that follows the planned area, ordered by a hashed priority, and accepted when no accepted seed
+ * lies closer than the smaller of the two spacings. Returns pixel indices in acceptance order.
+ */
+export function placeSeeds(request) {
+    const { width, height, kind, wanted, areaAt, minArea, seed, salt } = request;
+    const stride = Math.max(1, Math.floor(0.35 * SEED_SPACING * Math.sqrt(minArea)));
+    const cx = [];
+    const spacing = [];
+    const keys = [];
+    const limit = request.avoidBarrierAbove ?? 64;
+    for (let y0 = 0; y0 < height; y0 += stride) {
+        for (let x0 = 0; x0 < width; x0 += stride) {
+            const h = hash32(seed + salt, x0 * 0x10001 + 1, y0);
+            const x = Math.min(width - 1, x0 + (h % stride));
+            const y = Math.min(height - 1, y0 + (((h >>> 8) >>> 0) % stride));
+            const pixel = y * width + x;
+            if (kind[pixel] !== wanted)
+                continue;
+            if (request.barrier !== undefined && request.barrier[pixel] > limit)
+                continue;
+            const area = areaAt(pixel);
+            const chance = (OVERSAMPLE * stride * stride) / area;
+            if (chance < 1 && unit32(hash32(seed + salt, pixel, 7)) >= chance)
+                continue;
+            cx.push(pixel);
+            spacing.push(SEED_SPACING * Math.sqrt(area));
+            keys.push(hash32(seed + salt, pixel, 13) >>> 4);
+        }
+    }
+    const count = cx.length;
+    if (count === 0)
+        return new Int32Array(0);
+    if (count >= 1 << 24)
+        throw new ServiceError('MAP_PARTITION_TOO_MANY_CANDIDATES', 'The planned province areas are too small for this map', { candidates: count });
+    const order = new Float64Array(count);
+    for (let i = 0; i < count; i++)
+        order[i] = keys[i] * 16_777_216 + i;
+    order.sort();
+    let smallest = Infinity;
+    for (const value of spacing)
+        if (value < smallest)
+            smallest = value;
+    const cell = smallest / Math.SQRT2;
+    const columns = Math.ceil(width / cell) + 1;
+    const rows = Math.ceil(height / cell) + 1;
+    const grid = new Int32Array(columns * rows).fill(-1);
+    const seedPixels = [];
+    const seedSpacing = [];
+    for (let k = 0; k < count; k++) {
+        const index = order[k] % 16_777_216;
+        const pixel = cx[index];
+        const d = spacing[index];
+        const x = pixel % width;
+        const y = (pixel - x) / width;
+        const gx = Math.floor(x / cell);
+        const gy = Math.floor(y / cell);
+        const reach = Math.ceil(d / cell);
+        let free = true;
+        for (let dy = -reach; dy <= reach && free; dy++) {
+            const row = gy + dy;
+            if (row < 0 || row >= rows)
+                continue;
+            for (let dx = -reach; dx <= reach; dx++) {
+                let column = gx + dx;
+                // The map wraps east-west.
+                const wrapped = Math.ceil(width / cell);
+                if (column < 0)
+                    column += wrapped;
+                else if (column >= wrapped)
+                    column -= wrapped;
+                const other = grid[row * columns + column];
+                if (other < 0)
+                    continue;
+                const ox = seedPixels[other] % width;
+                const oy = (seedPixels[other] - ox) / width;
+                let ddx = ox - x;
+                if (ddx > width / 2)
+                    ddx -= width;
+                else if (ddx < -width / 2)
+                    ddx += width;
+                const ddy = oy - y;
+                const near = Math.min(d, seedSpacing[other]);
+                if (ddx * ddx + ddy * ddy < near * near) {
+                    free = false;
+                    break;
+                }
+            }
+        }
+        if (!free)
+            continue;
+        grid[gy * columns + gx] = seedPixels.length;
+        seedPixels.push(pixel);
+        seedSpacing.push(d);
+    }
+    return Int32Array.from(seedPixels);
+}
+/** A plain step has this multiplier, and costs 10 for a cardinal move and 14 for a diagonal one. */
+export const STEP_UNIT = 256;
+/**
+ * Label every pixel with the seed that reaches it at the least cost. The cost of a move onto pixel
+ * `q` is `base * step[q] / 256` plus a penalty when the region or terrain class changes, so
+ * wavefronts slow down on natural lines and meet on them. Ties go to the first arrival. The
+ * result labels exactly the pixels connected to a seed through pixels of one kind (eight
+ * neighbours, wrapping east-west).
+ */
+export function weightedWatershed(input) {
+    const { width, height, kind, step, seeds } = input;
+    const total = width * height;
+    const regionPenalty = input.regionPenalty ?? 0;
+    const terrainPenalty = input.terrainPenalty ?? 0;
+    const region = input.regionId;
+    const terrain = input.terrainClass;
+    let maxStep = 0;
+    for (let p = 0; p < total; p++)
+        if (step[p] > maxStep)
+            maxStep = step[p];
+    const maxCost = ((14 * maxStep) >> 8) + 1 + regionPenalty + terrainPenalty;
+    let buckets = 1;
+    while (buckets <= maxCost)
+        buckets <<= 1;
+    const mask = buckets - 1;
+    const heads = new Int32Array(buckets).fill(-1);
+    let capacity = Math.max(1 << 16, seeds.length * 4);
+    let nodePixel = new Int32Array(capacity);
+    let nodeNext = new Int32Array(capacity);
+    let used = 0;
+    let free = -1;
+    let live = 0;
+    const distance = new Int32Array(total).fill(0x7fffffff);
+    const labels = new Int32Array(total).fill(-1);
+    const push = (cost, pixel) => {
+        let node;
+        if (free >= 0) {
+            node = free;
+            free = nodeNext[node];
+        }
+        else {
+            if (used === capacity) {
+                capacity *= 2;
+                const pixels = new Int32Array(capacity);
+                pixels.set(nodePixel);
+                nodePixel = pixels;
+                const next = new Int32Array(capacity);
+                next.set(nodeNext);
+                nodeNext = next;
+            }
+            node = used++;
+        }
+        const bucket = cost & mask;
+        nodePixel[node] = pixel;
+        nodeNext[node] = heads[bucket];
+        heads[bucket] = node;
+        live++;
+    };
+    for (let i = 0; i < seeds.length; i++) {
+        const p = seeds[i];
+        if (labels[p] !== -1)
+            continue;
+        labels[p] = i;
+        distance[p] = 0;
+        push(0, p);
+    }
+    const relax = (q, from, current, base, label) => {
+        let cost = current + ((base * step[q]) >> 8);
+        if (region !== undefined && region[q] !== region[from])
+            cost += regionPenalty;
+        if (terrain !== undefined && terrain[q] !== terrain[from])
+            cost += terrainPenalty;
+        if (cost < distance[q]) {
+            distance[q] = cost;
+            labels[q] = label;
+            push(cost, q);
+        }
+    };
+    const last = width - 1;
+    const signal = input.signal;
+    let settled = 0;
+    for (let current = 0; live > 0; current++) {
+        const bucket = current & mask;
+        while (heads[bucket] !== -1) {
+            const node = heads[bucket];
+            heads[bucket] = nodeNext[node];
+            const p = nodePixel[node];
+            nodeNext[node] = free;
+            free = node;
+            live--;
+            if (distance[p] !== current)
+                continue;
+            if ((++settled & 0xffff) === 0)
+                signal?.throwIfAborted();
+            const y = (p / width) | 0;
+            const x = p - y * width;
+            const label = labels[p];
+            const here = kind[p];
+            const west = x > 0 ? p - 1 : p + last;
+            const east = x < last ? p + 1 : p - last;
+            if (kind[west] === here)
+                relax(west, p, current, 10, label);
+            if (kind[east] === here)
+                relax(east, p, current, 10, label);
+            if (y > 0) {
+                const north = p - width;
+                const northWest = x > 0 ? north - 1 : north + last;
+                const northEast = x < last ? north + 1 : north - last;
+                if (kind[north] === here)
+                    relax(north, p, current, 10, label);
+                if (kind[northWest] === here)
+                    relax(northWest, p, current, 14, label);
+                if (kind[northEast] === here)
+                    relax(northEast, p, current, 14, label);
+            }
+            if (y < height - 1) {
+                const south = p + width;
+                const southWest = x > 0 ? south - 1 : south + last;
+                const southEast = x < last ? south + 1 : south - last;
+                if (kind[south] === here)
+                    relax(south, p, current, 10, label);
+                if (kind[southWest] === here)
+                    relax(southWest, p, current, 14, label);
+                if (kind[southEast] === here)
+                    relax(southEast, p, current, 14, label);
+            }
+        }
+    }
+    return labels;
+}

package/dist/hoi4_agent_tools/map/partition.js

@@ -0,0 +1,163 @@
+import { buildProvinceGraph } from './partition-graph.js';
+import { clusterProvinces } from './partition-groups.js';
+import { PARTITION_KIND, PARTITION_TERRAIN } from './partition-fields.js';
+import { partitionProvinces, } from './partition-provinces.js';
+import { resolvePartitionTuning } from './partition-tuning.js';
+/**
+ * Which partition a request gets. A request that names one gets it; otherwise a world described
+ * by a geography model gets the feature-aware partition (the model has regions, walls and
+ * densities that only it can use) and every other request keeps the legacy partition, so its
+ * output stays byte-identical for a seed.
+ */
+export function resolvePartitionMode(requested, hasGeography) {
+    return requested ?? (hasGeography ? 'feature-aware' : 'legacy');
+}
+/** The class or region holding most pixels of every province. */
+function majorityPerProvince(pixel, plane, count, include, empty) {
+    const best = new Uint16Array(count).fill(empty);
+    const bestCount = new Uint32Array(count);
+    const tally = new Map();
+    let lastKey = -1;
+    let run = 0;
+    const flush = () => {
+        if (lastKey < 0)
+            return;
+        const total = (tally.get(lastKey) ?? 0) + run;
+        tally.set(lastKey, total);
+        const id = Math.floor(lastKey / 65_536);
+        const value = lastKey % 65_536;
+        if (total > bestCount[id] || (total === bestCount[id] && value < best[id])) {
+            bestCount[id] = total;
+            best[id] = value;
+        }
+        run = 0;
+    };
+    for (let p = 0; p < pixel.length; p++) {
+        if (!include(p))
+            continue;
+        const key = pixel[p] * 65_536 + plane[p];
+        if (key !== lastKey) {
+            flush();
+            lastKey = key;
+        }
+        run++;
+    }
+    flush();
+    return best;
+}
+/** Cut a map into provinces along its natural lines and build the weighted province graph. */
+export function partitionWorld(input) {
+    const { fields } = input;
+    const result = partitionProvinces(input);
+    input.signal?.throwIfAborted();
+    const { provinces } = result;
+    const graph = buildProvinceGraph({
+        width: fields.width,
+        height: fields.height,
+        pixel: provinces.pixel,
+        kind: provinces.kind,
+        size: provinces.size,
+        sumX: provinces.sumX,
+        sumY: provinces.sumY,
+        barrier: result.barrier,
+    });
+    const count = provinces.kind.length;
+    const provinceRegion = majorityPerProvince(provinces.pixel, fields.regionId, count, (p) => fields.kind[p] !== PARTITION_KIND.lake, 0);
+    const provinceGround = Uint8Array.from(majorityPerProvince(provinces.pixel, fields.terrainClass, count, (p) => fields.kind[p] === PARTITION_KIND.land, PARTITION_TERRAIN.water));
+    for (let id = 0; id < count; id++)
+        if (provinces.kind[id] === PARTITION_KIND.sea) {
+            let shelf = false;
+            for (let e = graph.offsets[id]; e < graph.offsets[id + 1]; e++)
+                if (graph.kind[graph.to[e]] === PARTITION_KIND.land)
+                    shelf = true;
+            provinceGround[id] = shelf ? 0 : 1;
+        }
+    return {
+        fields,
+        tuning: input.tuning,
+        provinces,
+        graph,
+        barrier: result.barrier,
+        provinceRegion,
+        provinceGround,
+        statistics: result.statistics,
+        notes: result.notes,
+    };
+}
+/** Resolve tuning against a request and partition in one call. */
+export function partitionWorldFromRequest(fields, seed, tuning, base, signal) {
+    return partitionWorld({
+        fields,
+        seed,
+        signal,
+        tuning: resolvePartitionTuning(tuning, {
+            ...base,
+            width: fields.width,
+            height: fields.height,
+        }),
+    });
+}
+/**
+ * Cluster land provinces into states. `members` are one country's provinces of one strategic
+ * region (or any group the caller chose); the clusters follow natural lines, never join provinces
+ * of different geography regions and prefer like ground. Returns the cluster of every member,
+ * numbered from 0 by smallest member id.
+ */
+export function clusterStates(partition, members) {
+    const { states } = partition.tuning;
+    const region = partition.provinceRegion;
+    const ground = partition.provinceGround;
+    const table = new Map((partition.fields.regions ?? []).map((entry) => [entry.id, entry]));
+    // A geography region may ask for its own state size; its provinces never mix with another's.
+    const byRegion = new Map();
+    for (const id of members) {
+        const list = byRegion.get(region[id]) ?? [];
+        list.push(id);
+        byRegion.set(region[id], list);
+    }
+    const combined = new Map();
+    let offset = 0;
+    for (const regionId of [...byRegion.keys()].sort((x, y) => x - y)) {
+        const per = table.get(regionId)?.provincesPerState;
+        const options = per === undefined
+            ? { min: states.min, target: states.target, max: states.max }
+            : { min: per[0], target: per[1], max: Math.max(per[2], per[1]) };
+        const clusters = clusterProvinces(byRegion.get(regionId), partition.graph, options, {
+            label: (id) => ground[id],
+        });
+        let largest = -1;
+        for (const [id, cluster] of clusters) {
+            combined.set(id, offset + cluster);
+            if (cluster > largest)
+                largest = cluster;
+        }
+        offset += largest + 1;
+    }
+    // Number the clusters by their smallest member, as every clustering here does.
+    const dense = new Map();
+    const result = new Map();
+    for (const id of [...members].sort((x, y) => x - y)) {
+        const cluster = combined.get(id);
+        let number = dense.get(cluster);
+        if (number === undefined) {
+            number = dense.size;
+            dense.set(cluster, number);
+        }
+        result.set(id, number);
+    }
+    return result;
+}
+/**
+ * Cluster provinces into strategic regions: land by basin and ground inside each geography
+ * region, sea by named sea and by shelf against open water. Pass the land provinces or the sea
+ * provinces as `members`.
+ */
+export function clusterRegions(partition, members, kind) {
+    const options = kind === 'land' ? partition.tuning.regions : partition.tuning.seaRegions;
+    const region = partition.provinceRegion;
+    const ground = partition.provinceGround;
+    return clusterProvinces(members, partition.graph, { min: options.min, target: options.target, max: options.max }, {
+        group: (id) => region[id],
+        label: (id) => ground[id],
+    });
+}