Add MIT license, contributing guide, CLAUDE.md, architecture notes and repo skills
This commit is contained in:
parent
06576357c9
commit
443202876a
10 changed files with 457 additions and 1 deletions
53
.claude/skills/add-strings/SKILL.md
Normal file
53
.claude/skills/add-strings/SKILL.md
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
---
|
||||||
|
name: add-strings
|
||||||
|
description: Add or change player-facing text in Series of Tubes and keep every translation (site/i18n/*.js) complete.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Adding or changing player-facing text
|
||||||
|
|
||||||
|
The English text is the translation key. Every string a player can see must go
|
||||||
|
through the translation helpers and have an entry in every dictionary in `site/i18n/`
|
||||||
|
(currently `it.js`, Italian).
|
||||||
|
|
||||||
|
## In the code
|
||||||
|
|
||||||
|
- `tr('Text with {name}', {name})`: translate now and fill placeholders.
|
||||||
|
- `trn('{n} router', '{n} routers', n, vars)`: plurals; both forms are keys.
|
||||||
|
- `N_('Text')`: marks a literal kept in a table for later `tr()` (e.g. labels stored in
|
||||||
|
constants). Call `tr(x)` where it's shown.
|
||||||
|
- Static HTML: add `data-i18n` to the element; `aria-label` and `title` attributes are
|
||||||
|
collected automatically.
|
||||||
|
- Text must be a string literal inside the call, or the checker can't see it.
|
||||||
|
- Keep HTML (`<b>`, `<br>`, `<small>`) and `{placeholders}` identical in translations.
|
||||||
|
- Don't build sentences by concatenating translated fragments; translate whole sentences.
|
||||||
|
|
||||||
|
## In the dictionary
|
||||||
|
|
||||||
|
`site/i18n/it.js` is one object, `"English": "Italiano",` per line, ending with `};`.
|
||||||
|
Append new entries before the closing `};`. A small script avoids quoting mistakes:
|
||||||
|
|
||||||
|
```python
|
||||||
|
import json
|
||||||
|
it = {"New English text": "Nuovo testo italiano"}
|
||||||
|
q = 'site/i18n/it.js'; t = open(q).read().rstrip()
|
||||||
|
assert t.endswith('};')
|
||||||
|
t = t[:-2] + ''.join(json.dumps(k, ensure_ascii=False) + ':' + json.dumps(v, ensure_ascii=False) + ',\n'
|
||||||
|
for k, v in it.items() if json.dumps(k, ensure_ascii=False) + ':' not in t) + '};\n'
|
||||||
|
open(q, 'w').write(t)
|
||||||
|
```
|
||||||
|
|
||||||
|
When you **change** English text, rename the key in every dictionary too; when you
|
||||||
|
remove text, delete its entry.
|
||||||
|
|
||||||
|
## Italian style
|
||||||
|
|
||||||
|
Natural, friendly Italian, informal "tu". Keep networking terms that Italian engineers
|
||||||
|
use in English (peering, transit, router, POP, PNI, LAG, dark fiber). Translate puns
|
||||||
|
into an Italian joke when one fits; otherwise keep the pun name and translate the rest.
|
||||||
|
|
||||||
|
## Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node scripts/i18n-check.js # must say: 0 missing, 0 unused, 0 broken
|
||||||
|
npm test # includes tests/i18n.test.js
|
||||||
|
```
|
||||||
55
.claude/skills/release/SKILL.md
Normal file
55
.claude/skills/release/SKILL.md
Normal file
|
|
@ -0,0 +1,55 @@
|
||||||
|
---
|
||||||
|
name: release
|
||||||
|
description: Cut and ship a Series of Tubes release (patch or minor) from main via the auto-release workflow.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Releasing Series of Tubes
|
||||||
|
|
||||||
|
Bumping `version` in `package.json` on `main` is the release button. The
|
||||||
|
`auto-release.yml` workflow tests, tags `v<version>`, publishes a GitHub release with
|
||||||
|
that version's CHANGELOG section as notes, and dispatches `release.yml`, which deploys
|
||||||
|
to GitHub Pages (https://seriesoftub.es).
|
||||||
|
|
||||||
|
## Pick the version
|
||||||
|
|
||||||
|
- Patch (`x.y.Z`): fixes, small tweaks, wording, icons.
|
||||||
|
- Minor (`x.Y.0`): new features or content.
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. Make sure `main` is green: `npm test` and `node scripts/i18n-check.js`
|
||||||
|
("0 missing, 0 unused, 0 broken").
|
||||||
|
2. In `CHANGELOG.md`, move the bullets from `## [Unreleased]` into a new section
|
||||||
|
right below it: `## [x.y.z] — YYYY-MM-DD` (em dash, today's date). Keep an empty
|
||||||
|
`## [Unreleased]` heading above it. The build fails if the section has no bullets.
|
||||||
|
3. Bump the version in **both** files:
|
||||||
|
- `package.json` → `"version"`
|
||||||
|
- `package-lock.json` → top-level `"version"` and `packages[""].version`
|
||||||
|
4. `npm test` once more.
|
||||||
|
5. Commit on `main` as Frederic, with no attribution trailers:
|
||||||
|
```bash
|
||||||
|
git -c user.name="Frederic Jung" -c user.email="frederic@jc-ix.net" commit \
|
||||||
|
--author="Frederic Jung <frederic@jc-ix.net>" -m "Short summary (x.y.z)"
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
|
6. Watch the workflows until both finish:
|
||||||
|
```bash
|
||||||
|
gh run list --repo fjaeckel/seriesoftubes --limit 4
|
||||||
|
gh run watch <id> --repo fjaeckel/seriesoftubes
|
||||||
|
```
|
||||||
|
7. Confirm it is live: `https://seriesoftub.es/version.json` shows the new version.
|
||||||
|
|
||||||
|
## Release notes rules
|
||||||
|
|
||||||
|
- Written for players, in plain English. One bullet per change, issue numbers like `(#37)`.
|
||||||
|
- Never mention hidden easter eggs or explain jokes.
|
||||||
|
- No internal function names.
|
||||||
|
|
||||||
|
## If something fails
|
||||||
|
|
||||||
|
- "not newer than the latest release": the version was not bumped, or was bumped
|
||||||
|
backwards.
|
||||||
|
- "CHANGELOG.md has no notes under ## [x.y.z]": the heading doesn't match the version
|
||||||
|
exactly or has no bullets.
|
||||||
|
- Tests fail in the workflow but pass locally: look for unseeded randomness in a test.
|
||||||
|
- Fix forward with a new patch version; never move or delete an existing tag.
|
||||||
49
.claude/skills/write-tests/SKILL.md
Normal file
49
.claude/skills/write-tests/SKILL.md
Normal file
|
|
@ -0,0 +1,49 @@
|
||||||
|
---
|
||||||
|
name: write-tests
|
||||||
|
description: Write deterministic jsdom tests for Series of Tubes features and fixes in tests/*.test.js.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Writing tests
|
||||||
|
|
||||||
|
Tests use `node:test` and `tests/harness.js`, which loads `site/index.html` in jsdom
|
||||||
|
with the animation loop off, a seeded `Math.random` and a recording fake canvas.
|
||||||
|
Code runs inside the page through `ev()`.
|
||||||
|
|
||||||
|
## Pattern
|
||||||
|
|
||||||
|
```js
|
||||||
|
const test = require('node:test');
|
||||||
|
const assert = require('node:assert/strict');
|
||||||
|
const { load } = require('./harness');
|
||||||
|
|
||||||
|
test('what the player should see happen', () => {
|
||||||
|
const { ev, errors } = load();
|
||||||
|
ev("ACT.start({});S.cash=1e8;for(const g of GOALS)S.done[g.id]=0;ACT.launchBB({city:'fra'})");
|
||||||
|
ev("ACT.buyTransit({city:'fra',net:'cog',tier:1});compute()");
|
||||||
|
assert.ok(ev("R.served") > 0);
|
||||||
|
assert.deepEqual(errors, []); // always: no page errors
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Where to put it
|
||||||
|
|
||||||
|
Pick the suite by topic: `game` (core loop), `build`, `persist` (save/import/migrate),
|
||||||
|
`services` (customers), `peering`, `issues` (GitHub issue regressions, name them
|
||||||
|
`#NN …`), `regions`, `modes` (scenarios, sandbox, weekly), `i18n`. A new file must be
|
||||||
|
added to the `test` script in `package.json`.
|
||||||
|
|
||||||
|
## Rules
|
||||||
|
|
||||||
|
- **Deterministic.** Never rely on luck. Use the default seed, `window.__reseed(n)`,
|
||||||
|
or set state directly (`S.day=…`, `S.ev.x=…`).
|
||||||
|
- **Force a specific random failure or event** by patching the picker:
|
||||||
|
```js
|
||||||
|
ev("eval('('+fireFailure.toString().replace('const e=pick(opts);',\"const e='crash';\")+')')()");
|
||||||
|
```
|
||||||
|
Check the current source for the exact `pick` line first; it may differ.
|
||||||
|
- **Drive the game through `ACT`** like a player would, then `compute()` or `dayTick()`.
|
||||||
|
- **Saves:** for persistence changes, round-trip `JSON.stringify(S)` through
|
||||||
|
`parseSave()`/`migrate()`, and test that an *old* save without the new field still loads.
|
||||||
|
- **UI:** render with `renderAll()` and query `dom.window.document`; check phone
|
||||||
|
layouts by setting `window.innerWidth = 390` before rendering.
|
||||||
|
- Run `npm test`; the whole suite must pass, not just the new test.
|
||||||
66
CLAUDE.md
Normal file
66
CLAUDE.md
Normal file
|
|
@ -0,0 +1,66 @@
|
||||||
|
# Series of Tubes: notes for Claude
|
||||||
|
|
||||||
|
A free cartoon browser game about how the internet works, live at
|
||||||
|
https://seriesoftub.es. The whole game is one static page: `site/index.html`
|
||||||
|
(HTML, CSS and JS in one file, no framework, no build step for development).
|
||||||
|
|
||||||
|
Read these before larger changes:
|
||||||
|
|
||||||
|
- `docs/ARCHITECTURE.md`: how the code is laid out and how a day of simulation runs.
|
||||||
|
- `.claude/skills/`: step-by-step procedures (release, translations, tests).
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm ci # once: installs jsdom for the tests
|
||||||
|
npm test # node:test + jsdom, all suites, must stay green
|
||||||
|
node scripts/i18n-check.js # must report "0 missing, 0 unused, 0 broken"
|
||||||
|
npm run build # builds _site/ (stamps version, bakes release notes)
|
||||||
|
npm run serve # build and serve locally
|
||||||
|
```
|
||||||
|
|
||||||
|
To play during development, open `site/index.html` directly or run `npm run serve`.
|
||||||
|
|
||||||
|
## Hard rules
|
||||||
|
|
||||||
|
- **Git:** work on `main`, no branches. Commits are authored and committed as
|
||||||
|
`Frederic Jung <frederic@jc-ix.net>`. Never add `Co-Authored-By`, `Claude-Session`
|
||||||
|
or any other attribution trailers.
|
||||||
|
- **Releases** happen by bumping `version` in `package.json` on `main` (see the
|
||||||
|
`release` skill). Small fixes or tweaks get a patch release (`x.y.Z`); new features a
|
||||||
|
minor release.
|
||||||
|
- **Names are puns.** No real company names for networks, vendors, cables, banks,
|
||||||
|
data centers or exchanges (Cogentle, Goggle, NetChill, Junipurr, Arrrhipster…).
|
||||||
|
Real conference names (NANOG, RIPE, DENOG) are fine. Avoid lazy "-ish" names: find
|
||||||
|
a real pun, or keep the plain word.
|
||||||
|
- **Easter eggs stay secret.** Never mention hidden jokes or easter eggs (for example
|
||||||
|
whatever `elephant()` does) in commit messages, release notes or the CHANGELOG.
|
||||||
|
- **Every player-facing string is translated.** Wrap it in `tr()`, `trn()` or `N_()`
|
||||||
|
and add the Italian to `site/i18n/it.js` in the same change (see `add-strings`).
|
||||||
|
- **Phones first.** About 70% of players are on phones. Every new panel, button and
|
||||||
|
modal must work at 360 px wide, in portrait and landscape, using the phone tab bar
|
||||||
|
and bottom sheets. Check `isPhone()` layouts, not just desktop.
|
||||||
|
- **Saves are sacred.** Old saves must keep loading. Any new state field gets a default
|
||||||
|
in `newGame()` and a check/repair in `sanitize()`; renamed fields are migrated there.
|
||||||
|
- **Tests come with features.** Add or extend a test in `tests/` for every feature or
|
||||||
|
fix. Tests are seeded, so they must not depend on luck.
|
||||||
|
- **CHANGELOG style:** plain English, written for players, one bullet per change,
|
||||||
|
issue numbers in parentheses like `(#37)`. No internal names, no jokes explained.
|
||||||
|
|
||||||
|
## Style of the code
|
||||||
|
|
||||||
|
- Dense, single-file JavaScript. Match the surrounding style: short helper names,
|
||||||
|
arrow functions, template-literal HTML, no new dependencies.
|
||||||
|
- UI is rebuilt from state: change `S`, then call `after()` (recompute, check goals,
|
||||||
|
re-render, save). Buttons are `btn(label, actName, args, cls, disabled)`, which
|
||||||
|
dispatch to `ACT[actName](args)` through `data-act`/`data-args`.
|
||||||
|
- Never trust saved or imported state: anything read from `S` that came from a save
|
||||||
|
must already have been validated in `sanitize()`.
|
||||||
|
- Keep comments short and about *why*.
|
||||||
|
|
||||||
|
## Tone
|
||||||
|
|
||||||
|
Friendly, nerdy and accurate underneath the jokes. Mechanics should follow how
|
||||||
|
networks really work (95th-percentile billing, peering policies, LAGs, DWDM reach,
|
||||||
|
route leaks, RPKI) and then exaggerate for fun. When unsure how something works in
|
||||||
|
real life, look it up before modelling it.
|
||||||
62
CONTRIBUTING.md
Normal file
62
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,62 @@
|
||||||
|
# Contributing to Series of Tubes
|
||||||
|
|
||||||
|
Thanks for wanting to help build the cartoon internet. Bug reports, ideas, puns,
|
||||||
|
translations and code are all welcome.
|
||||||
|
|
||||||
|
## Reporting bugs and ideas
|
||||||
|
|
||||||
|
Open an issue on GitHub. For bugs, include what you did, what you expected and what
|
||||||
|
happened. If it involves a game in progress, attach an export of your save (menu →
|
||||||
|
Export), which lets us load your exact network.
|
||||||
|
|
||||||
|
Ideas are best when they say what happens in real networks and how that could become
|
||||||
|
a fun mechanic.
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
The game is one static page, `site/index.html`, with no framework and no build step
|
||||||
|
while developing.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm ci # installs jsdom for the tests
|
||||||
|
npm run serve # builds and serves the game locally
|
||||||
|
npm test # all tests must pass
|
||||||
|
node scripts/i18n-check.js # translations must be complete
|
||||||
|
```
|
||||||
|
|
||||||
|
Opening `site/index.html` directly in a browser also works.
|
||||||
|
|
||||||
|
A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
||||||
|
|
||||||
|
## Pull requests
|
||||||
|
|
||||||
|
- Keep each pull request focused on one change, and target `main`.
|
||||||
|
- Add or update a test in `tests/` for every feature or fix. Tests are seeded and
|
||||||
|
must not depend on luck.
|
||||||
|
- Add a bullet for players under `## [Unreleased]` in `CHANGELOG.md`, in plain English.
|
||||||
|
Releases are cut by the maintainer.
|
||||||
|
- Old saves must keep loading. New state needs a default for new games and a check in
|
||||||
|
`sanitize()`.
|
||||||
|
- Check your change on a phone-sized screen (about 360 px wide). Most players are on
|
||||||
|
phones.
|
||||||
|
|
||||||
|
## House rules for content
|
||||||
|
|
||||||
|
- **Every name is a pun.** No real company names for networks, vendors, cables, banks,
|
||||||
|
data centers or exchanges. Real conference names (NANOG, RIPE, DENOG…) are fine.
|
||||||
|
Please don't use lazy "-ish" names; find a proper pun or use a plain word.
|
||||||
|
- **Accurate underneath the jokes.** Mechanics should be recognisable to a network
|
||||||
|
engineer: exaggerated, not invented.
|
||||||
|
- **Friendly humour.** Punch at technology, bureaucracy and ourselves, not at people.
|
||||||
|
|
||||||
|
## Translations
|
||||||
|
|
||||||
|
Every player-facing string goes through `tr()`, `trn()` or `N_()`. Dictionaries live
|
||||||
|
in `site/i18n/` (English text → translation). To add a language, copy `it.js`, translate
|
||||||
|
the values, register the language in the language list in `site/index.html`, and run
|
||||||
|
`node scripts/i18n-check.js <lang>` until it reports nothing missing, unused or broken.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
By contributing, you agree that your contributions are licensed under the
|
||||||
|
[MIT License](LICENSE).
|
||||||
21
LICENSE
Normal file
21
LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Frederic Jung
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
|
|
@ -145,3 +145,11 @@ sites:
|
||||||
- domain: seriesoftub.es
|
- domain: seriesoftub.es
|
||||||
origins: ["https://seriesoftub.es", "https://www.seriesoftub.es"]
|
origins: ["https://seriesoftub.es", "https://www.seriesoftub.es"]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
[MIT](LICENSE) © 2026 Frederic Jung
|
||||||
|
|
|
||||||
140
docs/ARCHITECTURE.md
Normal file
140
docs/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,140 @@
|
||||||
|
# Architecture
|
||||||
|
|
||||||
|
Everything that runs in the browser lives in `site/index.html`. It is large (several
|
||||||
|
thousand lines), so find things by the section banners rather than by line number:
|
||||||
|
|
||||||
|
```
|
||||||
|
/* ================= PHONES ================= */ phone CSS
|
||||||
|
/* ================= LANGUAGE ================= */ tr(), trn(), N_(), dictionary loading
|
||||||
|
/* ================= ANALYTICS ================= */ privacy-friendly event counter
|
||||||
|
/* ================= CONSTANTS ================= */ prices, ports (PORT), routers (RG), optics
|
||||||
|
/* ================= WORLD ================= */ CITIES, CABLES, display nudges
|
||||||
|
/* ================= NETWORKS ================= */ NETS (other ASes), traffic shares (NSH)
|
||||||
|
/* ================= BUSINESSES ================= */ BIZ_T customer types, LEVELS
|
||||||
|
/* ================= GOALS ================= */ GOALS checklist
|
||||||
|
/* ================= STATE ================= */ S, R, UI globals
|
||||||
|
/* ================= BANKS & LOANS ================= */
|
||||||
|
scenarios (SCN), conferences, tutorial, traceroute, share card
|
||||||
|
/* ================= HELPERS ================= */ formatting, geometry, small queries
|
||||||
|
/* ================= SIMULATION ================= */ RouteScript, compute(), costs, sanitize()
|
||||||
|
failures & events, daily tick, badges
|
||||||
|
/* ================= ACTIONS ================= */ the ACT map: every player action
|
||||||
|
/* ================= SAVE ================= */
|
||||||
|
/* ================= AUDIO ================= */
|
||||||
|
/* ================= DOM RENDER ================= */ HUD, left panel, side panel, modals, toasts
|
||||||
|
/* ================= PHONE ================= */ tab bar, bottom sheets
|
||||||
|
/* ================= INSTALL (PWA) ================= */
|
||||||
|
/* ================= CANVAS ================= */ map drawing, level of detail
|
||||||
|
/* ================= LOOP ================= */ frame(), boot()
|
||||||
|
```
|
||||||
|
|
||||||
|
Other files:
|
||||||
|
|
||||||
|
| Path | What it is |
|
||||||
|
| --- | --- |
|
||||||
|
| `site/i18n/it.js` | Italian dictionary: English text → Italian, loaded when the language is `it` |
|
||||||
|
| `site/sw.js` | Service worker: network-first for pages, stale-while-revalidate for assets. Cache name is stamped with the version |
|
||||||
|
| `site/site.webmanifest`, icons | PWA install metadata |
|
||||||
|
| `scripts/build.sh` | Copies `site/` to `_site/`, stamps `__VERSION__`/`__BUILD_DATE__`, bakes release notes, writes `version.json` |
|
||||||
|
| `scripts/release-notes.js` | Extracts a version's CHANGELOG bullets |
|
||||||
|
| `scripts/i18n-check.js` | Compares every `tr`/`trn`/`N_` literal and `data-i18n` text with each dictionary |
|
||||||
|
| `tests/harness.js` | Loads the page in jsdom with a seeded `Math.random` and a fake canvas |
|
||||||
|
| `.github/workflows/ci.yml` | Tests and build on every push and PR |
|
||||||
|
| `.github/workflows/auto-release.yml` | On a `package.json` version bump on `main`: test, tag, GitHub release from the CHANGELOG, start the deploy |
|
||||||
|
| `.github/workflows/release.yml` | Builds and deploys to GitHub Pages |
|
||||||
|
|
||||||
|
## Globals
|
||||||
|
|
||||||
|
- **`S`**: the whole saved game (one JSON object). Cash, day, POPs, links, transit,
|
||||||
|
IX ports, PNIs, caches, customers (`biz`), offers, incidents (`inc`), live events
|
||||||
|
(`ev`), stats, settings. Saved to `localStorage` key `sot-save-v1`.
|
||||||
|
- **`R`**: results of the last `compute()`: per-link load, per-exit use, served and
|
||||||
|
demanded traffic, reach, costs and revenue. Never saved; always rebuilt.
|
||||||
|
- **`UI`**: view state (selection, open tabs, speed, confirmations). Not game state.
|
||||||
|
- **`cam`**: map camera (x, y, zoom).
|
||||||
|
|
||||||
|
Lookup tables built at load: `CITY[id]`, `NET[id]`, `CABLE`, `FAB`, `BIZ_T`, `REQS`.
|
||||||
|
|
||||||
|
## The life of a day
|
||||||
|
|
||||||
|
`frame()` (requestAnimationFrame) accumulates time; every `DAY_MS × speed` it calls
|
||||||
|
`dayTick()`, at most four times per frame, each inside a try/catch so one bad tick
|
||||||
|
never freezes the game.
|
||||||
|
|
||||||
|
`dayTick()`:
|
||||||
|
|
||||||
|
1. Advances `S.day`, runs scheduled world events (conferences, IX price wars, licences).
|
||||||
|
2. Runs `compute()` to route today's traffic.
|
||||||
|
3. Records history for 95th-percentile billing, stats and streaks.
|
||||||
|
4. Rolls failures (`fireFailure()`) and events (`fireEvent()`) when their timers run out,
|
||||||
|
and expires incidents.
|
||||||
|
5. Updates customer mood, churn and new offers; IX members join; loans tick.
|
||||||
|
6. Every 30 days: bills the month (revenue minus costs) and checks for bankruptcy.
|
||||||
|
7. Checks goals, level, badges and scenario end conditions.
|
||||||
|
|
||||||
|
## compute(): the traffic model
|
||||||
|
|
||||||
|
1. Builds a graph from your live links: parallel links between the same two cities
|
||||||
|
merge into one edge with summed capacity. Link metrics set weights; Dijkstra gives
|
||||||
|
shortest paths from each POP.
|
||||||
|
2. Builds the exit list `E`: embedded caches (rank 0), PNIs (1), IX ports (2),
|
||||||
|
transit (3). Each exit has a capacity, the networks it can reach (`ok(net)`) and an
|
||||||
|
egress preference (`high`, `normal`, `low` = backup only).
|
||||||
|
3. Builds flows: for every POP, its demand (eyeballs and customers) split across
|
||||||
|
destination networks by their traffic share (`NSH`, with regional variants for
|
||||||
|
China, Russia and Korea). Incidents can add junk flows or scale demand.
|
||||||
|
4. Routes flows rank by rank: the nearest usable exit first, ECMP across equal exits,
|
||||||
|
consuming link, router (`nodeCap`) and exit capacity. With Auto-TE, overflow spills
|
||||||
|
onto alternate paths; RouteScript rules (`teRules()`) can prefer, avoid, cap, drain
|
||||||
|
or blackhole.
|
||||||
|
5. Layer-2 customers (L2VPN, SD-WAN, waves) are carved out of link capacity first.
|
||||||
|
6. Totals costs (`R.cost`) and revenue (`R.rev`) per month.
|
||||||
|
|
||||||
|
Served share per city (`sfOf`) drives eyeball revenue and customer mood.
|
||||||
|
|
||||||
|
## Actions and rendering
|
||||||
|
|
||||||
|
- Player actions live in `ACT`. Buttons render as `btn(label, act, args, cls, disabled)`
|
||||||
|
and a delegated click handler calls `ACT[act](JSON args)`.
|
||||||
|
- An action validates its inputs (they come from the DOM), mutates `S`, shows a
|
||||||
|
`toast()` and calls `after()`.
|
||||||
|
- `after()` = `purgeInc()` + `compute()` + `checkGoals()` + `renderAll()` + `save()`.
|
||||||
|
- `renderLeft()` draws the left tabs (deals, NOC, customers…), `renderPanel()` the
|
||||||
|
selection panel (city, link, network). On phones these become bottom sheets
|
||||||
|
controlled by `renderTabbar()`.
|
||||||
|
- The map is a canvas drawn every frame by `draw()`. Zoomed out (`lodFar()`) it uses
|
||||||
|
a simplified style; parallel waves are grouped by `linkGroups()`.
|
||||||
|
|
||||||
|
## Saves, imports and migration
|
||||||
|
|
||||||
|
- `save()` writes `S` to localStorage every few seconds and after actions.
|
||||||
|
- `boot()` loads the save through `migrate()` → `sanitize()`. If loading throws, the
|
||||||
|
damaged save is kept under `sot-save-broken` and the player starts fresh.
|
||||||
|
- `sanitize(s)` is the gate for all untrusted state (saves and imported files): it
|
||||||
|
drops unknown ids, clamps numbers, repairs references and fills defaults. Every new
|
||||||
|
field in `S` needs a line there.
|
||||||
|
|
||||||
|
## Translations
|
||||||
|
|
||||||
|
- `tr(text, vars)` looks up `DICT[text]` and fills `{placeholders}`; `trn(one, other, n)`
|
||||||
|
picks the plural; `N_(text)` marks a literal for the checker and translates later.
|
||||||
|
- Static markup uses `data-i18n`; `i18nDom()` swaps it at boot.
|
||||||
|
- The English text is the key, so changing English text means updating the key in
|
||||||
|
every dictionary.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
`tests/*.test.js` use `node:test` and `tests/harness.js`:
|
||||||
|
|
||||||
|
```js
|
||||||
|
const { load } = require('./harness');
|
||||||
|
const { ev, errors } = load(); // seeded, deterministic
|
||||||
|
ev("ACT.start({});S.cash=1e8;ACT.launchBB({city:'fra'})");
|
||||||
|
ev("compute()");
|
||||||
|
assert.equal(ev("R.reach>0"), true);
|
||||||
|
assert.deepEqual(errors, []);
|
||||||
|
```
|
||||||
|
|
||||||
|
`ev()` runs code inside the page. To force a specific random failure, patch the
|
||||||
|
picker, e.g. evaluate `fireFailure` with `.replace('const e=pick(opts);', "const e='x';")`.
|
||||||
|
Use `window.__reseed(n)` to reset the random sequence mid-test.
|
||||||
3
package-lock.json
generated
3
package-lock.json
generated
|
|
@ -12,7 +12,8 @@
|
||||||
},
|
},
|
||||||
"engines": {
|
"engines": {
|
||||||
"node": ">=20"
|
"node": ">=20"
|
||||||
}
|
},
|
||||||
|
"license": "MIT"
|
||||||
},
|
},
|
||||||
"node_modules/@asamuzakjp/css-color": {
|
"node_modules/@asamuzakjp/css-color": {
|
||||||
"version": "3.2.0",
|
"version": "3.2.0",
|
||||||
|
|
|
||||||
|
|
@ -3,6 +3,7 @@
|
||||||
"version": "1.16.0",
|
"version": "1.16.0",
|
||||||
"description": "A cartoon browser game about building the internet.",
|
"description": "A cartoon browser game about building the internet.",
|
||||||
"private": true,
|
"private": true,
|
||||||
|
"license": "MIT",
|
||||||
"homepage": "https://seriesoftub.es/",
|
"homepage": "https://seriesoftub.es/",
|
||||||
"repository": { "type": "git", "url": "git+https://github.com/fjaeckel/seriesoftubes.git" },
|
"repository": { "type": "git", "url": "git+https://github.com/fjaeckel/seriesoftubes.git" },
|
||||||
"scripts": {
|
"scripts": {
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue