Valenar - World Generation Contract

This document is the top-level contract for Valenar world generation. It defines the boundary between production physical world data, Valenar gameplay map facts, Location records, Feature populations, pressure systems, and UI consumers.

Status: planned authoritative contract. The current executable Valenar map is a stepping-in prototype runtime fixture. It uses a low-density, once-only SECS generator plus server-side Voronoi geometry for the current example map. Any rule below is target behavior unless a current implementation note explicitly says otherwise. Later campaign/world maps may be much larger and may use larger or variable-sized Locations.

Authority

Generation ownership is split:

production world data provider:
  physical world, hierarchy ids, topology, hydrology, scalar layers,
  classification layers, deterministic WorldData, content hash

Valenar world adapter:
  immutable gameplay map facts derived from WorldData

Valenar simulation:
  ownership, discovery, pressure changes, Features, Sites, activities,
  modifiers, channels, settlement state

Valenar UI:
  reads snapshots and presents known state

The UI, renderer, and SECS systems must not infer missing geography. If Valenar needs a map fact, the adapter contract must expose it.

Scope

This contract covers:

• source inputs
• required outputs
• scale budget
• world-data import boundary
• generation pipeline
• cross-document ownership
• determinism
• validation
• current prototype separation

Detailed child contracts:

• Location Generation Contract
• Feature Generation Contract

Non-Goals

This document does not define:

• production rendering implementation
• individual feature scripts
• final numeric balance
• MC combat internals
• district development internals
• final UI layout

Source Inputs

World generation consumes:

worldSeed
  world generation config
  world generation selections
  production WorldData
Valenar generation config
Valenar feature template registry
Valenar act/start constraints
Valenar pressure config
Valenar naming config

Production WorldData is immutable and validated before Valenar imports it.

Required production world-data inputs include:

metadata:
  seed
  contentHash
  worldWidth_m
  worldHeight_m
  heightmapResolution

scalar layers:
  elevation
  waterSurface
  temperature
  moisture
  flowAccumulation
  slope

classification layers:
  biome
  waterMask
  isLake
  isRiver

hierarchy fields:
  idLocation
  idProvince
  idArea
  idRegion
  locationHierarchy

topology structures:
  riverGraph
  corridorGraph
  thalwegGraph
  lakeComponents

If a target Valenar field has no source layer yet, the contract must say so. Do not fill missing fields with arbitrary random values and treat them as final.

Required Outputs

Valenar world generation outputs:

WorldMapFacts:
  seed
  worldDataContentHash
  generationVersion
  world dimensions
  region records
  area records
  province records
  location records
  location adjacency graph
  pressure source records
  feature records
  start selection record
  validation report

The output is deterministic and cacheable. Given the same production WorldData, Valenar generation config, feature definitions, and code version, the generated facts must be identical.

Scale Budget

Valenar targets a large playable world beyond the current example map. The design operates at strategic scale, not city-builder scale.

Authoritative scaling:

• A Province is roughly the size of an Estonian county (Järvamaa, ~2,600 km² with ~30,000 population) — a real administrative region the player rules at Count rank, not a town district.
• A Province contains 5 to 10 Locations.
• Therefore each Location is roughly 250-500 km² (an irregular Voronoi cell at this scale). The MC's marker on the map represents which Location contains the MC, not a tile they stand on. Travel between adjacent Locations is hours-to-days of in-world time, not minutes.
• The player's starting Shielded Zone is roughly 3 to 6 Provinces, so 15 to 60 Locations at game start.
• The full world contains roughly 50 to 150 Provinces (so 250 to 1500 Locations) spread across multiple Shielded Zones plus corrupted territory between them.

Rules:

• Locations are variable strategic units, not fixed tiles.
• Larger Locations are allowed where terrain density, water, hierarchy, or gameplay scale calls for it; 250-500 km² is the design centroid.
• Do not describe Valenar as a fixed hex or tile grid.
• Do not describe Valenar as a city-builder where the player paints individual buildings on a map; the strategic cell is the unit of player attention.
• Generated display names are never identity.

Current Prototype Boundary

The current live Valenar map is not the target generator.

Current prototype:

• runs MapGenerationSystem once at startup
• creates 1 Region, 2-3 Areas, 4-9 Provinces, and roughly 40-100 Locations
• places Features after hierarchy generation through generated placement profile/query data plus deterministic score, budget, spacing, and conflict selection
• assigns current example-map Voronoi geometry server-side
• exposes snapshot polygons, neighbours, and visible Features to the client

Target production:

• consumes production WorldData
• maps each Valenar Location to a production Location id
• imports real hierarchy, topology, scalar layers, and land/water type
• derives immutable gameplay map facts
• places Features by suitability, rarity, spacing, pressure, and story rules
• validates start constraints and all generated facts

Docs must clearly say whether they are describing current prototype behavior or target production-world behavior.

World-Data Import Boundary

Every Valenar Location maps to one production Location record. Valenar must not regenerate production geometry after import.

Import invariants:

every production Location id imported by Valenar has one Location record
every Location has exactly one Province parent
every Province has exactly one Area parent
every Area has exactly one Region parent
parent child collections match child parent ids
Location adjacency is symmetric
Location adjacency comes from production topology
Location polygons/centroids come from production world data or its projection
water and land Location kind rules are preserved

Valenar may derive additional gameplay graph fields such as route difficulty, route importance, claimability, and control-route state. Those fields must be derived from imported facts and simulation state.

Numeric Fact Ownership

Immutable generated map facts are host-owned fields:

fertility
forestCoverage
waterCoverage
mineralWealth
elevation
slope
moisture
routeImportance
baseThreat
shieldCoverage
corruption

SECS channels are resolved gameplay values:

FoodOutput
WoodOutput
MetalOutput
RouteSafety
RestSafety
ThreatLevel
SettlementSuitability
SurveyDifficulty

Province, Area, and Region terrain numbers are aggregates for display, selection, AI, and planning. They are not independent terrain truth. Prefer area-weighted aggregation from child Locations.

Generation Pipeline

Target pipeline:

1. Validate production WorldData.
2. Import hierarchy ids, location geometry, and topology.
3. Build Location records.
4. Aggregate physical layers into Location numeric facts.
5. Derive terrain classes and tags.
6. Derive travel and route facts.
7. Derive pressure fields from shield, gates, taint, distance, and geography.
8. Select starting Location using Nexus/Wardheart constraints.
9. Generate pressure sources and story-required Features.
10. Generate ordinary Feature candidates.
11. Place Features by suitability, budget, spacing, conflict, and synergy.
12. Initialize discovery and knowledge state.
13. Build initial activity availability.
14. Validate hierarchy, topology, facts, Features, pressure, and start.
15. Publish WorldMapFacts to runtime.

The order matters. Feature placement depends on Location facts, pressure, and story constraints. UI presentation comes after generated state exists.

Cross-Document Ownership

Use these docs as authorities:

gd-world-generation-contract.md:
  top-level generation boundary, inputs, outputs, world-data import, validation

gd-location-generation-contract.md:
  Location record shape, numeric facts, classes, tags, topology, knowledge,
  control, and settlement compatibility

gd-feature-generation-contract.md:
  Feature families, template shape, score-and-budget placement, discovery,
  activities, causal rewards, sites, and Feature validation

../systems/gd-world-pressure-nexus.md:
  shield, taint, gates, starting Nexus, leyline, shard, and pressure rules

../ux/gd-location-dossier.md:
  how known generated state is presented to the player

../systems/gd-settlements-and-outposts.md:
  how claimed Locations become footprint, districts, outposts, domains, and
  development plans

UX docs consume generated truth. They do not define spawning rules.

Determinism

Generation must be deterministic:

same worldSeed
same world data contentHash
same Valenar config
same feature definitions
same code version
-> same WorldMapFacts

Rules:

• Stable ids beat generated names.
• Sorting must use deterministic keys.
• Tie-breaks must use stable ids or seeded noise.
• Feature selection must not depend on dictionary iteration order.
• Validation must include enough hashes or snapshots to catch drift.

Validation Contract

World validation must check:

WorldData content hash is present
every imported Location has valid parent links
parent child collections are symmetric
adjacency is symmetric
land/water Location kind constraints hold
numeric ranges are bounded
coverage values are normalized
province/area/region aggregates match child data
starting Location passes Nexus/Wardheart rules
starting Nexus Feature exists
no generic settlement suitability unlocks founding
feature placements pass hard gates
feature density and spacing budgets hold
all visible activities reference existing entities
all modifiers target valid scopes

World generation without validation is incomplete.

Open Questions

• Is the 50-150 Province world-size range fixed, configurable per world, or seed-dependent within bounds?
• How are Provinces and Areas grouped into Shielded Zones — by Region boundary, by adjacency, or by a separate Zone hierarchy field?
• Which source layer should produce geology and mineral richness in production world data?
• Which source layer should produce ancientness/ruin potential?
• How many ordinary Features should exist per Province by family at the 250-500 km² Location scale?
• What is the exact serialized shape of WorldMapFacts?