hoi4-agent-tools 4.0.4 → 4.1.0

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

@@ -0,0 +1,273 @@
+import { ServiceError } from '../core/result.js';
+function fail(message) {
+    throw new ServiceError('INVALID_WORLD_DRAINAGE', message);
+}
+function validate(spec) {
+    const { width, height, kind, elevation, count, seed } = spec;
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1)
+        fail('Drainage dimensions must be positive integers.');
+    if (width * height > 13_238_272)
+        fail('Drainage raster exceeds 13,238,272 pixels.');
+    if (!(kind instanceof Uint8Array) || !(elevation instanceof Float32Array))
+        fail('Drainage requires typed land and elevation rasters.');
+    if (kind.length !== width * height || elevation.length !== kind.length)
+        fail('Drainage raster lengths must match the dimensions.');
+    if (!Number.isSafeInteger(seed) || !Number.isSafeInteger(count) || count < 0 || count > 4096)
+        fail('Drainage requires an integer seed and a river count between 0 and 4,096.');
+    for (let pixel = 0; pixel < kind.length; pixel += 1) {
+        const value = elevation[pixel];
+        if (kind[pixel] > 2)
+            fail('Drainage contains an unknown land or water kind.');
+        if (!Number.isFinite(value) ||
+            (kind[pixel] === 1 ? value < 0 || value > 1 : value < -1 || value > 0))
+            fail('Drainage elevations must be finite, with land in [0, 1] and water in [-1, 0].');
+    }
+    let points = 0;
+    for (const line of spec.referenceRivers ?? []) {
+        if (line.length < 2)
+            fail('A reference river requires at least two points.');
+        points += line.length;
+        if (points > 100_000)
+            fail('Reference rivers exceed 100,000 points.');
+        for (const point of line)
+            if (!Number.isFinite(point.x) ||
+                !Number.isFinite(point.y) ||
+                point.x < 0 ||
+                point.y < 0 ||
+                point.x >= width ||
+                point.y >= height)
+                fail('Reference river coordinates must lie inside the raster.');
+    }
+}
+/** Four cardinal directions, with opposite directions paired. No wrapping across map edges. */
+function neighbor(pixel, direction, width, height) {
+    if (direction === 1)
+        return pixel % width > 0 ? pixel - 1 : -1;
+    if (direction === 2)
+        return pixel % width < width - 1 ? pixel + 1 : -1;
+    if (direction === 3)
+        return pixel >= width ? pixel - width : -1;
+    return pixel < width * (height - 1) ? pixel + width : -1;
+}
+function hash(pixel, seed) {
+    let value = Math.imul(pixel ^ Math.imul(seed, 0x9e3779b1), 0x45d9f3b);
+    value = Math.imul(value ^ (value >>> 16), 0x45d9f3b);
+    return (value ^ (value >>> 16)) >>> 0;
+}
+/** A packed heap avoids millions of JS objects on full-size maps. */
+class FloodHeap {
+    #pixels;
+    #levels;
+    #seed;
+    #length = 0;
+    constructor(capacity, levels, seed) {
+        this.#pixels = new Uint32Array(capacity);
+        this.#levels = levels;
+        this.#seed = seed;
+    }
+    get length() {
+        return this.#length;
+    }
+    #before(left, right) {
+        const level = this.#levels[left] - this.#levels[right];
+        if (level !== 0)
+            return level < 0;
+        const order = hash(left, this.#seed) - hash(right, this.#seed);
+        return order < 0 || (order === 0 && left < right);
+    }
+    push(pixel) {
+        let index = this.#length++;
+        while (index > 0) {
+            const parent = (index - 1) >>> 1;
+            if (!this.#before(pixel, this.#pixels[parent]))
+                break;
+            this.#pixels[index] = this.#pixels[parent];
+            index = parent;
+        }
+        this.#pixels[index] = pixel;
+    }
+    pop() {
+        const first = this.#pixels[0];
+        const last = this.#pixels[--this.#length];
+        if (this.#length === 0)
+            return first;
+        let index = 0;
+        while (index * 2 + 1 < this.#length) {
+            let child = index * 2 + 1;
+            if (child + 1 < this.#length && this.#before(this.#pixels[child + 1], this.#pixels[child]))
+                child += 1;
+            if (!this.#before(this.#pixels[child], last))
+                break;
+            this.#pixels[index] = this.#pixels[child];
+            index = child;
+        }
+        this.#pixels[index] = last;
+        return first;
+    }
+}
+/**
+ * Priority-flood assigns each land pixel an acyclic route to sea or lake. Flood levels are
+ * temporary routing costs: only accepted channels alter the returned elevation, by lowering
+ * downstream pixels. This preserves downhill flow after any monotone heightmap quantization.
+ * Rivers are disjoint, cardinal, one-pixel paths; width is encoded by palette index, not dilation.
+ * Work is O(N log N), with a bounded O(N) tracing budget and packed raster storage.
+ */
+export function generateWorldDrainage(spec) {
+    validate(spec);
+    const { width, height, kind, seed } = spec;
+    const total = kind.length;
+    const elevation = Float32Array.from(spec.elevation);
+    const riverPixels = Uint8Array.from(kind, (value) => (value === 1 ? 255 : 254));
+    const warnings = [];
+    if (spec.count === 0)
+        return { riverPixels, elevation, count: 0, warnings };
+    const referenceSources = [];
+    let referenceBudget = total * 4;
+    for (const [index, line] of (spec.referenceRivers ?? []).entries()) {
+        let source = -1;
+        // Lower routing costs along hints without committing an uphill or disconnected channel.
+        for (let vertex = 1; vertex < line.length; vertex += 1) {
+            const a = line[vertex - 1];
+            const b = line[vertex];
+            let x = Math.floor(a.x);
+            let y = Math.floor(a.y);
+            const endX = Math.floor(b.x);
+            const endY = Math.floor(b.y);
+            const dx = Math.abs(endX - x);
+            const dy = Math.abs(endY - y);
+            let error = dx - dy;
+            while (referenceBudget-- > 0) {
+                const pixel = y * width + x;
+                if (kind[pixel] === 1) {
+                    elevation[pixel] = spec.elevation[pixel] * 0.85;
+                    if (source < 0 || spec.elevation[pixel] > spec.elevation[source])
+                        source = pixel;
+                }
+                if (x === endX && y === endY)
+                    break;
+                const twice = error * 2;
+                if (twice > -dy) {
+                    error -= dy;
+                    x += x < endX ? 1 : -1;
+                }
+                if (twice < dx) {
+                    error += dx;
+                    y += y < endY ? 1 : -1;
+                }
+            }
+        }
+        if (source >= 0)
+            referenceSources.push(source);
+        warnings.push(source >= 0
+            ? `Reference river ${index + 1} is a drainage hint; its route may divert to a safe outlet.`
+            : `Reference river ${index + 1} contains no land; generated drainage will be used.`);
+    }
+    if (referenceBudget <= 0)
+        warnings.push('Reference river rasterization exceeded its bounded budget; remaining hints were omitted.');
+    // Direction zero means undiscovered; every assigned direction points to an earlier visit.
+    const downstream = new Uint8Array(total);
+    const heap = new FloodHeap(total, elevation, seed);
+    for (let pixel = 0; pixel < total; pixel += 1) {
+        if (kind[pixel] !== 1)
+            continue;
+        for (let direction = 1; direction <= 4; direction += 1) {
+            const next = neighbor(pixel, direction, width, height);
+            if (next < 0 || kind[next] === 1)
+                continue;
+            downstream[pixel] = direction;
+            heap.push(pixel);
+            break;
+        }
+    }
+    if (heap.length === 0) {
+        elevation.set(spec.elevation);
+        warnings.push('No river can be generated because the land has no sea or lake outlet.');
+        return { riverPixels, elevation, count: 0, warnings };
+    }
+    while (heap.length > 0) {
+        const pixel = heap.pop();
+        for (let direction = 1; direction <= 4; direction += 1) {
+            const next = neighbor(pixel, direction, width, height);
+            if (next < 0 || kind[next] !== 1 || downstream[next] !== 0)
+                continue;
+            downstream[next] = direction % 2 === 1 ? direction + 1 : direction - 1;
+            elevation[next] = Math.max(elevation[next], elevation[pixel]);
+            heap.push(next);
+        }
+    }
+    elevation.set(spec.elevation);
+    // Sample across the whole raster, then prefer higher headwaters. Never sort all N pixels.
+    const candidates = new Set(referenceSources);
+    const sampleCount = Math.min(total, Math.max(256, Math.min(65_536, spec.count * 128)));
+    for (let sample = 0; sample < sampleCount; sample += 1) {
+        const pixel = Math.floor((hash(sample, seed ^ 0x9e3779b9) / 4294967296) * total);
+        if (kind[pixel] === 1 && downstream[pixel] !== 0)
+            candidates.add(pixel);
+    }
+    const hinted = new Set(referenceSources);
+    const sources = [...candidates].sort((a, b) => Number(hinted.has(b)) - Number(hinted.has(a)) ||
+        elevation[b] - elevation[a] ||
+        hash(a, seed) - hash(b, seed) ||
+        a - b);
+    const blocked = new Uint8Array(total);
+    const minLength = Math.max(3, Math.min(12, Math.floor(Math.min(width, height) / 4)));
+    const maxPathSteps = Math.min(total, 65_536, 8 * (width + height));
+    let budget = total * 4;
+    let count = 0;
+    for (const source of sources) {
+        if (count >= spec.count || budget <= 0)
+            break;
+        if (blocked[source] !== 0 || downstream[source] === 0)
+            continue;
+        const path = [];
+        const positions = new Map();
+        let current = source;
+        let reachedWater = false;
+        let collided = false;
+        for (let step = 0; step < maxPathSteps && budget-- > 0; step += 1) {
+            if (kind[current] !== 1) {
+                reachedWater = true;
+                break;
+            }
+            if (blocked[current] !== 0 || downstream[current] === 0) {
+                collided = blocked[current] !== 0;
+                break;
+            }
+            // Remove chords as a node arrives: the final path never touches itself or forms a 2x2.
+            let predecessor = path.length - 1;
+            for (let direction = 1; direction <= 4; direction += 1) {
+                const around = neighbor(current, direction, width, height);
+                const position = positions.get(around);
+                if (position !== undefined)
+                    predecessor = Math.min(predecessor, position);
+            }
+            while (path.length > predecessor + 1)
+                positions.delete(path.pop());
+            positions.set(current, path.length);
+            path.push(current);
+            current = neighbor(current, downstream[current], width, height);
+        }
+        if (collided)
+            for (const pixel of path)
+                blocked[pixel] = 1;
+        if (!reachedWater || path.length < minLength)
+            continue;
+        let level = elevation[source];
+        for (const [position, pixel] of path.entries()) {
+            level = Math.min(level, elevation[pixel]);
+            elevation[pixel] = level;
+            riverPixels[pixel] =
+                position === 0 ? 0 : 3 + Math.min(8, Math.floor((position * 9) / path.length));
+            blocked[pixel] = 1;
+            for (let direction = 1; direction <= 4; direction += 1) {
+                const around = neighbor(pixel, direction, width, height);
+                if (around >= 0)
+                    blocked[around] = 1;
+            }
+        }
+        count += 1;
+    }
+    if (count < spec.count)
+        warnings.push(`Generated ${count} of ${spec.count} rivers; remaining routes lack a clear disjoint outlet.`);
+    return { riverPixels, elevation, count, warnings };
+}

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

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { reconcileManagedOutputs } from '../core/managed-outputs.js';
+export const WORLD_OUTPUT_MANIFEST = '.hoi4-agent-world.json';
+export function reconcileWorldOutputs(sources, proposed, operationId, mapRoot, stateRoots, localisationRoots) {
+    const mapFiles = new Set([
+        'provinces.bmp',
+        'definition.csv',
+        'default.map',
+        'continent.txt',
+        'adjacencies.csv',
+        'adjacency_rules.txt',
+        'positions.txt',
+        'ambient_object.txt',
+        'heightmap.bmp',
+        'terrain.bmp',
+        'rivers.bmp',
+        'trees.bmp',
+        'cities.bmp',
+        'world_normal.bmp',
+        'buildings.txt',
+        'unitstacks.txt',
+        'weatherpositions.txt',
+        'supply_nodes.txt',
+        'railways.txt',
+    ]);
+    const permitsPath = (name) => {
+        const dir = path.posix.dirname(name), file = path.posix.basename(name);
+        return ((dir === mapRoot && mapFiles.has(file)) ||
+            (dir === `${mapRoot}/terrain` && /^colormap_[a-z0-9_]+\.dds$/u.test(file)) ||
+            (dir === `${mapRoot}/strategicregions` && /^\d+.*\.txt$/u.test(file)) ||
+            (stateRoots.includes(dir) && /^\d+.*\.txt$/u.test(file)) ||
+            (['common/countries', 'history/countries'].includes(dir) &&
+                /^[A-Z][A-Z0-9]{2} - [^/]+\.txt$/u.test(file)) ||
+            (dir === 'history/units' && /^[A-Z][A-Z0-9]{2}_world\.txt$/u.test(file)) ||
+            (['gfx/flags', 'gfx/flags/medium', 'gfx/flags/small'].includes(dir) &&
+                /^[A-Z][A-Z0-9]{2}\.tga$/u.test(file)) ||
+            [
+                'common/countries/colors.txt',
+                'common/country_tags/zz_world_countries.txt',
+                'common/bookmarks/world.txt',
+                'common/on_actions/world.txt',
+                'common/ai_areas/world.txt',
+                'common/ai_strategy_plans/world.txt',
+            ].includes(name) ||
+            localisationRoots.some((root) => name === `${root}/english/world_l_english.yml` ||
+                name === `${root}/replace/world_l_english.yml`));
+    };
+    return reconcileManagedOutputs({
+        manifestPath: WORLD_OUTPUT_MANIFEST,
+        sources,
+        proposed,
+        operationId,
+        permitsPath,
+    });
+}

package/dist/hoi4_agent_tools/map/world-preview-style.js

@@ -0,0 +1,157 @@
+import { compareCodeUnits, sha256Bytes } from '../core/canonical.js';
+import { hasBlockingDiagnostics } from '../core/diagnostics.js';
+import { assignments, childBlocks, firstScalar, parseClausewitz, } from '../core/source/index.js';
+import { BmpImage } from './bmp.js';
+import { defaultMapSelectorValue } from './model.js';
+const PREVIEW_STYLE_FILE_BYTES = 65_536;
+const PREVIEW_STYLE_TOTAL_BYTES = 4_194_304;
+const PREVIEW_STYLE_FILE_COUNT = 512;
+function normalized(value) {
+    return value.replaceAll('\\', '/').replace(/^\.\//u, '').toLowerCase();
+}
+/** Preview interpretation stays bounded and uses only authorized active source bytes. */
+class PreviewStyleParser {
+    #bytes = 0;
+    #files = 0;
+    parse(file) {
+        if (file.bytes.length > PREVIEW_STYLE_FILE_BYTES ||
+            this.#bytes + file.bytes.length > PREVIEW_STYLE_TOTAL_BYTES ||
+            this.#files >= PREVIEW_STYLE_FILE_COUNT)
+            return undefined;
+        this.#bytes += file.bytes.length;
+        this.#files += 1;
+        const document = parseClausewitz(file.bytes, file.displayPath);
+        return hasBlockingDiagnostics(document.diagnostics) ? undefined : document;
+    }
+}
+/** Resolve the generated/active tag binding and its byte RGB color through the shared parser. */
+export function previewPoliticalPalette(index, owners) {
+    const parser = new PreviewStyleParser();
+    const bindings = new Map();
+    for (const file of index.activeFiles.all) {
+        if (!/^common\/country_tags\/[^/]+\.txt$/u.test(normalized(file.relativePath)))
+            continue;
+        const document = parser.parse(file);
+        if (document === undefined)
+            continue;
+        for (const entry of assignments(document.root)) {
+            if (!owners.has(entry.key.value) ||
+                entry.operator.text !== '=' ||
+                entry.value.type !== 'scalar')
+                continue;
+            const path = normalized(entry.value.value);
+            if (/^countries\/(?:[^/:]+\/)*[^/:]+\.txt$/u.test(path) &&
+                !path.split('/').some((segment) => segment === '.' || segment === '..'))
+                bindings.set(entry.key.value, `common/${path}`);
+            else
+                bindings.delete(entry.key.value);
+        }
+    }
+    const colors = new Map();
+    const sources = new Map();
+    const fallbackTags = [];
+    for (const tag of [...owners].sort(compareCodeUnits)) {
+        const binding = bindings.get(tag);
+        const file = binding === undefined ? undefined : index.activeFiles.byRelativePath.get(binding);
+        const document = file === undefined ? undefined : parser.parse(file);
+        const blocks = document === undefined ? [] : childBlocks(document.root, 'color');
+        const values = blocks.length === 1 &&
+            document !== undefined &&
+            assignments(document.root, 'color').length === 1
+            ? blocks[0].entries.flatMap((entry) => entry.type === 'scalar' && /^\d+$/u.test(entry.value)
+                ? [Number(entry.value)]
+                : [Number.NaN])
+            : [];
+        if (values.length === 3 &&
+            values.every((value) => Number.isInteger(value) && value >= 0 && value <= 255) &&
+            file !== undefined) {
+            colors.set(tag, [values[0], values[1], values[2]]);
+            sources.set(tag, file.displayPath);
+        }
+        else {
+            const digest = sha256Bytes(tag);
+            colors.set(tag, [0, 2, 4].map((offset) => 72 + (Number.parseInt(digest.slice(offset, offset + 2), 16) % 144)));
+            fallbackTags.push(tag);
+        }
+    }
+    return { colors, sources, fallbackTags };
+}
+/** Read graphical terrain and city footprints without changing combat province definitions. */
+export function previewGraphicalTerrain(index) {
+    const parser = new PreviewStyleParser();
+    const types = new Map();
+    const snowIndices = new Set();
+    const sourceFiles = [];
+    for (const file of index.activeFiles.all) {
+        if (!/^common\/terrain\/[^/]+\.txt$/u.test(normalized(file.relativePath)))
+            continue;
+        const document = parser.parse(file);
+        if (document === undefined)
+            continue;
+        sourceFiles.push(file.displayPath);
+        for (const block of childBlocks(document.root, 'terrain'))
+            for (const entry of assignments(block)) {
+                if (entry.value.type !== 'block')
+                    continue;
+                const type = firstScalar(entry.value, 'type')?.value;
+                const colorBlocks = childBlocks(entry.value, 'color');
+                if (type === undefined || colorBlocks.length !== 1)
+                    continue;
+                const values = colorBlocks[0].entries.flatMap((value) => value.type === 'scalar' && /^\d+$/u.test(value.value)
+                    ? [Number(value.value)]
+                    : [Number.NaN]);
+                if (!values.length ||
+                    values.some((value) => !Number.isInteger(value) || value < 0 || value > 255))
+                    continue;
+                const snow = firstScalar(entry.value, 'perm_snow')?.value === 'yes';
+                for (const paletteIndex of values) {
+                    types.set(paletteIndex, type);
+                    if (snow)
+                        snowIndices.add(paletteIndex);
+                    else
+                        snowIndices.delete(paletteIndex);
+                }
+            }
+    }
+    if (sourceFiles.length === 0)
+        for (const [paletteIndex, type] of [
+            [0, 'plains'],
+            [1, 'forest'],
+            [17, 'hills'],
+            [3, 'desert'],
+            [6, 'mountain'],
+            [9, 'marsh'],
+            [13, 'urban'],
+            [14, 'lakes'],
+            [15, 'ocean'],
+            [21, 'jungle'],
+        ])
+            types.set(paletteIndex, type);
+    // Generated worlds retain the vanilla mountain/snow-plain slots without installed definitions.
+    for (const paletteIndex of [16, 19])
+        if (!types.has(paletteIndex))
+            snowIndices.add(paletteIndex);
+    const bitmap = (name) => {
+        if (index.raster === undefined)
+            return undefined;
+        const selector = defaultMapSelectorValue(index.defaultMapFile, name, `${name}.bmp`);
+        const file = index.sourceRoots.map
+            .map((root) => index.activeFiles.byRelativePath.get(normalized(`${root}/${selector}`)))
+            .find((value) => value !== undefined);
+        if (file === undefined)
+            return undefined;
+        try {
+            const image = BmpImage.decode(file.bytes);
+            if (image.bitsPerPixel !== 8 ||
+                image.width !== index.raster.width ||
+                image.height !== index.raster.height)
+                return undefined;
+            sourceFiles.push(file.displayPath);
+            return image;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return { terrain: bitmap('terrain'), cities: bitmap('cities'), types, snowIndices, sourceFiles };
+}