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

• City progress bar under the city name, plus a quick production view in the city panel.
• Remove the city "improve" button; cities improve themselves as railways are laid.
• Per-improvement buttons above the tile panel, with a control to remove an improvement.
• Manual unit selection in the stack panel (checklist).
• Clicking a unit opens the panel for its tile or city.
• A stack splits immediately when a member leaves it.
• Logarithmic scale for the population map mode.
• Building squares drawn around the city icon, in a seeded pattern.
• Upgrade tooltip forecasts the resulting budget income.
• Artillery barrages are always visible, dimmed unless selected.
• Square icon buttons for tile improvements: name in the tooltip, cost beneath the icon.
• A progress bar for a tile improvement under construction, like a city's.
• 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.
• Key art behind the main menu.
• Double-clicking a city opens its full city panel.
• Barrages drawn as animated parabolic arcs from attacker to target (SVG Bezier, marching dashes, a shell riding the curve).

2. Populations and popularity

• Popularity counted in integer points, shown through a logistic curve (0 -> 50%, +100 -> 75%).
• Opinions drift one point an hour toward neutral.
• War effects: declaring war, being declared on (rally when the aggressor is loathed), unit losses and kills, city capture and loss.
• Pillaging leaves a popularity stain, doubled among the affected peoples.
• 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

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

4. Technologies

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

5. War mechanics

• 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.
• Battleships and ground batteries bombard coastal units and defenceless cities from range.
• Capturing a city takes the aircraft based there.
• Infantry capture unaccompanied artillery; a warship over a launch stack sinks it.
• Trenches: dug by infantry, defensive bonus against melee and artillery, local GDP cost.
• Combat order: infantry absorbs blows first; exposed support units are hit before dug-in troops.
• New units: mobile radar (wide vision, captured or destroyed easily) and the launch transport (embark, carry one infantry, disembark a whole stack).
• 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).
• Embark / disembark orders wired on server and client, with a cargo readout in the unit panel.
• Easy and ergonomic way to split unit stacks.
• 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

• Market and Bank base cost reduced tenfold (500k and 1M).

7. Resources

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

• Resources are stored on every tile that is either a city or a resource production building.
  • Cities and tiles automatically try to buy necessary resources from their neighbours, including non-hostile cities.
  • Energy produced by power plants cannot be stored.
• Keep track of resource prices in the global market.
  • 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

• 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.
• A delivery graph, revealed only in the economic map mode, is created.
  • 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

• 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.
• Producing 1 tonne of food requires 1 MWh of energy.

Energy

• 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.
• 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.
• 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.
• Energy is needed to create all other resources

Steel

• Everything requires steel to be built.
• 20 MWh/tonne of steel at the steel mill
• Each inhabitant consumes 1 kg of steel per day.

Luxury

• Inhabitants require 0.01 ct of luxury per day. No building or military unit requires that.

High-tech

• 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

• New resource-producing buildings, built only outside of cities:

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

• 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.

• 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.

• 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

• 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.
• Construction spends materials as well as money (steel proportional to the cost, high-tech for advanced items).
• 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.
• 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.
• 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.
• 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).
• 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).
• 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.
• 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.
• 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.
• A dedicated structure hit-point model for cities and tile improvements (see the [~] note above).
• 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.