seriesoftubes/.claude/skills/edit-the-game/SKILL.md
Frederic Jung 05ff4ea7ad
Docs and guard rails: GitHub Pages only, where code goes, updated skills
- docs/adr/0001: GitHub Pages is the only host, not open for renegotiation
- docs/adr/0002: source in many files, shipped as one page assembled at build
- tests/pages.test.js: builds stay static files Pages can serve, all local
  references resolve, only release.yml deploys and only via the Pages actions
- tests/build.test.js: partial naming and layout rules
- new skills: github-pages, edit-the-game; add-strings, performance, release
  and write-tests updated for src/, sorted dictionaries and --base-ref
- CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md (incl. porting older branches),
  README.md and the PR template describe the new layout
2026-10-27 10:15:12 +01:00

4 KiB

name description
edit-the-game Find, change and add game code in Series of Tubes, which lives in many small files under src/ that the build joins into one page. Use for any feature, fix or refactor in the game itself (anything in src/).

Editing the game

The game's source is src/. The build (scripts/lib/page.js) pastes the files together, in path order, into one index.html with one inline <style> and one inline <script>. That is exactly what players load, so splitting code across files costs nothing at runtime. Why it works this way: docs/adr/0002-one-page-assembled-at-build.md.

src/index.html            the shell: <head>, static markup, `<!-- @include styles -->`, `<!-- @include game -->`
src/styles/NN-*.css        CSS, in order (phones last)
src/game/NN-area/NN-*.js   the game script, in order (see the map in docs/ARCHITECTURE.md)
site/                      static files copied as they are (dictionaries, icons, service worker)

Find the code

Search by name, not by line: grep -rn "function compute(" src/game. Folder names say what lives there: 10-catalog prices and gear, 20-world cities and cables, 30-networks other ASes, 70-rules peering and market rules, 80-simulation routing and the save gate, 85-incidents, 88-days the daily tick, 90-actions every player action, 93-ui HUD and panels, 94-dashboard, 95-modals, 96-map the canvas. docs/ARCHITECTURE.md has the full table.

Run it

npm run dev        # http://localhost:8080, assembled on every request, reloads on save
npm test           # all suites (assembles src/ in memory; no build needed)
npm test -- tests/peering.test.js    # one suite

A browser error points at a line of the assembled page; the dev server prints the src/ file and line next to it. npm run page -- -o /tmp/page.html writes the assembled page if you want to look at it.

Where new code goes

  • A new feature or system: its own file in the folder of its topic, e.g. src/game/70-rules/85-route-servers.js. Pick a number between its neighbours; gaps are there for this. Small files that own one topic are what keep pull requests from conflicting.
  • Order matters at the top level. Files run in path order. Top-level const/let values and top-level statements may only use top-level values from earlier files. Functions are fine anywhere: everything is one script, so function declarations are hoisted and are all defined by the time anything runs after boot. When in doubt, put constants in an earlier file and logic in functions.
  • Actions: add name:(args)=>{…}, to the matching src/game/90-actions/*.js. Only 10-interface.js declares const ACT={; the others are Object.assign(ACT,{ … });. A new area can get a new NN-area.js file of that second form.
  • Panels and modals: 93-ui/ (HUD, side panels), 94-dashboard/ (NOC dashboard, bank), 95-modals/.
  • Styles: the matching src/styles/*.css; phone rules go in 60-phone.css.
  • Data tables (cities, cables, networks): one entry per line, and keep id-keyed objects such as CITY_LL sorted by id, so two people adding cities touch different lines.
  • Static markup goes in src/index.html; it is short and rarely changes.
  • Files that ship as they are (icons, dictionaries, sw.js, robots.txt) live in site/. site/index.html must not exist; the build refuses it.

Every partial ends with a newline and must not contain </script> or </style> at the start of a line. File names are NN-lower-case.js / .css; tests/build.test.js checks both.

Still the same rules

Everything in CLAUDE.md applies unchanged: translate every string (add-strings), sanitize saves, phones first, a test with every change (write-tests), performance shown against main (performance), hosting on GitHub Pages only (github-pages), a CHANGELOG bullet for players. The CHANGELOG is the one file every change touches; a conflict there is expected: keep both bullets.