Skip to main content

Archetype Composition Grammar

Why archetypes are open composition, not enums​

A closed-enum archetype field would freeze the morphology universe at M11. Every new continent kind would force a recipe schema version bump and a backfill of every existing recipe. The user has directed that mapv10 use open archetype composition instead: recipes name vocabulary tokens, and new tokens land by editing the registry rather than by bumping the recipe schema.

The future-proofing rationale: new morphology families surface as the project ships. A Mediterranean-like archetype, a glacier-dominated archetype, an island-archipelago-only archetype - each needs a different combination of orogen kinds, craton kinds, rainfall patterns, and coast policies. None of those combinations can be predicted at M11. Treating the archetype as a composition of independent tokens keeps the door open without recipe-schema churn.

The token-id approach has a second benefit: the bundled vocabulary instance is a real artifact the World Lab UX (M11k) reads to populate dropdowns, build tooltips, and present AAA references. An enum-closed archetype would force the UX to ship the same metadata internally; the registry centralizes it.

The vocabulary registry​

schema/world-vocabulary.schema.json defines the registry shape. The bundled instance at vocabulary/default-world-vocabulary.json is the canonical token universe for M11.

Nine token categories live in the registry. Each is a separately versionable list:

  • orogenKinds - mountain-belt families. M11 commits seven: active-margin, collisional, hotspot-volcanic-arc, passive-margin, rift-flank, residual-eroded, transform-margin.
  • cratonKinds - continental basement families. M11 commits three: shield, platform, accreted-terrane.
  • ageBands - tectonic age bands with an erosionMaturity scalar that drives Stage 3 erosion. M11 commits five: young (0.15), mature (0.45), old (0.75), ancient (0.95), mid (0.30).
  • rainfallPatterns - climate families. M11 commits six: zonal-temperate, zonal-tropical, monsoonal, orographic-dominant, arid-continental, rift-driven.
  • residualHighlandKinds - shapes of residual relief on cratons. M11 commits five: flat, eastern-escarpment, residual-ranges, shield-dome, atlas-style-fold-belt.
  • interiorBasinKinds - basin morphologies in the craton interior. M11 commits five: arid-interior, endorheic-basins, wet-interior, rift-valley, none.
  • islandPolicies - offshore island patterns. M11 commits four: no-islands, small-coastal, archipelago-fringe, scattered-major.
  • isthmusPolicies - continental-edge isthmus patterns. M11 commits three: mainland-only, one-isthmus, broken-isthmus.
  • nameStyles - phonological style for procedurally-generated feature names. M11 commits four: archetype-default, classical, high-fantasy, germanic-tolkien.

Every token carries an id, displayName, and definition. Most tokens also carry an aaaReference field naming the real-world morphology that inspired them. Some categories carry category-specific extras: orogenKinds carry defaultLengthKm, defaultHeightMeters, defaultAsymmetryFactor, and windwardSidePolicy; cratonKinds carry defaultAgeBand and defaultAreaFraction; ageBands carry erosionMaturity; rainfallPatterns carry defaultOrographicStrength.

Adding a new token is two steps: append it to the bundled vocabulary instance with the required fields; reference it from a recipe. No schema change is needed unless the token category itself is new.

The four starter archetypes​

South-America-like (active margin + shield)​

AAA reference: Andes mountain belt plus the Brazilian Shield. The contemporary South American continent is the canonical active-margin archetype: a long, linear, coast-parallel cordillera on the west; a foreland basin (the Llanos and the western Amazon foreland) immediately east of the cordillera; a vast ancient shield (the Brazilian and Guianan shields) filling the eastern two-thirds of the continent.

Tokens used: orogen kind active-margin; craton kind implicit through ageBand: ancient and residualHighlandPolicy: residual-ranges plus interiorBasinPolicy: wet-interior; rainfall pattern orographic-dominant; coast policy small-coastal + mainland-only; custom-anchor policy hard-directive-overrides-archetype.

Morphology that should emerge: a single high primary cordillera along the west coast with peaks in the 3,500-5,500 m band; a foreland basin between the cordillera and the shield interior, 100-400 m deep; a wet craton interior with multiple major rivers (Strahler order three or higher) draining east; short, steep, west-coast drainages; smooth-to- moderately-jagged east coast with small islands.

Forbidden-pattern absences: no closed-ellipse lake polygons (the recipe carries no custom-lake directive); no hardcoded river-node geometry (the major-river count is soft and the generator routes from flow products); no hardcoded place names.

Australia-like (old craton + eastern escarpment + arid interior)​

AAA reference: the Australian continent. An ancient shield dominates the interior; an eastern escarpment runs along the east coast (the Great Dividing Range); the interior is arid with endorheic basins (Lake Eyre basin); the rest is dry continental.

Tokens used: orogen kind residual-eroded (the Great Dividing Range is an old eroded fold belt, not an active orogen); craton age band ancient; rainfall pattern arid-continental; residual-highland policy residual-ranges; interior-basin policy endorheic-basins; coast policy small-coastal + mainland-only.

Morphology that should emerge: a single residual orogen along the east coast in the 800-1,800 m band; a vast central shield occupying 55-75% of the continent area; one to three endorheic basins on the shield interior, 200-800 m deep; one to three interior basins, 100-350 m deep; few major rivers (the AAA reference has only a handful of named systems); modest coast jaggedness.

Forbidden-pattern absences: no closed-ellipse lakes; no fixed river-node chain; the great-central-dry-sink directive is a custom-dry-sink request, not an authored ellipse.

Europe-like (collisional fragmented)​

AAA reference: the Alpine-Carpathian-Pyrenees system plus the Baltic Shield. Multiple collisional orogens cut through the continent in different orientations; foreland basins flank each orogen; the Baltic Shield in the north anchors the ancient interior; the western and northern coasts are jagged with fjord potential; temperate zonal rainfall dominates.

Tokens used: two orogens both of kind collisional with different azimuth bands (one E-W like the Alps, one N-S like the Pyrenees); craton age band ancient; rainfall pattern zonal-temperate; residual-highland policy shield-dome; interior-basin policy wet-interior; coast policy archipelago-fringe + broken-isthmus.

Morphology that should emerge: two to three primary belts (the recipe hard-fails outside that range); two to three foreland basins (hard); jagged northern coast with strong fjord likelihood; three to six major rivers including the soft great-pass-between-collisionals directive linking the two orogens.

Forbidden-pattern absences: the pass-between-orogens directive uses between-anchors placement and references the two orogen ids, not a hardcoded ridge node.

Africa-like (shield + rift + Atlas-style margin)​

AAA reference: the African continent. An ancient shield occupies the center; the East African Rift cuts through the eastern half with rift-flank highlands and a chain of rift lakes; an Atlas-style fold belt runs along the north coast; the interior is arid in the north, savanna in the center, and forested in the equatorial belt.

Tokens used: two orogens of different kinds (active-margin for the Atlas-style fold belt; rift-flank for the East African Rift flanks); craton age band ancient; rainfall pattern rift-driven; residual-highland policy shield-dome; interior-basin policy arid-interior; coast policy scattered-major + one-isthmus.

Morphology that should emerge: exactly two primary belts (the recipe sets exact: 2); a central shield occupying 50-70% area; two to four interior basins; one to two endorheic basins; a soft custom-lake rift directive placed along a near-meridional axis (the great-rift-lake).

Forbidden-pattern absences: the rift lake is a directive resolved into the hydrology lake-polygon family (marching squares), not an authored ellipse; the rift-flank orogen is twinned by the generator from a single declaration rather than authored as two ridge chains.

Composing new archetypes​

When the four starter presets do not match the continent the author wants:

  1. Pick an orogen combination. Decide what mountain types belong. The four presets cover most common combinations, but combinations like "transform margin + collisional interior" (California + Sierras-like) are not represented. Choose tokens from orogenKinds and place each with coast-parallel, interior-axis, or archetype-derived mode.

  2. Pick a craton combination. Most continents have a single dominant craton, but accreted-terrane belts paired with shields are common (the Cordilleran terrane belt + North American craton, for instance). Multiple cratons in archetype.cratons[] are supported.

  3. Pick rainfall. Match the prevailing wind direction to the orogen axis. Zonal-temperate for mid-latitude continents with westerly winds; zonal-tropical for low-latitude continents with trade winds; monsoonal for continents where seasonal wind reversal is the dominant control; orographic-dominant for continents where a single orogen overwhelms the zonal pattern (Andes, Western Ghats); arid-continental for dry interior continents (Australian interior, Central Asia); rift-driven for continents where rift flanks dominate the rainfall pattern.

  4. Pick basin counts. Active-margin recipes want one or two foreland basins. Collisional recipes want foreland basins on both flanks of each orogen. Old-craton recipes want multiple endorheic basins. Rift recipes want interior basins (the rift floor itself is a basin family).

  5. Pick coast policy. Match coast jaggedness and fjord likelihood to the morphology. Glacier-imprinted coasts (Norway, Patagonia) have high fjord likelihood. Sediment-loaded passive margins (eastern North America, eastern South America) have low jaggedness and few islands. Active-margin coasts have moderate jaggedness with small coastal islands.

  6. Pick directive policy. hard-directive-overrides-archetype is the permissive default that lets directives override archetype constraints when they conflict. archetype-overrides-soft-directive is stricter: only hard directives can override archetype declarations. directives- suggest-only and directives-forbidden are strict modes for recipes that want archetype-only control.

AAA inspiration references​

Per-archetype real-world references:

  • South-America-like - Andes (active-margin cordillera); Brazilian Shield (ancient craton); Amazon basin (foreland-to-wet-interior drainage); Atacama (rain-shadow desert).
  • Australia-like - Australian Shield (ancient craton interior); Great Dividing Range (residual-eroded eastern escarpment); Lake Eyre Basin (endorheic interior); Western Australian arid interior.
  • Europe-like - Alps (collisional E-W orogen); Pyrenees (collisional N-S orogen); Baltic Shield (ancient craton); Norwegian fjord coast (glacial coast jaggedness); Mediterranean foreland basins.
  • Africa-like - East African Rift (rift-flank orogen + interior rift lake); Atlas Mountains (active-margin fold belt on north coast); African Shield (ancient shield); Congo basin (wet interior); Sahara (arid-continental rainfall).
  • Other AAA targets the project may pursue in M12+ - Himalayas (collisional + Tibetan plateau); Indonesian arc (hotspot-volcanic-arc + archipelago); North American Cordillera (active-margin + accreted- terrane); Iberian peninsula (Mediterranean transform-margin).

Per-engineering technique references:

  • Priority-flood DEM conditioning - Barnes et al., "Priority-flood: An optimal depression-filling and watershed-labeling algorithm for digital elevation models", Computers & Geosciences, 2014.
  • Anisotropic uplift fields - Whipple & Tucker, "Dynamics of the stream-power river incision model: implications for height limits of mountain ranges, landscape response timescales, and research needs", Journal of Geophysical Research, 1999.
  • Ridged multifractal noise - Musgrave, "Methods for realistic landscape imaging", chapter in Texturing and Modeling (3rd ed., 2003).
  • Marching squares lake polygons - Lorensen & Cline, "Marching cubes: A high resolution 3D surface construction algorithm", SIGGRAPH 1987 (the 2D version is well-known).
  • Orographic rainfall - Roe, "Orographic precipitation", Annual Review of Earth and Planetary Sciences, 2005.

What archetypes do NOT do​

An archetype is a declarative morphology family. It does NOT own:

  • Renderer settings. Material constants, opacity, fade duration, shader uniforms, label styling, overlay colors, semantic-zoom policies are all renderer concerns. They live in the viewer, not in the recipe.
  • Scale preset choice. The province-slice / regional-slice / realm-slice / continent selection is owned by GeneratorConfig, not by the recipe. The same recipe runs at every scale preset.
  • Seed selection. The seed is a CLI argument. The recipe is replayable across seeds.
  • Determinism opt-out. The canonicalization block is const-valued at every nested field. Recipes cannot opt out of sorted keys, shortest round-trip f64 representation, LF line endings, or UTF-8 NFC encoding.
  • Bypass of satisfaction reporting. emitUnsatisfiedHardFails is const true. Hard failures are always reported. Recipes cannot silence them.