hoi4-agent-tools 2.5.3 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 No unreleased changes.
 
+## 2.6.0 - 2026-08-22
+
+- Added a shared complete map catalog with resolved names, source locations, geometry, memberships, networks, positions, buildings, ports, adjacency, and localisation evidence.
+- Made map inspection return a full-map overview and a searchable, clickable HTML navigator with exact province hit testing and pixel/map coordinate lookup.
+- Added compact state and province creation defaults, rectangle province geometry, and one-call province, state, and strategic-region ID swapping with connected map-reference and standard localisation updates.
+
 ## 2.5.3 - 2026-08-22
 
 - Resolved and embedded technology icons through the complete mod, dependency, and installed-game load order, including vanilla sprites used by mod content.

package/README.md

@@ -6,7 +6,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 
 - Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
 - Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
-- Maps: inspect provinces, states, regions, adjacency, supply, and railways; render layers; create and repair exact map data.
+- Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected map data.
 - Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
 - AI and MTTH: evaluate weighted choices and timing across explicit scenarios, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
@@ -40,9 +40,9 @@ Paste the printed Codex or generic global-install entry into your MCP client, th
 | `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                     |
 | `hoi4.gui_render`           | Render GUI scenario variants, states, resolutions, hierarchy, and layout diagnostics.    |
 | `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                   |
-| `hoi4.map_inspect`          | Read map, state, province, region, supply, and railway data.                             |
-| `hoi4.map_render`           | Render map layers and overlays.                                                          |
-| `hoi4.map_rewrite`          | Create or update map data from an ordered list of exact changes.                         |
+| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.      |
+| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.   |
+| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.    |
 | `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                 |
 | `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.  |
 | `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                          |
@@ -71,7 +71,7 @@ Ask your agent in normal task language. A typical workflow is inspect, render, r
 
 - Focus trees: "Create a complete national focus tree for this route specification," or "Compact this existing tree into a balanced, readable layout." Existing trees can use a plan-free compact reflow; new trees use a complete plan. See [Focus trees](docs/focus.md).
 - Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render every value-driven version of this window and fix hidden controls, off-center button text, background alignment, clipping, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
-- Maps: "Create a state from these exact provinces," or "Inspect this state and split these provinces while keeping supply and railway references valid." See [Maps](docs/map.md).
+- Maps: "Render the whole map and find this state by name," "Create a state from these provinces," "Create a province inside this exact rectangle," or "Swap these state IDs and update connected references." See [Maps](docs/map.md).
 - Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
 - Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
 - AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).

package/dist/hoi4_agent_tools/map/catalog.js

@@ -0,0 +1,398 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { nodeLocation } from '../core/source/parser.js';
+function localisedValues(entries) {
+    return entries
+        .map(({ file, entry }) => ({
+        language: entry.language,
+        value: entry.value,
+        sourcePath: file.displayPath,
+        line: entry.line,
+        loadOrder: file.loadOrder,
+    }))
+        .sort((left, right) => compareCodeUnits(left.language, right.language) ||
+        left.loadOrder - right.loadOrder ||
+        compareCodeUnits(left.sourcePath, right.sourcePath) ||
+        left.line - right.line)
+        .map(({ loadOrder: _loadOrder, ...value }) => value);
+}
+function resolvedName(entriesByKey, keys, fallback) {
+    for (const key of keys) {
+        const values = localisedValues(entriesByKey.get(key) ?? []);
+        if (values.length === 0)
+            continue;
+        const english = values.filter(({ language }) => language === 'l_english').at(-1);
+        return { key, displayName: english?.value ?? values.at(-1)?.value ?? fallback, values };
+    }
+    const key = keys[0] ?? fallback;
+    return { key, displayName: fallback, values: [] };
+}
+function aggregateGeometry(index, provinceIds) {
+    const geometries = provinceIds.flatMap((id) => {
+        const geometry = index.raster?.geometry.get(id);
+        return geometry === undefined ? [] : [geometry];
+    });
+    if (geometries.length === 0 || index.raster === undefined)
+        return null;
+    const pixelCount = geometries.reduce((total, { pixelCount: count }) => total + count, 0);
+    if (pixelCount <= 0)
+        return null;
+    const centerX = geometries.reduce((total, geometry) => total + geometry.centerX * geometry.pixelCount, 0) /
+        pixelCount;
+    const centerY = geometries.reduce((total, geometry) => total + geometry.centerY * geometry.pixelCount, 0) /
+        pixelCount;
+    return {
+        pixelCount,
+        minX: geometries.reduce((value, geometry) => Math.min(value, geometry.minX), Infinity),
+        minY: geometries.reduce((value, geometry) => Math.min(value, geometry.minY), Infinity),
+        maxX: geometries.reduce((value, geometry) => Math.max(value, geometry.maxX), -Infinity),
+        maxY: geometries.reduce((value, geometry) => Math.max(value, geometry.maxY), -Infinity),
+        centerX,
+        centerY,
+        mapX: centerX,
+        mapZ: index.raster.height - 1 - centerY,
+    };
+}
+function sortedObject(values) {
+    return Object.fromEntries([...values].sort(([left], [right]) => compareCodeUnits(left, right)));
+}
+export function buildMapCatalog(index) {
+    const raster = index.raster;
+    const width = raster?.width ?? 0;
+    const height = raster?.height ?? 0;
+    const localisationEntriesByKey = new Map();
+    for (const entry of index.localisationEntries) {
+        const values = localisationEntriesByKey.get(entry.entry.key) ?? [];
+        values.push(entry);
+        localisationEntriesByKey.set(entry.entry.key, values);
+    }
+    const portsByProvince = new Map(index.ports.map((port) => [port.provinceId, port]));
+    const supplyNodeLevelsByProvince = new Map();
+    for (const node of index.supplyNodes) {
+        const levels = supplyNodeLevelsByProvince.get(node.provinceId) ?? [];
+        levels.push(node.level);
+        supplyNodeLevelsByProvince.set(node.provinceId, levels);
+    }
+    const buildingPositionsByProvince = new Map();
+    for (const [ordinal, position] of index.buildingPositions.entries()) {
+        const provinceId = index.provinceAtMapCoordinate(position.x, position.z);
+        if (provinceId === undefined)
+            continue;
+        const ordinals = buildingPositionsByProvince.get(provinceId) ?? [];
+        ordinals.push(ordinal);
+        buildingPositionsByProvince.set(provinceId, ordinals);
+    }
+    const unitPositionsByProvince = new Map();
+    for (const [ordinal, position] of index.unitPositions.entries()) {
+        const ordinals = unitPositionsByProvince.get(position.provinceId) ?? [];
+        ordinals.push(ordinal);
+        unitPositionsByProvince.set(position.provinceId, ordinals);
+    }
+    const railwayOrdinalsByProvince = new Map();
+    for (const [ordinal, railway] of index.railways.entries()) {
+        for (const provinceId of new Set(railway.provinces)) {
+            const ordinals = railwayOrdinalsByProvince.get(provinceId) ?? [];
+            ordinals.push(ordinal);
+            railwayOrdinalsByProvince.set(provinceId, ordinals);
+        }
+    }
+    const specialAdjacencyOrdinalsByProvince = new Map();
+    for (const [ordinal, adjacency] of index.adjacencies.entries()) {
+        for (const provinceId of new Set([adjacency.from, adjacency.to, adjacency.through])) {
+            if (provinceId < 0)
+                continue;
+            const ordinals = specialAdjacencyOrdinalsByProvince.get(provinceId) ?? [];
+            ordinals.push(ordinal);
+            specialAdjacencyOrdinalsByProvince.set(provinceId, ordinals);
+        }
+    }
+    const provinces = [...index.definitions]
+        .sort((left, right) => left.id - right.id)
+        .map((definition) => {
+        const id = definition.id;
+        const port = portsByProvince.get(id);
+        return {
+            kind: 'province',
+            id,
+            name: resolvedName(localisationEntriesByKey, [`PROV${id}`, `VICTORY_POINTS_${id}`], `Province ${id}`),
+            definition: {
+                color: definition.color,
+                type: definition.type,
+                coastal: definition.coastal,
+                terrain: definition.terrain,
+                continent: definition.continent,
+                sourcePath: definition.document.file.displayPath,
+                line: definition.line,
+            },
+            geometry: aggregateGeometry(index, [id]),
+            stateIds: index.stateForProvince(id).map(({ id: stateId }) => stateId),
+            regionIds: index.regionForProvince(id).map(({ id: regionId }) => regionId),
+            neighborProvinceIds: [...(raster?.adjacency.get(id) ?? [])].sort((a, b) => a - b),
+            victoryPoints: index.victoryPointsByProvince
+                .get(id)
+                ?.map(({ stateId, value }) => ({ stateId, value })) ?? [],
+            provinceBuildings: index.provinceBuildingsByProvince.get(id)?.map(({ stateId, buildings }) => ({
+                stateId,
+                buildings: sortedObject(buildings),
+            })) ?? [],
+            port: port === undefined
+                ? null
+                : {
+                    stateId: port.stateId,
+                    level: port.level,
+                    coastal: port.coastal,
+                    adjacentSeaProvinceIds: [...port.adjacentSeaProvinceIds],
+                },
+            supplyNodeLevels: supplyNodeLevelsByProvince.get(id) ?? [],
+            railwayOrdinals: railwayOrdinalsByProvince.get(id) ?? [],
+            specialAdjacencyOrdinals: specialAdjacencyOrdinalsByProvince.get(id) ?? [],
+            buildingPositionOrdinals: buildingPositionsByProvince.get(id) ?? [],
+            unitPositionOrdinals: unitPositionsByProvince.get(id) ?? [],
+        };
+    });
+    const states = [...index.states]
+        .sort((left, right) => left.id - right.id)
+        .map((state) => ({
+        kind: 'state',
+        id: state.id,
+        name: resolvedName(localisationEntriesByKey, [state.name], state.name),
+        geometry: aggregateGeometry(index, state.provinces),
+        capital: state.capital ?? null,
+        manpower: state.manpower,
+        category: state.category,
+        provinceIds: [...state.provinces].sort((a, b) => a - b),
+        regionIds: [
+            ...new Set(state.provinces.flatMap((provinceId) => index.regionForProvince(provinceId).map(({ id }) => id))),
+        ].sort((a, b) => a - b),
+        resources: sortedObject(state.resources),
+        owner: state.owner ?? null,
+        controller: state.controller ?? null,
+        cores: [...state.cores].sort(compareCodeUnits),
+        claims: [...state.claims].sort(compareCodeUnits),
+        victoryPoints: state.victoryPoints
+            .map(({ provinceId, value }) => ({ provinceId, value }))
+            .sort((left, right) => left.provinceId - right.provinceId || left.value - right.value),
+        stateBuildings: sortedObject(state.stateBuildings),
+        provinceBuildings: Object.fromEntries([...state.provinceBuildings]
+            .sort(([left], [right]) => left - right)
+            .map(([provinceId, buildings]) => [String(provinceId), sortedObject(buildings)])),
+        sourcePath: state.file.displayPath,
+        sourceLine: nodeLocation(state.document, state.assignment).start.line,
+    }));
+    const strategicRegions = [...index.regions]
+        .sort((left, right) => left.id - right.id)
+        .map((region) => ({
+        kind: 'strategic-region',
+        id: region.id,
+        name: resolvedName(localisationEntriesByKey, [region.name], region.name),
+        geometry: aggregateGeometry(index, region.provinces),
+        provinceIds: [...region.provinces].sort((a, b) => a - b),
+        stateIds: [
+            ...new Set(region.provinces.flatMap((provinceId) => index.stateForProvince(provinceId).map(({ id }) => id))),
+        ].sort((a, b) => a - b),
+        navalTerrain: region.navalTerrain ?? null,
+        sourcePath: region.file.displayPath,
+        sourceLine: nodeLocation(region.document, region.assignment).start.line,
+    }));
+    const normalAdjacencies = [...(raster?.adjacency ?? [])]
+        .flatMap(([from, neighbors]) => [...neighbors].flatMap((to) => (from < to ? [{ from, to }] : [])))
+        .sort((left, right) => left.from - right.from || left.to - right.to);
+    return {
+        schemaVersion: 2,
+        dimensions: { width, height },
+        coordinateSystems: {
+            pixel: { origin: 'top-left', xDirection: 'right', yDirection: 'down' },
+            map: { origin: 'bottom-left', xDirection: 'right', zDirection: 'up' },
+        },
+        counts: {
+            provinces: provinces.length,
+            states: states.length,
+            strategicRegions: strategicRegions.length,
+            normalAdjacencies: normalAdjacencies.length,
+            specialAdjacencies: index.adjacencies.length,
+            supplyNodes: index.supplyNodes.length,
+            railways: index.railways.length,
+            ports: index.ports.length,
+            victoryPoints: [...index.victoryPointsByProvince.values()].reduce((count, entries) => count + entries.length, 0),
+            buildingPositions: index.buildingPositions.length,
+            unitPositions: index.unitPositions.length,
+            weatherPositions: index.weatherPositions.length,
+            entityLocators: index.entityLocators.length,
+        },
+        provinces,
+        states,
+        strategicRegions,
+        normalAdjacencies,
+        specialAdjacencies: index.adjacencies.map((adjacency, ordinal) => ({
+            ordinal,
+            from: adjacency.from,
+            to: adjacency.to,
+            type: adjacency.type,
+            through: adjacency.through,
+            startX: adjacency.startX,
+            startY: adjacency.startY,
+            stopX: adjacency.stopX,
+            stopY: adjacency.stopY,
+            rule: adjacency.rule,
+            comment: adjacency.comment,
+            sourcePath: adjacency.document.file.displayPath,
+            line: adjacency.line,
+        })),
+        supplyNodes: index.supplyNodes.map((node, ordinal) => ({
+            ordinal,
+            level: node.level,
+            provinceId: node.provinceId,
+            sourcePath: node.document.file.displayPath,
+            line: node.line,
+        })),
+        railways: index.railways.map((railway, ordinal) => ({
+            ordinal,
+            level: railway.level,
+            declaredCount: railway.declaredCount,
+            provinceIds: [...railway.provinces],
+            sourcePath: railway.document.file.displayPath,
+            line: railway.line,
+        })),
+        ports: index.ports.map(({ stateId, provinceId, level, coastal, adjacentSeaProvinceIds }) => ({
+            stateId,
+            provinceId,
+            level,
+            coastal,
+            adjacentSeaProvinceIds: [...adjacentSeaProvinceIds].sort((left, right) => left - right),
+        })),
+        victoryPoints: [...index.victoryPointsByProvince.values()]
+            .flatMap((entries) => entries.map(({ stateId, provinceId, value }) => ({ stateId, provinceId, value })))
+            .sort((left, right) => left.stateId - right.stateId ||
+            left.provinceId - right.provinceId ||
+            left.value - right.value),
+        buildingPositions: index.buildingPositions.map((position, ordinal) => ({
+            ordinal,
+            stateId: position.stateId,
+            building: position.building,
+            x: position.x,
+            y: position.y,
+            z: position.z,
+            rotation: position.rotation,
+            adjacentSeaProvince: position.adjacentSeaProvince,
+            sourcePath: position.document.file.displayPath,
+            line: position.line,
+        })),
+        unitPositions: index.unitPositions.map((position, ordinal) => ({
+            ordinal,
+            provinceId: position.provinceId,
+            type: position.type,
+            x: position.x,
+            y: position.y,
+            z: position.z,
+            rotation: position.rotation,
+            offset: position.offset,
+            sourcePath: position.document.file.displayPath,
+            line: position.line,
+        })),
+        weatherPositions: index.weatherPositions.map((position, ordinal) => ({
+            ordinal,
+            strategicRegionId: position.strategicRegionId,
+            x: position.x,
+            y: position.y,
+            z: position.z,
+            size: position.size,
+            sourcePath: position.document.file.displayPath,
+            line: position.line,
+        })),
+        entityLocators: [...index.entityLocators]
+            .sort((left, right) => compareCodeUnits(left.entity, right.entity) || compareCodeUnits(left.name, right.name))
+            .map(({ entity, name, position, file }) => ({
+            entity,
+            name,
+            position: [...position],
+            sourcePath: file.displayPath,
+        })),
+    };
+}
+function searchScore(query, id, key, displayName, alternatives) {
+    const idText = String(id);
+    const normalizedKey = key.toLocaleLowerCase('en-US');
+    const normalizedName = displayName.toLocaleLowerCase('en-US');
+    const normalizedAlternatives = alternatives.map((value) => value.toLocaleLowerCase('en-US'));
+    if (query === idText ||
+        query === normalizedKey ||
+        query === normalizedName ||
+        normalizedAlternatives.includes(query))
+        return 0;
+    if (idText.startsWith(query) ||
+        normalizedKey.startsWith(query) ||
+        normalizedName.startsWith(query) ||
+        normalizedAlternatives.some((value) => value.startsWith(query)))
+        return 1;
+    if (normalizedKey.includes(query) ||
+        normalizedName.includes(query) ||
+        normalizedAlternatives.some((value) => value.includes(query)))
+        return 2;
+    return undefined;
+}
+export function searchMapCatalog(catalog, query, limit = 100) {
+    const normalized = query.trim().toLocaleLowerCase('en-US');
+    if (normalized === '')
+        return [];
+    const entries = [
+        ...catalog.provinces.map(({ id, name, geometry }) => ({
+            kind: 'province',
+            id,
+            key: name.key,
+            displayName: name.displayName,
+            alternatives: name.values.map(({ value }) => value),
+            geometry,
+        })),
+        ...catalog.states.map(({ id, name, geometry }) => ({
+            kind: 'state',
+            id,
+            key: name.key,
+            displayName: name.displayName,
+            alternatives: name.values.map(({ value }) => value),
+            geometry,
+        })),
+        ...catalog.strategicRegions.map(({ id, name, geometry }) => ({
+            kind: 'strategic-region',
+            id,
+            key: name.key,
+            displayName: name.displayName,
+            alternatives: name.values.map(({ value }) => value),
+            geometry,
+        })),
+    ];
+    return entries
+        .flatMap((entry) => {
+        const score = searchScore(normalized, entry.id, entry.key, entry.displayName, entry.alternatives);
+        if (score === undefined)
+            return [];
+        const { alternatives: _alternatives, ...result } = entry;
+        return [{ ...result, score }];
+    })
+        .sort((left, right) => left.score - right.score || compareCodeUnits(left.kind, right.kind) || left.id - right.id)
+        .slice(0, Math.max(0, limit));
+}
+export function lookupMapCoordinate(index, coordinate) {
+    const raster = index.raster;
+    const pixel = coordinate.kind === 'pixel'
+        ? { x: Math.floor(coordinate.x), y: Math.floor(coordinate.y) }
+        : raster === undefined
+            ? null
+            : { x: Math.floor(coordinate.x), y: raster.height - 1 - Math.floor(coordinate.z) };
+    if (raster === undefined ||
+        pixel === null ||
+        pixel.x < 0 ||
+        pixel.y < 0 ||
+        pixel.x >= raster.width ||
+        pixel.y >= raster.height) {
+        return { coordinate, pixel: null, provinceId: null, stateIds: [], regionIds: [] };
+    }
+    const provinceId = raster.provinceIds[pixel.y * raster.width + pixel.x] ?? -1;
+    if (provinceId < 0)
+        return { coordinate, pixel, provinceId: null, stateIds: [], regionIds: [] };
+    return {
+        coordinate,
+        pixel,
+        provinceId,
+        stateIds: index.stateForProvince(provinceId).map(({ id }) => id),
+        regionIds: index.regionForProvince(provinceId).map(({ id }) => id),
+    };
+}

package/dist/hoi4_agent_tools/map/index.js

@@ -1,4 +1,5 @@
 export * from './bmp.js';
+export * from './catalog.js';
 export * from './limits.js';
 export * from './model.js';
 export * from './operations.js';