Battle-for-Tismo/AGENTS.md

AGENTS.md

Battle for 'Tismo — HTML5 port of the strategy game. Pure JavaScript: shared game logic runs both in Node (authoritative server) and in the browser (client). There is no build step and no runtime dependency; the client vendors jQuery and everything else (transport included) is hand-written.

Commands

• Install dev dependencies once: npm install (only c8 and jsdom, used by the test suite — nothing the game runs needs them).
• Run the test suite: node tests/run_tests.js (alias npm test; discovers every tests/*_test.js and runs each in its own worker process, prints a summary and exits non-zero on failure). --jobs N caps the pool and --file <name> runs a single suite in-process; the worker marker is internal.
• Never run the full test suite: the commit hook runs it anyway. During development run only the single affected suite with --file <name>.
• Coverage report: npm run coverage (c8, writes coverage/).
• Start the game server and client locally: node server/server.js --port 27015 --bind 127.0.0.1. Then open http://127.0.0.1:27015/ (redirects to /client/index.html). The browser connects to ws(s)://<page-origin>/ws. Before it listens the server settles the world until commodity prices hold steady over a seven-day window, so the economy opens established; pass --warmup <days> (or set WARMUP) to cap how many days the settle may run and --warmup 0 to skip it. The settle logs how many days it took and usually stops well short of the cap on the standard map.
• Install the versioned git hooks (runs the tests on every commit): ./scripts/install-git-hooks.sh; uninstall with git config --unset core.hooksPath.
• Build the deployable packages: nix build .#server and nix build .#web.
• If node is not on PATH, use the pinned one: nix-shell -p nodejs --run "node tests/run_tests.js".

There is no linter, formatter, or CI. Do not invent commands beyond these.

Visual changes

• A change that alters what the player sees is reviewed by eye before it is committed. Build a minimal standalone HTML example of the change first — the isolated element and each of its states, not a whole mocked-up screen — open it in a browser and show it to the user. Only commit once the user has seen and approved the preview.
• Whenever an HTML page is shown, open it in the user's Firefox directly (firefox <path>); never render a screenshot and never just print the path for them to find.
• Keep the examples small and self-contained: link the stylesheet and copy in the few assets they need. A short gallery of one small example per visual change is the right size. Do not add the examples to the repository.

Local testing mode

• The server creates its game at startup; add --testing to node server/server.js --testing to make it a test game, where every city's train and build rows gain a second "Free & instant" button.
• The free shortcut is gated on the server, never trusted from the client: server/server.js strips a free flag from any non-loopback order (isLoopback, handling 127.x, ::1 and ::ffff:127.0.0.1), and GameServer honours it only while this.testing is set. GameState.requestTrain/requestBuild(..., free) then spawn or raise immediately without cost or queue (placement rules still apply).
• The testing flag is shipped in the snapshot so joiners see the same buttons.

Gotchas

• Keep the shared modules framework-free: they are imported unchanged by both server/ (Node, ESM) and client/js/ (browser). No Node built-ins and no DOM APIs in shared/ (server/websocket.js is the only place Node built-ins are expected).
• Do not add JavaScript libraries. The only third-party code allowed is the vendored jQuery under client/vendor/; implement everything else by hand (see server/websocket.js, a dependency-free RFC 6455 server).
• The game server also serves the app as static files from the repository root, so modules resolve as /client/... and /shared/.... Preserve the client/ + shared/ layout when packaging (nix/package.nix).
• WebSocket state snapshots can be hundreds of KiB; the custom server handles fragmented and large frames (server/websocket.js). Do not lower the buffer limits without checking the snapshot path.
• Indent .js files with 2 spaces. .editorconfig only enforces UTF-8.
• Keep aircraft out of the melee: _battleTiles/_combatTarget skip them and their strikes are routed explicitly. Mirror the air rules (airport-only rebasing, strike radius, ferry fuel) on both client and server, or prediction and the authoritative state will disagree.

Architecture

• Game logic is server-authoritative. shared/game_state.js (GameState) is a framework-free model that owns the world, units, cities, territory, economy, training and visibility. server/game_server.js (GameServer) owns a GameState, validates orders and broadcasts snapshots over the transport in server/server.js. The browser client is a view: client/js/map_view.js rebuilds terrain from the shared seed, renders snapshots and sends orders. The map geometry (terrain, roads, borders, fog and the zoomed-out overview) is drawn on a single WebGL canvas by client/js/map_view/webgl.js, batched into per-layer buffers and row-banded so only visible tile rows are drawn; the unit, city, label, path and target icons stay DOM elements on top. MapView picks WebGL in renderer "auto" mode and falls back to the DOM chunk renderer when there is no context (jsdom), when the context is backed by a software rasteriser, or when constructed with { renderer: "dom" }.
• Movement is continuous: server/server.js advances movement every tick and strikes an in-game hour every SECONDS_PER_HOUR real seconds. The client extrapolates each unit along its snapshot path and predicts move orders locally (map_view.js), mirroring GameState.find_path so a click feels instant. Any pathfinding or movement-cost change must be mirrored on both sides or prediction will fight the server. Roads (shared/roads.js, pre-generated into GameState.roads) flatten a tile's movement cost on both sides through _tileTravelHours / _stepHours; the road set is shipped in the snapshot and drawn in the chunked layer-roads.
• Air and artillery are both ranged strikers (GameState._isStrikeUnit). A ground or naval battery ordered to attack opens a sustained hourly bombardment: it stays put and _tickStrikes removes a small share of its attack damage each hour (BOMBARD.hourlyDamageFraction), clearing the target when it dies or slips out of reach. An aircraft ordered to attack flies a sortie (requestAirStrike): it bombs once on arrival in advanceMovement and then returns to a friendly airport, where landing arms a two-day strikeReadyHour cooldown. The strike is charged up front per aircraft (AIR_STRIKE). Aircraft may only be rebased to one of their own airports and the ferry is bounded by fuel, not the combat missionRange; they never join melee. A strike may target a garrison inside a hostile city — the plane enters that tile as a goal only to bomb and turns for home, and captures skip aircraft, so it never occupies or takes the city. A strike is only accepted when the whole round trip fits the remaining fuel (out to the target, then home to a friendly airport), and the browser mirrors that check so an unreachable target is refused with a message instead of an order the server would drop. A standing strikeTarget is shipped in the snapshot and map_view/motion.js draws the red dashed line and target ring on #layer-targets while either endpoint is selected.
• Terrain generation is deterministic from (seed, mapConfig), so GameState._buildTerrain and the settlement/road step cache the world shape (shared/game_state/world.js) rather than regenerating it for every game with a known seed. The snapshot ships mapConfig and MapView.ensureTerrain rebuilds the exact same terrain from it (not the global MAP_CONFIG), which also lets the DOM tests use a small map fixture.
• The economy advances on an hourly tick (shared/game_state/resources.js _tickResources). Within one tick the city-market-access and node-population lookups are cached on GameState and dropped at the end, so an order that lands mid-tick still sees fresh data. The trade graph is the expensive part — a walk from each city floods the ocean, since a sea lane runs any distance — so it is kept across ticks and days. _tradeGraph caches each (city, mode) walk under a stamp built from the road/railway/work/territory version counters, so any network change rebuilds lazily while a quiet world reuses it; a unit move only drops it while a war is on (a hostile camp can sever a route). This is what stops a settled world re-flooding every sea lane each day. GameState.warmUp(days) runs a fixed number of days without players, while warmUpToStability({ maxDays }) settles until pricesAreSteady (every commodity within 10% over the trailing seven days) or the cap, and the server calls the latter from configureGame with the warmupDays that startServer/the --warmup flag supplies (0 skips it).
• Food is the one good a region synthesises from energy, so its price signal must come from the reserve, not the day's meal: _tickResources grows toward need + (stockpileTarget - store) - harvest, and _consumeCityResources books the empty-pantry appetite (reserveGap / stockpileDays) as demand. Without the reserve term a region lives hand-to-mouth with stores near zero and the food price stays flat. Keep the two in step: raising one without the other only forces synthesis or only bids the price, not both.
• shared/ holds the reusable algorithms so they stay testable without a server: hex.js (topology/geometry), map_generator.js, hex_pathfinder.js, terrain_stats.js, rules.js, economy figures in game_state.js, game_clock.js, rng.js, noise.js, text_format.js, login_manager.js. Data-driven content lives in shared/data/ (one small module per topic: civilisations, units, buildings, governments, technologies, terrain, ...). shared/data.js is a barrel re-exporting the whole catalogue, so keep importing from shared/data.js and edit the file under shared/data/. shared/game_state.js is likewise a thin class composed from the mixins in shared/game_state/ (world, territory, economy, movement, combat, air, status, diplomacy, orders, visibility, serialization).
• client/js/ splits the UI: app.js (screens and flow), net.js (transport wrapper), game_screen.js + game_screen/ (HUD and panels), map_view.js + map_view/ (DOM map), modals.js + modals/ (city training/buildings/regional budget, nation/technology, confirm, news).
• Tests live in tests/ as *_test.js files extending the TestCase base in tests/framework/; tests/run_tests.js discovers and runs them. Add a new tests/<topic>_test.js for each new pure behaviour.

Deployment

• flake.nix exposes packages.<system>.server and .web, plus nixosModules.default. There is no compiler step: nix/package.nix copies the app and wraps node server/server.js; web is the static client/ and shared/ tree.
• nix/module.nix runs the server as a services.battle-for-tismo systemd unit and serves the static client through nginx, redirecting / to /client/index.html and proxying /ws to the local Node server. The browser client connects to the page's own origin, so HTTPS gives it wss://.
• Build locally with nix build .#server and nix build .#web.
• Updating without a rebuild: set services.battle-for-tismo.appDirectory to a writable checkout (e.g. /opt/battle-for-tismo); the unit then runs node <dir>/server/server.js instead of the Nix-store copy. Serve nginx client/ and shared/ from that same checkout (e.g. alias locations), then git pull and systemctl restart battle-for-tismo. Keep the client and server trees on the same commit: the client mirrors the server's movement model, so a mismatched pair makes prediction fight the server.

CodeGraph

In repositories indexed by CodeGraph (a .codegraph/ directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:

• MCP tool (when available): codegraph_explore answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.
• Shell (always works): codegraph explore "<symbol names or question>" prints the same output.

If there is no .codegraph/ directory, skip CodeGraph entirely — indexing is the user's decision.