Battle-for-Tismo/ROADMAP.md

# Battle for 'Tismo — roadmap

This reconstructs the feature brief that drove the recent work, from the task
list given in the project chat and the state of the code afterwards. It is a
reconstruction, not a verbatim copy: where the original wording was lost it has
been restated from what was actually built.

`[x]` = implemented and covered by the test suite. `[~]` = implemented with a
simplification worth revisiting. Anything unticked is still open.

## General guidelines

- If an icon is missing, add a dummy SVG that reads `dummy icon - <name>`.
- Once an item is finished, move on to the next; keep the suite green and add
  tests for each new pure behaviour.
- Percentages are for the final figure only; raw effects are stated in the
  model's own integer units (e.g. popularity points).

## 1. Visual / UI

- [x] City progress bar under the city name, plus a quick production view in
      the city panel.
- [x] Remove the city "improve" button; cities improve themselves as railways
      are laid.
- [x] Per-improvement buttons above the tile panel, with a control to remove an
      improvement.
- [x] Manual unit selection in the stack panel (checklist).
- [x] Clicking a unit opens the panel for its tile or city.
- [x] A stack splits immediately when a member leaves it.
- [x] Logarithmic scale for the population map mode.
- [x] Building squares drawn around the city icon, in a seeded pattern.
- [x] Upgrade tooltip forecasts the resulting budget income.
- [x] Artillery barrages are always visible, dimmed unless selected.
- [x] Square icon buttons for tile improvements: name in the tooltip, cost
      beneath the icon.
- [x] A progress bar for a tile improvement under construction, like a city's.
- [x] Technology tab: wide, short (3:1) cards in a grid; a focused technology
      shows a progress bar with `X / Y` to its right; the button no longer
      repeats the cost.
- [x] Key art behind the main menu.
- [x] Double-clicking a city opens its full city panel.
- [x] Barrages drawn as animated parabolic arcs from attacker to target (SVG
      Bezier, marching dashes, a shell riding the curve).

## 2. Populations and popularity

- [x] Popularity counted in integer points, shown through a logistic curve
      (0 -> 50%, +100 -> 75%).
- [x] Opinions drift one point an hour toward neutral.
- [x] War effects: declaring war, being declared on (rally when the aggressor is
      loathed), unit losses and kills, city capture and loss.
- [x] Pillaging leaves a popularity stain, doubled among the affected peoples.
- [x] Minorities above 10% cannot be expelled.
- [~] Structure and city damage is modelled as city population/GDP loss plus
      improvement hit points, not a dedicated per-structure HP system.

## 3. Nation top info bar

- [x] Month-over-month arrows on population, GDP, GDP per capita, budget and
      popularity.
- [x] GDP, population and GDP per capita double their arrow past a 10% move;
      popularity past ten percentage points.
- [x] No arrows for January 2000, which has no past month.
- [x] Popularity tooltip estimates hours/days to neutrality at the drift rate.

## 4. Technologies

- [x] Focused research: every point flows straight into the chosen technology;
      there is no bank, so no focus means no progress.
- [x] Committed progress is kept per technology, so changing focus never loses
      work already done.
- [x] Repeatable technologies with a 2% cost growth per level, notified without
      flooding the news list.
- [x] Repeatable technologies, once researched, get automatically focused again
- [x] Theme tabs (Science / Economy / Society / Military).
- [x] Technology panel shows the research rate rather than a stockpile.
- [x] Readable effect text for the military and repeatable effects.

## 5. War mechanics

- [x] Zone of control: units deny their tile and the ring around it to hostile
      movement, mirrored in client prediction; the deliberate goal is exempt so
      charges resolve.
- [x] Battleships and ground batteries bombard coastal units and defenceless
      cities from range.
- [x] Capturing a city takes the aircraft based there.
- [x] Infantry capture unaccompanied artillery; a warship over a launch stack
      sinks it.
- [x] Trenches: dug by infantry, defensive bonus against melee and artillery,
      local GDP cost.
- [x] Combat order: infantry absorbs blows first; exposed support units are hit
      before dug-in troops.
- [x] New units: mobile radar (wide vision, captured or destroyed easily) and
      the launch transport (embark, carry one infantry, disembark a whole
      stack).
- [x] Buildable military tile improvements: fortifications (permanent area of
      control, defensive bonus, battle damage), radar tower (captured by an
      enemy walking on it), coastal cannon (auto-fires on warships).
- [x] Embark / disembark orders wired on server and client, with a cargo readout
      in the unit panel.
- [x] Easy and ergonomic way to split unit stacks.
- [x] Give stacks with range units a dedicated button to perform ranged attacks,
      right-clicking will now ONLY move (obviously triggers a battle when moving on the same tile)

## 6. Content and tuning

- [x] Market and Bank base cost reduced tenfold (500k and 1M).

## 7. Resources

- [x] Add the following resource groups:
  - [x] Energy. Uses the electric icon. In kWh, MWh, GWh, TWh.
  - [x] Steel. Uses the I-beam icon. In tonnes.
  - [x] Food. Uses the apple icon. In tonnes.
  - [x] Luxury. Uses the diamond icon. In carats.
  - [x] High-tech. Uses the microchip icon. In units.

* [x] Resources are stored on every tile that is either a city or a resource production building.
  * [x] Cities and tiles automatically try to buy necessary resources from their neighbours, including non-hostile cities.
  * [x] Energy produced by power plants cannot be stored.
* [x] Keep track of resource prices in the global market.
  * [x] Transporting resources costs additional money, used to automatically buy energy.
* [~] Fossil fuels are abstracted into the transformative plants' money upkeep
      rather than a stored fuel resource: the roadmap lists only the five
      groups above, so coal, gas and oil are not separately tracked.
* [~] Energy is modelled as a daily flow everywhere, so no city can bank it.
      Only the other four groups have per-tile storage.


### Delivering resources
* [x] Delivering 1 tonne of resources over 1 tile requires 10 MWh by truck over roads, 50 MWh * tile movement cost without roads, 1 MWh by train, 50 kWh by ship.
* Freight is deliberately costly: hauling goods burns far more energy than the
  goods themselves are worth over any real distance, so the heavy electricity
  load the delivery graph puts on the grid is intended, not a leak to shave.
* [x] A delivery graph, revealed only in the economic map mode, is created.
  * [x] The delivery graph is built
* [~] 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.

### Food
* [x] Each person requires 1 kg of food per day. That's how much cities have to buy. Cities attempt to buy up to 130 % of their needs for the month.
* [x] Producing 1 tonne of food requires 1 MWh of energy.

### Energy
* [x] Cities require energy to function. Add a new economic metric (not in the top though), kWh/€ of GDP. This determines the base energy consumption of cities.
* [x] Electric energy is delivered instantly to the entire connected region when requested, at no cost.
      Every country starts having each of their contiguous cities be connected.
* [x] Without electric energy, cities and buildings attempt to buy energy that has to be delivered. 10 GWh of energy count as 1 tonne of material.
* [x] Energy is needed to create all other resources

### Steel
* [x] Everything requires steel to be built.
* [x] 20 MWh/tonne of steel at the steel mill
* [x] Each inhabitant consumes 1 kg of steel per day.

### Luxury
* [x] Inhabitants require 0.01 ct of luxury per day. No building or military unit requires that.

### High-tech
* [x] Science buildings require high-tech so they can be built, and they will consume 1 unit of high-tech per tech point they produce.

### Buildings
* [x] New resource-producing buildings, built only _outside_ of cities:
  * [x] Energy buildings:
    * [x] Electricity buildings
      * [x] Transformative plants: turn storable fossil fuels into electricity.
        * [x] Coal power plant
        * [x] Natural gas power plant
        * [x] Oil power plant
      * [x] Renewable energy plants: create a limited amount of electricity for free
        * [x] Solar power plant
        * [x] Geothermal plant
        * [x] Wind turbines
        * [x] Offshore wind turbines
        * [x] Fusion power plant
  * [x] Steel buildings:
    * [x] Steel mill
  * [x] Food buildings:
    * [x] Food is automatically produced by tiles, in the same proportions as their population.
  * [x] Luxury buildings:
    * [x] Gold mine. 10 MWh/ct
    * [x] Diamond mine. 5 MWh/ct
  * [x] High-tech building:
    * [x] Chip foundry.

* [x] A dedicated resource panel in the nation modal: the Resources tab shows
      each group's stores, daily need, upkeep and production beside the global
      market's price and the world's supply and demand.
* [x] Every nation opens with the resource works its economy needs, laid out
      randomly from the world seed at map generation (converters first, then
      enough power for each connected grid) so the opening economy covers its
      people's, industry's and upkeep's needs. Works beside the transport
      network get a one-tile road spur so their output can reach a city, and the
      per-capita balance is re-derived afterwards so no nation starts richer
      just because its land hosts more industry. Food is not covered by any
      building, so a food-poor nation still buys on the market.
* [x] A port also lifts its region's food output: 5% per adjacent sea tile per
      level, on top of its GDP-per-capita bonus.

### Upkeep and repairs
* [x] Buildings, units, tile works and the transport network no longer cost
      money to keep; they wear out in materials (steel, with high-tech for
      advanced things) that the state buys from its stores and the market.
      Money upkeep is now only propaganda campaigns.
* [x] Construction spends materials as well as money (steel proportional to the
      cost, high-tech for advanced items).
* [x] Repairs cost materials: a razed city building level is rebuilt once paid
      for, a damaged unit heals at a steel/high-tech cost, a damaged tile work
      heals once its steel debt is cleared, and a tile with unpaid damage does
      not recover its GDP.
* [x] Infantry units carry 1,000 soldiers. Training one draws that many people
      at random out of the region's population, and healing a damaged unit draws
      replacement soldiers the same way. A unit's soldiers need double rations in
      combat and triple while wounded and resting in one of their own cities.
* [x] Supply applies to every land unit: it carries 50 days of food. At home, or
      in foreign territory with a clear route (land or maritime) to an allied
      city, it eats from the nearest such city and tops its pack up; cut off, the
      days run down and then the soldiers start dying of starvation.
* [x] Encirclement is local: a tile is encircled when enemy units hold every
      land tile beside it and it has no working port. An encircled city or unit
      loses its neighbours and the foreign market and eats its own reserves. A
      port keeps its tile supplied unless enemy warships hold every sea tile
      around the city (a blockade).
* [x] Every naval city opens the game with a port. A working port on a city's
      continent is the only link to other continents: without one, cities trade
      over land on their own continent only and cannot use the foreign market
      (nor can construction, upkeep, combat or unit supply draw on it).
* [x] Every delivery runs on the transport network: roads and railways on land,
      shipping lanes across water (which need a working port). There is no
      off-road trucking, so a resource building or city off the network cannot be
      bought from until it is linked, and a nation's market is reached along the
      same roads and rails. Goods never cross the land of a nation you are at war
      with.
* [x] Guns and aircraft are cheap parked and costly to fire: air defense,
      artillery and aircraft have little standing upkeep and spend munitions
      (steel/high-tech) on every volley or sortie, with no shot when the
      materials cannot be found.
* [x] The fusion power plant is gated behind Fusion Power, a 500,000-point
      technology.
* [ ] A resource budget line in the national budget breakdown (the money spent
      on upkeep, electric imports, goods and their transport is tracked by the
      model but the actual spend is not yet its own row in the budget table; the
      table currently forecasts upkeep at market prices).


## Open items

- [ ] Faster politics tick: with the trade-graph walks cached, `_tickPolitics` is
      the largest remaining cost in a settled world -- `_migrateForIncome`
      through `_regionIncomePerCapita` and `_movePopulation`, and the repeated
      `_cityMechanicLevel` lookups each of them makes. Memoise the per-region
      income the way the trade graph is now kept, and let a migration sweep visit
      only the regions whose pull actually changed.
- [ ] Luxury and high-tech prices climb to a plateau far above their base (the
      economy simulator's index reaches about 500-650 for luxury and 200-230 for
      high-tech) instead of settling; revisit the supply and demand balance of
      the two rarer goods.
- [ ] Real art for the placeholder "dummy icon" SVGs: `icon_radar.svg`,
      `icon_coastal_cannon.svg`, `icon_chip_foundry.svg`,
      `icon_geothermal_plant.svg`, `icon_offshore_wind_turbines.svg`,
      `icon_wind_turbines.svg`.

### Player interaction 
- [x] In-game chat
  - Access by pressing T
  - Shows a text input field in the bottom center
  - chat messages are ordered down to up, last to first

- [x] Player list
  - In the diplomacy tab, show who's in control of a nation: the AI or a player
  - Show it using an icon: human or computer
  - Also add a column with the leader's name

- [x] Diplomatic treaties, that can convey custom text
  - [x] In the diplomacy tab, show currently active and past treaties
  - [x] Players receiving a treaty proposal get a notification, clicking on it opens the treaty info
  - [x] Treaties have a "Sign" and "Reject" buttons
  - [x] The whole world is informed that a treaty is being sought, has been signed or has been rejected
  - Types of treaty effects:
    - [x] Peace: stops the state of war between two players. All battles cease, troops in enemy territory immediately move to their closest city.
        - Stranded troops on islands get teleported back, for now
        - Going back to war breaks the treaty and warns the player
    - [x] Alliance: signatory players cannot go to war with each other without breaking the treaty. Attacking a member of an alliance declares war on the entire alliance.
    - [x] Free trade: all tariffs to 0 between the signatory parties
    - [x] Give city
    - [x] Give military materials (cannot gift infantry)
    - [x] Give resources
    - [~] Give money
      - Denominated in any currency. Taken from the giving player's central bank foreign reserves if possible, otherwise, bought from the relevant central bank
        (simplified: the sum moves straight between the two treasuries, no FX or reserves leg)
      - Cannot get currency from a central bank from a country at war with you
    - [x] Joint research
      -  Each players gets the sum of tech points produced by the signatory parties when they focus tech, except on military technology

### Military

- [x] Better troop management
  - [x] In the unit stack panel, can select all units of a type at once
  - [x] Show a table of icons instead of the current list
- [x] Submarine unit
  - [x] Invisible to other players unless a naval unit is DIRECTLY adjacent
- [~] Missiles
  - [x] One-use units.
  - [x] Types of missiles
    - [x] Conventional, 30 tiles range
    - [x] Nuclear (locked behind nuclear tech), 30 tiles range
    - [x] ICBM, nuclear (locked behind nuclear tech and space program), reaches any tile
    (a plain missile carries a conventional warhead unless the player arms it
    nuclear from the unit panel; the ICBM is nuclear by design)
- [~] WMDs
  - [x] Nuclear program
    - [x] Build uranium enrichment centers in cities
    - [ ] Foreign intelligence may be warned that you are enriching uranium
    - [x] Once a uranium enrichment center exists, the nuclear weapons tech is unlocked
    - [x] Once the technology research is complete, players can choose nuclear payloads
          in their missiles
    - [x] Nuclear explosion effects:
      - [x] -90% population on a tile
      - [x] All buildings and improvements destroyed, except for bunkers and fortifications
      - [x] -1000 popularity across the board
      (any unit caught in the blast is destroyed too)
- [x] Stacks must behave as single units when it comes to pathfinding
  - [x] Cannot go through neutral third-party territory, allied and at-war territory can be walked through
- [x] Airplanes move in straight lines as they are not bound by tiles.
* [x] Non-melee units such as artillery, airplanes, have an 80 % chance to be destroyed when an enemy attempts to capture them

### Intelligence
* [ ] Gets its own tab
  - Move propaganda operations to intelligence
* [ ] Spy unit
  - Invisible to all other players, by default
  - 1 tile-radius vision
  - Mostly high-tech cost
  - Can move into enemy territory
  - [ ] Sabotage action:
    - Blocks production of on a given tile for a week, performed while in *any* country
    - Perpetrator is given a choice to try and blame someone else
    - The victim gets a notification, depending on intelligence and counterintelligence level, someone, or no one, will be blamed.
      - No way for the player to differentiate between a correct blame assignment or a successful false flag
  - [ ] City spying
    - Perpetrator gets a report on a city's status, building levels, etc. Counter-intelligence can make the report contain false information
  - [ ] Comms spying
    - Done in the capital of a country
    - Reveals the N last private messages sent from and to that player
    - Counter-intelligence may garble the messages, or change the sender and receiver of messages
* [ ] Counter-intelligence tech
  - [ ] Extremely expensive
* [ ] Spy satellites
  - [ ] New space launch center
    - Extremely expensive
    - [ ] allow "send spy satellite" action
      - Everyone is made aware that a satellite was launched
  - Reveal a random 2-tile-radius chunk of the map every two days

### Migrations

- [x] Populations cannot migrate from their country to a hostile one
- [x] Expel [population] prevents that population from moving to the country
- [x] Migration rate cannot be more than 0,01%/day from the original tile.

### Economics
- [x] Remove the "1% per day budget increase". A construction site simply tries to get materials at current market prices.
- [ ] Show that units being trained are gathering resources when the player clicks on training them