Battle-for-Tismo/SIMPLIFICATIONS.md

# Simplifications worth revisiting — design brief

The `[~]` items in `ROADMAP.md`: features that are implemented with a deliberate
shortcut, kept honest so a later session can decide whether to build them out.

---

## 1. Shared project context (read this first)

*Battle for 'Tismo* is an HTML5 port of a turn-of-the-millennium strategy game.
Pure JavaScript, no build step, no runtime dependencies.

- **Server-authoritative.** `shared/game_state.js` (`GameState`) is the model;
  `server/game_server.js` validates orders; the browser renders snapshots.
- **Shared logic runs in Node and the browser**; `shared/` stays framework-free
  (no Node, no DOM).
- **GameState is mixins.** `shared/game_state.js` imports each
  `shared/game_state/<topic>.js` and adds its methods to the prototype.
- **Data** lives in `shared/data/` (barrel: `shared/data.js`).
- **Version counters / memoisation** guard the snapshot and tick paths
  (`_populationVersion`, `_territoryVersion`, `_tileImprovementVersion`,
  `_gdpEpoch`, the trade-graph stamp). A new snapshot collection needs a
  `DELTA_COLLECTIONS` entry and a version.

### Commands

- Install once: `npm install`.
- One suite: `node tests/run_tests.js --file <name>.js`. **Never the full suite**
  during development — the commit hook runs it.
- Server: `node server/server.js --port 27015 --bind 127.0.0.1`.

### Conventions

- 2-space indent; no new libraries; dummy icon `dummy icon - <name>`.
- Tests in `tests/<topic>_test.js` extending `TestCase`; force RNG with
  `state._random = () => value`.
- Commit only when asked; one imperative sentence; the hook runs the full suite.

---

## 2. Structure damage is abstracted

**`[~]`** *Structure and city damage is modelled as city population/GDP loss
plus improvement hit points, not a dedicated per-structure HP system.*

- Today: a city level or tile work has hit points / a repair debt
  (`RESOURCE_RULES.repair`, `shared/game_state/` combat/improvements), and its
  loss shows as population and GDP loss. There is no per-building HP.
- Full model: each structure on a tile tracks its own condition, so a
  bombardment knocks out one specific building rather than degrading the city as
  a whole; repairs target the structure.
- Questions: does per-structure HP add meaningful decisions, or just bookkeeping?
  How does it interact with the existing repair debt and the capture/destruction
  rules? Snapshot cost if every structure carries HP.
- Files: `shared/game_state/resources.js` (repair rules), combat/improvements
  mixins, `shared/data/combat.js`.

## 3. Fossil fuels are not a resource

**`[~]`** *Fossil fuels are abstracted into the transformative plants' money
upkeep rather than a stored fuel resource (the roadmap lists only the five
groups: energy, steel, food, luxury, high-tech).*

- Today: coal/gas/oil plants pay their fuel as money upkeep; there is no coal,
  gas or oil stock to buy, store or blockade.
- Full model: fossil fuels as storable resources with extraction buildings,
  market prices and a transport bill, making a blockade or a price spike bite.
- Questions: does adding two-to-three more resources pay for the extra UI and
  simulation? The roadmap deliberately lists only five groups.
- Files: `shared/data/resources.js`, `shared/data/buildings.js`,
  `shared/game_state/resources.js`.

## 4. Energy is a daily flow, not a store

**`[~]`** *Energy is modelled as a daily flow everywhere, so no city can bank
it. Only the other four groups have per-tile storage.*

- Today: electricity is produced and consumed within the tick; no battery.
- Full model: energy storage (batteries), so a surge can be banked and a
  brownout ridden out; possibly strategic reserves.
- Questions: does storage break the "energy is cheap and everywhere" balance?
  Round-trip losses? Interaction with the delivery graph (10 GWh = 1 t of
  delivered energy).
- Files: `shared/game_state/resources.js`, `shared/data/resources.js`,
  `shared/data/buildings.js`.

## 5. Cities buy from the cheapest source with a nominal delivery

**`[~]`** *A city always buys from the cheapest source: a nearby store whose
delivered price beats the market, or the global market itself. Market buying
uses a nominal two-tile road delivery.*

- Today: the choice is price-only; distance affects the delivered price but not
  which routes are physically available beyond the network rules.
- Full model: a city bids across the transport network with real routing, lead
  times and possible stock-outs, instead of a nominal two-tile market leg.
- Questions: does the simplification hide transport bottlenecks the delivery
  graph is meant to surface? How is the nominal leg calibrated?
- Files: `shared/game_state/resources.js`, `shared/game_state/economy.js`,
  `client/js/map_view/modes.js` (delivery graph), `client/js/map_view/economic.js`.

## 6. Missiles / WMD

**`[~]`** *Missiles* and *WMDs* are marked `[~]` while their sub-items are
largely `[x]`.

- Today: a plain `missile` is conventional unless the player arms it nuclear
  from the unit panel (then it needs `nuclear_weapons`); the `icbm` is nuclear by
  design and needs `nuclear_weapons` + `space_program`. A nuclear blast kills
  ~90% of a tile's people, destroys buildings/improvements except bunkers and
  fortifications, and costs every nation popularity.
- What is unfinished: further refinement of blast falloff / interception (the
  "foreign intelligence may be warned that you are enriching uranium" follow-up
  is now implemented).
- Files: `shared/game_state/wmd.js`, `shared/data/units.js`,
  `shared/data/combat.js`, `client/js/game_screen/panels.js`.

---

## 7. Related design docs

`DESIGN.md` (index), `ICONS.md`.