hoi4-agent-tools 4.3.0 → 4.4.0

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

@@ -0,0 +1,119 @@
+import { PARTITION_KIND, PARTITION_TERRAIN, partitionFieldsFromBitmaps, } from './partition-fields.js';
+import { PARTITION_PROVINCE_ERROR, PARTITION_PROVINCE_WARNING, } from './partition-tuning.js';
+import { partitionFieldsFromGeography, partitionFieldsWithTerrainLines, } from './partition-geography.js';
+/** Terrain class of each reference terrain code (`referenceTerrainNames` in `world.ts`). */
+const REFERENCE_CLASSES = [
+    PARTITION_TERRAIN.plains,
+    PARTITION_TERRAIN.forest,
+    PARTITION_TERRAIN.desert,
+    PARTITION_TERRAIN.mountain,
+    PARTITION_TERRAIN.snow,
+    PARTITION_TERRAIN.mountain,
+    PARTITION_TERRAIN.hills,
+    PARTITION_TERRAIN.marsh,
+    PARTITION_TERRAIN.jungle,
+];
+/** Value below which a share of the land lies, from a coarse histogram (no sort of 13 million). */
+function landQuantiles(input, shares) {
+    const bins = 2048;
+    const histogram = new Uint32Array(bins);
+    let land = 0;
+    for (let p = 0; p < input.kind.length; p++) {
+        if (input.kind[p] !== PARTITION_KIND.land)
+            continue;
+        const value = Math.min(1, Math.max(0, input.elevation[p]));
+        histogram[Math.min(bins - 1, Math.floor(value * bins))]++;
+        land++;
+    }
+    return shares.map((share) => {
+        let seen = 0;
+        for (let bin = 0; bin < bins; bin++) {
+            seen += histogram[bin];
+            if (seen >= share * land)
+                return (bin + 1) / bins;
+        }
+        return 1;
+    });
+}
+/**
+ * Partition fields from the generator's own rasters: heights as `heightmap.bmp` will hold them,
+ * the drainage rivers, and a per-pixel terrain class (the reference picture's when there is one,
+ * otherwise elevation and moisture rules like the province terrain rules).
+ */
+export function surfacePartitionFields(input) {
+    const { width, height, kind, elevation, moisture } = input;
+    const total = width * height;
+    const heights = new Uint8Array(total);
+    const terrain = new Uint8Array(total).fill(PARTITION_TERRAIN.water);
+    const wet = new Uint8Array(total);
+    const [hillLevel = 1, mountainLevel = 1] = input.referenceTerrain === undefined ? landQuantiles(input, [0.72, 0.88]) : [1, 1];
+    for (let p = 0; p < total; p++) {
+        wet[p] = Math.round(Math.min(1, Math.max(0, moisture[p])) * 255);
+        if (kind[p] !== PARTITION_KIND.land) {
+            heights[p] = 89;
+            continue;
+        }
+        const value = elevation[p];
+        heights[p] =
+            input.heights === undefined
+                ? Math.min(255, Math.max(96, Math.round(96 + value * 110)))
+                : Math.max(96, input.heights[p]);
+        if (input.referenceTerrain !== undefined) {
+            terrain[p] = REFERENCE_CLASSES[input.referenceTerrain[p]] ?? PARTITION_TERRAIN.plains;
+            continue;
+        }
+        const y = Math.floor(p / width);
+        const latitude = Math.abs(y / height - 0.5) * 2;
+        const m = moisture[p];
+        terrain[p] =
+            value >= mountainLevel
+                ? PARTITION_TERRAIN.mountain
+                : value >= hillLevel
+                    ? PARTITION_TERRAIN.hills
+                    : latitude < 0.3 && m > 0.55
+                        ? PARTITION_TERRAIN.jungle
+                        : latitude > 0.25 && latitude < 0.55 && m < 0.42
+                            ? PARTITION_TERRAIN.desert
+                            : m > 0.62
+                                ? PARTITION_TERRAIN.marsh
+                                : m > 0.5
+                                    ? PARTITION_TERRAIN.forest
+                                    : PARTITION_TERRAIN.plains;
+    }
+    const identity = Uint8Array.from({ length: 256 }, (_, index) => index);
+    return partitionFieldsFromBitmaps({
+        width,
+        height,
+        kind,
+        heights,
+        rivers: input.riverPixels,
+        terrain,
+        terrainClasses: identity,
+        moisture: wet,
+    });
+}
+/**
+ * Partition fields of a world built from a geography model: the surface fields read from the
+ * synthesised heights, with the model's regions, densities and wall ranges
+ * (`partitionFieldsFromGeography`) and the walls, fort lines and crests the synthesis drew
+ * (`partitionFieldsWithTerrainLines`).
+ */
+export function geographyPartitionFields(input, geography, terrain) {
+    return partitionFieldsWithTerrainLines(partitionFieldsFromGeography(surfacePartitionFields(input), geography), terrain.barrier);
+}
+/** A province-count note for the legacy partition and the final check of the feature-aware one. */
+export function provinceCountNote(provinces, mode) {
+    if (provinces <= PARTITION_PROVINCE_WARNING)
+        return undefined;
+    return {
+        code: 'MAP_PARTITION_PROVINCE_COUNT_HIGH',
+        severity: 'warning',
+        message: `The world has ${provinces} provinces. Vanilla has about 13,400 and the wiki advises at most about 21,000; the text tables (definitions, positions, buildings) near 16 MiB each stop loading beyond that. Raise landProvincePixels and seaProvincePixels to reduce the count`,
+        details: {
+            provinces,
+            warningAbove: PARTITION_PROVINCE_WARNING,
+            errorAbove: PARTITION_PROVINCE_ERROR,
+            mode,
+        },
+    };
+}

package/dist/hoi4_agent_tools/map/world-provinces.js

@@ -10,15 +10,31 @@ function hash(seed, value) {
 function circularDelta(x, origin, width) {
     return x - origin - Math.round((x - origin) / width) * width;
 }
+/** Extra land sites a sampling box gets from its mean height and wetness, before rounding. */
+function landDensity(relief, wet) {
+    return Math.max(0, relief) * 1.3 + Math.max(0, wet);
+}
 /**
  * Jittered sites use ordinary Euclidean distance, rather than cardinal flood distance.
- * Additional sites in elevated/wet land give those areas a denser, varied partition.
+ * Additional sites in elevated/wet land give those areas a denser, varied partition; the
+ * sampling box grows by the mean of those extras, so they redistribute provinces instead of
+ * adding to the requested `landProvincePixels`. Lakes take the sea target.
  * Each occupied sampling box has a site, including thin coasts and small islands.
  */
 function sites(input, wanted) {
     const { width, height, kind, elevation, moisture, seed } = input;
-    const target = wanted === 0 ? input.seaProvincePixels : input.landProvincePixels;
-    const cell = Math.max(2, Math.floor(Math.min(Math.sqrt(target), width / 20, height / 20)));
+    const target = wanted === 1 ? input.landProvincePixels : input.seaProvincePixels;
+    let extras = 0;
+    let pixels = 0;
+    if (wanted === 1)
+        for (let p = 0; p < kind.length; p++) {
+            if (kind[p] !== 1)
+                continue;
+            pixels++;
+            extras += Math.min(2, landDensity(elevation[p], moisture[p]));
+        }
+    const meanExtra = pixels === 0 ? 0 : extras / pixels;
+    const cell = Math.max(2, Math.floor(Math.min(Math.sqrt(target * (1 + meanExtra)), width / 20, height / 20)));
     const columns = Math.ceil(width / cell);
     const rows = Math.ceil(height / cell);
     const result = {
@@ -57,7 +73,7 @@ function sites(input, wanted) {
             }
             if (count === 0)
                 continue;
-            const density = wanted === 1 ? Math.max(0, relief / count) * 1.3 + Math.max(0, wet / count) : 0;
+            const density = wanted === 1 ? landDensity(relief / count, wet / count) : 0;
             const extra = Math.min(2, Math.floor(density + hash(seed, bin + wanted * 7717)));
             const used = new Set();
             for (let slot = 0; slot <= extra; slot++) {
@@ -152,6 +168,7 @@ function connectedParts(input, labels) {
         maxX: [],
         minY: [],
         maxY: [],
+        group: [],
     };
     const limitX = Math.max(1, Math.floor(width / 8));
     const limitY = Math.max(1, Math.floor(height / 8));
@@ -161,6 +178,8 @@ function connectedParts(input, labels) {
         const id = parts.parent.length;
         parts.parent.push(id);
         parts.kind.push(kind[start]);
+        if (input.group !== undefined)
+            parts.group.push(input.group[start]);
         const origin = start % width;
         let minX = 0;
         let maxX = 0;
@@ -218,13 +237,15 @@ function root(parts, id) {
     }
     return r;
 }
-function merge(parts, a, b, width, height) {
+function merge(parts, a, b, width, height, sameGroup = false) {
     a = root(parts, a);
     b = root(parts, b);
     if (a === b)
         return true;
     if (parts.kind[a] !== parts.kind[b])
         return false;
+    if (sameGroup && parts.group[a] !== parts.group[b])
+        return false;
     const shift = parts.origin[b] - parts.origin[a];
     const minX = Math.min(parts.minX[a], parts.minX[b] + shift);
     const maxX = Math.max(parts.maxX[a], parts.maxX[b] + shift);
@@ -246,25 +267,39 @@ function merge(parts, a, b, width, height) {
 function absorbSlivers(input, parts) {
     const { width, height } = input;
     // Every successful operation removes a whole connected component. The scan is
-    // repeated because a previously isolated fragment may become mergeable afterwards.
-    for (let pass = 0; pass < 4; pass++) {
-        let changed = false;
-        for (let p = 0; p < parts.pixel.length; p++) {
-            const x = p % width;
-            const adjacent = [x + 1 < width ? p + 1 : p + 1 - width, p + width];
-            for (const q of adjacent) {
-                if (q >= parts.pixel.length)
-                    continue;
-                const a = root(parts, parts.pixel[p]);
-                const b = root(parts, parts.pixel[q]);
-                if (a === b || (parts.size[a] >= 20 && parts.size[b] >= 20))
-                    continue;
-                if (merge(parts, a, b, width, height))
-                    changed = true;
+    // repeated because a previously isolated fragment may become mergeable afterwards. With groups
+    // or lines, the first stages merge inside a group and not across a line, and the last stage
+    // takes what is left.
+    const stages = [];
+    if (input.group !== undefined && input.line !== undefined)
+        stages.push({ sameGroup: true, avoidLine: true });
+    if (input.line !== undefined)
+        stages.push({ sameGroup: false, avoidLine: true });
+    if (input.group !== undefined)
+        stages.push({ sameGroup: true, avoidLine: false });
+    stages.push({ sameGroup: false, avoidLine: false });
+    for (const { sameGroup, avoidLine } of stages) {
+        for (let pass = 0; pass < 4; pass++) {
+            let changed = false;
+            for (let p = 0; p < parts.pixel.length; p++) {
+                const x = p % width;
+                const adjacent = [x + 1 < width ? p + 1 : p + 1 - width, p + width];
+                for (const q of adjacent) {
+                    if (q >= parts.pixel.length)
+                        continue;
+                    if (avoidLine && (input.line[p] !== 0 || input.line[q] !== 0))
+                        continue;
+                    const a = root(parts, parts.pixel[p]);
+                    const b = root(parts, parts.pixel[q]);
+                    if (a === b || (parts.size[a] >= 20 && parts.size[b] >= 20))
+                        continue;
+                    if (merge(parts, a, b, width, height, sameGroup))
+                        changed = true;
+                }
             }
+            if (!changed)
+                break;
         }
-        if (!changed)
-            break;
     }
 }
 /** Removing a pixel may not cut its donor; verify the donor's local four-way paths. */
@@ -352,6 +387,14 @@ function rebalanceSlivers(input, parts) {
 }
 function repairCrossings(input, parts) {
     const { width, height, kind } = input;
+    const repairStages = [];
+    if (input.group !== undefined && input.line !== undefined)
+        repairStages.push({ sameGroup: true, avoidLine: true });
+    if (input.line !== undefined)
+        repairStages.push({ sameGroup: false, avoidLine: true });
+    if (input.group !== undefined)
+        repairStages.push({ sameGroup: true, avoidLine: false });
+    repairStages.push({ sameGroup: false, avoidLine: false });
     for (let pass = 0; pass < 12; pass++) {
         let changed = false;
         for (let y = 0; y + 1 < height; y++) {
@@ -369,22 +412,32 @@ function repairCrossings(input, parts) {
                     [2, 3],
                 ];
                 let repaired = false;
-                // Whole-cell unions cannot introduce crossings or disconnected provinces.
-                for (const [i, j] of edges) {
-                    if (merge(parts, ids[i], ids[j], width, height)) {
-                        repaired = true;
-                        break;
+                // Whole-cell unions cannot introduce crossings or disconnected provinces. With groups or
+                // lines, the repairs inside one group and not across a line come first.
+                for (const { sameGroup, avoidLine } of repairStages) {
+                    for (const [i, j] of edges) {
+                        if (avoidLine && (input.line[corners[i]] !== 0 || input.line[corners[j]] !== 0))
+                            continue;
+                        if (merge(parts, ids[i], ids[j], width, height, sameGroup)) {
+                            repaired = true;
+                            break;
+                        }
                     }
-                }
-                if (!repaired) {
+                    if (repaired)
+                        break;
                     for (const [i, j] of edges.flatMap(([i, j]) => [
                         [i, j],
                         [j, i],
                     ])) {
                         const p = corners[i];
                         const q = corners[j];
+                        if (avoidLine && (input.line[p] !== 0 || input.line[q] !== 0))
+                            continue;
                         if (kind[p] !== kind[q] || !removable(parts, p, width, height))
                             continue;
+                        if (sameGroup &&
+                            parts.group[root(parts, ids[i])] !== parts.group[root(parts, ids[j])])
+                            continue;
                         const target = ids[j];
                         const dx = (p % width) - parts.origin[target];
                         const py = Math.floor(p / width);
@@ -404,6 +457,8 @@ function repairCrossings(input, parts) {
                         repaired = true;
                         break;
                     }
+                    if (repaired)
+                        break;
                 }
                 if (!repaired)
                     throw new ServiceError('MAP_WORLD_UNREPRESENTABLE_TOPOLOGY', 'The exact land/sea/lake mask cannot resolve a four-province corner while preserving connected provinces and size limits', { x, y });
@@ -416,33 +471,13 @@ function repairCrossings(input, parts) {
     throw new ServiceError('MAP_WORLD_UNREPRESENTABLE_TOPOLOGY', 'Province corner repair did not converge');
 }
 /**
- * Deterministic province geometry with periodic adjacency, but separate province IDs at the seam.
- * Native province bounding boxes use bitmap coordinates, not circular spans. Work is proportional to pixels
- * with bounded local candidate searches; no retained per-pixel objects or global site scans.
+ * Refuse a mask that needs more provinces than the engine tolerates before any site is built:
+ * a singleton component of one kind necessarily needs its own province, which is an inexpensive
+ * lower bound for a hostile fragmented mask.
  */
-export function generateWorldProvinces(input) {
-    const { width, height, kind, elevation, moisture, seed } = input;
-    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 16 || height < 16)
-        invalid('Province dimensions must be integers of at least 16 pixels');
-    const total = width * height;
-    if (!Number.isSafeInteger(total) || total > 13_238_272)
-        invalid('Province dimensions exceed the 13,238,272-pixel map limit');
-    if (!Number.isSafeInteger(seed))
-        invalid('The province seed must be a safe integer');
-    if (!(kind instanceof Uint8Array) ||
-        !(elevation instanceof Float32Array) ||
-        !(moisture instanceof Float32Array))
-        invalid('Province fields must use the specified typed arrays');
-    if (kind.length !== total || elevation.length !== total || moisture.length !== total)
-        invalid('Province fields must match the map dimensions');
-    if (![input.landProvincePixels, input.seaProvincePixels].every((v) => Number.isFinite(v) && v >= 20))
-        invalid('Province target areas must be finite and at least 20 pixels');
-    for (let p = 0; p < total; p++) {
-        if (kind[p] > 2 || !Number.isFinite(elevation[p]) || !Number.isFinite(moisture[p]))
-            invalid('Province fields contain an unsupported kind or non-finite terrain value');
-    }
-    // A singleton kind component necessarily needs its own province. Count that
-    // inexpensive lower bound before building sites for a hostile fragmented mask.
+export function assertProvinceMaskFeasible(input) {
+    const { width, kind } = input;
+    const total = width * input.height;
     let isolated = 0;
     for (let p = 0; p < total; p++) {
         const x = p % width;
@@ -456,7 +491,18 @@ export function generateWorldProvinces(input) {
     }
     if (isolated > 65_000)
         throw new ServiceError('MAP_WORLD_TOO_MANY_PROVINCES', 'The kind mask requires more than 65,000 isolated provinces', { isolated });
-    const parts = connectedParts(input, nearestPartition(input));
+}
+/**
+ * Turn one label per pixel into provinces: split disconnected and over-wide parts, absorb slivers,
+ * keep every province at least 20 pixels where the mask allows, repair four-province corners and
+ * number the provinces by their first pixel. Both partitions finish through this function, so the
+ * engine rules (connected provinces, the bounding box limit, no X crossing, the 65,000 cap) hold
+ * whichever one made the labels.
+ */
+export function assembleWorldProvinces(input, labels) {
+    const { width, height, kind } = input;
+    const total = width * height;
+    const parts = connectedParts(input, labels);
     absorbSlivers(input, parts);
     rebalanceSlivers(input, parts);
     repairCrossings(input, parts);
@@ -522,3 +568,32 @@ export function generateWorldProvinces(input) {
     }
     return result;
 }
+/**
+ * Deterministic province geometry with periodic adjacency, but separate province IDs at the seam.
+ * Native province bounding boxes use bitmap coordinates, not circular spans. Work is proportional to pixels
+ * with bounded local candidate searches; no retained per-pixel objects or global site scans.
+ */
+export function generateWorldProvinces(input) {
+    const { width, height, kind, elevation, moisture, seed } = input;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 16 || height < 16)
+        invalid('Province dimensions must be integers of at least 16 pixels');
+    const total = width * height;
+    if (!Number.isSafeInteger(total) || total > 13_238_272)
+        invalid('Province dimensions exceed the 13,238,272-pixel map limit');
+    if (!Number.isSafeInteger(seed))
+        invalid('The province seed must be a safe integer');
+    if (!(kind instanceof Uint8Array) ||
+        !(elevation instanceof Float32Array) ||
+        !(moisture instanceof Float32Array))
+        invalid('Province fields must use the specified typed arrays');
+    if (kind.length !== total || elevation.length !== total || moisture.length !== total)
+        invalid('Province fields must match the map dimensions');
+    if (![input.landProvincePixels, input.seaProvincePixels].every((v) => Number.isFinite(v) && v >= 20))
+        invalid('Province target areas must be finite and at least 20 pixels');
+    for (let p = 0; p < total; p++) {
+        if (kind[p] > 2 || !Number.isFinite(elevation[p]) || !Number.isFinite(moisture[p]))
+            invalid('Province fields contain an unsupported kind or non-finite terrain value');
+    }
+    assertProvinceMaskFeasible(input);
+    return assembleWorldProvinces(input, nearestPartition(input));
+}