# Epic 4 - World Topology and Zone Infrastructure

## Source Anchors

- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 4
- Related modules: E4.M1, E4.M2, E4.M3, E4.M4

## Ownership and success (Level 1)

- **Ownership focus:** Online/Backend Engineering + World Design
- **Success criteria:** Mostly seamless open world runs reliably with predictable transitions and low-disruption handoffs.

## Objective

Represent the world as a zone graph with travel rules, security-tier signaling for PvP policy, and later spawn ecology and seamless handoffs so content scales from one district to regional scope without rewiring fundamentals.

## Module Breakdown

### E4.M1 - ZoneGraphAndTravelRules

- Responsibility: Regional zone graph, transition links, movement and travel constraints.
- Key contracts: `ZoneDef`, `ZoneEdge`, `TravelRule`
- Dependencies: None
- Stage target: Prototype

### E4.M2 - SpawnEcologyController

- Responsibility: Resource and NPC spawn profiles per zone, respawn pacing, depletion recovery.
- Key contracts: `SpawnProfile`, `RespawnRule`, `ZoneEcologyState`
- Dependencies: E4.M1, E3.M1, E5.M2
- Stage target: Pre-production

### E4.M3 - SeamlessHandoffAndRegionState

- Responsibility: Cross-region handoff behavior and region authority ownership boundaries.
- Key contracts: `RegionHandoffEvent`, `RegionAuthority`, `TransferState`
- Dependencies: E4.M1, backend world services
- Stage target: Pre-production

### E4.M4 - SecurityTierZoneFlags

- Responsibility: High/contested/low-security tagging and client/server zone risk signaling.
- Key contracts: `SecurityTier`, `ZonePolicyState`, `ZoneEntryWarning`
- Dependencies: E4.M1
- Stage target: Prototype

## Implementation Slices (Backlog-Ready)

### Slice 1 - Prototype district zone graph

- Scope: E4.M1 defining hub, PvE pocket, and edge zones with valid transitions.
- Dependencies: None
- Acceptance criteria:
  - Server and client agree on current zone id for every player.
  - Travel rules prevent illegal shortcuts.
- Telemetry hooks: `zone_enter`, `zone_exit`, invalid transition attempts.

### Slice 2 - Security tier tagging and UI hooks

- Scope: E4.M4 on E4.M1: per-zone `SecurityTier`, `ZonePolicyState`, and entry-warning payloads. E6.M1 subscribes to this data for PvP eligibility (implemented in Epic 6; no circular module dependency).
- Dependencies: E4.M1
- Acceptance criteria:
  - Server-authoritative tier matches client display for each zone transition; entry-warning contract is stable for E6.M2 to consume.
- Telemetry hooks: `security_zone_enter`, `security_zone_exit` (aligned with PvP events).

### Slice 3 - Spawn ecology (pre-production)

- Scope: E4.M2 driving node and NPC densities per zone from data.
- Dependencies: E4.M1, E3.M1, E5.M2
- Acceptance criteria:
  - No zone starvation or infinite respawn exploits in test scenarios.
- Telemetry hooks: `spawn_wave`, ecology depletion/recovery markers.

### Slice 4 - Seamless handoff spike (pre-production)

- Scope: E4.M3 minimal viable handoff between two regions with authority transfer.
- Dependencies: backend world services
- Acceptance criteria:
  - Handoff completes without duplicate entities; rollback path documented.
- Telemetry hooks: `region_handoff_start`, `region_handoff_complete`, failures.

## Risks and Mitigations

- Risk: Zone/security inconsistencies between client and server.
  - Mitigation: Server is source of truth; client prediction only for display.
- Risk: Premature seamless complexity for solo dev.
  - Mitigation: Prototype stays single region; handoff is gated pre-production slice.

## Definition of Done

- Prototype zone and security signaling validated with Epic 6.
- Pre-production spawns and handoffs meet stage gates in master plan.