# Galactic Conquest Classic — Game Design Document

**Status:** Draft (interactive fill-in progress)  
**Build label:** 2.77 (`Application.cfc` `this.Version`)  
**Last updated:** 2026-05-11  

**Companion (no code):** For **design theory, pillars, and idea comparison** without implementation detail, see **`docs/GDD-design-theory.md`**.

This document merges **design intent** (product) with **observed behavior** (code/manuals). Paragraphs prefixed with **`[Code]`** trace to templates or CFML referenced in-repo.

---

## 1. Document control

| Role | Owner |
|------|-------|
| Product / narrative | *TBD* |
| Balance / pacing | *TBD* |
| Engineering reference | Repo: `AGENTS.md`, `project_overview.md` |

**Convention:** Database schema `gcc`; core routing via `i.cfm` (`url.f` authenticated, `url.p` public).

### Stakeholder decisions log

| Date | Topic | Decision |
|------|--------|----------|
| 2026-05-11 | Canonical pillar | **Shared persistent multiplayer world** — not a single-player game; **no server resets; no seasons**; gameplay revolves around what other players do. |
| 2026-05-11 | Monetization | **No pay-to-win combat.** Paid items adjust **play style**, **QoL**, or **speed up boring parts** only; must **not** grant a massive combat edge. |
| 2026-05-11 | Primary persona | **Federation / social-first** players; **lone wolves are OK** but not the primary optimization target. |
| 2026-05-11 | Session model | **Several check-ins per day**; **~2 hours total** engagement is normal, often **not in one sitting**. |
| 2026-05-11 | Live turn timing | **Production matches** `s_loadvar.cfm` for servers 3–4 (confirmed). |
| 2026-05-11 | Server design focus | **RT (server 4) is primary** for design and balance. **TB (server 3)** remains for players who want a **slower mirror**, not a co-primary design target. |
| 2026-05-11 | Multi-accounting | **Not allowed** — **one account per person** (policy; enforce alongside existing same-PC / same-IP attack restrictions in code). |
| 2026-05-11 | First-day success (RT) | Build **some colony infrastructure**, **explore another planet**, **research a few technologies** — not gated on missions, feds, or combat. |
| 2026-05-11 | Federation onboarding | **Soft nudge** toward federations is OK; **joining remains optional**. |
| 2026-05-11 | Solo progression | Players must **always be able to progress without a fed**, consistent with current game behavior. |
| 2026-05-11 | Premium turn bank | **`paid_turnmax` (1.5× turn reservoir)** is **acceptable** — does not, in product judgment, **materially skew** competitive combat outcomes. |
| 2026-05-11 | Future paid scope | **Cosmetics**, **time-savers**, **playstyle adjusters** that **avoid a full reset** (e.g. moving to another **race without losing everything**). |
| 2026-05-11 | Turn docs / glossary | **Both:** in-game **manual** already carries a full player glossary (**live** today); **UI tooltips** are added incrementally alongside page work (`text/manual_*.cfm`, `help/`). |
| 2026-05-11 | Turn balance (RT) | **No** standout mis-priced turn sinks today; roadmap: **overflow turns** — slower **offline-style** progression pool that **stacks over time** (energy-like), **separate exercise** when implemented. |
| 2026-05-11 | Newbie power protection | **5,000** power threshold for attack eligibility / target protection stays **fixed** — **no scaling** with galaxy age (permanent rule). |
| 2026-05-11 | Anti-bully / anti-farm | **Damage protection** (`planetlost` + timed window) remains the **primary** lever **for now**; no mandated add-ons (fed truce, newcomer channels) in near-term scope. |
| 2026-05-11 | Empire “death” (in-world) | **Bankruptcy**; **loss of all colonies** for **certain races** — both qualify as empire failure/end states worth documenting against debt/colony rules. |
| 2026-05-11 | Inactive accounts | **No inactivity purges** — dormant accounts remain in the world as-is (no seasonal cleanup of empires). |
| 2026-05-11 | Account removal | **Bans** for rule-breaking; **voluntary deletion** allowed where permitted by **applicable law** / global compliance requirements. |
| 2026-05-11 | Mentor / linkage model | Historic **annex / enslave** framing is shifting toward a **recruitment / referral**-style program: linked players **help newcomers along** cooperatively (**product direction**; legacy systems may persist in code until refit). |
| 2026-05-11 | Referral rewards mix | Predominantly **merit-based** recognition; layered **marginal boosts:** **small economic bonus** → **referrer**; **small defensive bonus** → **recruit** — must remain **non-decisive** vs §7 / §10. |
| 2026-05-11 | Bankruptcy flow | Not **instant wipe** at insolvency: include a **grace period** during which players may **sell accrued resources**, use **markets**, or receive **ally / federation aid** to **recover solvency** before final failure. |
| 2026-05-11 | Email validation vs gameplay gates | Email **verification remains** as an account-health / comms mechanic, but **`[Product]`**: **nothing may hard-block gameplay** solely for unvalidated mail—**remove** validation gates across tasks (historically e.g. explore when **`confirmflag`** and planet-count exceeded — **`f_com_explore.cfm`**). **`[Code]`** audit & removal **TBD**. |
| 2026-05-11 | Page / template permanence | **No screen layout or component pattern is fixed long-term** yet — including **`f_com_income.cfm`** and **`theme.css`** conventions. **Later** design passes will set standards; today’s pages are **working drafts** only. |

---

## 2. Elevator pitch & positioning

Galactic Conquest Classic is a **browser-based**, **persistent-universe**, **multiplayer** empire strategy game: colony development, technology, fleets, alliances, combat, trade, and long-form politics—primarily delivered as server-rendered HTML with progressive JS.

**[Code]** Pitch copy and loop summary on landing: `p_main.cfm` (persistent universe, races, colonies, research scale, fleets, federation politics).

---

## 3. Design pillars *(locked hierarchy)*

**North-star pillar**

1. **Persistent shared multiplayer world** — One continuous galaxy per shard where **player actions define the simulation**. Not a seasonal ladder; not single-player-story-first.

**Supporting pillars**

2. **Strategic identity through races** — Races diverge economically and militarily, not cosmetically (`help/race.htm`, `p_main.cfm`).
3. **Player-driven alliances & politics** — Federations coordinate real teams; diplomacy, war, betrayal emerge from humans (`text/manual_fed.cfm`, `help/federationwar.htm`). Design prioritizes players who thrive in fed/social play; solo remains valid.
4. **Universal turn economy** — Turns gate empire actions from economy through warfare (`AGENTS.md`; `cf_s_endturn`, `z_endturn.cfm`).

### Explicit non-goals *(locked)*

- **Seasonal resets**, **server wipes**, or **“fresh start worlds”** as core product (not planned).
- **Pay-to-win combat** — paid advantages must stay out of decisive military advantage (see §7).
- **Single-player-first** positioning — the game is defined by other players in the same persistent world.

---

## 4. Audience & session model *(locked)*

**North Star:** Federation / **social-first** players who coordinate, trade intel, and wage politics together. **Lone wolves** are supported but not the main balance target.

**Engagement pattern:** Multiple **short check-ins per day**; **~2 hours total** daily play is reasonable when summed across sessions—often **fragmented**, not one continuous block.

**[Code]** Mobile-friendly / play-anywhere goal: `p_main.cfm`. Comms surfaces: game frame + PM + sector messages + `forum2/`.

---

## 4.1 Accounts & fair play *(product + code overlap)*

**Product policy:** **One account per real person.** Multi-accounting is **not permitted**.

**Design intent:** Preserves persistence and reputation; reduces alt-based market/scout/exploit churn; aligns competition with individual identity.

**[Code]** Related enforcement patterns already exist around **shared device / IP** blocking certain attacks (`s_com_attack_req.cfm` — same PC cookie, same IP). Policy and tooling should be documented and consistent (moderation / admin — `edmin/`).

---

## 5. Worlds & servers

### 5.1 Persistent universe

**Product:** No resets; no seasons; world history is cumulative.  
**[Code]** Persistence assumed per server; no seasonal reset in application logic.

### 5.2 Shard roles *(product + code)*

| `session.server` | Label `[Code]` | Turn interval `[Code]` | Turn cap `[Code]` | Design role *(product)* |
|------------------|----------------|-------------------------|-------------------|---------------------------|
| 3 | TB | 150 s | 300 | **Secondary** — slower mirror for players who want more planning time between grants. |
| 4 | RT | 6 s (~8 s described in comment) | 60 | **Primary** — main balance, feature, and pacing reference. |

**[Code]** Signup offers only **3 and 4** (`p_signup.cfm`); default `url.se = 4` (RT). Labels: `l/s_getvalue_server.cfm` (TB / RT).

Slots **0–2** and **5** exist in config (`s_loadvar.cfm`, login options in some templates) for legacy / special use — **not** the new-player path on current signup.

**Premium turn reservoir:** `application.paid_turnmax = 1.5` (`s_loadvar.cfm`) — **approved** product-wide as non–pay-to-win (see stakeholder log).

**NPC tuning:** `application.NPC_#server#_*` per slot (`s_loadvar.cfm`) — RT vs TB may differ; when balancing, **start from server 4**.

---

## 6. Core game loop *(observed + product)*

**Macro loop (player-facing, `p_main.cfm`):**

1. **Develop colonies** — infrastructure, population, extraction; colonies are production units.  
2. **Research** — large tech tree shapes military and economy.  
3. **Build fleets** — construct ships, organize formations / escorts.  
4. **Engage** — attack, defend, negotiate, join or lead federations.

**Turns** remain the shared currency for most actions (`AGENTS.md`).

**Social loop (fed-first design target):** recruit / apply → share attack intel → coordinate counters → elect leadership → declare fed war or treaties (`f_fed_*.cfm`, manuals). **Optional** for any given player (see below).

**Recruitment / referral:** Product direction shifts **veteran–newbie linkage** toward a **mentor-style referral program** (help along, onboarding support) rather than punitive overlord framing — details in **§11.4**.

### 6.1 Onboarding & first-day bar *(product)*

**Target outcomes (first day on RT, not necessarily in one sitting):**

- Build **some infrastructure** on a colony.  
- **Explore** to another planet.  
- **Research** a few technologies.  

No requirement to join a federation, complete a mission arc, or engage in PvP on day one.

### 6.2 Federation discovery *(product)*

The game **may nudge** (copy, UI hints, optional mission flavor) toward federations early. **Membership stays optional**; solo progression must remain viable (§6.3).

### 6.3 Solo (“lone wolf”) floor *(product)*

Empires **must always remain able to progress** without federation membership — matching **current gameplay**. Solo may be **riskier or slower socially**, not **structurally blocked**.

---

## 7. Monetization principles *(locked)*

**Combat boundary:** Paid offerings must **not** deliver a **large combat advantage**.

**Approved categories (long-term direction):**

- **Cosmetics**  
- **Time-savers** (reduce dull wait or repetitive actions)  
- **Playstyle adjusters without a hard reset** — e.g. **adopt another race without losing the entire empire**  

**Premium subscription / flag — turn bank:** `paid_turnmax = 1.5` is **intentionally retained**; product view is that a **larger turn reservoir** does **not** constitute pay-to-win combat in practice.

**[Code]** PayPal integration (`Application.cfc`); premium affects max turns (`s_loadvar.cfm`, `s_endturn.cfm` / `z_endturn.cfm`); storefront flows `f_com_donate*`, `f_com_cart*`.

---

## 8. Progress — remaining work

Drafted §§13–22 (resources through **ships**). Still **thin or missing**:

- Exhaustive **`f_com_*` turn-sink checklist**  
- **`§11–12`** grace/bankruptcy + **debt lock** reconciliation in **`s_endturn.cfm`** + attack/ship guards  
- **Fleet tactics** deep dive (`f_com_ship2.cfm`, `f_com_ship_r.cfm` — formations, escorts, battle cards)  
- **Race datasheet** numeric export from live **`race`** DB (values beyond modifier list)  
- **NPC** spawn rules (`Modules/NPC/`) per server slot  
- **Live ops** metrics & alerting  

---

## 9. Turns — overview *(partial, code-backed)*

- Turns accrue automatically on a timer; spending flows through **`cf_s_endturn`** (`z_endturn.cfm`) and **`s_endturn.cfm`** for player actions (`AGENTS.md`).  
- **Attack floor:** initiating combat requires **≥ 5 turns** available at check time (`s_com_attack_req.cfm`).  
- **Income modifier:** cluster-wide econ modifier `application.mod#server#_59` when defined (`z_endturn.cfm`).

### 9.1 Documentation: glossary + tooltips *(product)*

Players get **both**:

- **Manual / glossary** — complete reference already **live** (in-game manual and related help corpus). **`[Code]`** `text/manual_*.cfm`, `help/`.
- **Contextual tooltips** — layered in **incrementally** as individual screens are improved (no substitution for manual; complements it).

Balance: no systemic turn-cost issues flagged for immediate RT retuning (**stakeholder 2026-05-11**).

### 9.2 Roadmap — overflow turns *(planned, not shipped)*

**Intent:** Introduce **`overflow turns`** (working name): a slower **offline-friendly** reservoir that **accrues and stacks over time**, analogous to **energy** mechanics in mobile games — supporting fragmented sessions without replacing the core turn clock.

**GDD placeholder:** Detailed caps, sinks, monetization coupling, and RT-vs-TB rules TBD when the feature is scoped in engineering.

---

## 10. Combat & protection *(code-backed + product locks)*

**Power ratio gating:** Normal attacks use tiered attacker/target **power rating** comparisons; **federation war** relaxes bands (e.g. up to **2×** stronger target vs **non-war** pathways) (`s_com_attack_req.cfm`, `help/federationwar.htm`).

**Newbie band *(product forever rule)*:** Attackers must have **power > 5,000** to launch attacks; targets **under 5,000** remain protected (**no** planned scaling by galaxy maturity or median power). **`[Code]`** `s_com_attack_req.cfm`. Exceptions remain for scripted cases (NPC, overmind, etc.).

**Damage suppression *(product: sufficient for now)*:** Targets with **`planetlost ≥ 3`** enter protection for a **server-configured window** (`protection_hour` / `application.server#server#_dp`) (`s_com_attack_req.cfm`). This stays the **primary** anti-harassment / farming brake; additional systems (fed truces, newcomer channels, etc.) are **not required** near-term.

**Same-machine / alt pressure:** Attacks blocked vs same shared PC fingerprint or same IP as target (`s_com_attack_req.cfm`) — complements **§4.1** policy.

---

## 11. Empire lifecycle, accounts & recruitment *(product + code overlap)*

### 11.1 In-world failure (“empire death”)

Gameplay-defined loss / end states documented for design and help:

| State | Meaning *(product)* |
|-------|------------------------|
| **Bankruptcy** | Ultimate failure when debts / obligations cannot be sustainably resolved — **after** a **grace period** (§12.1) that preserves agency to recover. Align long-form manual copy accordingly. |
| **Zero colonies (race-qualified)** | For **some races**, losing **all colonies** constitutes empire failure — exact race roster **TODO** tie to DB / `race` tuning (not identical for every species). |

**[Code]** Econ clamps, debt accumulation, colony counts surface in turnover logic (`s_endturn.cfm` / related); authoritative race rules live in data + scattered checks.

### 11.2 Dormancy & persistence

There are **no inactivity-driven purges** of empires. Accounts that stop logging in **persist** on the shard; the world does not reclaim them automatically for seasonality (**product**, consistent with no seasonal resets §3).

### 11.3 Moderation bans & voluntary deletion

- **Bans** — Removing access for players who **violate rules** (moderation / admin tooling — `edmin/`).  
- **Voluntary deletion** — Allowed when consistent with **applicable law** and platform policy (**product**).

### 11.4 Recruitment / referral program *(planned direction)*

**Product intent:** Replace (or refactor) narrative-heavy **annex / enslave** positioning with a **recruitment–referral** model: veterans **actively help** new recruits learn the ropes (aligned with §6 federations optional-but-nudged, fed-first pillar).

**Rewards philosophy *(locked)*:**  
- **Merit-first** — primary progression / recognition through **earning** milestones, participation quality, longevity, contributed teaching—not one-off payouts for raw clicks alone.  
- **Referrer** — **minor economic** uplift (bonus income, stipend-flavor, fee relief, etc.—exact shape **TBD**). Must stay **additive**, not dominance-inducing (**§7**).  
- **Recruit** — **minor defensive** benefit only (incoming damage cushioning, upkeep relief, newbie shield parity—exact shape **TBD**). Explicitly **not** a blanket combat stat boost that replaces ships or exploits **§10** protections.

Still **TBD (implementation):** anti-abuse (self-link, dormant farming), cadence resets, linkage to signup **`[Code]`** `p_signup.cfm`, RT vs TB parity copy, moderator visibility.

**[Code]** Today’s codebase still implements **annex**, **enslave** attack paths, `user.annex` fields, signup introducer hooks — refactor needs **dual-write or migration** in engineering specs.

---

## 12. Economy — credits, debt & recovery *(product locks + `[Code]` reality)*

### 12.1 Bankruptcy grace window *(planned / product lock)*

**Before final bankruptcy / empire dissolution**, empires enter a **grace interval** permitting counterplay:

- **Liquidate** stored resources (**market** sells, other sinks—design must surface clear UI).  
- **Social recovery** — **allies**, **federation mates**, diplomacy-based aid (**fed-first pillar**) can help stabilize accounts.

Purpose: deepen persistence fantasy (mistakes redeemable short-term); reward coordination over instant deletion.

**Debt-phase restrictions *(product lock)*:** Whenever an empire qualifies as **in debt** (exact threshold / flagging **TBD**, must align with grace messaging), the empire **may not initiate combat in any form**: no offensive opens, **retaliation launches**, **counter-attacks**, or other flows that **start** an engagement (including offensive actions under **federation wars** where applicable). **New ship construction is blocked.** **Being attacked by others** is unchanged unless separately specified (**`[Code]`**, §10). Other actions—research, non-ship infra where permitted, **market** sales, diplomacy, federation coordination toward recovery—remain available.

**Implementation scope:** **`[Code]`** must block initiation across **`f_com_attack*` / `s_com_attack*`** (and parity paths such as scripted/mission attack entry); ship pipeline via **`f_com_ship*` / `Modules/Ships/Builder.cfm`**. Current behavior may differ until shipped.

**TBD engineering:** grace **duration** & UI (§12.4), mails, escalating warnings, hard floor before termination; reconciliation with **`s_endturn.cfm`** compounding on negative credit.

### 12.2 Referral econ hooks *(see §11.4)*

Referrer **tiny economic** drip + recruit **tiny defensive** buffer — implemented after merit framework; econ systems here must reconcile with **trade** (`f_com_market*`).

### 12.3 Open decisions *(deferred)*

- **21.** Grace **sizing** rule (calendar vs turns vs debt-scaled vs hybrid) — **later**.  
- **22.** Any **extra** layered restrictions beyond §12.1 **combat-initiation + ship-build** lock — **later**.

---

## 13. Resources & economic loop *(code-backed skeleton)*

**Empire balances (`user` row, surfaced every turn)** — Credits, Food, pooled **Goods** aggregate, Ore, Raw material; plus **`user_good`** rows for six tradable/mineral-ish **goods** slots (`good_1`…`good_6` in turnover).

**Debt & interest:** Negative **credit** accrues a **compound-style interest charge each turn-use** chunk (`Tempdebt` formula in **`s_endturn.cfm`**). **`[Product]`** must reconcile this with §12 grace + debt combat lock UI.

**Colony-span income streams (inside `cf_s_endturn` / colony loop)** — Rough categories:

| Stream | Depends on *(high level `[Code]`)* |
|--------|--------------------------------------|
| **Population tax credits** | Pop, colony loyalty; race **tax** multiplier |
| **Primary mineral per colony** | **Mining**, planet mining %, infra research (**`res_5`**), planets in system, planet **type**, race **mineral** |
| **Industry → goods** | **Industry**, empire **raw material** stock, infra research (**`res_3`**), race **industry** |
| **Consumers → credits** | **Goods** diverted to “sales” (~5.5 credit per consumed good unit), colony pop consumption (**`race_good`**) |
| **Commercial synergy** | **Commercial** buildings + infra (**`res_2`**) can convert raw mats → extra goods (`tmpGoods` path) |
| **Agriculture** | Agri infra, planet agr %, infra (**`res_4`**), produces **Food** & **Raw** |
| **Mining → ore stock** | **Ore** vein on colony, **mining**, planet mining % (**`application.server_type` “GC”** path differs from legacy UC branch in file) |

**Fleet / empire-wide overlays:** Aggregate **commercial building floor** earns **TempCommercialIN** (`* 5 * race commercial * incomemod`); **Infrastructure count** (**housing + commercial + industry + agriculture + mining**) pays upkeep **TempCreditOUT** scaled by **`race_maintenance`**; **`shipUpkeep`** credits deducted per fleet (`evaluate("application.shipupkeep_userid")).

**Bonuses:** If empire has **planetlost < 3**, positive colony credit flux, **power > 5000**, a **planet-lost consolation credit** (**5%** of gain) fires (`planetlostcredit`).

**Annex / tributary carve-out (legacy):** Positive credit delta splits **15% `annex_income`** to overlord **`session.annex`** (`annex_income` subtraction on parent update **`s_endturn.cfm`**). **`[Product]`** future **referral** program should converge or supersede narration.

### 13.1 Hard numeric caps *(today’s `[Code]`* **`s_endturn.cfm`** *)*

Clamp after full tick math (before DB write):

| Field | Clamp |
|-------|-------|
| **Raw material** | max **25 000 000 000** |
| **Food** | max **25 000 000 000** |
| **Ore** | max **2 000 000 000** |
| **Goods (aggregate)** | max **25 000 000 000** |
| **Credit upper** | max **5 000 000 000 000** |
| **Credit lower** | min **−200 999 999 999** (distinct from sentinel `-999999999999` clamp earlier in block) |

Per-slot **planet-mineral reserves** (**`good_1`–`good_6`**) capped at **2 000 000 000** each when summed with staged yields.

**Current income page (provisional `[Code]` reference only):** **`f_com_income.cfm`** — cited in **`AGENTS.md`** as one **early** modernized screen; **not** a frozen design system.

### 13.2 Page & component design *(product lock — non-permanence)*

**No UI pattern in GCC Classic is “final” yet** — including **`f_com_income.cfm`**, **`theme.css`** **`gc-*`** components, **Nebula/Daylight** theming rules, and legacy **Classic** parity. A **future holistic design pass** will define what (if anything) becomes **standard**; until then, templates are **iteration-friendly** and **may be replaced**.

**Implication for documentation:** **`AGENTS.md`** engineering notes about “reference implementations” describe **current working direction**, not irrevocable product canon.

---

## 14. Colonies & planetary infrastructure *(code-backed skeleton)*

**Colony entities** keyed in **`application.col_{id}_*`** caches; iterated via **`application.col_{userid}_colonylist`** per empire.

**Structural buildings** (five counters rolled into infra upkeep & income):  

**Housing**, **Commercial**, **Industry**, **Agriculture**, **Mining** (`s_endturn.cfm` loop).

**Key colony attributes `[Code]`:** `pop`, `loyalty`, colony-stored `ore` (vein), `land`, `type` (planet archetype id), `planet` count, optional `goodid` primary mineral profile, owner `userid`.

**Population growth:** Default races consume **food** each turn (`col_food = pop/10 * endturn`); growth toward **maxpop = (10 + res_1) * housing** using planet pop suitability %; **Guardian** (`session.race is 3`) skips food-based pop rules in this block. **Starvation** path applies **85%** pop crash + loyalty hit when food missing.

**Colony cap:** Max colonies per race via **`application.s_getvalue_race_{race}_maxcolony`** enforced when attacking (`s_com_attack_req.cfm`).

---

## 15. Research & technology *(code-backed skeleton)*

**Tree data** loaded application-scope from **`restree`** per **`AGENTS.md`** (**`s_loadsystem.cfm`**).

**UI / commands:** **`f_com_research.cfm`**, **`f_com_research_tree.cfm`**, graph / mineral overlays **`f_com_research_graph.cfm`**, **`f_com_research_mineral.cfm`**.

**Infra-linked modifiers** (examples seen in econ): **`res_1`** pop cap boost, **`res_2`** commercial synergy, **`res_3`** industry throughput, **`res_4`** agriculture tuning, **`res_5`** mining / refining — exact mapping stored per player in **`application.research_infrastructure_{userid}_{slot}`**.

**Policy:** Maintain **meaningful divergence by race** (§3 pillar); manual advertises tech count > ~100 (**`p_main.cfm`**). Full **race playbook** is **§21**; deep prerequisite matrix still **data-export TBD**.

---

## 16. Exploration & expansion *(partial `[Code]`)*

**Screens:** **`f_com_explore.cfm`**, calculator **`f_com_explore_cal.cfm`**, secondary **`f_com_explore2.cfm`**; localized mirror **`l/f_com_explore.cfm`**.

**Gating examples `[Code]` (legacy patterns — reconcile with stakeholder email policy):**  

- **`application.s_getvalue_race_{race}_allowexplore`** may hard-block exploration for some races (`f_com_explore.cfm`).
- ~~**Email validation**: previously blocked exploration (`session.confirmflag is 0` + **`planetcount > 20`**)~~ — **scheduled for removal**: **validated or not**, explore and other gameplay must remain **accessible** (**stakeholder** row *Email validation vs gameplay gates*).
- **Tournament-flag** shards may still demand **fed membership** (`server#slot#_tournament_start`) where applicable — separate from mail validation.

**Project synergy:** Active **project slots** (`project_user.project = 7`, **PL1–PL3**) scale **ExploreDiffMulti**.

**Manual alignment:** onboarding goal includes **finding another planet early** (**§6.1 product**).

---

## 17. Federations *(mixed manual + `[Code]`)*

**Screens / actions (`f_fed*`):** create **`f_fed_new`**, dossier **`f_fed.cfm`** / **`f_fed_detail.cfm`**, roster **`f_fed_member.*`**, apply **`f_fed_join*`**, resign **`f_fed_leave`**, ballots **`f_fed_elect`**, diplomacy **`f_fed_war`**, website field **`f_fed_website`**, forum **`f_fed_forum`**.

**Manual facts (`text/manual_fed.cfm`, `help/`):** Typical **≤ 20 empires**/fed; federation **leader-only** diplomacy (war / alliance posture); promotes **intel sharing**, mentoring, protectors for weak players; warns about **spy infiltration**.

**Fed war `[Code]` + help:** Owning federation stores single **`fed.war` target ID** (`f_fed_war.cfm` leader flow); declares broadcast **once per real day** (**dup flag**) into **`event`**; attack routing tags **“Federation War”** unlocking wider **power disparity** (**2×** stronger target permissible **vs baseline bands** **`s_com_attack_req.cfm`**). **`help/federationwar.htm`** player-facing wording references **“200%”** power stretch — aligns conceptually with code relaxations.

**NAT treaties & alliances:** Referenced in federation manual TOC (`text/manual_fed.cfm`) — expand when diplomacy scope is next revised.

---

## 18. Market & trade *(code-backed skeleton)*

**Trading loop:** **`f_com_market*.cfm`** + **`s_com_market*.cfm`** / **`s_com_market_use*.cfm`** — listings, execution, timer hooks tied to **`server#turnmin`**.

**Design position:** Primary **player-to-player** liquidations; critical for **§12** debt recovery (sell stockpiles).

---

## 19. Projects *(code-backed skeleton)*

**Modular feature set** per **`AGENTS.md`**: controllers **`Modules/Controllers/Projects/`** (incl. **HT** variants), views **`Modules/Pages/Projects/`**, command surface **`f_com_project*.cfm`**.

**Behavior:** Long-horizon builds / activations with multi-step state in **`project_user`** (example fields influence explore difficulty — §16).

---

## 20. Missions & guided acts *(structural `[Code]`)*

**Layout:** Directory **`mission/r{race}/act{1|2}/`** with **`m_*.cfm`**, **`mp_*.cfm`**, **`top.cfm`** scene headers (example race **1** Terran intro copy in **`mission/r1/act1/top.cfm`**).

**Design use:** Onboarding **optional** per §6; provides narrative beats and objective checks; not required for first-day success bar.

---

## 21. Races *(code-backed + manual copy)*

### 21.1 Source of truth

- **Database:** **`race`** table — loaded at app init into **`application.race_{id}`** metadata + boolean/number gates (**`s_loadsystem.cfm`** loop).  
- **Per-race economy & rules scalars:** **`s_getvalue_race.cfm`** → **`application.s_getvalue_race_{id}_*`** (below).  
- **Localized display names & long lore:** **`l/s_getvalue_race.cfm`** (`application.en_s_getvalue_race_{id}`, `_desc`) — also surfaces on marketing tabs (**`p_main.cfm`**).

### 21.2 Playable roster (numeric **IDs** as in **`[Code]`**)

| ID | Common name *(EN display)* | Notes from manuals / marketing |
|----|----------------------------|--------------------------------|
| 1 | Terran | **Starter race**; manual: complete **intro missions** before others; flexible economy. |
| 2 | Marauder | Raiding / **plunder** fantasy; manual: **empire death if zero colonies** + bankruptcy. |
| 3 | Guardian | **No food** consumption for pop; strong **shields**; manual: zero-colony death. |
| 4 | Collective | **Assimilation** ships/colonies; large cluster cap (manual claims **256** planets / special rules). |
| 5 | Viral (Viral 106) | **Infection** ships/colonies; reverse-engineer foreign hulls (manual). |
| 6 | A.Miner (Aspha Miners) | Defensive / mineral identity; manual: **bankruptcy-only** death line (no “no colonies” line in snippet). |
| 7 | KalZul | Rare / advanced; unique tech thread (manual). |
| 8 | D.Marauder (Dark Marauder) | Mutation-line Marauder offshoot (manual lore). |
| 9 | Unknown | Placeholder label in locale file. |

**`[Code]`** also references **race `> 60`** sentinel in **`s_com_attack_req.cfm`** (Kal-Z–related attack-protection bypass semantics — treat as balance-critical when editing).

### 21.3 Data-driven knobs (`s_getvalue_race.cfm` → `race` row)

These keys exist for **each** race id and feed **colonies**, **income**, **explore**, **combat** edge cases:

| Key suffix | Role *(summary)* |
|------------|-------------------|
| `_tax` | Scales colony **population tax** credit drip (`s_endturn.cfm`). |
| `_commercial` | Scales aggregated **commercial** income floor. |
| `_industry` | Scales **industry→goods** conversion efficiency. |
| `_agriculture` | Scales **food + raw** from farms. |
| `_mineral` | Scales colony **mining→goods/mineral** branch. |
| `_good` | Pop consumption debit of pooled **goods** (`total_colgood` path). |
| `_maintenance` | Credits charged per infra building for **maintenance**. |
| `_plunder` | Hooks into **loot / aggression** econ (see combat annex). |
| `_maxcolony` | Hard cap on **owned colonies** (enforced in **`s_com_attack_req.cfm`**). |
| `_allowexplore` | **`0`** blocks exploration UI (`f_com_explore.cfm`). |
| `_enslaveflag` | Whether race can be **enslave-attack target** (**legacy** mechanic). |
| `_missionflag` | Mission/script eligibility partition. |

Parallel **`*_text`** fields hold formatted **±%** strings for UI.

**Gates (from `race` columns cached in **`s_loadsystem.cfm`):** `selectflag`, `difficulty`, `reqpaid`, `reqact`, `reqmission` — control whether race appears as selectable advancement.

### 21.4 Product alignment

**Pillar §3:** Race must stay **gameplay-deep**, not cosmetic — metrics above underpin distinct **loops** (e.g., Guardian vs food-burn races). Any **referral / mentor** rework (**§11.4**) should preserve **clear race onboarding** (Terran first, then earned unlocks).

### 21.5 Open / drift

- Manual **empire death** lines differ by race (§11.1); ensure **future grace/bankruptcy** copy is **race-aware** where needed.  
- **Collective / Viral** special rules need a **single combat + colony annex** spec when legacy **enslave** copy is retired.

---

## 22. Ships, fleets & upkeep *(code-backed skeleton)*

### 22.1 Data model

- **`ship_class`** — human-facing **class names** (Fighter, Cruiser, …); cached **`application.shipclass_*`** (`s_loadsystem.cfm`).  
- **`ship_type`** — each **buildable / spawnable design**; fields drive **combat math**, **cost**, **racial availability**. At load, each id receives dozens of **`application.s_getvalue_ship_{id}_*`** mirrors including:  
  **`_race`**, **`_class`** (with **`class 20` remapped to `8`** for internal starbase handling), **`_range`**, **`_weapon1`–`_weapon4`**, **`_shield1`–`_shield4`**, **`_hull`**, **`_scanner`**, **`_power`**, **`_upkeep`**, **`_reqturn`**, **`_treeid`** (research gate), **`_returnfire`**, **`_longrange`**, **`_afire`**, **`_dfire`**, **`_capture`**, mineral costs **`_g1`–`_g6`**, derived **`_shipcost`**, optional **`_payaccount`** (premium-gated build flag in UI).  
- **Per-race ship ID lists:** **`application.shiptype_r1` … `shiptype_r9`** (comma lists) — used to filter what an empire of that **race** may field.

### 22.2 Construction loop

**Entry:** **`f_com_ship.cfm`** includes **`Modules/Ships/Builder.cfm`**.

**Player inputs:** `user_ui` stores **builder visibility / dummy “fill fleet” sets / custom order** (`builder_visible_ships`, `builder_dummy_ships`, `builder_ship_order`). Research unlock list **`application.s_getvalue_user_{userid}_r_ship`** defines which **hull ids** appear.

**Spend:** Batch build deducts **credits**, **minerals `g1–g6`**, and **turns** — per-hull **`reqturn` * `application.mod#{server}#_51`** (`buildmod` in **`Builder.cfm`**). Locks prevent concurrent corrupt builds (**`Exclusive` locks**).

**Debt note *(product §12):* **planned** ban on **new ship construction** while insolvent must hook here.**

**Premium:** Ships with **`_payaccount = 1`** hidden from non-premium builders in **`f_com_ship.cfm`** card loop.

### 22.3 Upkeep & batch jobs

**Per-ship upkeep estimate** composes weapon diversity, shields, hull, range, specials, racial **scalar** from **`Z_Upkeep_Calc.cfm`** (`RaceMod[race]` table in file — Terran vs Marauder vs Guardian..., starbase **`class==8`** × **1.2**, neutral hull-type multipliers for **NPC/zero race** subsets). Stored aggregate **`application.shipupkeep_{userid}`** consumed each **`cf_s_endturn`** (`s_endturn.cfm`).

### 22.4 Combat resolution (fleet vs fleet)

Round script **`s_com_attack.cfm`** walks paired stacks: damage blends **up to four weapon channels** against four **shield** channels, applies **hull** loss, handles **defensive fire / flanking** via **`_dfire`** counters, prunes destroyed ships from **stack lists**. PR **power ratings** elsewhere (`user.power`) gate **§10 eligibility**.

### 22.5 Supporting UI surfaces

| Surface | File(s) |
|---------|---------|
| Builder grid | **`f_com_ship.cfm`** (modern **`gc-builder-*`** layout) |
| Builder preferences | **`f_com_ship_settings.cfm`** |
| Ship detail sheet | **`f_com_ship2.cfm`** (`shiptype` query param) |
| Race-flavored ship listing | **`f_com_ship_r.cfm`** |

### 22.6 Design backlog

Document **fleet deployment** (**formations**, **escorts**, reinforcement caps) directly from attack UI templates when consolidating **PvP playbook**. Tie **capture / assimilate / infect** verbs to **`_capture`** and race branches in **`f_com_attack*`** suite.

---

### Deferred work

**Holistic UI / page design:** establish permanent patterns when the dedicated **design modernization** effort runs; **`§13.2`** supersedes any prior “economy-only migration” tracking.

---

## Appendix A — Key code reference (quick)

| Topic | Location |
|-------|----------|
| Turn generation / spend; debt on negative credit | `z_endturn.cfm`, `s_endturn.cfm`, `cf_s_endturn` in `z_endturn.cfm` |
| Server timing constants | `s_loadvar.cfm` |
| Attack eligibility | `s_com_attack_req.cfm` |
| Round damage resolution | `s_com_attack.cfm` |
| Fed war declare / cooldown | `f_fed_war.cfm`, `help/federationwar.htm` |
| Signup server list & introducer refs | `p_signup.cfm` |
| Player market (liquidation pathway) | `f_com_market*.cfm`, `s_com_market*.cfm` |
| Frame / themes | `i_f_800.cfm`, `theme.css`, `AGENTS.md` |
| Ship construction | `f_com_ship*.cfm`, `Modules/Ships/Builder.cfm` |
| Colony commands | `f_com_col*.cfm` |
| Colony tick / income math | `s_endturn.cfm` (colony loop inside `cf_s_endturn`), `cf_s_endturn` in `z_endturn.cfm` |
| Research UI / DB tree | `f_com_research*.cfm`, `restree` loaded in `s_loadsystem.cfm` |
| Exploration | `f_com_explore.cfm`, `f_com_explore_cal.cfm`, `f_com_explore2.cfm` |
| Federation hub | `f_fed*.cfm`, `text/manual_fed.cfm`, `help/federation*.htm` |
| Projects | `Modules/Controllers/Projects/`, `Modules/Pages/Projects/`, `f_com_project*.cfm` |
| Mission arcs | `mission/r*/act*/` |
| Income page (**provisional** UX experiment) | `f_com_income.cfm` |
| Player manual | `text/manual_*.cfm`, `help/` |
| Race DB + scalars | `race` table, `s_getvalue_race.cfm`, `l/s_getvalue_race.cfm` |
| Ship types + classes | `ship_type`, `ship_class` (via `s_loadsystem.cfm`) |
| Ship builder | `Modules/Ships/Builder.cfm`, `f_com_ship*.cfm` |
| Upkeep formula | `Z_Upkeep_Calc.cfm` |