hoi4-agent-tools 4.2.0 → 4.4.0

package/dist/hoi4_agent_tools/map/world.js

@@ -9,9 +9,19 @@ import { ServiceError } from '../core/result.js';
 import { createBmp } from './bmp.js';
 import { generateWorldDrainage } from './world-drainage.js';
 import { generateWorldProvinces } from './world-provinces.js';
+import { clusterRegions, clusterStates, partitionWorldFromRequest, } from './partition.js';
+import { repairSeamCorners, smoothDiagonalContacts } from './partition-fields.js';
+import { PARTITION_PROVINCE_ERROR, PARTITION_PROVINCE_WARNING } from './partition-tuning.js';
+import { geographyPartitionFields, provinceCountNote, surfacePartitionFields, } from './world-partition.js';
+import { fractal, lattice } from './world-noise.js';
+import { calibratedColourMap, COLOUR_CLASSES, } from './colormap.js';
+import { ambientObjectText, applyEdgePolicy, assertFeaturesOutsideBand, edgeWaterDarkness, RIM_COLOUR_FACTOR, rimAdjacencyRows, rimHeight, rimStrength, } from './world-edge.js';
+import { landDistanceField, lakeHeight, normalizeLakes, waterColourLevel } from './water.js';
+import { overlayGeographyLakes, rasterizeGeographyKind } from './relief/land.js';
+import { synthesizeTerrain } from './relief/terrain-synthesis.js';
 // ---------------------------------------------------------------------------------------------
 // Deterministic randomness and noise
-class Random {
+export class Random {
     #state;
     constructor(seed) {
         this.#state = (seed ^ 0x9e3779b9) >>> 0;
@@ -27,38 +37,6 @@ class Random {
         return Math.floor(this.next() * limit);
     }
 }
-function lattice(seed, x, y) {
-    let hash = Math.imul(x, 374761393) + Math.imul(y, 668265263) + Math.imul(seed, 982451653);
-    hash = Math.imul(hash ^ (hash >>> 13), 1274126177);
-    return ((hash ^ (hash >>> 16)) >>> 0) / 4294967296;
-}
-function smooth(t) {
-    return t * t * (3 - 2 * t);
-}
-function valueNoise(seed, x, y) {
-    const x0 = Math.floor(x);
-    const y0 = Math.floor(y);
-    const tx = smooth(x - x0);
-    const ty = smooth(y - y0);
-    const a = lattice(seed, x0, y0);
-    const b = lattice(seed, x0 + 1, y0);
-    const c = lattice(seed, x0, y0 + 1);
-    const d = lattice(seed, x0 + 1, y0 + 1);
-    return a + (b - a) * tx + (c - a) * ty + (a - b - c + d) * tx * ty;
-}
-function fractal(seed, x, y, scale, octaves = 5) {
-    let total = 0;
-    let amplitude = 1;
-    let weight = 0;
-    let frequency = 1 / scale;
-    for (let octave = 0; octave < octaves; octave += 1) {
-        total += valueNoise(seed + octave * 101, x * frequency, y * frequency) * amplitude;
-        weight += amplitude;
-        amplitude *= 0.5;
-        frequency *= 2;
-    }
-    return total / weight;
-}
 // ---------------------------------------------------------------------------------------------
 // Raster helpers
 const LAND = 1;
@@ -204,10 +182,99 @@ function generateSurface(spec, random) {
     }
     return { kind, elevation, moisture };
 }
+/**
+ * Surface of a world described by a geography model: land and lakes from the model (or lakes laid
+ * over a reference picture's coast); elevation is filled in by the terrain synthesis later.
+ */
+/** Province count the vanilla map holds; defaulted sizes grow towards it. */
+const PROVINCE_COUNT_GOAL = 13_000;
+/**
+ * Check the province count the sizes give before partitioning. Defaulted sizes above the warning
+ * grow until the world holds about the base game's count; sizes the caller chose that give more
+ * than the text tables allow are refused before any work.
+ */
+function provinceBudget(spec, kind) {
+    let land = 0;
+    let water = 0;
+    for (const value of kind)
+        if (value === LAND)
+            land += 1;
+        else
+            water += 1;
+    const expected = land / spec.landProvincePixels + water / spec.seaProvincePixels;
+    const sizes = {
+        landProvincePixels: spec.landProvincePixels,
+        seaProvincePixels: spec.seaProvincePixels,
+    };
+    if (expected <= PARTITION_PROVINCE_WARNING)
+        return sizes;
+    if (spec.provinceSizesDefaulted === true) {
+        const factor = expected / PROVINCE_COUNT_GOAL;
+        const landProvincePixels = Math.ceil(spec.landProvincePixels * factor);
+        const seaProvincePixels = Math.ceil(spec.seaProvincePixels * factor);
+        return {
+            landProvincePixels,
+            seaProvincePixels,
+            note: {
+                code: 'MAP_WORLD_PROVINCE_SIZE_RAISED',
+                severity: 'info',
+                message: `The default province sizes would give about ${Math.round(expected)} provinces on this much land; they were raised to ${landProvincePixels} land and ${seaProvincePixels} sea pixels for about ${PROVINCE_COUNT_GOAL}. Set landProvincePixels and seaProvincePixels to choose them`,
+                details: { expectedProvinces: Math.round(expected), landProvincePixels, seaProvincePixels },
+            },
+        };
+    }
+    if (expected > PARTITION_PROVINCE_ERROR)
+        throw new ServiceError('MAP_PARTITION_PROVINCE_COUNT_HIGH', `landProvincePixels ${spec.landProvincePixels} and seaProvincePixels ${spec.seaProvincePixels} give about ${Math.round(expected)} provinces on this map, above the ${PARTITION_PROVINCE_ERROR} the text tables allow; raise them`, { expectedProvinces: Math.round(expected), maximum: PARTITION_PROVINCE_ERROR });
+    return sizes;
+}
+function geographySurface(spec, geography, reference) {
+    const { width, height } = spec;
+    const total = width * height;
+    const options = { width, height, seed: spec.seed };
+    let kind;
+    let moisture;
+    if (reference === undefined) {
+        kind = rasterizeGeographyKind(geography, options);
+        moisture = new Float32Array(total);
+        const scale = Math.max(width, height) / 6;
+        for (let y = 0; y < height; y += 1)
+            for (let x = 0; x < width; x += 1)
+                moisture[y * width + x] = fractal(spec.seed + 7919, x, y, scale * 0.8, 4);
+    }
+    else {
+        kind = new Uint8Array(reference.kind);
+        overlayGeographyLakes(kind, geography, options);
+        moisture = new Float32Array(reference.moisture);
+    }
+    return { kind, elevation: new Float32Array(total), moisture };
+}
+function terrainSummaryNote(terrain, geography) {
+    const { relief, riverStatistics } = terrain;
+    return {
+        code: 'MAP_RELIEF_SYNTHESIZED',
+        severity: 'info',
+        message: `Synthesised relief and rivers from the geography model: land height median ${relief.median}, 99th percentile ${relief.p99}, maximum ${relief.maximum}, mean step ${relief.meanStep.toFixed(2)} per half-resolution pixel; ${riverStatistics.count} rivers (${riverStatistics.named} named) on ${(riverStatistics.landShare * 100).toFixed(2)}% of the land`,
+        details: {
+            modelHash: geography.hash,
+            relief,
+            rivers: riverStatistics,
+            // The first of the named rivers only: the response budget is shared with everything else the
+            // world reports, and a river that did not complete is always listed.
+            namedRivers: terrain.rivers
+                .filter((river) => river.named && river.junction !== 'distributary')
+                .slice(0, 24)
+                .map(({ id, pixels, mouth, complete }) => ({ id, pixels, mouth, complete })),
+            incompleteRivers: terrain.rivers
+                .filter((river) => river.named && !river.complete)
+                .slice(0, 24)
+                .map(({ id }) => id),
+        },
+    };
+}
 // ---------------------------------------------------------------------------------------------
 // Grouping provinces into regions and states
 /** Grow clusters of about `target` members over a graph from spread-out seeds. */
-function growClusters(members, neighbors, target, random, weight = () => 1) {
+export function growClusters(members, neighbors, target, random, weight = () => 1) {
     const cluster = new Map();
     const memberSet = new Set(members);
     const pending = new Set(members);
@@ -324,10 +391,23 @@ const DEFAULT_TERRAIN_INDEX = new Map([
     ['mountain', 6],
     ['marsh', 9],
     ['urban', 13],
-    ['lakes', 14],
+    ['lakes', 15],
     ['ocean', 15],
     ['jungle', 21],
 ]);
+/**
+ * A graphical terrain index of the base game's numbering (farmland 5, sparse forest 4, mountain
+ * with grass 20), used only when the active terrain files confirm that index still has that
+ * category and draws a tile. Without any terrain files the base game's numbering is assumed.
+ */
+function terrainVariant(context, index, type) {
+    const entries = context.terrainEntries;
+    if (entries === undefined)
+        return context.terrainIndex === undefined ? index : undefined;
+    return entries.some((entry) => entry.index === index && entry.type === type && entry.texture !== 255 && !entry.permSnow)
+        ? index
+        : undefined;
+}
 /** Approximate seasonal weather: signed latitude is positive north of the equator. */
 function weatherBlock(signedLatitude, desert) {
     const latitude = Math.abs(signedLatitude);
@@ -358,7 +438,7 @@ function weatherBlock(signedLatitude, desert) {
     }
     return `\tweather={\n${periods.join('\n')}\n\t}`;
 }
-export function generateWorld(spec, context) {
+export function generateWorld(spec, context, options = {}) {
     const { width, height } = spec;
     if (width % 256 !== 0 || height % 256 !== 0)
         throw new ServiceError('MAP_WORLD_DIMENSIONS_INVALID', 'Both map dimensions must be multiples of 256', { width, height });
@@ -382,34 +462,171 @@ export function generateWorld(spec, context) {
     const reference = spec.referenceSurface;
     if (reference !== undefined && (reference.width !== width || reference.height !== height))
         throw new ServiceError('MAP_WORLD_REFERENCE_DIMENSIONS', 'Reference raster dimensions do not match the world');
-    const surface = reference === undefined
-        ? generateSurface(spec, random)
+    const geography = spec.geography;
+    if (geography !== undefined &&
+        (geography.frame.width !== width || geography.frame.height !== height))
+        throw new ServiceError('MAP_GEOGRAPHY_FRAME_MISMATCH', 'The geography model was resolved for a different map size than the world being created', {
+            model: { width: geography.frame.width, height: geography.frame.height },
+            world: { width, height },
+        });
+    const surface = geography !== undefined
+        ? geographySurface(spec, geography, reference)
+        : reference === undefined
+            ? generateSurface(spec, random)
+            : {
+                kind: new Uint8Array(reference.kind),
+                elevation: new Float32Array(reference.elevation),
+                moisture: new Float32Array(reference.moisture),
+            };
+    const notes = [];
+    const edge = spec.edge ?? { mode: 'none', bandPx: 0, polarPx: 0, rimPx: 0 };
+    if (edge.mode !== 'none') {
+        assertFeaturesOutsideBand(edge, width, height, (spec.referenceCities ?? []).map(({ name, x, y }) => ({ name, x, y, kind: 'city' })));
+        const applied = applyEdgePolicy(surface.kind, surface.elevation, width, height, edge, spec.seed, Math.max(40, Math.round(spec.landProvincePixels / 4)));
+        notes.push(...applied.notes.map((note) => note));
+    }
+    // Lakes need a minimum size and may not touch the open sea (ADR 0053).
+    for (const note of normalizeLakes(surface.kind, surface.elevation, width, height))
+        notes.push({
+            code: note.code,
+            severity: 'warning',
+            message: `${note.message} near (${note.x}, ${note.y})`,
+            details: { pixels: note.pixels, x: note.x, y: note.y },
+        });
+    // A coast that touches itself only at corners cannot be cut into valid provinces, so the
+    // feature-aware partition smooths it when it builds its own fields. A geography world smooths
+    // before the synthesis, so its heights, rivers and fields follow the smoothed mask; any other
+    // world smooths after its drainage and patches those rasters, as it always has.
+    const smoothMask = spec.partition?.mode === 'feature-aware' && spec.partition.fields === undefined;
+    let smoothed = smoothMask && geography !== undefined
+        ? smoothDiagonalContacts(surface.kind, width, height)
+        : [];
+    // A coast crossing the east-west seam is repaired in every world, before the synthesis of a
+    // geography world and after the drainage of any other, like the smoothing.
+    let seamRepaired = geography !== undefined ? repairSeamCorners(surface.kind, width, height) : [];
+    // A geography model gets its relief and rivers from the synthesis of ADR 0056; every other world
+    // keeps the original elevation classes and drainage, byte for byte.
+    const synthesized = geography === undefined
+        ? undefined
+        : synthesizeTerrain({
+            geography,
+            width,
+            height,
+            seed: spec.seed,
+            kind: surface.kind,
+            relief: spec.relief,
+            rivers: { density: spec.riverDensity, count: spec.riverCount },
+            adjustHeight: edge.mode === 'rim'
+                ? (x, _y, value) => rimHeight(value, rimStrength(edge, width, x))
+                : undefined,
+            signal: options.signal,
+        });
+    if (synthesized !== undefined) {
+        for (const note of synthesized.notes) {
+            if (note.severity === 'error')
+                throw new ServiceError(note.code, note.message, note.details);
+            notes.push({
+                code: note.code,
+                severity: note.severity,
+                message: note.message,
+                ...(note.details === undefined ? {} : { details: note.details }),
+            });
+        }
+        notes.push(terrainSummaryNote(synthesized, geography));
+    }
+    const drainage = synthesized === undefined
+        ? generateWorldDrainage({
+            width,
+            height,
+            kind: surface.kind,
+            elevation: surface.elevation,
+            seed: spec.seed,
+            count: spec.rivers,
+            ...(reference === undefined ? {} : { referenceRivers: reference.rivers }),
+        })
         : {
-            kind: new Uint8Array(reference.kind),
-            elevation: new Float32Array(reference.elevation),
-            moisture: new Float32Array(reference.moisture),
+            riverPixels: synthesized.riverBitmap,
+            elevation: synthesized.elevation,
+            count: synthesized.riverStatistics.count,
+            warnings: [],
         };
-    const drainage = generateWorldDrainage({
-        width,
-        height,
-        kind: surface.kind,
-        elevation: surface.elevation,
-        seed: spec.seed,
-        count: spec.rivers,
-        ...(reference === undefined ? {} : { referenceRivers: reference.rivers }),
-    });
     surface.elevation = drainage.elevation;
-    const provinces = generateWorldProvinces({
-        width,
-        height,
-        seed: spec.seed,
-        kind: surface.kind,
-        elevation: surface.elevation,
-        moisture: surface.moisture,
-        landProvincePixels: spec.landProvincePixels,
-        seaProvincePixels: spec.seaProvincePixels,
-    });
+    if (smoothMask && geography === undefined) {
+        smoothed = smoothDiagonalContacts(surface.kind, width, height);
+        for (const pixel of smoothed) {
+            const isLand = surface.kind[pixel] === LAND;
+            surface.elevation[pixel] = isLand ? 0.02 : -0.02;
+            drainage.riverPixels[pixel] = isLand ? 255 : 254;
+        }
+    }
+    if (geography === undefined) {
+        seamRepaired = repairSeamCorners(surface.kind, width, height);
+        for (const pixel of seamRepaired) {
+            const isLand = surface.kind[pixel] === LAND;
+            surface.elevation[pixel] = isLand ? 0.02 : -0.02;
+            drainage.riverPixels[pixel] = isLand ? 255 : 254;
+        }
+    }
+    if (seamRepaired.length > 0)
+        notes.push({
+            code: 'MAP_WORLD_SEAM_CORNER_REPAIRED',
+            severity: 'info',
+            message: `Changed ${seamRepaired.length} pixel(s) at the east-west seam where a coast crosses it, because province parts cannot join across the seam`,
+            details: { pixels: seamRepaired.length },
+        });
+    if (smoothed.length > 0)
+        notes.push({
+            code: 'MAP_PARTITION_MASK_SMOOTHED',
+            severity: 'info',
+            message: `Changed ${smoothed.length} coast pixel(s) that touched their own kind only at a corner, which no province partition can represent`,
+            details: { pixels: smoothed.length },
+        });
+    const sizes = provinceBudget(spec, surface.kind);
+    if (sizes.note !== undefined)
+        notes.push(sizes.note);
+    let featurePartition;
+    let provinces;
+    if (spec.partition?.mode === 'feature-aware') {
+        const surfaceInput = {
+            width,
+            height,
+            kind: surface.kind,
+            elevation: surface.elevation,
+            moisture: surface.moisture,
+            riverPixels: drainage.riverPixels,
+            ...(reference === undefined ? {} : { referenceTerrain: reference.terrain }),
+        };
+        // A geography world hands the partition its regions, densities and walls, the synthesised
+        // heights and the model-drawn lines of the synthesis (ADR 0058).
+        featurePartition = partitionWorldFromRequest(spec.partition.fields ??
+            (synthesized === undefined || geography === undefined
+                ? surfacePartitionFields(surfaceInput)
+                : geographyPartitionFields({ ...surfaceInput, heights: synthesized.heights }, geography, synthesized.fields)), spec.seed, spec.partition.tuning, {
+            landProvincePixels: sizes.landProvincePixels,
+            seaProvincePixels: sizes.seaProvincePixels,
+            provincesPerState: spec.provincesPerState,
+            landProvincesPerRegion: spec.landProvincesPerRegion,
+            seaProvincesPerRegion: spec.seaProvincesPerRegion,
+        }, options.signal);
+        provinces = featurePartition.provinces;
+        for (const note of featurePartition.notes)
+            notes.push(note);
+    }
+    else
+        provinces = generateWorldProvinces({
+            width,
+            height,
+            seed: spec.seed,
+            kind: surface.kind,
+            elevation: surface.elevation,
+            moisture: surface.moisture,
+            landProvincePixels: sizes.landProvincePixels,
+            seaProvincePixels: sizes.seaProvincePixels,
+        });
     const count = provinces.kind.length;
+    const countNote = provinceCountNote(count, featurePartition === undefined ? 'legacy' : 'feature-aware');
+    if (countNote !== undefined)
+        notes.push(countNote);
     const center = (id) => ({
         x: provinces.sumX[id] / provinces.size[id],
         y: provinces.sumY[id] / provinces.size[id],
@@ -704,8 +921,12 @@ export function generateWorld(spec, context) {
         }
     // Strategic regions: land regions over the land graph, sea regions over the sea graph.
     const graph = (id) => provinces.neighbors[id];
-    const landRegion = growClusters(landIds, graph, spec.landProvincesPerRegion, random);
-    const seaRegion = growClusters(seaIds, graph, spec.seaProvincesPerRegion, random);
+    const landRegion = featurePartition === undefined
+        ? growClusters(landIds, graph, spec.landProvincesPerRegion, random)
+        : clusterRegions(featurePartition, landIds, 'land');
+    const seaRegion = featurePartition === undefined
+        ? growClusters(seaIds, graph, spec.seaProvincesPerRegion, random)
+        : clusterRegions(featurePartition, seaIds, 'sea');
     const regionOf = new Map();
     const landRegionCount = Math.max(-1, ...landRegion.values()) + 1;
     for (const [id, region] of landRegion)
@@ -734,7 +955,9 @@ export function generateWorld(spec, context) {
     const stateOf = new Map();
     for (const key of [...groups.keys()].sort()) {
         const members = groups.get(key);
-        const clusters = growClusters(members, graph, spec.provincesPerState, random);
+        const clusters = featurePartition === undefined
+            ? growClusters(members, graph, spec.provincesPerState, random)
+            : clusterStates(featurePartition, members);
         const byCluster = new Map();
         for (const [id, cluster] of clusters) {
             const list = byCluster.get(cluster) ?? [];
@@ -951,10 +1174,27 @@ export function generateWorld(spec, context) {
         '',
     ].join('\n')));
     add(`${map}/continent.txt`, text(`continents = {\n${[...new Set([...continentNames.map((_, index) => `world_continent_${index + 1}`), ...(context.continentKeys ?? [])])].map((key) => `\t${key}`).join('\n')}\n}\n`));
-    add(`${map}/adjacencies.csv`, text('From;To;Type;Through;start_x;start_y;stop_x;stop_y;adjacency_rule_name;Comment\r\n-1;-1;;-1;-1;-1;-1;-1;-1\r\n'));
+    const rimRows = edge.mode === 'rim'
+        ? rimAdjacencyRows({
+            provincePixels: provinces.pixel,
+            provinceKinds: provinces.kind,
+            width,
+            height,
+        })
+        : [];
+    if (rimRows.length > 0)
+        notes.push({
+            code: 'MAP_EDGE_RIM_ADJACENCIES',
+            severity: 'info',
+            message: `The rim edge policy wrote ${rimRows.length} impassable adjacency row(s) for provinces that meet across the seam`,
+            details: { rows: rimRows.length },
+        });
+    add(`${map}/adjacencies.csv`, text(`From;To;Type;Through;start_x;start_y;stop_x;stop_y;adjacency_rule_name;Comment\r\n${rimRows.map((row) => `${row}\r\n`).join('')}-1;-1;;-1;-1;-1;-1;-1;-1\r\n`));
     add(`${map}/adjacency_rules.txt`, text('# No straits or canals in this world yet.\n'));
     add(`${map}/positions.txt`, text(''));
-    add(`${map}/ambient_object.txt`, text('# No ambient objects: the base-game map frame does not fit this map.\n'));
+    add(`${map}/ambient_object.txt`, text(spec.ambientFrame === true
+        ? ambientObjectText(width, height)
+        : '# No ambient objects: the base-game map frame does not fit this map.\n'));
     // City groups use palette 15 only for urban footprints. Water and undeveloped land stay 0.
     const cityPixels = new Uint8Array(width * height);
     const nearestCenter = new Int32Array(count).fill(-1);
@@ -996,33 +1236,90 @@ export function generateWorld(spec, context) {
         const type = terrain.get(provinces.pixel[pixel]) ?? 'plains';
         return type === 'urban' ? 'plains' : type;
     };
-    // heightmap.bmp: sea below 95, land from 96 up.
-    const heights = new Uint8Array(width * height);
-    for (let pixel = 0; pixel < width * height; pixel += 1) {
-        const value = surface.elevation[pixel];
-        heights[pixel] =
-            surface.kind[pixel] === LAND
-                ? Math.min(255, Math.round(96 + value * 110))
-                : surface.kind[pixel] === LAKE
-                    ? 93
-                    : Math.max(60, Math.round(94 + value * 30));
-    }
+    // heightmap.bmp: sea below 95, land from 96 up. Lakes sit at the sea's interior height with a
+    // one to two pixel translucent bank, so the water layer draws them opaque (ADR 0053).
+    const landDistance = landDistanceField(surface.kind, width, height);
+    const heights = synthesized?.heights ?? new Uint8Array(width * height);
+    if (synthesized === undefined)
+        for (let pixel = 0; pixel < width * height; pixel += 1) {
+            const value = surface.elevation[pixel];
+            heights[pixel] =
+                surface.kind[pixel] === LAND
+                    ? rimHeight(Math.min(255, Math.round(96 + value * 110)), rimStrength(edge, width, pixel % width))
+                    : surface.kind[pixel] === LAKE
+                        ? lakeHeight(landDistance[pixel])
+                        : Math.max(60, Math.round(94 + value * 30));
+        }
     const grey = Array.from({ length: 256 }, (_, index) => ({ r: index, g: index, b: index }));
     add(`${map}/heightmap.bmp`, createBmp({ width, height, bitsPerPixel: 8, palette: grey, indexedPixels: heights }), 'image/bmp');
     // terrain.bmp from province terrain, with snow on high-latitude mountains.
     const terrainIndex = context.terrainIndex ?? DEFAULT_TERRAIN_INDEX;
+    // Lake pixels use the ocean's graphical terrain: the lake entry names no atlas tile.
+    const lakeIndex = terrainIndex.get('lakes') ?? terrainIndex.get('ocean') ?? 15;
+    const calibrated = spec.colormapProfile === 'calibrated';
+    const farmlandIndex = calibrated ? terrainVariant(context, 5, 'plains') : undefined;
+    const sparseForestIndex = calibrated ? terrainVariant(context, 4, 'forest') : undefined;
+    const mountainGrassIndex = calibrated ? terrainVariant(context, 20, 'mountain') : undefined;
     const terrainPixels = new Uint8Array(width * height);
+    const colourClasses = calibrated ? new Uint8Array(width * height) : undefined;
+    const classCode = (name) => COLOUR_CLASSES.indexOf(name);
+    const flatSlope = (x, y) => Math.abs(heights[y * width + Math.min(width - 1, x + 1)] - heights[y * width + Math.max(0, x - 1)]) +
+        Math.abs(heights[Math.min(height - 1, y + 1) * width + x] -
+            heights[Math.max(0, y - 1) * width + x]) <=
+        2;
     for (let pixel = 0; pixel < width * height; pixel += 1) {
         const id = provinces.pixel[pixel];
         const type = visualTerrain(pixel);
-        const snowy = reference === undefined
-            ? type === 'mountain' && latitude(id) > 0.7
-            : reference.terrain[pixel] === 4 && surface.kind[pixel] === LAND;
-        terrainPixels[pixel] = snowy
+        const snowy = synthesized !== undefined
+            ? (synthesized.snow[pixel] === 1 || reference?.terrain[pixel] === 4) &&
+                surface.kind[pixel] === LAND
+            : reference === undefined
+                ? type === 'mountain' && latitude(id) > 0.7
+                : reference.terrain[pixel] === 4 && surface.kind[pixel] === LAND;
+        const x = pixel % width;
+        const rimmed = rimStrength(edge, width, x) > 0.35 && surface.kind[pixel] === LAND;
+        let index = snowy
             ? reference === undefined
                 ? 16
                 : 19
-            : (terrainIndex.get(type) ?? DEFAULT_TERRAIN_INDEX.get(type) ?? 0);
+            : rimmed
+                ? 16
+                : type === 'lakes'
+                    ? lakeIndex
+                    : (terrainIndex.get(type) ?? DEFAULT_TERRAIN_INDEX.get(type) ?? 0);
+        let colour = type === 'lakes' || type === 'ocean' || type === 'urban'
+            ? type === 'urban'
+                ? 'urban'
+                : type
+            : snowy || rimmed
+                ? 'snow'
+                : type;
+        if (calibrated && !snowy && !rimmed && surface.kind[pixel] === LAND) {
+            // Variant graphical terrains by rule, so one class is not one flat texture.
+            const y = (pixel - x) / width;
+            if (type === 'plains' &&
+                farmlandIndex !== undefined &&
+                surface.moisture[pixel] >= 0.6 &&
+                flatSlope(x, y)) {
+                index = farmlandIndex;
+                colour = 'farmland';
+            }
+            else if (type === 'forest' &&
+                sparseForestIndex !== undefined &&
+                fractal(spec.seed + 7001, x, y, Math.max(16, width / 30), 3) < 0.42)
+                index = sparseForestIndex;
+            else if (type === 'mountain' &&
+                mountainGrassIndex !== undefined &&
+                surface.moisture[pixel] > 0.45 &&
+                fractal(spec.seed + 7919, x, y, Math.max(16, width / 20), 3) > 0.5)
+                index = mountainGrassIndex;
+        }
+        terrainPixels[pixel] = index;
+        if (colourClasses !== undefined) {
+            if (!COLOUR_CLASSES.includes(colour))
+                colour = 'plains';
+            colourClasses[pixel] = classCode(colour);
+        }
     }
     add(`${map}/terrain.bmp`, createBmp({
         width,
@@ -1098,23 +1395,33 @@ export function generateWorld(spec, context) {
         palette: bmpPalette(context.palettes.cities, (index) => ({ r: index, g: index, b: index })),
         indexedPixels: cityPixels,
     }), 'image/bmp');
-    // world_normal.bmp at half size from the height gradient.
+    // world_normal.bmp at half size. Geography worlds shade from the float height field at the
+    // base game's response; every other world from the quantised heights.
     const halfWidth = width / 2;
     const halfHeight = height / 2;
-    const normals = new Array(halfWidth * halfHeight);
-    const heightAt = (x, y) => heights[Math.min(height - 1, Math.max(0, y)) * width + Math.min(width - 1, Math.max(0, x))];
-    for (let y = 0; y < halfHeight; y += 1)
-        for (let x = 0; x < halfWidth; x += 1) {
-            const dx = (heightAt(x * 2 + 2, y * 2) - heightAt(x * 2 - 2, y * 2)) / 4;
-            const dy = (heightAt(x * 2, y * 2 - 2) - heightAt(x * 2, y * 2 + 2)) / 4;
-            const length = Math.hypot(dx, dy, 8);
-            normals[y * halfWidth + x] = {
-                r: Math.round(128 - (dx / length) * 127),
-                g: Math.round(128 + (dy / length) * 127),
-                b: Math.round(128 + (8 / length) * 127),
-            };
-        }
-    add(`${map}/world_normal.bmp`, createBmp({ width: halfWidth, height: halfHeight, bitsPerPixel: 24, rgbPixels: normals }), 'image/bmp');
+    if (synthesized !== undefined)
+        add(`${map}/world_normal.bmp`, createBmp({
+            width: halfWidth,
+            height: halfHeight,
+            bitsPerPixel: 24,
+            rgbBytes: synthesized.normals,
+        }), 'image/bmp');
+    else {
+        const normals = new Array(halfWidth * halfHeight);
+        const heightAt = (x, y) => heights[Math.min(height - 1, Math.max(0, y)) * width + Math.min(width - 1, Math.max(0, x))];
+        for (let y = 0; y < halfHeight; y += 1)
+            for (let x = 0; x < halfWidth; x += 1) {
+                const dx = (heightAt(x * 2 + 2, y * 2) - heightAt(x * 2 - 2, y * 2)) / 4;
+                const dy = (heightAt(x * 2, y * 2 - 2) - heightAt(x * 2, y * 2 + 2)) / 4;
+                const length = Math.hypot(dx, dy, 8);
+                normals[y * halfWidth + x] = {
+                    r: Math.round(128 - (dx / length) * 127),
+                    g: Math.round(128 + (dy / length) * 127),
+                    b: Math.round(128 + (8 / length) * 127),
+                };
+            }
+        add(`${map}/world_normal.bmp`, createBmp({ width: halfWidth, height: halfHeight, bitsPerPixel: 24, rgbPixels: normals }), 'image/bmp');
+    }
     // Colour maps: land tint and city lights at half size; water at half, quarter and eighth.
     const tint = {
         plains: { r: 121, g: 133, b: 76 },
@@ -1128,36 +1435,65 @@ export function generateWorld(spec, context) {
         lakes: { r: 70, g: 96, b: 110 },
         ocean: { r: 50, g: 70, b: 92 },
     };
-    const colormap = new Uint8Array(halfWidth * halfHeight * 4);
-    for (let y = 0; y < halfHeight; y += 1)
-        for (let x = 0; x < halfWidth; x += 1) {
-            // DDS rows run top to bottom, like the bitmaps' top-left coordinates used here.
-            const source = y * 2 * width + x * 2;
-            const color = tint[visualTerrain(source)];
-            const shade = 0.85 + surface.moisture[source] * 0.3;
-            const offset = (y * halfWidth + x) * 4;
-            colormap[offset] = Math.min(255, Math.round(color.b * shade));
-            colormap[offset + 1] = Math.min(255, Math.round(color.g * shade));
-            colormap[offset + 2] = Math.min(255, Math.round(color.r * shade));
-            colormap[offset + 3] = cityPixels[source] === 15 ? 200 : 0;
-        }
-    add(`${map}/terrain/colormap_rgb_cityemissivemask_a.dds`, encodeDds(halfWidth, halfHeight, colormap), 'image/vnd-ms.dds');
-    for (const level of [0, 1, 2]) {
-        const factor = 2 ** (level + 1);
-        const levelWidth = width / factor;
-        const levelHeight = height / factor;
-        const water = new Uint8Array(levelWidth * levelHeight * 4);
-        for (let y = 0; y < levelHeight; y += 1)
-            for (let x = 0; x < levelWidth; x += 1) {
-                const depth = Math.max(0, -surface.elevation[y * factor * width + x * factor]);
-                const offset = (y * levelWidth + x) * 4;
-                water[offset] = Math.round(120 - depth * 50);
-                water[offset + 1] = Math.round(90 - depth * 40);
-                water[offset + 2] = Math.round(40 - depth * 20);
-                water[offset + 3] = 255;
+    let colormap;
+    if (colourClasses !== undefined) {
+        const lights = new Uint8Array(width * height);
+        for (let pixel = 0; pixel < lights.length; pixel += 1)
+            if (cityPixels[pixel] === 15)
+                lights[pixel] = 200;
+        colormap = calibratedColourMap({
+            width,
+            height,
+            seed: spec.seed,
+            classes: colourClasses,
+            moisture: surface.moisture,
+            heights,
+            lights,
+            look: spec.look ?? 'vanilla-temperate',
+            ...(spec.colormapPalette === undefined ? {} : { overrides: spec.colormapPalette }),
+        });
+    }
+    else {
+        colormap = new Uint8Array(halfWidth * halfHeight * 4);
+        for (let y = 0; y < halfHeight; y += 1)
+            for (let x = 0; x < halfWidth; x += 1) {
+                // DDS rows run top to bottom, like the bitmaps' top-left coordinates used here.
+                const source = y * 2 * width + x * 2;
+                const color = tint[visualTerrain(source)];
+                const shade = 0.85 + surface.moisture[source] * 0.3;
+                const offset = (y * halfWidth + x) * 4;
+                colormap[offset] = Math.min(255, Math.round(color.b * shade));
+                colormap[offset + 1] = Math.min(255, Math.round(color.g * shade));
+                colormap[offset + 2] = Math.min(255, Math.round(color.r * shade));
+                colormap[offset + 3] = cityPixels[source] === 15 ? 200 : 0;
             }
-        add(`${map}/terrain/colormap_water_${level}.dds`, encodeDds(levelWidth, levelHeight, water), 'image/vnd-ms.dds');
     }
+    if (edge.mode === 'rim')
+        for (let y = 0; y < halfHeight; y += 1)
+            for (let x = 0; x < halfWidth; x += 1) {
+                const strength = rimStrength(edge, width, x * 2);
+                if (strength === 0 || surface.kind[y * 2 * width + x * 2] !== LAND)
+                    continue;
+                const factor = 1 - (1 - RIM_COLOUR_FACTOR) * strength;
+                const offset = (y * halfWidth + x) * 4;
+                colormap[offset] = Math.round(colormap[offset] * factor);
+                colormap[offset + 1] = Math.round(colormap[offset + 1] * factor);
+                colormap[offset + 2] = Math.round(colormap[offset + 2] * factor);
+            }
+    add(`${map}/terrain/colormap_rgb_cityemissivemask_a.dds`, encodeDds(halfWidth, halfHeight, colormap), 'image/vnd-ms.dds');
+    // Water colour maps: sea tint by distance from land, lake tint with a shore gradient, and the
+    // darkest tint at the world edge (ADR 0053, 0061).
+    for (const level of [0, 1, 2])
+        add(`${map}/terrain/colormap_water_${level}.dds`, encodeDds(width / 2 ** (level + 1), height / 2 ** (level + 1), waterColourLevel({
+            width,
+            height,
+            kind: surface.kind,
+            landDistance,
+            seed: spec.seed,
+            ...(edge.mode === 'none'
+                ? {}
+                : { darken: (x, y) => edgeWaterDarkness(edge, width, height, x, y) }),
+        }, level)), 'image/vnd-ms.dds');
     // Strategic regions with weather by latitude.
     const regionMembers = new Map();
     for (const [id, region] of regionOf) {
@@ -1385,6 +1721,8 @@ export function generateWorld(spec, context) {
     return {
         files,
         warnings: [...interpretationWarnings, ...drainage.warnings],
+        notes,
+        ...(synthesized === undefined ? {} : { terrain: synthesized }),
         summary: {
             width,
             height,