Skip to main content

State Axes and Thresholds

Status: authoritative design contract for the three named state axes. Feature discovery axis: authoritative — FeatureDiscoveryState enum is committed in Generated/Locations/FeaturePlacement/FeaturePlacementTypes.cs and aligns with gd-feature-generation-contract.md. The forward-compat int DiscoveryIntensity nuance field on FeatureData was added in Wave R-3 (2026-05-10); threshold semantics within each ladder label remain TBD per a future balance pass. Location knowledge axis: current — LocationKnowledgeState enum is committed in Generated/Locations/LocationKnowledgeTypes.cs and aligns with the "Knowledge Values" block in gd-location-generation-contract.md. The prototype int Explored field was retired in Wave R-1 (2026-05-10); LocationData.KnowledgeState plus the forward-compat LocationData.KnowledgeIntensity are the runtime state-storage points. Site state axis: current prototype shape via LocationContentState enum in Generated/Locations/FeaturePlacement/FeatureContentTypes.cs; numeric intensity field is not yet implemented. Status terms follow pr-status-and-sync-policy.md.

Purpose​

This document defines the three state axes used across the Valenar world model: the Feature discovery axis, the Location knowledge axis, and the Site state axis. Each axis is a named ladder with labels, optional numeric intensity, and a single owning subsystem. This document is the authoritative reference for which subsystem owns each axis and what the committed labels are.

A state axis answers a "how known / how progressed" question for a particular world entity. The three axes are independent: a Feature can be Surveyed inside a Location that the player has only Sighted; a Site can be Developed inside a Location that the player Claimed. Cross-axis rules are described at the end of this doc and are explicitly TBD.

Feature Discovery Axis​

Owner: Feature generation system, gd-feature-generation-contract.md.

Committed enum: FeatureDiscoveryState in Generated/Locations/FeaturePlacement/FeaturePlacementTypes.cs. The nine committed labels, in ladder order, are:

  • Hidden — feature exists but the player has no knowledge of it.
  • Hinted — the player has a clue but not the real identity.
  • Discovered — the player knows the Feature category or name.
  • Surveyed — quality, risk, blockers, and main outputs are known.
  • Handled — threat or obstacle has been resolved, but the site may not be developed.
  • Secured — controlled and protected.
  • Developed — owned or used as an ongoing Site/improvement.
  • Depleted — resource exhausted or inactive (terminal for productive Features).
  • Destroyed — the Feature has been removed from the world (terminal for destructive endings).

These labels are the committed runtime vocabulary. They match the ladder in gd-feature-generation-contract.md under "Existence Versus Discovery". Do not introduce alternate labels in live docs without updating both this page and the enum.

Numeric intensity: the design intent is that each non-terminal label corresponds to an intensity range on a 0–100 scale, allowing sub-label partial progress (e.g., Discovered at intensity 30 is further along than Discovered at intensity 25). The intent ranges are:

  • Hidden — intensity 0
  • Hinted — intensity 1–24
  • Discovered — intensity 25–49
  • Surveyed — intensity 50–74
  • Handled — intensity 75–89
  • Secured — intensity 90–95
  • Developed — intensity 96–100

Numeric thresholds (1–24, 25–49, ...) are target thresholds; TBD in balance pass — they are not committed values. Use these ranges as design guidance, not as runtime constants.

Numeric intensity field: int DiscoveryIntensity on FeatureData. Default 0. Bare integer per the unified convention established by R-1's KnowledgeIntensity and R-2's StateIntensity. The field is wired through H.DiscoveryIntensity in Generated/Hashes.cs + Generated/Declarations.cs and read/written via the Feature branch of HostBridge (Wave R-3, 2026-05-10). The field tracks intensity on the DiscoveryState ladder. Numeric thresholds within each ladder label remain TBD per a future balance wave; until those thresholds are committed, DiscoveryIntensity is a transparent nuance field that consumers can display without acting on. Wire projection (FeatureSnapshot.discoveryIntensity) is deferred to a future Server wave, mirroring the deferral pattern from R-2 (SiteSnapshot).

Pre-existing drift note: the Feature contract doc (gd-feature-generation-contract.md) lists an Interacting state that the committed FeatureDiscoveryState enum does not carry. This drift is out of scope for Wave R-3 and is tracked separately.

Depleted and Destroyed are terminal labels and do not participate in the 0–100 intensity scale.

Location Knowledge Axis​

Owner: Location system, gd-location-generation-contract.md.

Committed enum: LocationKnowledgeState in Generated/Locations/LocationKnowledgeTypes.cs. The eight committed labels, in ladder order, are:

  • Unknown — fog of war; the player has no knowledge of the location.
  • Sighted — the player has seen the location at a distance or via a lead, but has not investigated it.
  • Scouted — the player has visited and surveyed the immediate surroundings.
  • Surveyed — quality, risk, blockers, and main outputs are known (note: shares a label with the Feature axis; context disambiguates by axis owner — Location vs Feature.)
  • Secured — controlled and protected.
  • Claimed — the player owns the location through settlement designation.
  • Cleansed — taint, threat, or hostile occupation has been resolved.
  • Developed — the location is built up as part of an owned settlement or outpost.

These labels are committed runtime vocabulary (Wave R-1, 2026-05-10). The committed LocationData.KnowledgeState field (type LocationKnowledgeState) is the runtime state-storage point. The forward-compat LocationData.KnowledgeIntensity field (int) carries sub-label nuance and is committed but its threshold semantics remain TBD.

Numeric intensity: the generation contract names a surveyProgress field as part of the knowledge-values block. The runtime carries this as LocationData.KnowledgeIntensity (default 0 on every location, including the start camp). Numeric thresholds — for example, the intensity range that maps to each ladder rung — are TBD per future balance pass. Until those thresholds are committed, KnowledgeIntensity is a transparent nuance field that consumers can display without acting on. The previous int Explored prototype drift was closed by Wave R-1; see pr-code-sync-audit.md.

Site State Axis​

Owner: Site system, gd-sites-and-dungeons.md.

Committed enum: LocationContentState in Generated/Locations/FeaturePlacement/FeatureContentTypes.cs. The ten committed labels, in ladder order, are:

  • Hidden — site exists but the player has no knowledge of it.
  • Hinted — the player has a clue or partial sign of the site.
  • Discovered — the player knows the site exists and its category.
  • Surveyed — site interior or yields are partially mapped.
  • Active — site is currently in active use, exploration, or combat.
  • Handled — primary threat or blocker resolved.
  • Secured — site is controlled and protected.
  • Developed — owned or used as an ongoing Site/improvement.
  • Depleted — site yield exhausted (terminal for productive sites).
  • Destroyed — site removed from the world (terminal).

These labels are committed runtime vocabulary. SiteData carries two LocationContentState fields — DiscoveryState (visibility/discovery axis) and State (progress ladder). StateIntensity tracks intensity on the State axis. The Site State Axis is the State ladder, not the DiscoveryState ladder.

Numeric intensity: int StateIntensity on SiteData. Default 0. Bare integer per the unified convention established by R-1's KnowledgeIntensity. The field is wired through H.StateIntensity in Generated/Hashes.cs + Generated/Declarations.cs and read/written via the Site branch of HostBridge. Numeric thresholds within each ladder label remain TBD per a future balance wave; until those thresholds are committed, StateIntensity is a transparent nuance field that consumers can display without acting on. Wire projection (SiteSnapshot) is deferred to a future Server wave.

Cross-Axis Relationships​

The three axes are independent. Examples of valid combinations:

  • A Feature can be Surveyed inside a Location that is only Sighted — knowing one feature in a Location well does not mean the Location itself is fully scouted.
  • A Site can be Developed inside a Location that is Claimed (not yet Cleansed) — improvement of one Site does not require the whole Location to be cleansed.
  • A Feature can be Hidden inside a Surveyed Location — survey effort does not automatically reveal every Feature.

Cross-axis rules — for example, "a Site cannot be in Developed state unless the containing Location is at least Sighted" — are TBD and are not yet committed. When such rules are added, this section will become normative.