# World-First Dynamic Game Architecture

## 1. Vision

Build the world first, then layer player actions on top.

The world exists and changes continuously, even when no player touches it. Players are actors inside a 
living simulation, not the center of a reward machine.

Design shift:

```text
Old model: player clicks action -> player gets reward
World-first model: world state evolves -> player interacts -> world reacts
```

## Theme Lock (Canonical Setting)

Setting year: 2037.

World identity: a near-future civic-collapse dystopia.

Primary label: pressure dystopia.

Meaning in practice:

- Institutions still exist, but are degraded.
- Services still run, but intermittently.
- Law still exists, but is unevenly enforced.
- Markets still operate, but under scarcity and corruption.
- Districts drift into different realities based on control and pressure.

Design rule:

The world does not fully collapse and does not fully recover. It remains in contested, unstable order.

## Brand Lock (Official)

Official game name: Districts

Official tagline: Crushed by Pressure. Driven by Survival.

Official website domain: Districts.me

Brand format for marketing and store pages:

Districts - Crushed by Pressure. Driven by Survival.

## Brand Voice Lock

Brand voice must communicate pressure, consequence, and endurance without collapsing into empty doom language.

### Core Tone

- Grounded, tense, and human.
- Harsh, but never hopeless.
- Direct, sharp, and concrete.
- Serious without sounding theatrical or overwritten.

### Messaging Priorities

- Sell adaptation, not fantasy power.
- Emphasize systems, pressure, and survival choices.
- Focus on consequence, scarcity, and contested order.
- Show that the world is cruel, but still learnable and beatable.

### Copy Rules

- Prefer specific lived-world language over vague dystopian slogans.
- Avoid generic apocalypse phrasing.
- Avoid heroic power fantasy language that breaks the survival tone.
- Every major piece of copy should imply: pressure exists, choice matters, recovery is possible.

### Brand Promise

Districts is not about saving the world.
Districts is about surviving it, adapting to it, and eventually bending pieces of it in your favor.

## System Lock: Dual-Channel Access Model (Legal vs Illegal)

Core needs (food, medicine, treatment, utilities, transport, safety) are always served by two parallel paths:

- Legal path: regulated, slower, usually safer, queue-constrained.
- Illegal/sketchy path: faster, less reliable, higher long-term risk.

Both paths can solve immediate survival pressure, but they must produce different delayed outcomes.

### Legal Path Characteristics

- Access depends on eligibility, hours, staffing, and backlog.
- Outcomes are more predictable when service is available.
- Cost profile favors vouchers/credits and formal compliance.
- Failure mode is delay, denial, or stockout (not immediate fraud).

### Illegal/Sketchy Path Characteristics

- Access is often immediate during shortages and emergency windows.
- Outcomes vary by source quality and district control.
- Cost profile favors cash, favors, debt, or obligation.
- Failure mode includes scams, contamination, coercion, exposure, and retaliation.

### Mandatory Design Rule

Every legal service has a mirrored gray/black alternative.
Every illegal shortcut must generate delayed consequences.

### Example: Emergency Care

- Public emergency care: triage-based, quality-stable, delay-prone.
- Backstreet care: rapid access, quality-variable, debt/exposure risk.

### Simulation Variables (minimum)

- access_time
- monetary_cost
- quality_reliability
- heat_exposure
- traceability
- debt_obligation

These variables drive world reactions on future ticks and shape district divergence over time.

## System Lock: Currency and Payment Rails

Currency exists as parallel payment rails with different legal acceptance and risk profiles.

### Legal Rail (Digital Only)

- Official services use digital payment only.
- Food lines, pharmacies, clinics, utilities, and transit do not accept cash.
- Digital forms include account balance, vouchers/credits, and approved transfer methods.
- Digital payments are traceable and can trigger eligibility or compliance checks.

### Cash Rail (Gray/Backstreet)

- Possessing cash is legal.
- Using cash in official service channels is not supported.
- Cash is primarily used in gray/black market channels and emergency shortcut transactions.
- Cash reduces traceability but increases scam, theft, extortion, and enforcement risk.

### Mandatory Design Rule

- Legal access routes must require digital rails.
- Illegal/sketchy routes may accept cash, favors, debt, or mixed payment.
- Players should feel a constant tradeoff between legal reliability and low-trace flexibility.

### Economic Pressure Effects

- Digital outages can temporarily paralyze legal access.
- Voucher/credit policy shifts can throttle legal survival options.
- Cash scarcity or counterfeit waves can destabilize gray markets.

This lock ties payment infrastructure directly to survival pressure, route choice, and world consequences.

## System Lock: Social Credit and Civic Standing

A social credit layer exists as a formal civic-standing system that influences legal access quality.

This system is separate from money balances. It represents institutional trust, compliance history, and flagged behavior risk.

### Core Effects

- Higher standing improves legal route outcomes (priority, eligibility resilience, reduced friction).
- Lower standing increases legal route friction (longer queues, stricter checks, reduced access windows).
- Severe standing loss can trigger targeted restrictions in official channels.

### Interaction with Existing Systems

- Legal route actions can raise or lower standing over time.
- Illegal/sketchy route choices may avoid immediate traceability but can create standing penalties when discovered.
- District policy shifts can change how heavily standing affects service access.

### Mandatory Design Rule

Social credit must shape legal reliability, but it must not hard-lock the player out of all survival paths.

The dual-channel model remains active: when legal access degrades, gray/backstreet alternatives still exist with higher long-term risk.

### Service Floor Policy (Locked)

- Social credit changes priority and processing speed, not baseline survival entitlement.
- Essential services (emergency care, baseline food access, critical medicine access) cannot be fully denied based only on low standing.
- Higher standing may grant faster lanes, wider booking windows, and reduced verification friction.
- Lower standing receives standard or delayed processing with additional checks, but still retains minimum legal access.

### Scope Note

Detailed scoring formulas, thresholds, and UI visibility are intentionally deferred for later definition.

## System Lock: Offline Continuity and Grace Window

The world simulation continues regardless of player presence.

Core rule:

- World time always advances via scheduled ticks (cron/scheduler), online or offline.
- Businesses, services, markets, deliveries, and district pressure continue to evolve without player input.

### Offline Safety Window (Locked)

- A player can be offline for up to 72 real-world hours (3 days) without hard-fail death state.
- Returning players may face meaningful degradation (resource loss, missed opportunities, higher pressure), but remain recoverable.

### Degradation While Offline (Expected)

- Scheduled expenses and consumption continue.
- Deliveries, market prices, and service backlogs continue to change.
- Territory/faction pressure and district conditions continue to shift.
- Time-sensitive opportunities can be missed.

### Mandatory Fairness Rule

- Offline time can punish efficiency, position, and inventory stability.
- Offline time cannot produce unavoidable account-ending failure inside the 72-hour window.

### Offline Overrun Recovery (Locked)

- If a player exceeds the 72-hour offline safety window, the character is not deleted.
- On next login, the player returns through a hospital recovery state.
- A short narrative incident script explains that an unseen event occurred and emergency intake prevented death.
- Recovery applies a material setback (time loss, condition penalties, missed opportunities) instead of permanent character loss.
- Medical debt is created and recorded as authority/government-linked debt.

### Debt Consequence Rule

- Hospital debt must be recoverable over time through legal or high-risk paths.
- Debt can increase future friction (reduced service priority, payment garnishes, standing penalties), but cannot hard-lock baseline survival access.

### Technical Implementation Rule

- Persist last_processed_world_time.
- On login/reconnect, execute deterministic catch-up ticks from last_processed_world_time to now.
- Apply bounded catch-up safeguards to prevent infinite loops and preserve simulation consistency.

## System Lock: Civic Event Engine and Dual-Surface News

Districts must run a living civic event layer that modifies simulation conditions over time.

Events are not quests and not marketing buffs. They are world-pressure shifts that alter real systems.

### Dual-Surface Rule (Locked)

Every major event must exist in two synchronized surfaces:

- External surface: social/news channel posts (site feed, social platform updates).
- Internal surface: simulation state mutations applied to districts, services, prices, and risk.

News is not flavor text. News communicates real state changes already active in the world.

### Event Design Rule (Locked)

- Events must feel like institutional strain, policy drift, infrastructure failure, or social instability.
- Events must avoid gamey bonus language (for example, "weekend boost" style framing).
- Effects should be explained in-world through pressure and consequence, not arcade modifiers.

### Event Trigger Sources

- Systemic triggers: thresholds crossed by simulation metrics (heat, backlog, scarcity, enforcement load).
- Scheduled triggers: pre-seeded seasonal or policy windows.
- Manual director triggers: creator-injected world incidents for controlled narrative drift.

### Mandatory Event Payload (minimum)

Every event should define:

- event_id
- title and public bulletin text
- affected_districts
- start_time and duration
- system_modifiers
- decay/recovery profile
- escalation hooks
- rollback/normalization conditions

### System Modifiers (example set)

- transit_efficiency
- clinic_backlog
- official_price_index
- gray_market_price_index
- police_response_time
- compliance_check_intensity
- spoilage_risk
- courier_demand

### Example Pattern

Public bulletin:

DISTRICT ALERT // SOUTH GRID

Overnight utility failures triggered rolling shutdowns across connected districts. Transit delays expected. Emergency backlog rising through the weekend.

Internal effects:

- South Grid transit efficiency: -40%
- Clinic backlog: +25%
- Gray transport prices: +60%
- Police response delay: increased
- Spoilage risk: increased

### Player Experience Rule

Players should infer opportunities and danger from world conditions.

The game should not announce "profit events" directly. It should present pressure conditions and let players adapt through legal and gray routes.

### Continuity Rule

- Event effects participate in normal world ticks.
- Event effects must persist offline and be reflected during deterministic catch-up processing.
- Event aftermath should leave residue (debt, shortages, standing shifts, district mood) instead of clean resets.

## 2. Core Design Principles

1. Persistent state over disposable encounters.
2. Systems over scripted buttons.
3. Consequences over instant reset loops.
4. Opportunity windows over guaranteed payouts.
5. Risk escalation for higher reward.

Players should interact with living systems, not static menus with random prizes.

## 3. World Model

### 3.1 Global Layers

- Cities
- Districts
- Businesses and properties
- NPC factions
- Police and government pressure
- Economy and supply flows
- Territory ownership/control
- Heat and crime pressure
- Dynamic events

### 3.2 Entity Contract (applies to any world object)

Every object should support:

- Persistent database state
- Timers and cooldowns
- Condition and recovery values
- Resource generation and drains
- Control and ownership data
- Consequence hooks (police, faction, economy)

## 4. Tick Engine (World Cron)

The tick engine advances simulation state at fixed intervals.

### Canonical Time Scale (Locked)

- 1 real-world second = 1 in-world minute.
- 1 real-world minute = 1 in-world hour.
- Baseline systemic tick cadence: every 1 in-world hour.

Player-facing requirement:

- In-world date/time must be visible at all times in UI.
- Time visibility is part of pressure communication, not optional flavor.

Responsibilities:

- Generate business income
- Refill registers and resource pools
- Grow safe cash
- Trigger automatic bank drops
- Recover damaged entities
- Raise/lower district heat
- Trigger police/faction responses
- Spawn dynamic events

High-level flow:

```text
for each tick:
  update economy
  update businesses
  update district pressure (heat, control)
  evaluate reactions/events
  persist all changes
```

## 5. Example System: Corner Store

A corner store is a simulation object, not a robbery button.

State fields:

- register_cash
- safe_cash
- staff_count
- customer_traffic
- security_level
- damage_level
- police_attention
- owner_protection_status
- cooldown_state

Tick updates modify these fields continuously whether players interact or not.

## 6. Safe and Bank Drop Logic

Safe cash accumulates over time but is periodically extracted by the world.

Rule:

- If safe_cash reaches threshold, perform bank drop.
- Bank drop resets safe cash.
- Players who arrive late lose the jackpot opportunity.

Example:

```text
SAFE_MAX = 2000

if safe_cash >= SAFE_MAX:
  perform_bank_drop()
  safe_cash = 0
```

Purpose:

- Prevent static farming loops
- Create uncertainty and timing strategy
- Keep high-value opportunities dynamic

## 7. Multi-Stage Action Design

Actions should be phase-based, with escalating exposure.

Example robbery sequence:

1. Enter store
2. Hit register
3. Pressure customers
4. Discover safe
5. Attempt breach
6. Escape before response arrival

Each phase should raise:

- Potential payout
- Detection chance
- Police response probability
- Chance of mission failure

## 8. Reaction Matrix (Persistent Consequences)

Player actions mutate world state.

Typical consequences:

- Business loses money
- Business damage increases
- District heat rises
- Police patrol density increases
- Faction retaliation risk rises
- Temporary closures occur
- Local economy shifts

These effects should decay or recover through systems, not instant resets.

## 9. Genre-Agnostic Architecture

This framework is reusable across genres:

- Crime simulation
- Survival simulation
- Medieval settlements
- Faction warfare
- Dystopian governance
- Political/economic simulations
- Territory control games

Core pattern stays the same:

```text
world object exists
-> tick updates object state
-> player interacts with object
-> world state changes
-> future interactions are altered
```

Only actions, flavor, and presentation change.

## 10. Build Order

1. World entities and persistence
2. Tick engine and scheduled updates
3. State transitions and recovery rules
4. Reaction systems (police, factions, economy)
5. Player interaction layers
6. Balancing, telemetry, and tuning

Build the forest first. Then let players decide what to do in it.

## 11. V1 Simulation Spec (Launch)

This section defines the minimum simulation contract for a production-safe launch.

### 11.1 Playable Hierarchy (Locked for V1)

```text
World
  -> City
    -> District
      -> Block
        -> Service/Business/Route
```

V1 control focus:

- District is the primary pressure container.
- Block is a local modifier layer (not a fully separate minigame loop in V1).

### 11.2 District Pressure Vector (Required)

Each district stores a standard pressure vector so all systems can compare, propagate, and rebalance consistently.

Required fields (0-100 normalized unless stated):

- pressure_score
- transit_efficiency
- clinic_backlog
- enforcement_delay
- scarcity_index
- standing_friction
- gray_activity
- unrest_risk
- district_recovery_rate (0.0-1.0)

### 11.3 Tick Application Order (Deterministic)

For each world tick:

1. Apply base drains and recoveries.
2. Apply active event modifiers.
3. Apply player and faction action deltas.
4. Propagate cross-district spillover.
5. Evaluate threshold reactions/escalations.
6. Persist state and append immutable event log entries.

No step may rely on client-side ordering.

### 11.4 Cross-District Spillover Rules

Pressure does not spread globally. It spreads through links.

Each district edge has:

- link_strength (0.0-1.0)
- transfer_type (transit, supply, social, enforcement)
- capacity_limit

V1 spillover model per metric:

$$
\Delta_{target} = (value_{source} - value_{target}) \times link\_strength \times transfer\_coefficient
$$

Only apply spillover where edge capacity and route state allow it.

### 11.5 Memory, Decay, and Recovery

District consequences must persist, then heal gradually.

- Use half-life decay for volatile metrics (panic, rumor, temporary scarcity).
- Use slower structural recovery for infrastructure and civic trust metrics.
- Event residue should remain after headline expiry (debt, backlog, standing friction).

V1 default windows:

- Short memory: 12-48 hours
- Medium memory: 3-10 days
- Structural memory: 2-6 weeks

### 11.6 Anti-Snowball Safeguards

To prevent permanent lock-in by dominant players/factions:

- Dominance maintenance cost rises with control share.
- High extraction increases detection and sabotage probability.
- Overheated districts trigger counter-pressure events.
- Recovery aid probability rises for critically degraded districts.

No district should remain permanently solved or permanently doomed.

### 11.7 Event Schema Contract (V1)

Each event record must include:

- event_id
- city_id
- primary_district_id
- affected_district_ids
- event_type
- start_at
- end_at
- public_bulletin_text
- modifiers_json
- decay_profile_json
- source_type (system, scheduled, director)
- status (scheduled, active, cooling, closed)

### 11.8 Database Strategy for District Growth (Important)

Do not create one table per district.

Reason:

- Per-district tables create migration overhead and query complexity.
- Cross-district analytics and spillover queries become expensive and brittle.
- Adding new districts should be data inserts, not schema rebuilds.

Use shared, indexed tables with district_id and city_id keys.

Minimum core table set:

- cities
- districts
- district_state
- district_links
- blocks
- block_state
- world_events
- event_effects
- world_tick_log

### 11.9 Modular Expansion and Premium District Packs

Expansion should be module-driven, not schema-driven.

Add:

- content_modules (module_id, name, version, access_tier)
- module_district_map (module_id, district_id)
- module_event_pool_map (module_id, event_template_id)

Premium access can gate modules by account entitlement while using the same world schema.

Result:

- New districts can be added seamlessly as content rows.
- No rebuild required.
- Existing simulation logic and queries remain stable.