Skip to main content

Defense Zones

This page owns the DefenseZone model: how Territories, Routes, and Sites are grouped into defensive responsibilities, how Forces are assigned to defend them, and how a ProvinceDefensePlan aggregates DefenseZones into a Province-level stance.

Role​

A DefenseZone is a player-assigned commitment to defend a specific group of nodes (Territories, Sites) and corridors (Routes) using a specific Force or Force pool. The DefenseZone records the detachment doctrine, reserve percentage, supply policy, fallback rules, and rules of engagement for that group.

DefenseZones become available at Act 5 (Province) when the player polity gains the Province rank and the standing-Force support that the ProvinceDefensePlan layer requires.

Design Reference: What This Is Not​

Rejected: HOI4 Continuous Front-Line Micro​

Hearts of Iron IV's defense model assigns units to a continuous front line defined by adjacency. Units micro-fill segments, patrol zones automatically, and combat resolves at the carpet level. This model is explicitly rejected for Valenar DefenseZones. Reasons:

  • It requires constant unit-density micromanagement inappropriate for an idle-cadence game (Valenar's design pacing keeps the player at strategic attention, not at micro-density attention).
  • It obscures the causal link between specific Sites, Routes, and the defense decisions that matter.
  • Continuous front-line geometry breaks down in a node-and-corridor world where passes, bridges, ward nodes, supply depots, and specific Sites are what actually matter — a continuous painted segment cannot tell the player which Site is at risk.

Rejected: Victoria 3 Opaque War Bars​

Victoria 3 abstracts fronts into invisible population-and-attrition comparisons with minimal player causality. Battle outcomes feel detached from the world; the player loses agency because they cannot trace the defense outcome back to a specific commitment. This is also rejected for Valenar DefenseZones. Defense decisions must be causally traceable: a DefenseZone is a commitment to defend specific Sites, Routes, and Territories; outcomes derive from those commitments and from the doctrine the player set.

Positive Reference: Node-And-Corridor Defense​

Valenar's defense model is node-and-corridor. The committed primitives:

  • Nodes — Sites (ward sites, strongholds, shrines, key supply depots), key Territories (choke points, river crossings, supply staging grounds), and special structures (bridges, ward-line anchors, gate-scar seal Sites).
  • Corridors — Routes between nodes. Losing a corridor lets hostile Forces bypass a node, sever supply, or split a DefenseZone into isolated fragments.
  • Defense — Forces assigned to defend specific nodes and corridors. The Force allocates detachments automatically per doctrine; the player can override individual detachment assignments or replace the DefenseZone's Force entirely.

The player reads the DefenseZone as a list of named nodes and corridors, a named Force, and a named doctrine. Every defense outcome is traceable back to those three things.

Positive Reference: Paradox-Style Macro Readability​

Paradox grand-strategy titles (CK3, EU4, Vic3) present standing defensive commitments as colored region overlays on the province map: a named realm's defended core regions, a marcher lord's holdings, a contested border march all show as readable, name-anchored area tinting on the strategic map. The macro presentation lets the player read the defensive picture at a glance; per-province detail is available on drill-in. This is adopted as the readability anchor for Valenar DefenseZone presentation.

A DefenseZone in Valenar shows on the strategic map as a tinted overlay on the Province polygons (Territories, Routes, and Sites within scope), color- coded by zone type (Capital / Heartland / Settlement / RouteCorridor / WardLine / FrontierScreen / Containment / Reserve) and labeled with the zone name and assigned Force. At Province / Crown scale the player reads the ProvinceDefensePlan as a tinted-overlay map of named zones; per-zone detail (doctrine, reserve %, fallback rules, supply policy, rules of engagement) is available on drill-in but does not crowd the macro view. The Crown-tier player operates on the tinted overlay; the per-zone setting sheet is for direct intervention when it matters.

Positive Reference: Open-World Strategy POI Clustering​

Open-world strategy and 4X UI patterns cluster point-of-interest markers as zoom-out aggregates: at low zoom a cluster medallion stands in for many underlying POIs; at high zoom the cluster fans out into individual markers. Valenar's DefenseZone overlay map UI is informed by this pattern.

DefenseZone-anchored POIs (assigned Forces, fallback Sites, supply depot markers, rules-of-engagement indicators) cluster on the strategic map per the same medallion / cluster / fanout-ring pattern as Site and Feature markers: at low zoom a Capital DefenseZone with three assigned Forces, two fallback Sites, and a supply depot collapses into a single cluster medallion summarizing the zone's commitment density; at high zoom the cluster fans out into one marker per Force, fallback Site, and depot. The cluster medallion is presentation only — the DefenseZone data row (carrying type, member nodes, member corridors, assigned Force, doctrine, reserve %, fallback rules, supply policy, ROE, threat priorities) remains the authoritative configuration surface. The tinted polygon overlay itself is also presentation: it is rendered from the DefenseZone's member node and corridor list, never edited by painting on the map. Cluster geometry and overlay tinting are never gameplay-authoritative; commit, override, redirect, and reconfigure all operate on the individual DefenseZone data row beneath the visuals.

DefenseZone Types​

The committed DefenseZone type list:

TypeDescription
CapitalThe Province capital and its immediate surrounding Territories; highest defense priority
HeartlandCore agricultural and population-bearing Territories; medium-high priority
SettlementA specific Settlement-containing Territory and its approach Routes
RouteCorridorA Route segment and the Territories along it; intended to keep supply and travel safe between two named endpoints
WardLineA line of ward-node Sites and the Territories between them; cleansing and corruption-resistance focus
FrontierScreenOuter Territories designated to absorb early hostile pressure, generate intelligence, and warn of advance; low expected hold strength
ContainmentA Territory or group of Territories established around an active Threat source (Demon Gate, taint front); intended to confine, not necessarily eliminate
ReserveUncommitted Territories held as fallback or reinforcement staging ground; the Force pool here is held back for response

DefenseZone types are gameplay primitives, not presentation labels. The type drives default doctrine, default reserve percentage, and the sub-activities the Force prefers when allocated to a zone of this type.

ProvinceDefensePlan​

A ProvinceDefensePlan is the Province-level aggregate of all DefenseZones within the Province. It is the canonical document the player reads when asking "how is this Province defended?" The plan records:

  • Which DefenseZones the Province maintains, and which type each is
  • The assigned Force (or Force pool) for each DefenseZone
  • Doctrine for each zone (Aggressive / Balanced / Defensive / Withdrawal-ready) — overrides the Force's default doctrine within this zone
  • Reserve percentage per zone (Force strength held uncommitted for response within the zone)
  • Fallback rules — where Forces retreat when a zone collapses; references another DefenseZone, a Reserve zone, or a named Site
  • Supply policy — which depots and Routes supply each zone; what happens to the zone if its supply Route is severed
  • Rules of Engagement — when to engage, hold, screen, or withdraw under the doctrine the zone was assigned
  • Threat priorities — which Threat sources and Site types to engage first when multiple threats are active simultaneously
  • Cross-zone reinforcement rules — which zones can pull strength from which Reserve zones, and under what conditions

A Province whose ProvinceDefensePlan.PlanState is Unplanned has no committed Force-level defense. Settlement garrisons defend the Province at the local scale, but the Province contributes NOTHING to adjacent Provinces' plans — adjacent plans must explicitly declare FrontierScreen Posture on their own DefenseZones to designate buffer responsibility. The previous "treated as Frontier Screen by adjacent Provinces' plans by default" rule is removed; silent inheritance of Posture across Province boundaries is forbidden. Unplanned Provinces surface as Current Plan urgency signals (per the Quest Thread urgency shape in gd-quest-thread-and-mission-state-machine.md, authored by Wave 3a-A) so the Crown player is invited to draft a plan rather than silently inheriting one.

PlanState​

Every Province with polity ownership carries a ProvinceDefensePlan row from the moment the Province is created. The plan's PlanState channel records its lifecycle position. There is no "missing plan" code path — Unplanned is the explicit starting state, not the absence of a row.

PlanState enum values (committed by Foundation Hardening resolver decision R4 on 2026-05-17 — the binding state-machine doc gd-state-machines-and-transitions.md is the canonical authoring surface; no separate ADR file backs this enum because Wave 2b explorer routing determined the state machine itself is the authoritative record):

ValueNameMeaning
0UnplannedDefault at Province creation; no DefenseZones committed; emits Current Plan urgency signal
1DraftingCrown has opened the plan and added at least one DefenseZone but has not committed; DefaultDoctrine and DefaultReservePercent apply as authoring defaults
2CommittedPlan is live; DefenseZones are active; tick pipeline honors Force assignments
3FailedA DefenseZone has failed and cascaded to plan-level failure (e.g., Capital zone lost; supply Route severed beyond endurance)
4RecoveredCrown has re-committed the plan after Failed; distinct from Committed so urgency surface and historical record can distinguish first-commit from recovery

Transitions:

  • Unplanned -> Drafting — Crown opens the plan UI for the Province.
  • Drafting -> Committed — Crown finalizes the plan; at least one DefenseZone with valid Posture and Force assignment is required for commitment.
  • Committed -> Failed — DefenseZone failure cascades to plan-level failure per ## Zone Failure And Recovery.
  • Failed -> Recovered — Crown re-commits the plan after failure.
  • Recovered -> Committed — collapse back to the standard committed state after a hysteresis window (<deferred-to-Wave-5a-runtime-backing>; predicate shape cited from the ad-0008 retirement-window precedent).

Runtime Backing Status: contract-only.

  • Host/Data owner: ProvinceDefensePlanData exists today; needs [SecsChannel] public int PlanState field added in the Wave 5a runtime-backing wave.
  • Read-model owner: ProvinceDefensePlansReadModel exists today; needs int State field added. The read-model emits Unplanned plans explicitly with State: Unplanned and never skips them; "no plan" is not a separate read-model code path.
  • Generated/.secs owner: the PlanState channel declaration lands in the Wave 5a Generated stand-ins paired with the matching .secs source.
  • Tests: <deferred-to-wave-7>.
  • Illegal fallback behavior: attempting to read Posture for an Unplanned Province must throw InvalidStateException at the runtime boundary; ReadModel skip of Unplanned plans is forbidden; client UI must render Unplanned with explicit visual treatment, not as a FrontierScreen tint or any other silent substitute.
  • Next closure wave: Wave 5a (parallel with R3 Realm rank closure).

Player Control Surface​

The player builds and maintains a ProvinceDefensePlan through this sequence:

  1. Select a Province; open its ProvinceDefensePlan.
  2. Add a DefenseZone — select a DefenseZone type; pick the Territories, Routes, and Sites that fall within the zone.
  3. Assign a Force (or Force pool) to the zone. The Force may be a newly-formed Force, an existing Available Force, or a Reserve pool drawn from existing Forces.
  4. Set the zone's doctrine and reserve percentage; defaults come from the DefenseZone type but can be overridden.
  5. Configure fallback rules, supply policy, rules of engagement, and threat priorities.
  6. Commit the zone. The Force allocates its detachments automatically per the assigned doctrine.

The player can override any individual detachment assignment after commit or directly redirect a detachment via a one-shot Operation. The Force returns to its DefenseZone-assigned configuration when the override Operation completes.

Zone Failure And Recovery​

A DefenseZone fails when the assigned Force is destroyed, when the zone's nodes are taken by hostile Forces, or when the zone's supply Route is severed for longer than the supply-endurance channel permits. Zone failure triggers:

  • The fallback rule (Force retreats to the named fallback Site or zone)
  • A Province-level alert surface (the player sees the failure on the ProvinceDefensePlan view immediately)
  • Adjacent zones' rules of engagement may upgrade automatically (e.g., a failed Heartland zone causes adjacent Capital zone to increase reserve commitment)

Zone recovery is a deliberate player decision, not automatic. The player re-commits the zone with a new Force, optionally a new doctrine, and a new supply policy that addresses whatever caused the failure.