Training / production UI — design brief

A working document for a session on showing what a unit being trained is gathering (and, relatedly, the materials a building or tile work is buying) when the player clicks it.

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 a framework-free model; server/game_server.js owns one and validates orders.
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.
The economy is hourly (shared/game_state/resources.js _tickResources) and materials are bought at current market prices; there is no more "1% per day budget increase" (a construction site just buys what it needs).
Data lives in shared/data/ (barrel: shared/data.js).

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 (--testing adds the free/instant train and build buttons).

Conventions

2-space indent; no new libraries; dummy icon dummy icon - <name>.
Tests in tests/<topic>_test.js extending TestCase; fixtures in tests/framework/helpers.js. Force RNG with state._random = () => value.
Visual changes get a minimal standalone HTML preview linking client/css/style.css, opened in Firefox, before commit.

2. Requirement (from `ROADMAP.md`)

Show that units being trained are gathering resources when the player clicks on training them

This sits directly under the Economics section, next to the construction-market change ("a construction site simply tries to get materials at current market prices"). The likely intent: the production queue should visibly account for the materials phase — as it already does for buildings — for units too, and clicking a queued/training item should reveal the resources it is drawing.

3. How production works today

City panel is client/js/modals/city.js; DOM in client/index.html (#city-train-list, #city-train-status, #city-train-label, #city-train-progress, #city-train-queue). The train tab shows both units and buildings (the shared production queue).
Queue rendering renderQueue(queue) (city.js:467) groups contiguous identical entries, shows "Ready in …" and a Cancel button, and — for a building in the phase === "materials" phase — swaps the timing for "Gathering materials" and adds no time to the estimate.
Training status beginTraining / setTrainingProgress / endTraining (city.js:516-531); setGatheringProgress (536) shows "Gathering materials for X…" with a fraction, used for the head-of-queue building.
Server side (to confirm): shared/game_state/orders.js requestTrain / requestBuild enqueue orders; shared/game_state/sites.js runs the building materials phase (buying steel/high-tech at market, a phase: "materials" with a fraction); shared/game_state/resources.js does the buying. Units are trained from money plus a population draw (infantry) and may have a materialUpkeep but currently have no materials-gathering phase visible to the client.
Testing mode adds free/instant variants (--testing), which skip the queue; keep the display correct there too (or intentionally silent).

4. Open questions (settle before coding)

What does "gathering resources" mean for a unit? Options: (a) units get a real materials phase (buy steel/high-tech before the clock starts), mirroring buildings — a model change; (b) units are paid in money and population only, and the UI should instead show the population draw (the soldiers taken from the region) and the money cost as it is paid; (c) the UI should show the materials upkeep the unit will need once built. The roadmap wording ("gathering resources") suggests (a).
Click to inspect. The requirement says when the player clicks on training them. Today queue rows are read-only (Cancel only). Decide whether clicking a queue row expands a detail panel (resources still to buy, bought so far, cost paid, population drawn, ready time) or opens a modal.
Where do the figures live? The queue entries need to ship the per-entry materials state (needed/bought/phase/fraction) in the snapshot; confirm what the server already sends (view.queue) and extend it. Watch snapshot size — the queue is small, so it is probably fine, but pair it with the city view.
Cancel/refund. Cancelling a building refunds nothing today. If units get a materials phase, does cancelling refund the materials? Keep it consistent with buildings.
Construction sites on tiles share this materials model (shared/game_state/sites.js); decide whether tile works get the same click-to-inspect treatment (they are improved in client/js/game_screen/panels.js tile panel / _openTileManageModal).
Testing mode. The free/instant button bypasses the queue; make sure the new display does not show a phantom materials phase.

5. Suggested order of work

Read shared/game_state/sites.js and orders.js to pin down exactly what the building materials phase is and what the snapshot already carries for the queue.
Decide question 1. If units stay money+population, the "gathering" UI is about the population draw and the money/materials cost; if they gain a materials phase, reuse the site phase.
Extend the queue entry with the fields the detail view needs and render the click-to-inspect panel in client/js/modals/city.js.
Add tests: the queue entry carries the right phase/fraction; clicking a training item shows the expected fields; testing mode does not show a materials phase.

6. Tests to add / extend

Server: a queued unit's entry exposes its materials/population state (whatever question 1 decides).
Client: tests/game_screen_test.js / a city-modal test clicks a training queue row and asserts the detail is shown; the gathering label appears only in the materials phase.
Keep tests/construction_site_test.js, tests/game_screen_test.js, tests/modals_test.js green.

7. Gotchas

Snapshot churn. The queue is rebuilt each refresh; keep the click-to-inspect selection keyed by queue index/run, not a DOM node that gets thrown away (the city panel already has this problem — see the "signature" guards in _renderTrainList/renderQueue).
Testing mode free/instant orders must not be given a fake gathering phase.
Population draw correctness: training draws people from the region at random; if you surface it, read the same code path the model uses.
Market prices move: a quoted cost is a snapshot; label it as an estimate the way the rest of the UI does (quotedBuildCost, _quoted).

8. Relevant files

client/js/modals/city.js — renderQueue, beginTraining, setTrainingProgress, setGatheringProgress, _renderTrainList.
client/index.html — the city modal and #city-train-* DOM.
shared/game_state/sites.js — the building/tile materials phase and fractions.
shared/game_state/orders.js — requestTrain / requestBuild / cancel_train.
shared/game_state/resources.js — buying and payCombatResources/ construction spending.
client/js/game_screen/panels.js — the city view (_cityView) that fills the queue, and the tile-improvement panel.
Tests: tests/construction_site_test.js, tests/game_screen_test.js, tests/modals_test.js, tests/testing_mode_test.js.

INTELLIGENCE.md, STACKS.md, AIR_MOVEMENT.md, ECONOMY_BALANCE.md, POLITICS_PERFORMANCE.md, ICONS.md (repo root).

8.0 KiB Raw Blame History