hoi4-agent-tools 4.4.0 → 4.6.0

package/dist/hoi4_agent_tools/map/gameplay/ports.js

@@ -0,0 +1,244 @@
+/**
+ * Ports and naval bases from the shape of the coast (ADR 0063). Every coastal province gets a
+ * harbour score from how sheltered its coast is (water share in a small and a large disc around
+ * the coast point), river mouths, the depth class of the sea it faces, the length of its coast
+ * and the port and city sites of the model. A state gets a port where the score is high, where a
+ * port site stands, or where its country has no other port on that coast.
+ */
+import { LAND, SEA, centerOf, distanceOnMap, pairKey } from './facts.js';
+import { SITE_WEIGHT } from './sites.js';
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+const DEPTH_SCORE = { shelf: 1, open: 0.6, abyss: 0.3 };
+/** Share of non-land samples in the disc of `radius` pixels around a point. */
+function waterShare(base, cx, cy, radius) {
+    const { width, height } = base.input;
+    const kind = base.input.provinces.kind;
+    const step = Math.max(1, Math.round(radius / 7));
+    let water = 0;
+    let total = 0;
+    for (let dy = -radius; dy <= radius; dy += step)
+        for (let dx = -radius; dx <= radius; dx += step) {
+            if (dx * dx + dy * dy > radius * radius)
+                continue;
+            const y = Math.round(cy + dy);
+            if (y < 0 || y >= height)
+                continue;
+            const x = ((Math.round(cx + dx) % width) + width) % width;
+            total += 1;
+            if (kind[base.view.pixel[y * width + x]] !== LAND)
+                water += 1;
+        }
+    return total === 0 ? 0.5 : water / total;
+}
+export function harbourScores(base, metrics, sites) {
+    const { width, geography, provinces } = base.input;
+    const kind = provinces.kind;
+    const count = base.view.count;
+    const small = Math.max(5, Math.round(0.006 * width));
+    const large = Math.max(14, Math.round(0.02 * width));
+    // Site strength near each province: in the province itself, or one province away.
+    const siteHere = new Float64Array(count);
+    for (const { site, province } of sites) {
+        if (province === undefined)
+            continue;
+        const weight = site.siteKind === 'port'
+            ? 1
+            : site.siteKind === 'capital' || site.siteKind === 'city'
+                ? 0.5
+                : SITE_WEIGHT[site.siteKind] * 0.3;
+        siteHere[province] = Math.max(siteHere[province], weight * (0.5 + site.importance / 10));
+    }
+    const out = new Map();
+    for (let id = 0; id < count; id += 1) {
+        if (kind[id] !== LAND)
+            continue;
+        let sea = -1;
+        let coast = 0;
+        let stat;
+        for (const other of [...provinces.neighbors[id]].sort((a, b) => a - b)) {
+            if (kind[other] !== SEA)
+                continue;
+            const candidate = base.borders.get(pairKey(id, other, count));
+            if (candidate !== undefined && candidate.count > coast) {
+                coast = candidate.count;
+                sea = other;
+                stat = candidate;
+            }
+        }
+        if (sea < 0 || stat === undefined)
+            continue;
+        let totalCoast = 0;
+        for (const other of provinces.neighbors[id])
+            if (kind[other] === SEA)
+                totalCoast += base.borders.get(pairKey(id, other, count))?.count ?? 0;
+        const cx = stat.sumX / stat.count;
+        const cy = stat.sumY / stat.count;
+        const w1 = waterShare(base, cx, cy, small);
+        const w2 = waterShare(base, cx, cy, large);
+        const concavity = clamp01((0.58 - w1) / 0.3);
+        const shelter = clamp01((0.6 - w2) / 0.35);
+        const mouth = clamp01(metrics.mouthWidth[id] / 11);
+        const seaFeature = base.features.sea[sea];
+        const lakeFeature = base.features.lake[sea];
+        const depthClass = lakeFeature >= 0 && seaFeature < 0
+            ? geography.lakes[lakeFeature].depthClass
+            : seaFeature >= 0
+                ? geography.seas[seaFeature].depthClass
+                : 'open';
+        const depth = DEPTH_SCORE[depthClass] ?? 0.6;
+        let near = siteHere[id];
+        for (const other of provinces.neighbors[id])
+            if (kind[other] === LAND)
+                near = Math.max(near, siteHere[other] * 0.6);
+        const contact = clamp01(totalCoast / Math.max(6, 2 * Math.sqrt(provinces.size[id])));
+        const score = clamp01(0.28 * concavity + 0.2 * shelter + 0.14 * mouth + 0.1 * depth + 0.18 * near + 0.1 * contact);
+        out.set(id, {
+            province: id,
+            sea,
+            score,
+            concavity,
+            shelter,
+            mouth,
+            depth,
+            sites: near,
+            coast: totalCoast,
+        });
+    }
+    return out;
+}
+/** The share of coastal states that get a port by score alone; port sites and capitals add more. */
+export const PORT_STATE_SHARE = 0.45;
+export function planPorts(base, scores, sites, states) {
+    const { provinces, geography } = base.input;
+    const kind = provinces.kind;
+    const ports = new Map();
+    const dockyards = new Set();
+    const notes = [];
+    const stateOfProvince = new Map();
+    for (const state of states)
+        for (const id of state.provinces)
+            stateOfProvince.set(id, state);
+    // Port sites name their province directly; one outside the coast cannot hold a port.
+    const portSiteOf = new Map();
+    for (const located of sites) {
+        const { site, province } = located;
+        if (site.siteKind !== 'port' || province === undefined)
+            continue;
+        if (site.lakeId !== undefined) {
+            const lake = geography.get('lake', site.lakeId);
+            if (lake !== undefined && lake.gameplay !== 'inland-sea') {
+                notes.push({
+                    code: 'MAP_PORT_LAKE_UNSUPPORTED',
+                    severity: 'warning',
+                    message: `Port ${site.id} stands on lake ${lake.id}, which is a decorative lake: the engine gives a lake province no fleet and no naval base. Set the lake's gameplay to "inland-sea" to give it ports, or make the site a city`,
+                    details: { siteId: site.id, lakeId: lake.id },
+                });
+                continue;
+            }
+        }
+        // A site on the shore may fall in a province just inland; the nearest harbour within a few
+        // percent of the map width then holds the port.
+        let target = province;
+        if (!scores.has(target)) {
+            const x = site.at.x * base.input.width;
+            const y = site.at.y * base.input.height;
+            let nearest = 0.03 * base.input.width;
+            for (const candidate of scores.keys()) {
+                const centre = centerOf(provinces, candidate);
+                const d = distanceOnMap(centre.x, centre.y, x, y, base.input.width);
+                if (d < nearest) {
+                    nearest = d;
+                    target = candidate;
+                }
+            }
+        }
+        if (!scores.has(target)) {
+            notes.push({
+                code: 'MAP_PORT_SITE_NOT_COASTAL',
+                severity: 'warning',
+                message: `Port site ${site.id} falls in an inland province (${province + 1}); no naval base was placed. Move the site to the coast`,
+                details: { siteId: site.id, province: province + 1 },
+            });
+            continue;
+        }
+        portSiteOf.set(target, Math.max(portSiteOf.get(target) ?? 0, site.importance));
+    }
+    const levelOf = (score, capital, importance) => Math.max(1, Math.min(6, 1 + Math.round(3 * score.score) + Math.max(0, importance - 2) + (capital ? 1 : 0)));
+    // States ranked by their best harbour.
+    const best = new Map();
+    for (const state of states) {
+        let top;
+        for (const id of state.provinces) {
+            const score = scores.get(id);
+            if (score === undefined)
+                continue;
+            if (top === undefined ||
+                score.score > top.score ||
+                (score.score === top.score && id < top.province))
+                top = score;
+        }
+        if (top !== undefined)
+            best.set(state.id, top);
+    }
+    const ranked = [...best.values()].map((score) => score.score).sort((a, b) => b - a);
+    const cutoff = ranked.length === 0
+        ? 1
+        : ranked[Math.min(ranked.length - 1, Math.floor(PORT_STATE_SHARE * ranked.length))];
+    const assign = (state, score, reason, importance) => {
+        const level = levelOf(score, state.capital, importance);
+        const previous = ports.get(score.province);
+        if (previous !== undefined && previous.level >= level)
+            return;
+        ports.set(score.province, { province: score.province, level, score: score.score, reason });
+        if (level >= 3 || state.capital)
+            dockyards.add(state.id);
+    };
+    for (const state of states) {
+        const sited = state.provinces
+            .filter((id) => portSiteOf.has(id))
+            .sort((a, b) => portSiteOf.get(b) - portSiteOf.get(a) || a - b);
+        for (const id of sited)
+            assign(state, scores.get(id), 'site', portSiteOf.get(id));
+        const top = best.get(state.id);
+        if (top === undefined || sited.length > 0)
+            continue;
+        if (state.capital)
+            assign(state, top, 'capital', 0);
+        else if (top.score >= cutoff && top.score > 0.25)
+            assign(state, top, 'score', 0);
+    }
+    // Every coastal territory of a country keeps at least one port.
+    const seen = new Set();
+    for (const state of states) {
+        for (const start of state.provinces) {
+            if (seen.has(start) || kind[start] !== LAND)
+                continue;
+            const queue = [start];
+            seen.add(start);
+            let hasPort = false;
+            let top;
+            for (const id of queue) {
+                if (ports.has(id))
+                    hasPort = true;
+                const score = scores.get(id);
+                if (score !== undefined && (top === undefined || score.score > top.score))
+                    top = score;
+                for (const next of provinces.neighbors[id])
+                    if (!seen.has(next) &&
+                        kind[next] === LAND &&
+                        stateOfProvince.get(next)?.owner === state.owner) {
+                        seen.add(next);
+                        queue.push(next);
+                    }
+            }
+            if (!hasPort && top !== undefined) {
+                const owner = stateOfProvince.get(top.province);
+                if (owner !== undefined)
+                    assign(owner, top, 'coast-floor', 0);
+            }
+        }
+    }
+    return { ports, dockyards, notes };
+}

package/dist/hoi4_agent_tools/map/gameplay/prepare.js

@@ -0,0 +1,27 @@
+import { planCrossings } from './crossings.js';
+import { buildBorderTable, provinceFeatures, provinceViewOf, } from './facts.js';
+export function prepareGameplay(input) {
+    const view = provinceViewOf(input.provinces, input.width, input.height);
+    const features = provinceFeatures({
+        geography: input.geography,
+        view,
+        kind: input.provinces.kind,
+    });
+    const borders = buildBorderTable({ view, heights: input.heights, rivers: input.riverBitmap });
+    const crossings = planCrossings({
+        width: input.width,
+        height: input.height,
+        geography: input.geography,
+        view,
+        kind: input.provinces.kind,
+        neighbors: input.provinces.neighbors,
+        center: input.provinces,
+        features,
+        borders,
+        autoStraits: input.autoStraits,
+        inlandSeas: input.inlandSeas,
+        impassableLimit: input.impassableLimit,
+        signal: input.signal,
+    });
+    return { input, view, features, borders, crossings, notes: [...crossings.notes] };
+}

package/dist/hoi4_agent_tools/map/gameplay/rail-cost.js

@@ -0,0 +1,77 @@
+/**
+ * The cost of laying a railway between two neighbouring provinces (ADR 0063). A railway follows
+ * the cheapest route through the land, so the cost has to say what is hard to build over: distance
+ * between the province centres, the ground (mountain, marsh and jungle cost more), the climb
+ * across the border (a pass is a low point of the ridge, so crossing it is cheap and crossing the
+ * ridge elsewhere is not), a river on the border, and a model road, which makes the way easier.
+ */
+import { nearestOnPolyline } from '../geography/index.js';
+import { LAND, centerOf, distanceOnMap, pairKey } from './facts.js';
+/** Cost per unit of distance by the ground of the province entered. */
+export const RAIL_TERRAIN_FACTOR = {
+    urban: 0.8,
+    plains: 1,
+    desert: 1.3,
+    forest: 1.25,
+    hills: 1.6,
+    jungle: 2,
+    marsh: 2.2,
+    mountain: 3,
+};
+/** Height units of climb that cost one step of plain ground. */
+const CLIMB_PER_STEP = 12;
+const RIVER_CROSSING_COST = 1.1;
+const GATE_DISCOUNT = 0.7;
+const ROAD_DISCOUNT = [1, 0.85, 0.72, 0.6];
+export function buildRailCost(base, metrics, terrain, trunk) {
+    const { geography, provinces, width, height } = base.input;
+    const count = base.view.count;
+    let landPixels = 0;
+    let landCount = 0;
+    for (let id = 0; id < count; id += 1)
+        if (provinces.kind[id] === LAND) {
+            landPixels += provinces.size[id];
+            landCount += 1;
+        }
+    const spacing = Math.max(8, Math.sqrt(landPixels / Math.max(1, landCount)));
+    const gates = new Set();
+    for (const [a, b] of base.crossings.gates)
+        gates.add(pairKey(a, b, count));
+    const cache = new Map();
+    const edge = (a, b) => {
+        const key = pairKey(a, b, count);
+        const known = cache.get(key);
+        if (known !== undefined)
+            return known;
+        const ca = centerOf(provinces, a);
+        const cb = centerOf(provinces, b);
+        const distance = distanceOnMap(ca.x, ca.y, cb.x, cb.y, width) / spacing;
+        const ground = Math.max(RAIL_TERRAIN_FACTOR[terrain.get(a) ?? 'plains'] ?? 1, RAIL_TERRAIN_FACTOR[terrain.get(b) ?? 'plains'] ?? 1);
+        let cost = distance * ground;
+        const stat = base.borders.get(key);
+        const ha = metrics.meanHeight[a];
+        const hb = metrics.meanHeight[b];
+        cost += Math.abs(ha - hb) / CLIMB_PER_STEP;
+        if (stat !== undefined && stat.count > 0) {
+            const crest = stat.top / stat.count;
+            cost += Math.max(0, crest - Math.max(ha, hb)) / CLIMB_PER_STEP;
+            cost += RIVER_CROSSING_COST * Math.min(1, (stat.rivers / stat.count) * 2);
+            if (gates.has(key))
+                cost *= GATE_DISCOUNT;
+            for (const road of geography.roads) {
+                const near = nearestOnPolyline(road.path, geography.frame, stat.sumX / stat.count / width, stat.sumY / stat.count / height);
+                if (near.distance <= Math.max(0.004, (1.5 * spacing) / width)) {
+                    cost *= ROAD_DISCOUNT[Math.min(3, road.importance)] ?? 0.85;
+                    break;
+                }
+            }
+        }
+        const result = Math.max(0.2, cost);
+        cache.set(key, result);
+        return result;
+    };
+    return {
+        cost: (from, to) => edge(from - 1, to - 1),
+        trunk,
+    };
+}

package/dist/hoi4_agent_tools/map/gameplay/sites.js

@@ -0,0 +1,61 @@
+import { LAND } from './facts.js';
+/** The land province at a pixel, else the nearest one within `reach` pixels. */
+export function landProvinceNear(base, x, y, reach) {
+    const { width, height } = base.input;
+    const kind = base.input.provinces.kind;
+    const pixel = base.view.pixel;
+    const px = Math.max(0, Math.min(width - 1, Math.floor(x)));
+    const py = Math.max(0, Math.min(height - 1, Math.floor(y)));
+    const here = pixel[py * width + px];
+    if (kind[here] === LAND)
+        return { province: here, moved: false };
+    for (let radius = 1; radius <= reach; radius += 1) {
+        for (let dy = -radius; dy <= radius; dy += 1) {
+            const yy = py + dy;
+            if (yy < 0 || yy >= height)
+                continue;
+            // The square ring: whole rows at the top and bottom, two cells on the rows between.
+            const step = Math.abs(dy) === radius ? 1 : 2 * radius;
+            for (let dx = -radius; dx <= radius; dx += step) {
+                const xx = (((px + dx) % width) + width) % width;
+                const candidate = pixel[yy * width + xx];
+                if (kind[candidate] === LAND)
+                    return { province: candidate, moved: true };
+            }
+        }
+    }
+    return undefined;
+}
+export function locateSites(base) {
+    const { width, height, geography } = base.input;
+    const reach = Math.max(10, Math.round(width * 0.012));
+    return geography.sites.map((site) => {
+        if (site.onWater)
+            return { site, province: undefined, moved: false };
+        const found = landProvinceNear(base, site.at.x * width, site.at.y * height, reach);
+        return {
+            site,
+            province: found?.province,
+            moved: found?.moved ?? false,
+        };
+    });
+}
+/** Sites that become victory points, and the weight each kind gives to development. */
+export const VICTORY_SITE_KINDS = new Set([
+    'capital',
+    'city',
+    'fortress',
+    'port',
+]);
+export const SITE_WEIGHT = {
+    capital: 1,
+    city: 0.9,
+    port: 0.7,
+    fortress: 0.6,
+    mine: 0.5,
+    temple: 0.4,
+    ruin: 0.2,
+    landmark: 0.1,
+};
+/** Victory points of a site by importance 1 to 5. */
+export const SITE_VICTORY_POINTS = [3, 5, 8, 12, 20];

package/dist/hoi4_agent_tools/map/geography/resolve.js

@@ -1082,16 +1082,26 @@ export function resolveGeography(model, options) {
             continue;
         const first = ends[0], second = ends[1];
         const idOf = (end) => (end.type === 'land' ? end.id : end.landId);
-        if (idOf(first) !== undefined && idOf(first) === idOf(second))
-            sink('MAP_GEOGRAPHY_STRAIT_SAME_LAND', derived ? 'warning' : 'error', `Strait ${input.id} joins ${idOf(first)} to itself; a strait separates two lands`, { featureId: input.id, land: idOf(first), derived });
-        if (first.type === 'point' && second.type === 'point') {
-            let water = false;
+        const bothPoints = first.type === 'point' && second.type === 'point';
+        let water = false;
+        if (first.type === 'point' && second.type === 'point')
             for (let step = 1; step < 32 && !water; step++) {
                 const f = step / 32;
                 if (surface(first.x + (second.x - first.x) * f, first.y + (second.y - first.y) * f)
                     .surface !== 'land')
                     water = true;
             }
+        if (idOf(first) !== undefined && idOf(first) === idOf(second)) {
+            // Two declared shore points of one land across water: a crossing between two coasts of the
+            // land, such as a bay mouth or a neck of sea (ADR 0062).
+            if (bothPoints && !derived && water)
+                sink('MAP_GEOGRAPHY_STRAIT_SAME_LAND', 'info', `Strait ${input.id} crosses water between two coasts of ${idOf(first)}`, { featureId: input.id, land: idOf(first), derived, coasts: 'same-land' });
+            else
+                sink('MAP_GEOGRAPHY_STRAIT_SAME_LAND', derived ? 'warning' : 'error', bothPoints
+                    ? `Strait ${input.id} joins ${idOf(first)} to itself across no water; a strait crosses water between two shores`
+                    : `Strait ${input.id} joins ${idOf(first)} to itself; give two shore points across the water for a crossing between two coasts of one land`, { featureId: input.id, land: idOf(first), derived });
+        }
+        if (bothPoints) {
             if (!water)
                 sink('MAP_GEOGRAPHY_STRAIT_NO_WATER', 'warning', `The straight line of strait ${input.id} crosses no water`, { featureId: input.id });
         }
@@ -1139,6 +1149,7 @@ export function resolveGeography(model, options) {
             importance: input.importance ?? GEOGRAPHY_DEFAULTS.site.importance,
             onWater,
             ...opt('country', input.country),
+            ...opt('resource', input.resource),
             ...(landId === undefined ? {} : { landId }),
             ...(regionId === undefined ? {} : { regionId }),
             ...(lakeId === undefined ? {} : { lakeId }),

package/dist/hoi4_agent_tools/map/model.js

@@ -4,7 +4,7 @@ import { SymbolIndex } from '../core/index.js';
 import { assertRenderDimensions } from '../core/render-budget.js';
 import { addMapDiagnostic, addMapDiagnostics } from './diagnostic-limit.js';
 import { ServiceError } from '../core/result.js';
-import { assignments, childBlocks, decodeSource, encodeSource, firstScalar, nodeLocation, parseClausewitz, parseLocalisation, } from '../core/source/index.js';
+import { assignments, assertSourceEncodingPreserved, childBlocks, decodeSource, encodeSource, firstScalar, nodeLocation, parseClausewitz, parseLocalisation, } from '../core/source/index.js';
 import { BmpImage, rgbKey } from './bmp.js';
 const defaultMapIndexSourceRoots = {
     map: ['map'],
@@ -119,6 +119,7 @@ export function parseTextDocument(file) {
     return { ...decoded, file, lines };
 }
 export function encodeTextDocument(document, text) {
+    assertSourceEncodingPreserved(document, document.file.displayPath);
     return encodeSource(text, document.encoding);
 }
 function lineLocation(document, line) {