Gave the world spies, treaties and nuclear weapons

2026-09-24 19:23:54 +02:00
parent 54efd66a63
commit cc5c57c5f4
85 changed files with 7219 additions and 260 deletions
@@ -0,0 +1,173 @@
+# Icons / art — design brief
+
+A working document for a session on replacing the placeholder **"dummy icon"**
+SVGs with real art.
+
+---
+
+## 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**, but art is purely client-side: SVGs live in
+  `client/assets/` and are referenced by filename from `shared/data/*.js`
+  (`icon: "icon_<name>.svg"`) and a few `client/assets/` references in JS.
+- **No build step and no image pipeline** — dropping an `.svg` in
+  `client/assets/` and referencing its filename is the whole process. The
+  `nix/package.nix` `web` output copies `client/` and `shared/` verbatim.
+- **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 + client: `node server/server.js --port 27015 --bind 127.0.0.1`.
+
+### Conventions
+
+- A missing icon gets a dummy SVG reading `dummy icon - <name>` (the standing
+  rule in `AGENTS.md`/`ROADMAP.md`).
+- **Visual changes are reviewed by eye before commit.** For icons, build a small
+  standalone HTML gallery that links `client/css/style.css` and shows the icons
+  at the sizes the UI actually uses, then **open it in Firefox**
+  (`firefox <path>`). Do not screenshot and do not just print the path.
+- 2-space indent for `.js`; no new libraries.
+- Commit only when asked; one imperative sentence; the hook runs the full suite.
+
+---
+
+## 2. Requirement (from `ROADMAP.md`)
+
+> - [ ] 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`.
+
+Note: `icon_radar.svg`, `icon_coastal_cannon.svg`, `icon_chip_foundry.svg` and
+`icon_wind_turbines.svg` no longer contain the word "dummy" (they appear to have
+been replaced already), so the list may be partly stale — **re-derive the live
+list** with the command below before starting.
+
+---
+
+## 3. Current placeholders
+
+Find them with:
+
+```sh
+rg -il "dummy" client/assets/*.svg
+```
+
+As of this writing that lists (subject to change):
+
+- `icon_computer.svg`, `icon_human.svg` — player-list control icons (diplomacy
+  tab; used at 20px).
+- `icon_geothermal_plant.svg`, `icon_offshore_wind_turbines.svg` — power plants.
+- `icon_icbm.svg`, `icon_missile.svg` — missiles.
+- `icon_spy.svg` — the spy unit.
+- `icon_submarine.svg` — the submarine.
+- `icon_uranium_enrichment.svg` — the nuclear building.
+
+The dummy template (all of them share it):
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" style="height:512px;width:512px">
+  <rect x="8" y="8" width="496" height="496" rx="24" fill="#2b3550" stroke="#ffffff" stroke-width="12"/>
+  <text x="256" y="266" fill="#ffffff" font-family="sans-serif" font-size="40" font-weight="700" text-anchor="middle">dummy icon</text>
+  <text x="256" y="316" fill="#ffffff" font-family="sans-serif" font-size="40" font-weight="700" text-anchor="middle">spy</text>
+</svg>
+```
+
+---
+
+## 4. Art direction
+
+- **Canvas:** `viewBox="0 0 512 512"`, square. Keep the `style="height:512px;width:512px"`
+  attribute the other assets use.
+- **Reads small.** Icons render at roughly **20-34 px** — `.stack-type-icon` 22,
+  `.stack-unit-icon` 26, `.bt-top .building-icon` 34, `.row-card .building-icon`
+  34, `.control-icon` 20, `.value .value-icon` 13. A single strong silhouette
+  beats detail; avoid thin strokes, fine text and tiny gradients.
+- **Flat, high-contrast vector** in the game's palette (see the existing icons
+  for the house style, e.g. `icon_battleship.svg`, `icon_jet_fighter.svg`,
+  `icon_modern_infantry.svg`). A dark plate behind the subject helps it read on
+  the map and in the panel, as the dummy does.
+- **No text** in real icons. Transparent or plate background, consistent with
+  neighbours.
+- **Specifics to capture:** a nuclear trefoil for the enrichment centre; a
+  country silhouette / masked figure for the spy; a fish-like hull for the
+  submarine; a rocket with fins for the missile and an intercontinental variant
+  for the ICBM; a globe/bust for human vs. a monitor/chip for computer; a
+  geyser for geothermal; an offshore turbine on its platform vs. an onshore
+  turbine.
+
+---
+
+## 5. Workflow per icon
+
+1. Draw the SVG (any editor; keep it hand-editable, no embedded bitmaps).
+2. Save as `client/assets/icon_<name>.svg` — **same filename**, so no data file
+   change is needed. If a filename must change, update the `icon` field in the
+   matching `shared/data/*.js` entry (units, buildings, resources, improvements,
+   technologies, ...).
+3. Build a small gallery HTML (below) linking `client/css/style.css`, showing
+   every changed icon at the real sizes, on the real backgrounds.
+4. Open it in Firefox and show the user; only commit once approved.
+5. Run `node tests/run_tests.js --file data_test.js` (it asserts some icons are
+   `.svg`) and any suite that references the icon.
+
+### Gallery skeleton
+
+```html
+<!doctype html><meta charset="utf-8">
+<link rel="stylesheet" href="file:///home/adrien/strategy-game/client/css/style.css">
+<body style="background:#05070c;color:#e8eef7;font:14px sans-serif;padding:24px">
+  <h1>Sizes: 20 / 22 / 26 / 34 px</h1>
+  <div style="display:flex;gap:24px;align-items:flex-end">
+    <!-- per icon: <img src="file:///home/.../client/assets/icon_x.svg" style="width:34px"> etc. -->
+  </div>
+</body>
+```
+
+---
+
+## 6. Tests to add / extend
+
+- `tests/data_test.js` already checks a few `icon` fields end in `.svg` and are
+  non-empty; extend it to cover the newly drawn assets (units, buildings,
+  resources) so a missing/renamed file is caught.
+- No pixel tests — icons are reviewed by eye, per the workflow above.
+
+---
+
+## 7. Gotchas
+
+- **The filename is the contract.** Most data entries reference the file by
+  string; renaming without editing the data leaves a broken `<img>` that only
+  shows in the browser, not in tests.
+- **Case and path.** Assets are served from the repo root as `/client/...`;
+  `client/js` references them as `assets/icon_x.svg` relative to the page. Keep
+  lowercase `snake_case` filenames.
+- **Small-size legibility** is the acceptance test, not how good it looks at
+  512px. Zoom the gallery down to 20px before judging.
+- **Nix packaging** copies the tree, so no manifest needs updating — but a new
+  file must be committed for the deployed build to include it.
+- A serving cache may hide a replaced file; hard-reload when checking in-game.
+
+---
+
+## 8. Relevant files
+
+- `client/assets/` — all icons (this is where art goes).
+- `shared/data/units.js`, `buildings.js`, `resources.js`, `improvements.js`,
+  `technologies.js` — the `icon:` references.
+- `client/css/style.css` — icon display sizes.
+- `client/index.html` — where icons appear in the HUD/modals.
+- `tests/data_test.js` — icon sanity checks.
+
+## 9. Related design docs
+
+`INTELLIGENCE.md`, `STACKS.md`, `AIR_MOVEMENT.md`, `ECONOMY_BALANCE.md`,
+`POLITICS_PERFORMANCE.md`, `TRAINING_UI.md` (repo root).