World Intent Directives Reference

What directives are

A World Intent Directive is a declarative custom-anchor request. The recipe author writes a directive saying "I want a feature of this kind, at this placement, with these constraints," and the generator resolves the directive during the terrain-genesis or hydrology stages. After resolution, the generator writes a resolutionStatus payload back into the directive document describing what was satisfied and where the resolved feature ended up.

Directives replace post-generation manual editing. Before M11, the recipe- equivalent surface (the hand-authored generator stages) could only be modified by editing Rust source. Directives let recipe authors request specific named features without touching the generator at all.

Directives are resolved, not placed verbatim. A near-point directive with point: (0.92, 0.55) and toleranceKm: 80 says "the generator should find a suitable feature within 80 km of (0.92, 0.55)." The generator decides exactly where the feature ends up based on its terrain and hydrology products, then reports the resolved coordinates back in resolutionStatus.resolvedCoordinatesKm[].

A directive is a request, not a command. The generator may fail to satisfy it. The author reads resolutionStatus.state and satisfactionScore to understand what happened.

The 13 committed kinds for M11

custom-basin

Request a topographic basin (closed depression) at a specific placement.

• Placement modes: any of near-point, between-anchors, along-axis, inside-selected-area, archetype-derived.
• Constraints that apply: terrainConstraints.requireBasinFloor, maxElevationMeters, maxSlopeDegrees; hydrologyConstraints. mustBeFreshwater, mustContainLake.
• AAA example: "place a Tibetan-plateau-like high closed basin near the intersection of two collisional orogens" -> between-anchors with both anchor ids set to the orogens, requireBasinFloor: true, minElevationMeters: 4000.

custom-valley

Request a long linear topographic depression (valley) between two anchors or along an axis.

• Placement modes: between-anchors, along-axis, inside-selected-area.
• Constraints: terrainConstraints.maxSlopeDegrees (valleys are gentle); hydrologyConstraints.mustTouchRiver (most valleys carry rivers).
• AAA example: "carve a Rhine-Valley-like rift-floor between the two Alpine collisional segments" -> between-anchors, mustTouchRiver: true, naming the two orogen ids.

custom-pass

Request a saddle (low point) on a ridge.

• Placement modes: between-anchors (the common case; names the two ridge segments the pass connects), near-point, archetype-derived.
• Constraints: terrainConstraints.requireSaddle: true, maxElevationMeters (capping the saddle height).
• AAA example: "place a Brenner-Pass-like saddle between the two Alpine segments at no more than 1800 m" -> between-anchors, requireSaddle: true, maxElevationMeters: 1800 (this is exactly the Europe-like preset's great-pass-between-collisionals directive).

custom-ridge

Request a secondary or named ridge.

• Placement modes: along-axis, between-anchors, near-point, inside-selected-area.
• Constraints: terrainConstraints.minElevationMeters, requireRidgeFlank: true.
• AAA example: "add a Sierra-Madre-like secondary ridge inboard of the primary cordillera" -> along-axis parallel to the primary orogen.

custom-plateau

Request an elevated plateau (high-elevation flat area).

• Placement modes: inside-selected-area (common; the plateau lives inside an orogen segment or a craton), near-point, archetype-derived.
• Constraints: terrainConstraints.minElevationMeters, maxSlopeDegrees (plateaus are flat by definition).
• AAA example: "place a Tibetan-Plateau-like high plateau between two collisional orogens" -> between-anchors, minElevationMeters: 4500, maxSlopeDegrees: 5.

custom-lake

Request a freshwater or saline lake.

• Placement modes: near-point, along-axis (for rift lakes), inside-selected-area (for basin-floor lakes).
• Constraints: terrainConstraints.requireBasinFloor: true; hydrologyConstraints.mustBeFreshwater, mustContainLake: true.
• AAA example: "place a Lake-Tanganyika-like elongated rift lake along the East African Rift axis" -> along-axis with widthKm: 40 (the Africa-like preset's great-rift-lake directive uses this shape).

custom-river-mouth

Request a major river-mouth (river terminus at the coast).

• Placement modes: near-point, archetype-derived.
• Constraints: hydrologyConstraints.mustBeNavigable, mustBeFreshwater.
• AAA example: "place an Amazon-like navigable river mouth at the east coast" -> near-point at (0.92, 0.55), toleranceKm: 80, mustBeNavigable: true, mustBeFreshwater: true (this is exactly the South-America-like preset's great-eastern-river-mouth directive).

custom-dry-sink

Request a dry endorheic sink (closed depression with no permanent water).

• Placement modes: near-point, inside-selected-area, archetype-derived.
• Constraints: terrainConstraints.requireBasinFloor: true, maxElevationMeters (often negative or low); hydrologyConstraints. mustBeDrySink: true.
• AAA example: "place a Lake-Eyre-like or Death-Valley-like dry sink in the arid interior" -> near-point deep in the craton (this is exactly the Australia-like preset's great-central-dry-sink directive).

custom-isthmus

Request a narrow land bridge connecting the continent to a neighbor.

• Placement modes: near-point (specifying which coast edge the isthmus extends from), along-axis.
• Constraints: terrainConstraints.maxElevationMeters (isthmuses are typically low).
• AAA example: "place a Panama-Isthmus-like land bridge on the north coast" -> near-point at the desired coast edge.

custom-coastal-plain

Request a wide coastal plain (low-relief band along a coast).

• Placement modes: near-point with toleranceKm; along-axis parallel to a coast edge; archetype-derived.
• Constraints: terrainConstraints.maxSlopeDegrees, maxElevationMeters.
• AAA example: "carve a Gulf-Coast-like wide coastal plain along the south coast" -> along-axis parallel to the south edge with a width hint in extentKm.maxLengthKm.

settlement-candidate

Request that the generator mark a Location as a settlement candidate. The directive does not place a settlement; it tags a Location for downstream consumption.

• Placement modes: near-point (with toleranceKm), inside-selected-area.
• Constraints: hydrologyConstraints.mustTouchRiver, mustBeFreshwater; terrainConstraints.maxSlopeDegrees.
• AAA example: "mark a Location near (0.5, 0.5) as a settlement candidate, must touch fresh water" -> near-point, mustTouchRiver: true, mustBeFreshwater: true.

starting-zone

Request a starting-zone marker for downstream gameplay (Valenar enrichment, future game logic).

• Placement modes: near-point, inside-selected-area, archetype-derived.
• Constraints: any combination of terrain and hydrology constraints the author wants the starting zone to satisfy.
• AAA example: "mark a starting zone in the foreland basin near the river mouth" -> near-point close to a custom-river-mouth directive.

named-feature

Request that the generator assign a specific name to a feature it would otherwise auto-name.

• Placement modes: any.
• Constraints: namingPreferences.overrideName is the primary payload; the directive can also carry terrain and hydrology constraints to select which feature gets the name.
• AAA example: "name the primary western cordillera 'Sky Wall'" -> inside-selected-area referencing the orogen id, overrideName: "Sky Wall".

Placement modes

All five committed modes:

near-point

The generator places the feature within toleranceKm of the requested point (fractional coordinates). The exact resolved location depends on the terrain and hydrology products; the generator picks the best-matching cell within the tolerance band.

• Failure mode: no suitable feature exists within the tolerance band. Hard directives fail; soft directives report unsatisfied.

between-anchors

The generator places the feature between two named anchors. Anchors are ids of features the generator has already emitted: orogen segment ids, basin candidate ids, craton ids. The generator picks the best path between the two anchors and places the directive feature along it.

• Failure mode: one or both anchor ids do not resolve to a generated feature. Hard directives fail; soft directives report unsatisfied with the missing anchor id in resolutionStatus.reasons[].

along-axis

The generator places the feature along a linear axis with fromFraction and toFraction endpoints (fractional coordinates) and an optional widthKm. Used for rift lakes, elongated valleys, coastal plain bands.

• Failure mode: no suitable corridor exists along the axis. Hard directives fail; soft directives report unsatisfied.

inside-selected-area

The generator places the feature inside a named selected area. The selectorId is the id of a tectonic province, a craton, an orogen segment, or a basin candidate. The generator picks a location within the selected area that satisfies the directive's constraints.

• Failure mode: the selectorId does not resolve to a generated area or no point inside the area satisfies the constraints. Hard directives fail; soft directives report unsatisfied.

archetype-derived

The generator picks placement based on the archetype's morphology. Used when the author wants the generator to make the call.

• Failure mode: the archetype produces no morphology compatible with the directive kind. Hard directives fail; soft directives report unsatisfied.

Soft / hard / suggest semantics for directives

Directives carry the same three priorities as recipes:

• hard - the directive must resolve. If it cannot, the generator emits a satisfaction record with state: unsatisfied, increments the manifest hard-fail count, sets manifest.validationStatus to fail, and (if the recipe's haltOnHardFail is true) halts the run.
• soft - the generator best-efforts. The state field reports satisfied, soft-satisfied, or unsatisfied; the satisfactionScore field reports a number in [0, 1]. The run continues.
• suggest - the generator best-efforts and reports satisfaction without a score.

The recipe's customAnchorPolicy.conflictResolution controls how a directive interacts with the archetype declarations:

• hard-directive-overrides-archetype. Hard directives override archetype declarations when they conflict. The default in the four starter presets.
• archetype-overrides-soft-directive. Soft directives that conflict with archetype declarations are dropped to unsatisfied. Hard directives still override.
• directives-suggest-only. All directives are treated as suggest regardless of their declared priority. Used by recipes that want the archetype to be the strict source of truth.
• directives-forbidden. Directives are rejected entirely. The recipe validator hard-fails if any directives are present.

resolutionStatus contract

The resolutionStatus field is generator-owned. The contract:

• Authors do not write to resolutionStatus. Every author-side write is overwritten by the next generator run. The schema does not forbid authoring it (no const field), but the validator script flags any authored resolutionStatus as a violation.
• The generator overwrites resolutionStatus on every run. The generator never preserves prior-run resolution; each run is independent.
• The state field reports one of unresolved, satisfied, soft-satisfied, or unsatisfied. unresolved is the default before the resolution stage runs; the generator should always overwrite it.
• The satisfactionScore field is a number in [0, 1] for soft directives. Omitted for hard and suggest directives.
• The reasons[] field carries human-readable explanations for the resolution outcome. Authors read this to understand why a soft directive scored less than 1.0 or why a hard directive failed.
• resolvedCoordinatesKm[] carries the resolved fractional-to-km coordinates. Empty when the directive did not resolve.
• resolvedFeatureRefs[] carries the ids of the generated features the directive resolved to (e.g. the basin candidate id for a custom-basin, the river segment ids for a custom-river-mouth).

Examples

South-America-like: great-eastern-river-mouth

{
  "intent_id": "great-eastern-river-mouth",
  "kind": "custom-river-mouth",
  "priority": "soft",
  "placement": {
    "mode": "near-point",
    "point": { "xFraction": 0.92, "yFraction": 0.55 },
    "toleranceKm": 80
  },
  "hydrologyConstraints": {
    "mustBeNavigable": true,
    "mustBeFreshwater": true
  },
  "namingPreferences": { "nameStyle": "archetype-default" }
}

A soft request for an Amazon-analog navigable river mouth near the east coast. The 80 km tolerance gives the generator room to align the mouth with the actual main river trunk emerging from the wet-interior craton.

Australia-like: great-central-dry-sink

{
  "intent_id": "great-central-dry-sink",
  "kind": "custom-dry-sink",
  "priority": "soft",
  "placement": {
    "mode": "near-point",
    "point": { "xFraction": 0.35, "yFraction": 0.55 },
    "toleranceKm": 150
  },
  "terrainConstraints": {
    "requireBasinFloor": true,
    "maxElevationMeters": 50
  },
  "hydrologyConstraints": { "mustBeDrySink": true }
}

A Lake-Eyre-analog dry sink in the central arid interior. The wide 150 km tolerance acknowledges that the actual lowest point of the central basin is generator-determined.

Europe-like: great-pass-between-collisionals

{
  "intent_id": "great-pass-between-collisionals",
  "kind": "custom-pass",
  "priority": "soft",
  "placement": {
    "mode": "between-anchors",
    "anchorIds": ["southern-collisional", "western-collisional"]
  },
  "terrainConstraints": {
    "requireSaddle": true,
    "maxElevationMeters": 1800
  }
}

A Brenner-Pass-analog saddle connecting the two collisional orogens at no more than 1800 m. The between-anchors placement references the orogen ids declared in archetype.orogens[].

Africa-like: great-rift-lake

{
  "intent_id": "great-rift-lake",
  "kind": "custom-lake",
  "priority": "soft",
  "placement": {
    "mode": "along-axis",
    "axis": {
      "fromFraction": { "xFraction": 0.71, "yFraction": 0.45 },
      "toFraction":   { "xFraction": 0.70, "yFraction": 0.62 }
    },
    "widthKm": 40
  },
  "terrainConstraints": { "requireBasinFloor": true },
  "hydrologyConstraints": { "mustBeFreshwater": true }
}

A Lake-Tanganyika-analog elongated freshwater rift lake along a north-south axis on the eastern half of the continent. The along-axis mode with widthKm: 40 shapes a long, narrow lake rather than a circular one.

Deferred kinds

The following directive kinds are NOT committed in M11:

• custom-volcano - hotspot or volcanic-arc peak. Deferred because M11 does not yet model volcanism as a generator stage. The vocabulary carries hotspot-volcanic-arc as an orogen kind, but the directive kind is M12+.
• custom-archipelago - named offshore island chain. Deferred because the M11 island-policy surface (islandPolicies) handles the archetype-level request; per-archipelago naming and placement is M12+.
• custom-strait - narrow ocean passage between two land masses. Deferred because the M11 coast-policy surface does not yet model multi-continent geometry; M12+ work.
• custom-canyon - deeply incised valley. Deferred because the hydrology stage in M11d focuses on river-network and lake topology, not on canyon-scale incision; canyons emerge from the stream-power erosion in Stage 3 but are not directive-addressable in M11.
• custom-glacier - mountain glacier or ice cap. Deferred because M11 does not model glaciation. The fjord-likelihood field in coastPolicy is the only glacial-imprint surface in M11.

Adding any of these in M12+ requires:

• Appending the kind to the world-intent-directives.schema.json enum (a v1 -> v2 bump on that schema).
• Adding any new vocabulary tokens needed (e.g. a volcanoKinds category if the directive needs sub-kinds).
• Implementing resolution in the redesigned Stage 2 (terrain genesis) or Stage 4 (hydrology) or a new stage.
• Documenting the new kind in this reference.

Authors should not use these tokens in M11 recipes. The schema enum rejects them, which keeps the recipe surface honest about what the generator can deliver.