Phase 4: close loot/refund leaks, landing-site garrisons, speed-scaled shipping, update/offsite tooling, broad e2e
Built: - Economy: raid loot capped to the room the raiders have at home (rest stays with the victim, "lootLeft" in the report); trade escrow reserves its room so refunds always fit; trade accept refuses with no_room_for_goods when the goods would not fit. Loot destroyed per 30-day run 31-61k -> ~1k, refunds clipped ~27k -> 0 (docs/BALANCE.md, 3 seeds). - End game: members of the holding alliance garrison landing sites (migration 005_site_garrison.sql), garrison counts in site defence, 72 h capture shield, withdraw route, POP view lists garrisoned units. Shipping capacity scales with world speed (3x world: winner 76-98 -> ~30-36 days after sites open). Bot runs show real contests (84-194 attacks on held sites at 1x). - Ops: deploy/update.sh (backup, stop, ff-merge, npm ci --ignore-scripts, health check, rollback), deploy/upstream-offsite (rsync only), admin end-world snapshots results, EPIPE fix, docs/workflows/ filled in. - e2e 62 -> 163 checks: units, raids/reports, alliance+messages, trade, end game, nb, PWA, reconnect, slow polling fallback (opt-in). Two app bugs found: message push ignored, "New" button stayed English. Tested: npm test 274/274, openapi check, npm run e2e 163/163 (137 s), bot runs 50x30d seeds 1-3 and 140-day/60-day speed-3 end-game runs INVARIANTS OK, adversarial review pass (findings fixed or documented). NOT tested: update.sh on a real box (systemd, real npm, runuser; stubs only, shellcheck not installed), garrison card/loot text on a phone, Node 22.13, humans. Known leaks left open and documented (BALANCE S6): loot/shipments can still overflow when stock arrives in flight, bounced backbone shipments lose overflow (reported to the sender). Garrison numbers (heldDefenceMult 2, shield 72 h) are first guesses from 2 seeds. Not claimed: balanced. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
parent
9104480463
commit
3c23c51902
92 changed files with 4887 additions and 300 deletions
78
docs/API.md
78
docs/API.md
|
|
@ -26,7 +26,7 @@ REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`
|
|||
| `GET /auth/tokens`, `DELETE /auth/tokens/:tokenId`, `POST /auth/logout` | list this account's active device tokens, revoke one, revoke the current one |
|
||||
| `GET /me` | user, operators (per world), POPs |
|
||||
| `POST /me/join {worldId?}` | an account with no operator (world reset, new world) founds its capital POP (201, returns `/me`); `409 conflict` if already joined |
|
||||
| `GET /towns/:id` | full POP state: resources `{amount, rate, cap}` at `serverTime`, power, buildings with the server's build plan, queue |
|
||||
| `GET /towns/:id` | full POP state: resources `{amount, rate, cap}` at `serverTime` (`cap` = Rack hall size minus the goods escrowed in open trade offers, `escrow` = those goods per resource), power, buildings with the server's build plan, queue |
|
||||
| `POST /towns/:id/build {key}` | build/upgrade one level of a field (`f1..f18`) or an infrastructure building |
|
||||
| `DELETE /towns/:id/queue/:eventId` | cancel a running build, 80% refund |
|
||||
| `POST /towns/:id/rename {name}` | rename a POP (2-40 chars) |
|
||||
|
|
@ -94,7 +94,7 @@ exist). The cursor is a rank offset (`next` = ranks already seen). Each response
|
|||
|
||||
Units are plain `{ unitId: count }` objects with the generic ids of `data.UNITS` (`port_scanner`, `soc_analyst`, `blue_team`,
|
||||
`honeypot`, `script_crew`, `botnet`, `ddos_rig`, `exploit_kit`, `rollout_crew`, `ma_team`); names live in `i18n.js`. `GET /towns/:id`
|
||||
now carries `town.military`: units at home (`online` flag, `offlineSince`), reinforcements standing here and away, the training queue,
|
||||
now carries `town.military`: units at home (`online` flag, `offlineSince`), reinforcements standing here and away, `units.garrisoned` `[{siteId, x, y, units}]` (this POP's units standing in backbone landing sites: they draw this POP's power), the training queue,
|
||||
what can be trained (cost, time, missing requirements), research levels and queue, transport links, and this POP's outgoing/incoming
|
||||
movements. Nothing resolves when you send it: combat, loot and arrival happen in the event queue at the arrival time, and reports and
|
||||
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `movement_lost`, `transport_arrived`,
|
||||
|
|
@ -105,7 +105,7 @@ buildings) tell you afterwards.
|
|||
| ----- | ------- |
|
||||
| `POST /towns/:id/train {unit, count}` | queue a batch (201). Batches of one training building (NOC / Ops lab / Rollout depot) run in order, buildings in parallel; queue limit 8 per building (`queue_full`) |
|
||||
| `POST /towns/:id/research {unit, stat}` | +5% `attack` or `defence` per level for one unit type, one research at a time per POP, level n needs a Research lab of level n + 2 |
|
||||
| `POST /movements {fromTownId, type, toTownId \| x,y, units, ...}` | send `scan`, `raid`, `attack`, `takeover`, `reinforce`, `settle` (201). `type: transport` carries `cargo: {fiber, hardware, capital}` (Internet exchange: level = concurrent transports, 1000 each, `D.TRANSPORT.capacityPerLink`). Extra fields: `target` (building for exploit kits), `wild` (two field types for a new POP), `confirmEndProtection` |
|
||||
| `POST /movements {fromTownId, type, toTownId \| x,y, units, ...}` | send `scan`, `raid`, `attack`, `takeover`, `reinforce`, `settle` (201). `type: transport` carries `cargo: {fiber, hardware, capital}` (Internet exchange: level = concurrent transports, each carries `rules.transportCapacity(speed)` = 1000 x the world speed; the POP view's `transport.capacityPerLink` already says the real number). Extra fields: `target` (building for exploit kits), `wild` (two field types for a new POP), `confirmEndProtection` |
|
||||
| `GET /movements` | your active movements (full detail, `recallableUntil`) and incoming ones from others: origin and ETA only, `type: "unknown"` |
|
||||
| `POST /movements/:id/recall` | turn an outbound movement around within the first 90 s (`recall_expired` after) |
|
||||
| `POST /towns/:id/withdraw {ownerTownId, units?}` | reinforcements in this POP go home (host kicks them out, or their owner calls them back) |
|
||||
|
|
@ -121,7 +121,7 @@ or take over each other; only the same alliance or a confederation may reinforce
|
|||
the movement arrives and bounces it (units come home, a `movement_failed` report says why) if something changed.
|
||||
|
||||
Report types: `raid`, `attack`, `takeover` (the same combat report: outcome, both sides' units and losses, attack/defence values,
|
||||
firewall, loot, siege, takeover/loyalty), `scan` (attacker; intel when it succeeded), `scan_detected` (defender; attacker identity only
|
||||
firewall, loot, `lootLeft` (what the raiders could carry and the target had, but their home Rack hall had no room for: it stayed with the target), siege, takeover/loyalty), `scan` (attacker; intel when it succeeded), `scan_detected` (defender; attacker identity only
|
||||
if the defender's scanners won), `incumbent`, `settle`, `reinforce`, `movement_failed`.
|
||||
|
||||
Later stages append their routes here and to the route table.
|
||||
|
|
@ -138,10 +138,10 @@ offer you have (older ones follow). `status`: `open`, `accepted`, `completed`, `
|
|||
| `GET /trade/offers?worldId&townId&give&want&after&limit` | open offers of others that one of your POPs (or `townId`) can take: within `min(maxDistance, 10 x exchange level)`. Each carries `acceptableFrom: [{townId, distance}]`; `exchangeLevels` lists your exchanges and their reach |
|
||||
| `GET /trade/offers/mine?worldId&status&after&limit` | offers you posted or accepted, any status, with `role` |
|
||||
| `GET /trade/offers/:id` | one offer: open ones to every operator of the world, closed ones to the two parties (`not_found` otherwise) |
|
||||
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP, capped by its Rack hall (stock already above the cap stays; a refund never lifts it further, and the clipped part is lost without a notice: BALANCE.md S2). `offer_closed` when it is not open |
|
||||
| `POST /trade/offers/:id/accept {townId}` | take it with one of your POPs (201): two transports leave at once (your payment, their goods); `own_offer`, `offer_closed`, `trade_out_of_range`, `no_transport_link`, `not_enough_resources`; all or nothing |
|
||||
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP and always fits: open escrow keeps its room in the Rack hall (`GET /towns/:id` `resources[r].cap` is hall size minus escrow, `escrow` lists it). Only a Rack hall shot down meanwhile can clip the refund; `returned.amount` is what was credited and a `trade_refund_clipped` notification says what was lost (BALANCE.md S2). `offer_closed` when it is not open |
|
||||
| `POST /trade/offers/:id/accept {townId}` | take it with one of your POPs (201): two transports leave at once (your payment, their goods); `own_offer`, `offer_closed`, `trade_out_of_range`, `no_room_for_goods` (your Rack hall would not have room for the goods when they arrive, projected with production and other cargo on its way: refused up front because overflow on arrival is destroyed), `no_transport_link`, `not_enough_resources`; all or nothing |
|
||||
|
||||
Notifications: `trade_accepted` (poster), `trade_completed` (both, when both transports arrived), `trade_expired`, `trade_void` (the POP
|
||||
Notifications: `trade_accepted` (poster), `trade_completed` (both, when both transports arrived), `trade_expired` (`returned` = what was credited), `trade_refund_clipped` `{offerId, townId, resource, lost, credited}` (a refund did not fit, rare), `trade_void` (the POP
|
||||
was taken over). Delivery notifications are the existing `transport_arrived` / `transport_delivered`. Direct transports (own POPs, any
|
||||
player) stay `POST /movements` with `type: "transport"`.
|
||||
|
||||
|
|
@ -151,20 +151,26 @@ player) stay `POST /movements` with `type: "transport"`.
|
|||
| ----- | ------- |
|
||||
| `GET /worlds/:id/status` | `phase` (`running`, `backbone_open`, `ended`), `ageDays`, `opensAt`, the 7 `sites` (empty before opening: `id` (null until first touched), `index`, `x`, `y`, `holder` `{allianceId, tag, name}` or null = incumbent, `takenBy`, `level`/`maxLevel`/`progress`, `pool` (stockpile), `build` `{toLevel, startedAt, dueAt}`, `next` `{toLevel, cost, durationMs}`), `winner`, `endsAt` (set once somebody won), `endedAt` |
|
||||
| `GET /worlds/:id/results` | the final snapshot once ended (`available: false` before): `winner`, `results.{operators, alliances, attackers, defenders, sites, totals}` (top 100 each, ranked) |
|
||||
| `GET /backbone/:id` | one site; holders also get `contributions` (who shipped what) and `you` `{holder, canBuild, canShip, canAttack}` |
|
||||
| `GET /backbone/:id` | one site (`shieldUntil` is set while a site that just changed hands cannot be attacked); holders also get `contributions` (who shipped what), `you` `{holder, canBuild, canShip, canAttack, canReinforce}`, `defence` `{static, garrison, total}` and `garrison` `[{ownerTownId, townName, operator, units, online, power, mine}]` (the units its members stationed there) |
|
||||
| `POST /backbone/:id/withdraw {fromTownId, units?}` | call units of one of YOUR POPs home from the site's garrison (201; default all of them; only their owner; works whoever holds the site); `not_enough_units`, `not_found` |
|
||||
| `POST /backbone/:id/ship {fromTownId, cargo}` | send resources to a site your alliance holds (201, a transport: same links and capacity); arrives into the stockpile, or rides home if the site changed hands |
|
||||
| `POST /backbone/:id/build` | start the next node level (201), paid from the stockpile at once, one level at a time, any holder with `backboneBuild`; `max_level`, `already_queued`, `not_enough_resources`, `forbidden` (not a holder), `backbone_closed` |
|
||||
|
||||
Taking a site is `POST /movements` with `type: "scan"` or `"attack"` and the site's `x, y` (no `toTownId`): needs an alliance, not against
|
||||
the own alliance or a NAP/confederation partner (`invalid_target`, `details.reason`: `no_alliance`, `own_site`, `pact`,
|
||||
`landing_scan_or_attack_only`); before opening `backbone_closed`. Settling a landing tile is `invalid_target` (`backbone_site`), also before
|
||||
it opens. Defence is static: `incumbentDefence x 12 x (1 + 0.03 x node level)`; a scan report shows it. Reports: scans as `scan` (with
|
||||
`landing_scan_or_attack_only`, `site_shielded` + `details.until`); before opening `backbone_closed`. Settling a landing tile is `invalid_target`
|
||||
(`backbone_site`), also before it opens. **Garrison:** `POST /movements` with `type: "reinforce"` and the site's `x, y` stations units there; only
|
||||
members of the holding alliance (`invalid_target`, `details.reason: not_holder`; checked again at arrival, the units turn back with a
|
||||
`movement_failed` report otherwise). Defence = static (`incumbentDefence x M x (1 + 0.03 x node level)`, M 12 unheld / 2 held) + the garrison
|
||||
(online groups, with their owners' research); a scan report shows `intel.static`, `intel.garrison` `{units, power}` and `intel.defence` (the sum).
|
||||
A `landing` report adds `defender.garrison` (per owner POP: sent, lost, survivors, offline) and `power.static` / `power.garrison`. Reports: scans as `scan` (with
|
||||
`site.type: "backbone"`), attacks as the new type `landing` (outcome, attack/defence, `taken`; recipients: the attacker and every member of the
|
||||
previous holder). `GET /map` lists open sites in `specials` as `type: "backbone"` with `site: {id, index, holder, level, maxLevel}`;
|
||||
`GET /map/tile` returns `type: "backbone"` and `backbone: {siteId, holder, level, pool, build, mine, canAttack}`.
|
||||
|
||||
Notifications: `backbone_open` (first touch), `backbone_taken` / `backbone_lost` (alliance members), `backbone_level` (every 10th level and the
|
||||
last, holder members), `backbone_delivered` / `backbone_ship_bounced` (sender), `backbone_won` (everybody), `world_ended` (everybody).
|
||||
Notifications: `backbone_open` (first touch), `backbone_taken` / `backbone_lost` (alliance members), `backbone_incoming` (holder members: a scan
|
||||
or attack was sent at their site, `{siteId, index, x, y, arriveAt}`, no type, no sender), `garrison_arrived` / `garrison_released` (the owner of the
|
||||
units; `reason`: `alliance_dissolved`, `left_alliance`, `town_lost`), `backbone_level` (every 10th level and the last, holder members), `backbone_delivered` / `backbone_ship_bounced` (sender), `backbone_won` (everybody), `world_ended` (everybody).
|
||||
|
||||
**An ended world** answers every game command with `409 world_ended` (build, send, train, trade, alliances, diplomacy, backbone, report
|
||||
sharing, ...). Still allowed: `GET` everything (map, reports, rankings, towns, status, results), `POST /reports/read-all`, `POST
|
||||
|
|
@ -178,3 +184,51 @@ reads one with its full data. Members with `viewSharedReports` only; `GET /allia
|
|||
**Allied incoming.** `GET /movements` has a new `alliedIncoming` list: movements heading for POPs of your alliance mates and of
|
||||
confederated alliances, same shape as `incoming` (type `unknown`, origin and ETA only) plus `ally: true` and `toOperator`. Friendly traffic
|
||||
(from partners of the target) is left out.
|
||||
|
||||
## Notification types (complete list)
|
||||
|
||||
Every row of `GET /notifications` has `type` and a `payload`; derived from the `notify` calls in `server/` (the list grows: clients treat an
|
||||
unknown `type` as generic). WebSocket hint `{type:"notification", id, kind}` carries the same `type` as `kind` (docs/PROTOCOL.md).
|
||||
`cargoLost` is `{resource: amount}` of what did not fit the Rack hall, exact, only the resources that lost something (rest of the
|
||||
cargo was stored).
|
||||
|
||||
| `type` | to | payload |
|
||||
| ------ | -- | ------- |
|
||||
| `build_done` | owner | `{townId, key, type, level}` |
|
||||
| `train_done` | owner | `{townId, unit, count}` |
|
||||
| `research_done` | owner | `{townId, unit, stat, level, key}` |
|
||||
| `incoming` | target's owner | `{movementId, toTownId, fromTownId, arriveAt}` (movement type hidden) |
|
||||
| `report` | report recipients | `{reportId, type, role}` |
|
||||
| `movement_returned` | owner | `{movementId, townId, units, cargo, cargoLost}`; also for a bounced shipment that carries cargo home (backbone, trade): `cargoLost` says exactly what the full hall destroyed |
|
||||
| `movement_lost` | owner | `{movementId}` (no POP left to go home to) |
|
||||
| `transport_arrived` | receiver | `{movementId, townId, fromTownId, cargo, cargoLost, own}` |
|
||||
| `transport_delivered` | sender (when not the receiver) | `{movementId, toTownId, cargo, cargoLost}` |
|
||||
| `reinforcements_sent_home` | owner of the units | `{hostTownId, ownerTownId, units}` |
|
||||
| `units_offline` | owner | `{townId, since}` (battery empty) |
|
||||
| `units_decommissioned` | owner | `{townId, units}` (24 h offline) |
|
||||
| `town_lost` / `town_gained` | old / new owner | `{townId, name, by}` / `{townId, name}` |
|
||||
| `trade_accepted` | poster | `{offerId, townId, byTownId, give, want}` |
|
||||
| `trade_completed` | both parties | see the trade section |
|
||||
| `trade_expired` | poster | `{offerId, townId, returned: {resource, amount}}` |
|
||||
| `trade_refund_clipped` | poster | `{offerId, townId, resource, lost, credited}` |
|
||||
| `trade_void` | poster | `{offerId, townId}` (the POP changed hands) |
|
||||
| `backbone_open` | everybody | `{sites: [{siteId, index, x, y}]}` (first touch after the sites open) |
|
||||
| `backbone_taken` / `backbone_lost` | attacker's / old holder alliance | site and alliance brief |
|
||||
| `backbone_incoming` | holder alliance | `{siteId, index, x, y, arriveAt}` (a scan or attack was sent; no type, no sender) |
|
||||
| `backbone_level` | holder alliance | `{siteId, index, level}` |
|
||||
| `backbone_delivered` | sender | `{movementId, siteId, cargo}` |
|
||||
| `backbone_ship_bounced` | sender | `{movementId, siteId, cargo}` (site changed hands: the cargo rides home, `movement_returned` follows with `cargoLost`) |
|
||||
| `backbone_won` | everybody | `{allianceId, name, tag, siteId, endsAt}` |
|
||||
| `world_ended` | everybody | `{winner, endedAt}` |
|
||||
| `garrison_arrived` | owner of the units | `{siteId, index, ownerTownId, units}` |
|
||||
| `garrison_released` | owner of the units | `{siteId, index, ownerTownId, reason, units, movementId}`; `reason`: `alliance_dissolved`, `left_alliance`, `town_lost` (a voluntary withdraw sends no notification) |
|
||||
| `alliance_invite` / `alliance_invite_declined` | invited operator / inviter | `{inviteId, allianceId, tag, name, by, expiresAt}` / `{inviteId, allianceId, by}` |
|
||||
| `alliance_member_joined` / `alliance_member_left` | alliance members | `{allianceId, operatorId, name}` (`kicked` on left) |
|
||||
| `alliance_kicked` | the kicked operator | `{allianceId, tag, name}` |
|
||||
| `alliance_role` | the operator | `{allianceId, tag, from, role}` |
|
||||
| `alliance_leader` | alliance members | `{allianceId, operatorId, name, from}` |
|
||||
| `alliance_disbanded` | alliance members | `{reason, ...alliance brief}` |
|
||||
| `alliance_message` / `message` | recipient | `{messageId, ...}` (`from`, `allianceId`/`tag`) |
|
||||
| `diplomacy_proposal` / `diplomacy_declined` | leader + diplomat of the other / proposing alliance | `{proposalId, from \| by, state, expiresAt?}` |
|
||||
| `diplomacy_changed` | both alliances | `{allianceId, other, from, to}` (also `reason: "disbanded"`) |
|
||||
| `diplomacy_cancel_pending` / `diplomacy_cancel_revoked` | both alliances | `{allianceId, other, ...}` (a pact cancel is scheduled / was revoked) |
|
||||
|
|
|
|||
164
docs/BALANCE.md
164
docs/BALANCE.md
|
|
@ -55,7 +55,7 @@ node tools/bot.js --help
|
|||
|
||||
| invariant | how it is checked |
|
||||
|---|---|
|
||||
| resources are conserved | `pools = sources + production - sinks`, per resource, at every midnight and at the end. Pools: POP stock, open trade escrow, cargo of movements that are out, landing-site stockpiles. **Production is exact**: a tap on `db.run` books the difference every `state.settle` writes (and drops it if the transaction rolls back). Sources: start stock of operators and founded POPs, the incumbent Hardware bonus. Sinks: build/train/research costs (command results), Backbone node levels, `cargoLost` in notifications (overflow at delivery), trade refunds clipped by the Rack hall cap (tap on the refund statement). Tolerance 0.5 per rounding event. |
|
||||
| resources are conserved | `pools = sources + production - sinks`, per resource, at every midnight and at the end. Pools: POP stock, open trade escrow, cargo of movements that are out, landing-site stockpiles. **Production is exact**: a tap on `db.run` books the difference every `state.settle` writes (and drops it if the transaction rolls back). Sources: start stock of operators and founded POPs, the incumbent Hardware bonus. Sinks: build/train/research costs (command results), Backbone node levels, `cargoLost` in notifications (overflow at delivery), `trade_refund_clipped` notifications (a refund that did not fit: only after a shot-down Rack hall since B6, 0 in every standard run). Open trade escrow is a pool. Tolerance 0.5 per rounding event. |
|
||||
| units are conserved | alive (home + stationed + on the road) = trained (`trainDone` events that ran) - lost (battle, scan, incumbent, landing reports, decommission notifications) - consumed (3 crews per founded POP, 1 M&A team per loyalty hit). Exact. |
|
||||
| no negative stock | SQL scan of towns and landing sites. |
|
||||
| no failed events | `events.status = 'failed'` and any server log line mentioning a failure. |
|
||||
|
|
@ -228,11 +228,34 @@ much as 1000 per link at both speeds (59 days at 1x; best level 94 on day 110 at
|
|||
was taken because the cost curve was set on purpose ("far more than anything else", DECISIONS E5, and DESIGN.md quotes 7.2 M) while carrying
|
||||
500 units per trip is a convenience limit nobody argued for, and because it also lifts bulk trade a little.
|
||||
|
||||
**Not solved by B2:** speed does not shorten the end game the way it shortens everything else. A 3x world opens its sites on day 33, but
|
||||
its alliances still take 76 days (seed 2) after that, about as long as a 1x world, because shipping is per sitting, not per hour (and
|
||||
at day 33 the members are at field level ~12 with fewer links). `capacityPerLink x world speed` in `rules.transportPlan` would
|
||||
restore the scaling (a 10x world with a final push finished 8.5 days after opening, below) but the client reads the constant directly
|
||||
(trade form limits, send dialog), so it was left to the owner of that code.
|
||||
**Not solved by B2 (solved by B7, below):** speed did not shorten the end game the way it shortens everything else. A 3x world opens its sites
|
||||
on day 33, but its alliances still took 76 days (seed 2) after that, about as long as a 1x world, because shipping is per sitting, not per hour.
|
||||
|
||||
(Re-measurement, 2026-10-11: the table above was measured on an older tree. The same command on HEAD today, `--days 240` because 175 is no longer enough,
|
||||
gives a winner on day 234.7 (134 days after opening) for seed 1 and day 200.2 (100 days) for seed 2 at speed 1, not 164 and 156. Something since the B2 runs
|
||||
(B4/B5, bot changes, other work in the tree) moved the end game; it was not bisected. Every "before" in B7 and E6 below is a run of today's HEAD, not a number from the B2 table.)
|
||||
|
||||
### B7. Transport capacity x world speed (`rules.transportCapacity`)
|
||||
|
||||
| parameter | old | new | file |
|
||||
|---|---|---|---|
|
||||
| link capacity | `TRANSPORT.capacityPerLink` (1000) at every speed | `rules.transportCapacity(speed)` = `capacityPerLink x speed` | `public/js/rules.js` (`transportPlan`, `tradeTermsCheck`), `server/military/views.js`, `public/js/screens/trade.js`, the bots |
|
||||
|
||||
Why: one link makes one trip per sitting, and a sitting does not get more frequent when the world is faster, so at 3x the shipping that the node needs
|
||||
(21.6 M units) took as many sittings as at 1x while everything else shortened. Cost: it applies to every transport and to the two sides of a trade
|
||||
offer (each side must fit one transport); production is also x speed, so the ratio of what a POP makes per sitting to what it can carry is unchanged.
|
||||
At speed 1 the factor is 1 and nothing changes, so **speed 1 cannot measure B7**: the table is speed 3 only. "Before" = HEAD today, "after" = this tree with
|
||||
`--no-contest --set ENDGAME.heldDefenceMult=12` (the pre-E6 end game: striker only, held sites as heavy as before), so only the capacity differs.
|
||||
`node tools/bot.js --players 50 --speed 3 --days 200 --seed S` (before, run from a `git archive HEAD` copy) and
|
||||
`node tools/bot.js --players 50 --speed 3 --days 110 --seed S --no-contest --set ENDGAME.heldDefenceMult=12` (after). The sites open on day 33.3.
|
||||
|
||||
| speed 3 | before: winner (days after the sites opened) | after (B7 only): winner (days after) |
|
||||
|---|---|---|
|
||||
| seed 1 | day 131.1 (97.7 days) | day 68.7 (35.4 days) |
|
||||
| seed 2 | day 109.9 (76.5 days) | day 62.8 (29.4 days) |
|
||||
|
||||
A 3x world now takes 29 to 35 days after opening, 2.6 to 2.8 times shorter, about a third of a 1x world's 100 to 134 days (which is what "3x" should mean),
|
||||
instead of 77 to 98 days. Not measured: speed 10 with this change (the 10x numbers in section 5 are from the 500/1000 pass). Every run `INVARIANTS OK`.
|
||||
|
||||
|
||||
### B4. Early-level build discount (the first hour and first day)
|
||||
|
|
@ -388,10 +411,11 @@ net worth = everything spent on buildings, units and research plus the stock lef
|
|||
`MILITARY.cacheMax 0.7 + cachePerLevel 0.14`: 4-6k, 181, -4 to -5 %; `cacheMax 0.8 + cachePerLevel 0.2`: 2-3k, 87 to 164, -8 to -11 %;
|
||||
`MILITARY.raidLossFactor 0.8`: 4-6k, 142-158, -4 to -6 %; `script_crew carry 30, botnet 90`: 3k, 137-197, -7 to -12 %. Untouched:
|
||||
10-11k, 188-198. None adopted: the untouched game is not dominant and bots scout better than most players will.
|
||||
- **Loot is mostly wasted on arrival** (`m2-after-d30-s1`): loot is split evenly over Fiber, Hardware and Capital whatever the raider
|
||||
needs, the raider's Hardware and Capital stores are usually full, and overflow at delivery is destroyed: over all deliveries of that run 77k Hardware,
|
||||
14k Capital and 2k Fiber vanished against 251k looted in total. Real value of a raid is mostly its Fiber. A rule that weights
|
||||
the split by free storage would double the effective loot; that is a design change, not a number.
|
||||
- **Loot was partly destroyed on arrival, and the incumbent bonus mostly** (fixed by B6, section 9; this bullet used to blame raid loot for all of it). Loot is split evenly over
|
||||
Fiber, Hardware and Capital whatever the raider needs, the raider's Hardware and Capital stores are usually full, and overflow at delivery was destroyed. Split by where it
|
||||
happened (new line "overflow by place" in the bot report; HEAD before B6, 30 days, seeds 1 / 2 / 3): raid returns lost 31k / 62k / 56k (17 to 22 % of the 187k / 275k / 268k
|
||||
looted, mostly Hardware and Capital), and the **one-time incumbent Hardware bonus lost 64.7k / 64.0k / 82.2k of the 77.5k / 77.5k / 97.5k it granted (83 to 84 %)**: the earlier
|
||||
"77k Hardware lost against 251k looted" was mostly that bonus.
|
||||
|
||||
### Takeover is expensive enough
|
||||
|
||||
|
|
@ -419,11 +443,9 @@ plus 4 substations), so the market has no natural counterparties and trade is mo
|
|||
other. Completed offers trade at 1.00 give/want (median). Not tuned: a thin market is an observation about this bot population, not a
|
||||
number to move.
|
||||
|
||||
**Server finding S2 (not fixed):** the escrow of an offer that expires or is cancelled after the POP's store filled up again is
|
||||
refunded only up to the Rack hall cap (`trade.refund`, decision R1). The harness books it: 36 refunds per 30-day run (all three seeds) lose
|
||||
12 to 15k Hardware and Capital in total (`arch-d30-s1`: 3.3k Hardware, 11.2k Capital in 36 events), invisibly to the player.
|
||||
DESIGN.md used to say nothing is lost in trade (corrected to describe the cap). Fix options: credit the clipped part back as a transport that waits, or let escrow refunds
|
||||
exceed the cap the way the existing "stock above a lowered cap is kept" rule does for stock.
|
||||
**Server finding S2 (fixed by B6, section 9):** the escrow of an offer that expired or was cancelled after the POP's store filled up again was
|
||||
refunded only up to the Rack hall cap (`trade.refund`, decision R1), invisibly to the player: 43 to 48 refunds per 30-day run lost 26 to 28k Hardware and Capital
|
||||
(seeds 1 / 2 / 3: 27.8k in 48, 26.7k in 44, 26.1k in 43 events). Now escrow keeps its room in the hall and the same runs clip 0.
|
||||
|
||||
### Power binds early and then recedes
|
||||
|
||||
|
|
@ -452,7 +474,7 @@ the capital's units offline (transient, fixed by the next substation level). Not
|
|||
|
||||
## 5. The end game
|
||||
|
||||
### What the bots do
|
||||
### What the bots do (before E6; the changes are in "E6" below)
|
||||
|
||||
When the world is at day `ENDGAME.openDay / speed` every alliance with at least 3 members plans (a shared in-memory plan, what an
|
||||
alliance would agree in its chat): the site with the lowest static defence (a little weight on distance); ONE member with an Ops lab trains
|
||||
|
|
@ -467,7 +489,7 @@ against the full static defence, so attacks cannot be added up); once the allian
|
|||
first attack that was strong enough; 3 of 3 landing attacks won), in the 3x world six sites were held by six alliances after 14 won attacks (sites
|
||||
change hands while the defence is still low). The static defence of a site at day 100 is 27k to 45k depending on the site (600 x 5.0 x 12 x a seeded +-25 %), i.e. an army of
|
||||
700 to 1 150 Script crews before research, which the striker (the member with the best economy and an Ops lab) had within days.
|
||||
- **Nothing is contested afterwards, and nothing can be.** The biggest army any single POP held at the end was 55 to 62k attack before research;
|
||||
- **(Before E6, HEAD: fixed by the next subsection.) Nothing is contested afterwards, and nothing can be.** The biggest army any single POP held at the end was 55 to 62k attack before research;
|
||||
the defence of a built-up site was 200 to 240k at speed 1 (levels 89+), 370 to 440k at speed 3. Defence passes what one POP can send
|
||||
at node level ~25 (weakest site) to ~40. That is E1 (no garrisons) showing up: after the opening days the race is shipping and node build
|
||||
time, not war. The only interaction is the opening scramble (the 3x world saw 14 won attacks for 6 sites; the 1x worlds none after the
|
||||
|
|
@ -483,16 +505,74 @@ against the full static defence, so attacks cannot be added up); once the allian
|
|||
`INVARIANTS OK` (the first speed-1 runs of this pass were flagged only because the bots kept commanding an ended world; the harness now stops
|
||||
and treats `world_ended` as expected).
|
||||
|
||||
### E6. Garrisons, a light static defence for held sites, a capture shield (the E1 finding)
|
||||
|
||||
What changed (all in `data.js` / `rules.js`, reasoning in DECISIONS E6): members of the holding alliance can station units in a site (`reinforce` to its x,y),
|
||||
the units defend on top of the static value at their owner's research and draw their owner's power, a lost attack kills (A/D)^1.5 of them, a won attack
|
||||
wipes them and takes the site; the static defence of a HELD site is `ENDGAME.heldDefenceMult` = 2 x incumbent (was 12; unheld sites keep 12);
|
||||
a site that changed hands is shielded for `ENDGAME.captureShieldHours` = 72 world hours (this was 24 in the first runs, see below).
|
||||
|
||||
What the bots do now (`tools/bot/endgame.js`, `--no-contest` switches it off): the holders of a site train defenders (towards 1.1 x what the strongest
|
||||
rival alliance could throw, shared by production, bots read it from the db: scouting is not simulated) and station every movable defender at the site;
|
||||
the others, when the target has a garrison, train crews towards a share of 1.15 x static + 2.2 x garrison, and when a war game (`rules.resolveBattle`, wave by
|
||||
wave over their members' real armies, nearest first) says the last wave takes the site, send their armies at their next sittings. A site without a garrison
|
||||
is still taken by one striker with a single army that beats the static part (waves cannot wear a static number down).
|
||||
|
||||
Commands: `node tools/bot.js --players 50 --speed S --days D --seed N [--no-contest] [--set ENDGAME.captureShieldHours=H]`. The "before" column is HEAD today
|
||||
(run from a `git archive HEAD` copy: it does not contain the other changes that are in the working tree now, e.g. the loot cap and the escrow room).
|
||||
Days after the sites opened (day 100.3 at 1x, 33.3 at 3x); "flips" = won attacks on a site somebody already held; "met a garrison" = attacks on a held site
|
||||
that found units there. Every run finished `INVARIANTS OK` (the ledger counts garrisons).
|
||||
|
||||
| world / seed | variant | winner: day (days after opening) | attacks on held sites | flips | met a garrison | units lost in landing battles (value) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1x, 1 | before (HEAD) | 234.7 (134.4) | 0 | 0 | 0 | 1.05 M |
|
||||
| 1x, 1 | **E6 adopted** (shield 72 h) | 202.8 (102.6) | 84 | 20 | 84 | 9.4 M |
|
||||
| 1x, 1 | shield 24 h (first runs) | 202.8 (102.6) | 166 | 43 | 164 | 13.4 M |
|
||||
| 1x, 2 | before (HEAD) | 200.2 (100.0) | 0 | 0 | 0 | 2.0 M |
|
||||
| 1x, 2 | **E6 adopted** | 208.4 (108.1) | 194 | 33 | 186 | 13.5 M |
|
||||
| 1x, 2 | shield 24 h | 220.7 (120.4) | 450 | 87 | 438 | 30.4 M |
|
||||
| 3x, 1 | before (HEAD) | 131.1 (97.7) | 0 | 0 | 0 | 1.4 M |
|
||||
| 3x, 1 | B7 only (`--no-contest`, held x12) | 68.7 (35.4) | 4 | 4 | 0 | 1.0 M |
|
||||
| 3x, 1 | **E6 adopted** (B7 + garrisons, shield 72 h) | 65.1 (31.8) | 93 | 54 | 70 | 6.1 M |
|
||||
| 3x, 1 | shield 24 h | 68.2 (34.9) | 188 | 142 | 108 | 12.7 M |
|
||||
| 3x, 1 | no shield | 60.6 (27.3) | 271 | 246 | 77 | 12.6 M |
|
||||
| 3x, 1 | shield 24 h, `heldDefenceMult` 3 | 68.2 (34.9) | 127 | 86 | 91 | 11.4 M |
|
||||
| 3x, 2 | before (HEAD) | 109.9 (76.5) | 0 | 0 | 0 | 1.3 M |
|
||||
| 3x, 2 | B7 only | 62.8 (29.4) | 4 | 4 | 0 | 1.0 M |
|
||||
| 3x, 2 | **E6 adopted** | 69.8 (36.4) | 109 | 65 | 90 | 7.3 M |
|
||||
| 3x, 2 | shield 24 h | 79.2 (45.8) | 266 | 174 | 193 | 14.5 M |
|
||||
| 3x, 2 | no shield | 68.1 (34.7) | 241 | 231 | 52 | 8.5 M |
|
||||
| 3x, 2 | shield 24 h, `heldDefenceMult` 3 | 80.9 (47.5) | 152 | 96 | 97 | 11.0 M |
|
||||
|
||||
(The adopted rows were re-run once with the new default in `data.js` and reproduce the `--set ENDGAME.captureShieldHours=72` runs exactly: 3x seed 1,
|
||||
winner 65.1, 54 flips.)
|
||||
|
||||
Reading it:
|
||||
- **Contests happen.** In the old world nobody attacked a held site after the opening (0 to 4 attacks, none against units). Now 84 to 194 attacks in the 100 days
|
||||
after the opening at 1x and 93 to 109 in 32 to 36 days at 3x, 75 to 100 % of them against a garrison, 20 to 33 and 54 to 65 flips, 6 to 13 M of unit value dying in
|
||||
landing battles (5 to 13 times before). That is a flip per site about every 25 to 35 days at 1x and about every 4 days at 3x (every 1.7 days with the 24 h shield).
|
||||
- **The end game can still be won, and is not slower on average**: 1x, days after opening 102.6 / 108.1 (adopted) against 134.4 / 100.0 (before), mean 105 against 117;
|
||||
3x 31.8 / 36.4 against 35.4 / 29.4 with B7 only, mean 34 against 32. With two seeds per cell that is "no worse", not a measurement of a difference.
|
||||
- **How much churn is right is the owner's call, and the numbers make it concrete.** With the 24 h shield 76 % (142 of 188) and 65 % (174 of 266) of the attacks on held
|
||||
sites at 3x succeeded, a site flipped every ~1.7 real days and the winner took up to 46 days; with no shield 91 to 96 % succeeded (the new holder had no garrison yet).
|
||||
With 72 h 24 % and 17 % of the attacks succeed at 1x (20 of 84, 33 of 194), 58 % and 60 % at 3x (54 of 93, 65 of 109), and the flips drop to 54 / 65 at 3x. A higher static defence (x3) did not help
|
||||
(`heldDefenceMult` is bounded from above by what one POP can send, DECISIONS E6). Not measured: a shield at 1x beyond 72 h, 72 h at speed 10, other seeds than 1 and 2.
|
||||
- **The static rule expires with world age** (DECISIONS E6): at world age 240 a held level-100 site's static part is ~51 000, at age 330 ~68 000, above the ~60 000 a
|
||||
single POP can send. The runs end (the winner appears) before that at 1x; a world that is meant to run longer needs `heldDefenceMult` or the growth to be capped.
|
||||
- **Not shown by these runs**: any human reaction. The holders do not react to `backbone_incoming` (they would garrison in time or recall), the attackers never feint,
|
||||
nobody scouts with `scan` (the bots read the garrison from the db), and every bot of an alliance obeys the plan. All of that is less friction than people.
|
||||
|
||||
|
||||
## 6. Server findings
|
||||
|
||||
| # | finding | status |
|
||||
|---|---|---|
|
||||
| S1 | **Cargo above the Rack hall cap was destroyed silently on bounced shipments.** A shipment that comes home (landing site changed hands, POP gone) rides back on a `link` return leg; `events/return.js` sent no notification for link legs, so the overflow was invisible to the player and to any audit. The conservation ledger found it as 1 000 Hardware + 2 718 Capital of drift in the first speed-10 end-game run (`node tools/bot.js --players 50 --days 14 --seed 1 --speed 10 --endgame-step-min 30`; with the fix the same command shows no drift, and it reproduces the bug if the `carrying` condition in `return.js` is taken out). | **fixed** (`return.js` notifies when a link leg carries cargo), `test/bot-server-fixes.test.js` fails without the fix |
|
||||
| S2 | Trade escrow refunds are clipped at the Rack hall cap and the loss is not reported (section 4). | open, design decision |
|
||||
| S2 | Trade escrow refunds were clipped at the Rack hall cap and the loss was not reported (section 4). | **fixed** by B6 (escrow keeps its room in the hall; a refund that still cannot fit, after a shot-down hall, is reported), `test/economy-leaks.test.js` |
|
||||
| S3 | `reports.id` is `INTEGER PRIMARY KEY` without `AUTOINCREMENT`; the 14-day cleanup can empty the table and SQLite then reuses low ids. A consumer that keeps "the last report id I saw" (the harness did, and silently missed every report after the first cleanup in a 170-day run) skips new reports. The API's own cursor (`GET /reports?after=` with `r.id < after`, newest first) is not hurt unless a client mixes old and new ids. Repro in five lines: insert three reports, `DELETE FROM reports`, insert one more: its id is 1 (the harness hit it in 170-day runs, where raids stop and every report expires). | open, low severity |
|
||||
| S4 | Loot is split evenly over the three resources and destroyed on overflow (section 4). | open, design |
|
||||
| S4 | Loot was split evenly over the three resources and destroyed on overflow; the incumbent bonus too (section 4). | **fixed** by B6 (loot limited to what home can bank, reported as `lootLeft`; the bonus is delivered above the cap), `test/economy-leaks.test.js` |
|
||||
| S5 | `ensureSites` is lazy (E2): the first touch of a landing site writes `backbone_open`; the harness reads sites with `E.siteStates` and never triggers it. No bug, noted so nobody expects the push in a bot run. | known |
|
||||
| S6 | **Room is still not reserved everywhere.** (a) Several raids from one home used to each project the same free room and the loot of all of them was banked against it (the overflow destroyed on landing); `combat.homeRoom` now subtracts the cargo of return legs that are already on the road to that POP, so the later raid is limited (and reports `lootLeft`). `test/economy-leaks.test.js` (two raids from one home with room for one) fails without it. (b) Still open, reported but not prevented: stock that production, a trade delivery or a transport adds while loot or a bounced shipment is on the road. A **bounced backbone shipment** (the site changed hands) rides home on a return leg and finds the hall full if production refilled it; the overflow is destroyed, and `movement_returned` carries the exact `cargoLost` (the client now prints it: "LOST, the Rack hall was full: ..."). Nobody reserves room for the outbound or the return leg of a shipment: that would cap production for as long as a shipment is in flight. (c) **Trade accept** now refuses with `no_room_for_goods` when the acceptor's hall will not have room for the goods at arrival (projected with production and other cargo already on the road to that POP; a projection, not a guarantee: stock can still grow on the way and then the overflow is destroyed and reported as before). | (a) **fixed**, (b) **open, reported**, (c) **fixed as a refusal**; `test/trade-flow.test.js`, `test/economy-leaks.test.js` |
|
||||
|
||||
## 7. Bot bugs that moved the numbers (so nobody trusts an early number from this pass)
|
||||
|
||||
|
|
@ -507,14 +587,15 @@ against the full static defence, so attacks cannot be added up); once the allian
|
|||
## 8. What is still unknown
|
||||
|
||||
- Bots are not humans. They never forget to log in, never panic, never coordinate beyond a shared in-memory plan, never mis-click, and play
|
||||
the same sittings every day. They do not use reinforcement, recall, the shared report folder, messages, sitters, or night play. They
|
||||
the same sittings every day. They use reinforcement only to garrison landing sites (E6), and do not use recall, the shared report folder, messages, sitters, or night play. They
|
||||
never choose a different capital or sell their stock off before an attack.
|
||||
- No real players means no data on how many sittings a day people really play; the whole B1 argument rests on the 2-to-8 sittings-a-day
|
||||
band that the CLAUDE.md pitch implies.
|
||||
- Rural bonuses, wild slots and the Peering office size ladder were not examined. The offline/decommission power path never ran in a bot
|
||||
run. The alliance war/peace states were exercised (NAP, confederation, war appear in the runs) but never made to matter in a fight.
|
||||
- The end game was run with a single plan per alliance that nobody contests after the first days (section 5); a determined rival with
|
||||
several armies cannot beat a built-up site (single-POP attack ceiling), so there is no data on what an actual fight for a site would look like.
|
||||
- The end game has a contest now (E6, section 5), played by bots that follow one shared plan per alliance, read their rivals' armies and the garrison from the
|
||||
db, and do not react to `backbone_incoming`. How humans would garrison, recall, feint or sit on a site is unknown; `heldDefenceMult` 2 and the 72 h shield are first
|
||||
guesses with two seeds per cell, and the static defence outgrows one POP's army around world age 280.
|
||||
- `--always-on` is an upper bound on attention, not a model of a person.
|
||||
|
||||
|
||||
|
|
@ -524,3 +605,42 @@ against the full static defence, so attacks cannot be added up); once the allian
|
|||
After B4 the owner's first hour on the live world was still described as "a bit slow". B4's own measurement (variant "START.resources 1000", no discount) showed
|
||||
the mid game unchanged (head start 0 to 0.1 days) and a 60-minute first sitting going from 12.1 to 15.4 builds at 1 h, so `START.resources` is now 1000 per
|
||||
resource. Not re-measured in combination with B4 beyond a 50 x 30-day bot run that ended INVARIANTS OK. No human data.
|
||||
|
||||
## 9. B6. Trade escrow keeps its room; loot is limited to what home can bank (S2 and S4)
|
||||
|
||||
Rules (decision B6 in DECISIONS.md has the reasoning and the rejected options):
|
||||
- **Trade (S2):** goods escrowed in open offers still occupy the Rack hall: that resource stops filling at hall size minus the escrow (`rules.storageCapOf`), so cancel / expiry /
|
||||
void always fit and the escrow is no extra storage (R1 stays closed). Residual clip only after a shot-down hall; it sends `trade_refund_clipped`.
|
||||
- **Loot (S4):** a win takes at most what the raiders' home Rack hall can bank when they are back (hall size minus the stock projected to then); a resource with no room is skipped and the
|
||||
carry goes to the others; the rest stays with the victim and the report shows it as "Left behind".
|
||||
- **Incumbent bonus:** the once-only 2 500 Hardware is delivered above the cap if the store is full.
|
||||
No `data.js` number changed.
|
||||
|
||||
**Before / after** (`node tools/bot.js --players 50 --days 30 --seed N --quiet --json out.json`, seeds 1 / 2 / 3; before = the tree at HEAD with the same reporting lines, after = this change; both
|
||||
`INVARIANTS OK` in all six runs; every number from the report's "overflow by place", "trade refunds" and raid lines):
|
||||
|
||||
| per 30-day run | before (s1 / s2 / s3) | after (s1 / s2 / s3) |
|
||||
|---|---|---|
|
||||
| raid loot destroyed on arrival (Fiber+Hardware+Capital) | 31.0k / 61.5k / 56.5k | 0.1k / 1.0k / 0.7k |
|
||||
| incumbent bonus destroyed on arrival | 64.7k / 64.0k / 82.2k of 77.5k / 77.5k / 97.5k | 0 (all delivered: 57.5k / 60.0k / 87.5k) |
|
||||
| trade refunds clipped (events) | 27.8k (48) / 26.7k (44) / 26.1k (43) | 0 (0) / 0 (0) / 0 (0) |
|
||||
| transport deliveries over the cap | 0 / 0 / 0 | 0 / 0 / 1 event (474 Fiber) |
|
||||
| loot per the reports (nominal, before = what the carry split gave, after = what was banked) | 187k / 275k / 268k in 170 / 214 / 193 raids | 144k / 207k / 175k in 190 / 247 / 189 raids |
|
||||
| loot left behind for lack of room (new) | - | 63k / 80k / 79k |
|
||||
| won raids with empty hands (new) | - | 1 / 4 / 0 |
|
||||
|
||||
Side effects, mean of the three seeds: raider net worth 287.6k -> 288.3k, builder 357.7k -> 357.5k, builder median footprint 11 784 -> 11 824, Hardware lost to full stores 29 % -> 31 % of
|
||||
what the rates would give (stores are as full as before, the loot just stops being destroyed). Offers completed per run 40 / 35 / 33 -> 42 / 28 / 39 (noise: the trajectories differ).
|
||||
|
||||
How to read it: **what changed is where the loss happens, not what players earn.** Before, the part of a raid that did not fit was thrown away at the door; now it is not taken, so it stays in the
|
||||
victim's stores (the 63 to 80k "left behind"), and the raider's net worth did not move. The loot that was banked per raid went down in these runs (about 920 -> 760 in seed 1, 1 000 -> 830 in seed 2,
|
||||
1 100 -> 920 in seed 3, counting before as nominal minus overflow). I did not find the cause; the raid mix changed (raids 170 -> 190 in seed 1) so it may be the bots targeting differently, or
|
||||
the projection being conservative, and it did not show up in net worth. Raiding is not stronger or weaker for it on this evidence.
|
||||
|
||||
Also run: `--days 14 --speed 1 --seed 1` (the CLAUDE.md run), `--days 60 --seed 1`, and `--days 14 --speed 10 --endgame-step-min 30 --seed 1` (end game with shipments): all `INVARIANTS OK`
|
||||
(the 60-day and speed-10 runs were not compared with a before; only the invariants were checked).
|
||||
|
||||
Not verified / left: the projection ignores other deliveries that reach the home store in between (hence the 0.1 to 1.0k that is still destroyed and still reported through `cargoLost`); transport
|
||||
deliveries (including trade goods) onto a full store still lose the overflow, reported; a human would see the shrunk Fiber/Hardware/Capital store while an offer is open (UI says so, text only,
|
||||
nobody has looked at it on a phone); how the reserved room changes what offers players post is not measured beyond the offer counts above.
|
||||
|
||||
|
|
|
|||
|
|
@ -152,8 +152,8 @@ target's owner `incoming` (town + ETA) and no plain `town` hint, so the type and
|
|||
would have to be excluded from footprint rankings, the last-POP / capital / footprint-gate counts, `homeTownFor`, `/me`, spawn spacing and
|
||||
the Rack hall cap (shipped resources would be thrown away at 250), and a leader change would have to re-own it. The holder is the
|
||||
alliance (`holder_alliance_id`, FK `ON DELETE SET NULL`, the disband hook also clears it), `holder_operator_id` only records who took it.
|
||||
Consequence, on purpose and to be revisited after the first world: **no units can stand at a site**, so there is no garrison and no
|
||||
reinforcement. A site is defended by the static value `incumbentDefence x 12 x (1 + 0.03 x level)` only, i.e. exactly the "incumbent
|
||||
Consequence, on purpose and to be revisited after the first world (**revisited in E6: garrisons exist now**; the rest of this paragraph is the
|
||||
original reasoning): **no units can stand at a site**, so there is no garrison and no reinforcement. A site is defended by the static value `incumbentDefence x 12 x (1 + 0.03 x level)` only, i.e. exactly the "incumbent
|
||||
with a backbone multiplier" of DESIGN.md; holders defend by growing the node (higher level = harder to take), attackers can scan the exact
|
||||
number. Hooks into the military code are small: `combat.arriveSite` hands `backbone` tiles to `military/landing.js`,
|
||||
`arrivals.arriveTransport` hands shipments (`extra.siteId`) to `endgame.deliverShipment`, `sendMovement` calls `endgame.checkLandingTarget`.
|
||||
|
|
@ -187,11 +187,45 @@ automatically as long as they carry one of those arguments.
|
|||
about 36 world days of building in total, level 100 alone 312 k each and 23 h). Pure guesses until a bot run (stage 7) says how much an
|
||||
alliance can ship; nothing here is balanced.
|
||||
|
||||
## E6 — Garrisons at landing sites, a light static defence for held sites, a capture shield (BALANCE.md section 5, E1 follow-up)
|
||||
Problem (bot runs, BALANCE.md section 5): after the opening scramble nobody could contest a held site. Its static defence was 12 x incumbent x (1 + 0.03 x level),
|
||||
200 to 440 k at node level 89+, and one attack is one movement from one POP, whose army tops out around 60 k attack; with no garrison there is nothing a wave can
|
||||
wear down, so "attacks cannot be added up". Adding a garrison ON TOP of that static value would only have made held sites harder, not contestable.
|
||||
Decided:
|
||||
- **Static defence of a HELD site drops to `ENDGAME.heldDefenceMult` = 2** x incumbent defence (x the per-level bonus); an unheld site keeps `defenceMult` 12 (the
|
||||
opening scramble is unchanged). The rule behind the number: static defence must stay below what one POP can send (about 60 k), otherwise the last wave of
|
||||
a fight could never win and a built-up site would be out of reach again. At day 100 a held site is ~7 k at level 0, ~28 k at level 100; at day 170 level 100 it is ~37 k.
|
||||
- **A garrison**: table `site_stationed(site_id, owner_town_id, unit, count)` (migration 005; `stationed` has a POP as host, a site is not a POP, E1). Members of the
|
||||
holding alliance, and only them, `reinforce` a site with the existing movement type (target = the site's x,y); the check is made when sending and again at arrival
|
||||
(a site that changed hands, or an alliance the sender left, turns the units back with a `movement_failed` report). Units are in exactly one place at a time; a table
|
||||
of its own makes the conservation ledger count them (`tools/bot/ledger.js`).
|
||||
- **Power**: garrison units draw their OWNER's POP (`state.unitDraw`, `power.drawingUnits`, `power.decommission`), because a site has no power budget; sending them
|
||||
changes no one's total draw, units on the road draw nothing (as everywhere), an owner POP without power takes its group offline (it does not defend, a won attack still
|
||||
wipes it) and decommission takes units out of the garrison last. Alternative rejected: free upkeep at the site (a bottomless defence) or an upkeep charged to the
|
||||
alliance (no such budget exists).
|
||||
- **Combat** is the POP law: `resolveBattle` with `staticDefence` AND defenders: D = static + the online groups' defence (their owner's research), no firewall, no
|
||||
base defence; a lost attack kills (A/D)^1.5 of each group's units, a won attack kills them all and the attacker's alliance holds the site (level, stockpile and a
|
||||
running build stay, as before). The static part loses nothing. No new combat rule, so waves resolve in arrival order, `(due_at, id)`, like every battle.
|
||||
Rejected: a "breach" counter on the static part that heals over time (one more number and one more stored timestamp for the same effect).
|
||||
- **Leaving**: `POST /backbone/:id/withdraw` (owner only, any time, works after the site changed hands) and automatic returns (a return movement each) when the owner
|
||||
leaves or is kicked (`allianceLeave`, `allianceKick`), the alliance disbands (`onAllianceDissolved`, before the holder is cleared) or the owner's POP is taken over
|
||||
(`combat.transferTown`, to the old owner's other POP). Rejected: "left in the site, withdrawable later" (the units of a non-member would defend a rival).
|
||||
- **Capture shield**: `ENDGAME.captureShieldHours` = 72 world hours (/ speed) after a site changes hands, no attack on it (refused when sent, bounced at arrival).
|
||||
A freshly taken held site has no garrison yet: with no shield bot runs flipped sites ~240 times in 27 to 35 days at 3x, with 24 h still ~140 to 175 times, with 72 h
|
||||
54 to 65 times and no slower a winner (BALANCE.md section 5; all of that is bots). Not a rule for unheld sites.
|
||||
- **The static rule expires**: `incumbentDefence` grows with world age, so the held static part of a level-100 site passes one POP's ceiling (~60 k) around world age 280
|
||||
(real day ~93 at 3x). From then on only a garrison that waves have already worn down can be finished by one army; `heldDefenceMult` has to come down or the
|
||||
growth stop at some age if a world is meant to run that long.
|
||||
- **Not decided here, and why**: a captured site keeps its node level (the existing rule, "take it over"; the task also named "down a level" as an option); if the first
|
||||
world shows the race ends by one late strike on a finished node, `captureLevelLoss` is the lever.
|
||||
- **Notifications**: `backbone_incoming` (holders, no type, no sender), `garrison_arrived`, `garrison_released`; push gets a `town` hint for the owner POP.
|
||||
Gaps: bots do not react to `backbone_incoming`, there is no sitter, `tools/admin.js inspect` does not list garrisons, a human alliance can still leave a site with zero garrison.
|
||||
|
||||
## T1 — Trade: escrow, one link per side, reach by exchange level
|
||||
- Offers are escrowed in `trade_offers` and hold one transport link of the poster's POP while open (`movements.activeLinks` counts open
|
||||
offers), so accepting never fails for lack of a link on the poster's side and cannot exceed the exchange level.
|
||||
- Each side of an offer must fit ONE transport (<= 1000, was 500 until B2); larger deals are several offers. The ratio band is count-based 1:2.
|
||||
- Escrow returned WITHOUT the Rack hall cap at first (conservation beats the cap); review round 1 (R1) reversed that: refunds are capped like `cancelBuild` (stock already above the cap stays, the clipped part is lost silently, BALANCE.md S2). Deliveries keep the cap rule (`cargoLost`).
|
||||
- Each side of an offer must fit ONE transport (`rules.transportCapacity(speed)`: 1000 x world speed, B7; was 500 until B2); larger deals are several offers. The ratio band is count-based 1:2.
|
||||
- Escrow returned WITHOUT the Rack hall cap at first (conservation beats the cap); review round 1 (R1) reversed that: refunds are capped like `cancelBuild` (stock already above the cap stays, the clipped part is lost silently, BALANCE.md S2; superseded by B6: escrow keeps its room in the hall, so the refund fits). Deliveries keep the cap rule (`cargoLost`).
|
||||
- Reach: `10 tiles x exchange level` of the taker's POP, and the offer's own `maxDistance`; the poster's level only matters for the number of
|
||||
offers they can hold open.
|
||||
- A POP changing hands voids its open offers (`combat.transferTown` calls `trade.onTownTransferred`); the escrow stays in the POP.
|
||||
|
|
@ -246,7 +280,7 @@ The end game is shipping-limited, not production-limited: 21.6 M units (7.2 M of
|
|||
won in each seed, 55 to 78 days after the sites opened (node build time alone is 36 days). Raising `ENDGAME.costGrowth` to 1.035 or
|
||||
the capacity to 2000 were measured and not taken (2000 leaves only the 36-day build floor as a constraint). Not solved: a 3x world takes about as
|
||||
long after the sites open as a 1x world, because shipping is per sitting, not per hour; `capacityPerLink x world speed` would fix it but the
|
||||
client reads the constant. See BALANCE.md section 5.
|
||||
client reads the constant. See BALANCE.md section 5. (Done in B7.)
|
||||
|
||||
## B3 — A bounced shipment reports its overflow
|
||||
`events/return.js` stayed silent for empty-carrier return legs AND for shipments that came home with cargo; cargo above the Rack hall cap is
|
||||
|
|
@ -264,3 +298,73 @@ different slope (default mix field level +2 % on day 30, +0.1 % on day 60; 2 a d
|
|||
were measured and dropped: the first does nothing for the first hour and shifts the mid game, the second multiplies the head start (up to ~11 days) for no first-hour gain.
|
||||
Not done, and probably the bigger lever for an engaged player: a higher starting stock (1000 of each moved the mid game by 0 days and gave a 60-minute first sitting 15.4 builds at 1 h
|
||||
instead of 12.1). Left for the owner to call.
|
||||
|
||||
## O1 — Admin `end-world` runs the real `worldEnd` handler (ops)
|
||||
The first CLI version only set `status = 'ended'`: no ranking snapshot, `/results` stayed unavailable, pending events and trade escrow were left
|
||||
behind. It now enqueues a `worldEnd` event (`reason: 'admin'`, due now) and processes it through the real `Scheduler` and the real handler, after
|
||||
processing that world's already-due events in order; every handler call is guarded by a status re-check inside the transaction, so a running
|
||||
server that handles the same event at the same moment cannot double-apply it. One implementation of "a world ends" instead of two. Cost: the CLI
|
||||
is a separate process, so the `world_ended` notification rows it writes are not pushed over a running server's sockets. Not repairable: a world
|
||||
the old command ended has no snapshot.
|
||||
|
||||
## O2 — `deploy/update.sh` rolls back one step with `git reset --hard`, and does not touch migrations
|
||||
The checkout is on `main` and the tree is required to be clean, so `git reset --hard <old rev>` loses nothing and keeps the branch (a
|
||||
`git checkout <rev>` would leave a detached HEAD that the next update refuses). The snapshot is taken (and verified) before any change; no
|
||||
snapshot, no update. Migrations are forward-only (`DEPLOY.md` section 8): the script announces new ones before it starts and names the
|
||||
snapshot to restore after a rollback, instead of pretending it can undo them. Origins with credentials in the URL are refused (the
|
||||
checkout must use plain HTTPS; nothing secret in `.git/config`).
|
||||
|
||||
## B6 — Trade escrow keeps its room in the Rack hall; loot is limited to what home can bank (BALANCE.md S2 and S4)
|
||||
Two economy leaks the bot ledger priced (30 days, 50 players, seeds 1 to 3): 43 to 48 trade refunds a run clipped at the Rack hall cap, 26 to 28k lost
|
||||
silently (S2); 17 to 22 % of the raid loot destroyed on arrival because the raiders' Hardware/Capital stores were full (S4), plus 83 to 84 % of the one-time
|
||||
incumbent Hardware bonus (64 to 82k a run; BALANCE.md had blamed raid loot for this).
|
||||
- **S2, chosen: escrow keeps its room.** `rules.storageCapOf(town, res) = hall size - town.escrow[res]` (the escrow is the sum of the POP's open offers, loaded by
|
||||
`state.townFromRow`). While an offer is open that resource stops filling at hall size minus the escrow, so a refund always fits and the escrow is never extra
|
||||
storage: R1's exploit (refill to the cap while the escrow is out, then cancel for cap + escrow) cannot happen, and nothing is lost. The one invariant to keep:
|
||||
**every way out of `open` must settle the POP first**, because the cap changes there (`closeOffer` settles and credits BEFORE the status change; `tradeAccept`
|
||||
settles the poster; creation settles before the insert). The same cap is used by deliveries (`addCargo`) and `cancelBuild`. The only residual clip is a Rack hall
|
||||
shot down below stock + escrow; it sends `trade_refund_clipped` and the ledger books that notification as a sink (the SQL-statement tap is gone).
|
||||
Rejected: a "held" amount the owner claims later (new state, command, route, expiry and a bounded hiding place, for the same outcome), and limiting the escrow
|
||||
so it always fits (impossible: stock grows while the offer is open). Cost to the player: a POP with 700 Fiber escrowed has a Fiber store 700 smaller for up to 48 h;
|
||||
the trade screen says so.
|
||||
- **S4, chosen: take only what home can bank.** `combat.homeRoom` = hall room minus the stock projected to the moment the raiders are back (pure projection, no
|
||||
write); `rules.lootSplit(carry, avail, room)` skips a resource with no room and shares the carry among the others; the rest stays with the victim and the report
|
||||
has `lootLeft`. Not exact (other deliveries can still fill the store in between: 0.7k of 175k looted remains destroyed and reported via `cargoLost`). No home POP:
|
||||
nothing is taken (before, it was deducted from the victim and vanished).
|
||||
- **Incumbent bonus, chosen: delivered above the cap.** It can be earned once per site, so a full store must not eat it; `extra.bonus` on the return leg is credited
|
||||
uncapped (kept, it only stops growing: the same rule as a lowered Rack hall). Bounded by 2 500 Hardware per site per operator; a reward gate (deferring the take)
|
||||
was rejected because bots would re-attack for nothing.
|
||||
Not changed: transport deliveries onto a full store still lose the overflow (reported; 0 to 1 event per 30-day run now).
|
||||
|
||||
## B7 — Transport capacity scales with world speed (`rules.transportCapacity`)
|
||||
Follow-up of B2: shipping is per sitting (one trip per link), not per hour, so the end game did not shorten with world speed. `D.TRANSPORT.capacityPerLink` stays the number
|
||||
at speed 1 and `rules.transportCapacity(speed)` = `capacityPerLink x speed` is the ONLY reader of it: `transportPlan` (by `town.speed`), `tradeTermsCheck(terms, speed)`
|
||||
(each side of an offer fits one transport), the POP view's `transport.capacityPerLink` (which the send dialog and the site sheet show), `client trade.js`, the bots. A test
|
||||
(`test/transport-speed.test.js`) fails when a source file outside rules.js/data.js mentions the constant. Rejected: a flag in data.js to turn the scaling off (a bot run
|
||||
with `--set TRANSPORT.capacityPerLink=...` reproduces any old value at a given speed). Numbers: BALANCE.md section 5.
|
||||
|
||||
## E2E: how flights are made to land, and what the nb detector can and cannot see
|
||||
- **Moving flights up instead of waiting.** `rules.latencyMs` has a 10 minute floor in real time, so a speed-1 raid, a trade leg or a site shipment cannot finish inside a test. The e2e
|
||||
(`e2e/lib.js` `hurryMovement` / `hurryEvents`) writes the new due time into the movement row and its pending event and calls `scheduler.arm()`; the handlers run unchanged. Chosen over a fake
|
||||
clock (the page uses the real browser clock and the server's `serverTime` offset) and over a speed-4000 world for everything (the flight must be on screen first: checks assert the countdown
|
||||
before the move-up). Rejected: a test-only latency override in server code.
|
||||
- **Norwegian check = detector + snapshot.** A raw key is any visible text matching `<known namespace>.<name>`; an English leftover is visible text equal to the English text of a key whose nb text
|
||||
differs (placeholders become wildcards). Both tables are snapshotted before the test touches anything, and the detector is calibrated on every run (it must find >= 8 English strings on the English POP
|
||||
screen, and a planted key / a deleted nb string). It cannot see an nb string that was copy-pasted from English, so a separate check fails on any multi-word nb string identical to its English text.
|
||||
Live switching is checked for visible text only; stale aria-labels after a live switch are reported in the run log, not failed (NEXT.md gaps).
|
||||
- **`{type:'message'}` push now acts.** `messages.js` refetches the unread count (a poll that arrives while one is in flight asks once more) and the visible inbox / alliance feed / open thread. Before, the
|
||||
hint was received and dropped.
|
||||
|
||||
## R2 — Review round 2 fixes: update.sh order, offsite scp, room reservation, garrisons in the POP view
|
||||
- **update.sh stops the service before it touches the tree** (it used to merge and `npm ci` under a running process that lazily `require()`s modules). The optional `--test` runs
|
||||
on a `git archive` copy of the new rev in a temp dir, as the service user (`runuser`), with `npm ci --ignore-scripts`; never as root, never in `/opt/upstream`. The snapshot is
|
||||
taken after the stop (final state of the database), so a failed snapshot costs a short outage and then the service is started again. Rejected: running tests as root in the live
|
||||
tree (fetched code as root, and the mixed-code window); a second snapshot before the stop (two snapshots, still not the final state).
|
||||
- **Rollback across migration 005** (site_stationed) is documented as unclean once anybody has garrisoned a site: old code does not know the table. No downgrade script (migrations are one-way, B-series rule).
|
||||
- **scp removed from upstream-offsite**: scp cannot refuse to overwrite, and the docs promised never to. rsync with `--ignore-existing` is the only method; `OFFSITE_METHOD=scp` is rejected (exit 2).
|
||||
- **Room for loot** is reserved only against return legs already on the road to the home POP (`combat.homeRoom`), not against production or deliveries that land meanwhile; bounced
|
||||
shipments are reported with exact `cargoLost`, not prevented. Rejected for now: reserving room through the escrow mechanism for every shipment (caps production for as long as it is
|
||||
out; a real economy change that wants a bot comparison first). BALANCE.md S6.
|
||||
- **Trade accept refuses with `no_room_for_goods`** when the projected hall of the acceptor cannot take the goods; it does not clip or split the trade. The projection ignores stock that appears on the way.
|
||||
- **`units.garrisoned`** in the POP view: units standing in landing sites draw the owner POP's power, so the owner's POP view lists them (site id and coordinates, units).
|
||||
|
||||
|
|
|
|||
155
docs/DEPLOY.md
155
docs/DEPLOY.md
|
|
@ -15,12 +15,14 @@ layer. The differences are the Node version (`node:sqlite` needs 22.13+), a stat
|
|||
|
||||
**What was and was not run while writing this** (so you know what to check on the real box):
|
||||
|
||||
* **Run:** `systemd-analyze verify` on the three unit files (syntax and directives only), the CLI `tools/admin.js`
|
||||
* **Run:** `systemd-analyze verify` on the unit files (syntax and directives only; the two off-site units: only the expected "not executable" warning for a script path that does not exist on the dev machine), the CLI `tools/admin.js`
|
||||
and its tests on a dev machine (Node 24.21), a backup, verify and prune cycle, `sh -n` on `deploy/upstream-admin`.
|
||||
Re-checked on 2026-10-11 with the code as it is now (Node 24.21, scratch directory, no systemd): first boot with `DB_PATH`/`PORT`/`HOST`
|
||||
(migrations 001-004 applied, `created world 1`), `/healthz`, `/` headers, signup + build over the API, `admin.js` status / worlds / users /
|
||||
operators / inspect-town / events / replay-events / backup / verify-backup / ban / unban / grant / end-world (refusal without `--yes`),
|
||||
SIGTERM and restart (state, queue and password kept, no migrations re-applied; tokens revoked by `ban` stay revoked), SIGKILL then restart after a build fell due (`caught up 1 overdue event(s)`, the build level was applied), and a restore by copying a snapshot to a fresh `DB_PATH` and starting on it (section 7: it logged `caught up 1 overdue event(s)`).
|
||||
* **Run, ops scripts (dev machine, stubs, no systemd):** `deploy/update.sh` and `deploy/upstream-offsite` and `admin.js end-world` through
|
||||
`test/deploy-update.test.js`, `test/deploy-offsite.test.js`, `test/admin-endworld.test.js`; sections 7 and 8 say exactly what each covers.
|
||||
* **Taken from NETWALL's docs, not re-run for UPSTREAM:** everything about nginx Proxy Manager (labels, header
|
||||
behaviour, "Client addresses"). NETWALL's guide records what was observed against NPM v2.16.0.
|
||||
* **Never run:** a Proxmox LXC, a started unit under systemd, the timer firing on its own, a Node install from the
|
||||
|
|
@ -113,6 +115,8 @@ mkdir -p /opt/upstream
|
|||
# from your workstation:
|
||||
# rsync -a --delete --exclude node_modules --exclude .git --exclude data --exclude e2e ./ root@<lxc>:/opt/upstream/
|
||||
# (needs server/, public/, tools/, deploy/, docs/, package.json, package-lock.json; `test/` is optional)
|
||||
# or, the way the live box is run, a git checkout that deploy/update.sh updates later (section 8):
|
||||
# git clone https://git.vanvikinternet.no/jvanvik/Upstream.git /opt/upstream (plain HTTPS URL, no token in it)
|
||||
cd /opt/upstream
|
||||
npm ci --omit=dev # only "ws"; follows the lockfile exactly
|
||||
chown -R root:root /opt/upstream
|
||||
|
|
@ -131,6 +135,7 @@ install -m 0644 /opt/upstream/deploy/upstream.service /opt/upstream/deploy/upstr
|
|||
systemctl daemon-reload
|
||||
systemctl enable --now upstream upstream-backup.timer
|
||||
systemctl status upstream
|
||||
# off-box copy of the snapshots is optional and not installed here: section 7
|
||||
journalctl -u upstream -f
|
||||
```
|
||||
|
||||
|
|
@ -153,7 +158,8 @@ The first start prints `applied migrations: 001_init.sql, ...`, `created world 1
|
|||
without it the database cannot be opened.
|
||||
* Shutdown: SIGTERM stops the scheduler timer, closes the listener and the database and exits 0 in about a second.
|
||||
Even a SIGKILL or power cut is survivable (WAL replay on the next open, then overdue events are caught up).
|
||||
* `deploy/upstream-backup.service` (oneshot) and `.timer`: see section 7.
|
||||
* `deploy/upstream-backup.service` (oneshot) and `.timer`: see section 7. `deploy/upstream-offsite.service` and `.timer` (optional off-box copy) and
|
||||
`deploy/update.sh` (section 8) are not installed by the steps above.
|
||||
|
||||
## 4. Configuration
|
||||
|
||||
|
|
@ -237,7 +243,7 @@ upstream-admin help
|
|||
upstream-admin status # file, size, migrations, overdue events
|
||||
upstream-admin worlds
|
||||
upstream-admin create-world --name "Summer" --speed 2 --radius 60 --seed 1234 --end-in 90d
|
||||
upstream-admin end-world 1 --yes # flag flip only, see below
|
||||
upstream-admin end-world 1 --yes # same as the natural end: final ranking, escrow back, events cancelled
|
||||
upstream-admin users [--banned] # no hashes or tokens are ever printed
|
||||
upstream-admin operators [--world 1]
|
||||
upstream-admin ban mallory # sets banned, revokes all tokens: old tokens give 401, login 403
|
||||
|
|
@ -255,7 +261,8 @@ upstream-admin reset-world 1 --yes-destroy --backup /var/lib/upstream/backups --
|
|||
upstream-admin migrate # apply pending migrations without starting the server
|
||||
```
|
||||
|
||||
All commands take `--json` (machine output) and `--db FILE` (otherwise `$DB_PATH`, otherwise `./data/game.db`).
|
||||
All commands take `--json` (machine output) and `--db FILE` (otherwise `$DB_PATH`, otherwise `./data/game.db`). Piping into `head` is fine: a closed
|
||||
pipe (EPIPE) stops the output quietly, no stack trace, and the exit code is kept.
|
||||
Exit codes: `0` ok, `1` failed, `2` usage error **or a destructive command missing its flag**, `3` not found.
|
||||
|
||||
Safety rules the CLI follows:
|
||||
|
|
@ -263,9 +270,16 @@ Safety rules the CLI follows:
|
|||
* Destructive or test-only commands refuse without a flag: `end-world` and `grant` need `--yes`; `reset-world`
|
||||
needs `--yes-destroy` (without it, it prints what it would delete and exits 2). `ban`, `unban`, `revoke-tokens` are
|
||||
reversible and need none.
|
||||
* `end-world` just sets the world's status to `ended` (and `end_at` to now): signup and join stop and every game command answers
|
||||
`world_ended`, but it writes no ranking snapshot (`GET /worlds/:id/results` stays `available: false`), cancels no pending event and
|
||||
closes no trade offer. The natural end (a backbone winner, then the `worldEnd` event two world days later) does all of that.
|
||||
* `end-world <id> --yes` ends a world exactly like the natural end: it runs the real `worldEnd` event handler (`server/events/worldEnd.js`,
|
||||
payload `{"reason":"admin"}`). So the final ranking snapshot is stored (`GET /worlds/:id/results` becomes `available: true`, `winner`
|
||||
null unless the backbone race had a winner already), open trade offers are closed and their escrow goes back to the POPs, **every
|
||||
other pending event of that world is cancelled** (builds in progress, training, movements on the road simply stop: the world is
|
||||
frozen), status becomes `ended` with `end_at` = now, and every operator gets a `world_ended` notification. Events of that world that
|
||||
were already due are processed first, in order, like the server's catch-up. Without `--yes` it refuses (exit 2) and says how many
|
||||
pending events and open offers it would cancel and close. A world that is already ended is left alone (exit 0). Other worlds are untouched.
|
||||
It works on a running or a stopped server; the CLI is a separate process, so a running server pushes nothing over WebSocket for the
|
||||
notification rows it wrote: open clients learn from their next request (`world_ended` error) or the next `/me`. A world that an
|
||||
older version of this command "ended" has no snapshot; the command says so and cannot repair it (reset the world or leave it).
|
||||
* `reset-world` deletes the world's game rows (everything with a `world_id`, plus tables pointing at them: towns,
|
||||
buildings, events, operators, alliances, messages, ... discovered from the schema, so tables added by later stages
|
||||
are covered) and **keeps accounts and tokens**; players must join the world again. It resets `start_at`, clears
|
||||
|
|
@ -307,8 +321,10 @@ Change the schedule or retention with `systemctl edit upstream-backup.timer` / `
|
|||
|
||||
### Off-box copy
|
||||
|
||||
Snapshots on the same disk die with the container. Pull them from another machine (NAS, workstation, the Proxmox host),
|
||||
for example from cron or a timer there:
|
||||
Snapshots on the same disk die with the container. Two ways to get them off the box; use one. Both only ever copy files that the backup
|
||||
unit already verified, and neither deletes anything on the far side (retention over there is yours).
|
||||
|
||||
**A. Pull from another machine** (NAS, workstation, the Proxmox host), for example from cron or a timer there:
|
||||
|
||||
```sh
|
||||
rsync -a --ignore-existing root@<lxc>:/var/lib/upstream/backups/ /srv/backups/upstream/
|
||||
|
|
@ -319,6 +335,52 @@ the LXC stay on the backup host until you decide otherwise). Better than a root
|
|||
`authorized_keys` to `command="rrsync -ro /var/lib/upstream/backups",restrict ...` (`rrsync` comes with the `rsync`
|
||||
package; not run here). The files are owner-only (`upstream`), so the reading user needs root or a group ACL.
|
||||
|
||||
**B. Push from the box: `upstream-offsite.service` + `.timer`** (`deploy/`). Disabled until you configure it; nothing here is installed by
|
||||
section 3. The script `deploy/upstream-offsite` picks the newest snapshot (by modification time), runs `verify-backup` on it (a snapshot that
|
||||
does not verify is never copied), copies it with `rsync` to a directory (`scp` is not supported: it cannot refuse to overwrite, `OFFSITE_METHOD=scp` is rejected with exit 2), **never overwrites** a file of the same
|
||||
name there, and re-reads the far copy and compares checksums. The timer fires daily at 05:00 (+ up to 10 min), after the backup timer (04:15).
|
||||
It runs as the `upstream` user and fails visibly (`journalctl -u upstream-offsite`).
|
||||
|
||||
Set it up (on the far side first, then the box):
|
||||
|
||||
```sh
|
||||
# far side (backup host): an account that can only write into one directory, no shell, append-only by convention
|
||||
useradd --system --create-home --shell /usr/sbin/nologin upstream-backup # or a NAS user
|
||||
install -d -o upstream-backup -m 0700 /srv/backups/upstream
|
||||
# ~upstream-backup/.ssh/authorized_keys, one line (the key generated below):
|
||||
# restrict,command="rrsync /srv/backups/upstream" ssh-ed25519 AAAA... upstream-offsite
|
||||
|
||||
# the box (as root): a key only for this, owned by the service user (ssh refuses keys readable by others)
|
||||
install -d -m 0750 -o root -g upstream /etc/upstream
|
||||
ssh-keygen -t ed25519 -N '' -C upstream-offsite -f /etc/upstream/offsite_key
|
||||
chown upstream:upstream /etc/upstream/offsite_key /etc/upstream/offsite_key.pub; chmod 0600 /etc/upstream/offsite_key
|
||||
# the far side's host key, checked by eye: compare with `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` over there
|
||||
ssh-keyscan -t ed25519 backup-host.example > /etc/upstream/offsite_known_hosts
|
||||
ssh-keygen -lf /etc/upstream/offsite_known_hosts
|
||||
|
||||
cat >> /etc/upstream/upstream.env <<'EOT'
|
||||
OFFSITE_DEST=upstream-backup@backup-host.example:/
|
||||
OFFSITE_SSH_KEY=/etc/upstream/offsite_key
|
||||
EOT
|
||||
# with rrsync the destination path is relative to its root, hence ":/" (or ":" ). A plain directory also works:
|
||||
# OFFSITE_DEST=/mnt/nas/upstream (a mounted share; then no key or known_hosts is needed)
|
||||
|
||||
install -m 0644 /opt/upstream/deploy/upstream-offsite.service /opt/upstream/deploy/upstream-offsite.timer /etc/systemd/system/
|
||||
systemctl daemon-reload
|
||||
systemctl start upstream-offsite # one run now: journalctl -u upstream-offsite -n 20
|
||||
systemctl enable --now upstream-offsite.timer
|
||||
```
|
||||
|
||||
Settings (all in `/etc/upstream/upstream.env`): `OFFSITE_DEST` (required; without it every run is skipped quietly by the unit's
|
||||
`ExecCondition`, so installing the timer early is harmless), `OFFSITE_METHOD` (only `rsync`; a far side without rsync needs `rrsync`/a different tool, scp was removed because it would overwrite), `OFFSITE_SSH_KEY`, `OFFSITE_KNOWN_HOSTS` (default `/etc/upstream/offsite_known_hosts`),
|
||||
`OFFSITE_SSH_OPTS` (for example `-p 2222`). Host keys are always checked and ssh never prompts (`BatchMode=yes`). To copy right after each
|
||||
backup instead of on its own timer: `systemctl edit upstream-backup` and add `[Unit]` `OnSuccess=upstream-offsite.service`.
|
||||
|
||||
The key on the box can write to the far directory; make that directory the only thing it can reach (the `restrict,command="rrsync ..."`
|
||||
line) and prune old files over there with a job that lives there, so a compromised game box cannot delete the history.
|
||||
**Test it once for real**: check that the file arrived and that `upstream-admin verify-backup` accepts the far copy (a restore from it is section 7). `upstream-offsite` was exercised with a local directory as the destination (rsync, checksum
|
||||
compare, no-overwrite, refusing an unverified snapshot); the ssh transport, `rrsync` and the units under systemd were **not** run.
|
||||
|
||||
### Restore
|
||||
|
||||
The restore is a file copy, and the time model makes it clean: the restored world simply fast-forwards. Every event that
|
||||
|
|
@ -343,12 +405,77 @@ still fits, the server does not check for that.
|
|||
|
||||
## 8. Upgrading
|
||||
|
||||
`/opt/upstream` is a root-owned git checkout of `https://git.vanvikinternet.no/jvanvik/Upstream.git` (plain HTTPS, no credentials in the URL
|
||||
or in `.git/config`; the script refuses an `http(s)://` origin URL that carries a user or token). Updates go through `deploy/update.sh`:
|
||||
|
||||
```sh
|
||||
upstream-admin backup /var/lib/upstream/backups --keep 14 # 1. snapshot first
|
||||
rsync -a --delete --exclude node_modules --exclude .git --exclude data ./ root@<lxc>:/opt/upstream/ # 2. new code (from your workstation)
|
||||
cd /opt/upstream && npm ci --omit=dev && chown -R root:root /opt/upstream # 3. dependencies, ownership
|
||||
systemctl restart upstream # 4. migrations apply at boot
|
||||
journalctl -u upstream -n 30 # 5. "applied migrations: ..." then the listen banner
|
||||
sudo sh /opt/upstream/deploy/update.sh --dry-run # fetch, list the commits and new migrations, change nothing
|
||||
sudo sh /opt/upstream/deploy/update.sh # the real thing
|
||||
sudo sh /opt/upstream/deploy/update.sh --test # also run `npm test` on the new code before the restart
|
||||
```
|
||||
|
||||
In order, stopping at the first failure (once the service is stopped, the script always starts it again):
|
||||
|
||||
0. **Tools**: `git`, `curl`, `npm`, `systemctl` and the admin wrapper must be on the PATH (`runuser`, `tar` and `mktemp` too with `--test`).
|
||||
A missing one is exit 2 before anything is touched (without `curl` the health check could never pass and a good release would be rolled back).
|
||||
1. **Refuses** on a dirty tree (tracked changes or untracked files that are not git-ignored; `node_modules/` and `data/` are ignored), on a
|
||||
checkout that is not on `main` (detached HEAD included), on an `http(s)://` origin whose authority carries `user:password@` or `token@`
|
||||
(an `ssh://git@host/...` or `git@host:path` remote is fine, so is an `@` later in the path), and while another update runs (lock directory
|
||||
`/run/upstream-update.lock`).
|
||||
2. `git fetch origin main`, no prompt. Not a fast-forward of the checkout (history rewritten, local commits): refuses, touches nothing.
|
||||
Nothing new: "already up to date", exit 0, **no stop, no backup and no restart**.
|
||||
3. Only with `--test`: `git archive` of the **new** rev into a temp directory, `npm ci --omit=dev --ignore-scripts` and `npm test` there **as the
|
||||
service user** (`runuser -u upstream`, `HOME` and the npm cache inside the temp directory; never as root, never in `/opt/upstream`). The live
|
||||
service keeps serving meanwhile. Red: exit 1, nothing was stopped or changed. (Fetched test code can still read what the service user can read,
|
||||
for example the database; `--test` is for your own commits.)
|
||||
4. `systemctl stop upstream`. **Why before the merge:** the running process `require()`s server modules lazily, so a process that keeps serving
|
||||
while the tree changes under it can load new files into old code. From here the tree and the process never disagree; the downtime is steps 5-8.
|
||||
5. **Verified snapshot** of the stopped (final) database: `upstream-admin backup /var/lib/upstream/backups --keep 14`, then `verify-backup` on the
|
||||
file it wrote. No verified snapshot, no update: the service is started again, exit 2, nothing changed. The snapshot path is printed at the end.
|
||||
6. `git merge --ff-only`.
|
||||
7. `npm ci --omit=dev --ignore-scripts` **only if** `package.json` / `package-lock.json` changed (or `node_modules` is missing). No package install
|
||||
script runs as root (`ws` needs none; if a future dependency needs one, run it by hand).
|
||||
8. `systemctl start upstream`, then wait for `http://127.0.0.1:<PORT>/healthz` (PORT from `/etc/upstream/upstream.env`, else 8080) for up to
|
||||
30 s (`HEALTH_TIMEOUT` or `--timeout N`).
|
||||
9. **Rollback** on any failure from step 6 on: `systemctl stop` (a crash-looping new process must not run against the old tree), `git reset --hard
|
||||
<old rev>` (the tree was clean, so nothing is lost; the branch stays on `main`), `npm ci` again if the lock file had changed, `systemctl start`,
|
||||
wait for `/healthz` again.
|
||||
10. Prints `old -> new` revs and the commits that went out.
|
||||
|
||||
Exit codes: `0` updated or already current, `1` failed and the old version answers again (or `--test` was red), `2` refused or usage error
|
||||
(nothing changed), `3` failed and the old version does **not** answer either (the output names the snapshot; `journalctl -u upstream -n 50`).
|
||||
|
||||
Things the script cannot undo: **migrations**. A migration that ran at the new version's first start stays applied when the code is rolled
|
||||
back. When the update contains new files in `server/migrations/` the script says so up front (`NEW MIGRATIONS ...`) and, after a rollback, prints
|
||||
the snapshot to restore if the old code misbehaves on the newer schema (section 7: stop, restore, start; players lose what they did since the
|
||||
snapshot). **Migration `005_site_garrison.sql`** is called out specially: it adds `site_stationed` (units garrisoned in backbone landing sites).
|
||||
The previous code knows nothing of that table: it neither lists those units, nor charges their power, nor lets them go home. A code-only rollback
|
||||
is therefore clean only while nobody has garrisoned a site since the new code started; otherwise restore the snapshot. A rollback target is always
|
||||
the previous revision only, one step. An interrupt (Ctrl-C, SIGTERM) after the stop starts the service again (before the merge, on the untouched old
|
||||
tree) or rolls back like any other failure (after it); SIGKILL or a power cut mid-update cannot be caught: then `git log -1`, `git status` and
|
||||
`systemctl status upstream` tell where it stopped (if the service is down: `systemctl start upstream`; if the tree is already new but the service
|
||||
ran the old code, `systemctl restart upstream`). The stop/start drops open WebSockets; clients reconnect on their own.
|
||||
|
||||
Settings: `UPSTREAM_DIR`, `UPSTREAM_UNIT`, `UPSTREAM_ENV_FILE`, `UPSTREAM_ADMIN`, `BACKUP_DIR`, `BACKUP_KEEP`, `UPSTREAM_REMOTE`,
|
||||
`UPSTREAM_SERVICE_USER` (the user `--test` runs as, default `upstream`), `UPSTREAM_BRANCH`, `HEALTH_URL`, `HEALTH_TIMEOUT`, `LOCK_DIR` (`sh update.sh --help` lists them). It needs `git`, `curl`, `npm`, `systemctl` and
|
||||
`upstream-admin` (section 3) on the PATH of root (checked up front).
|
||||
|
||||
**What was run:** `test/deploy-update.test.js` drives the real script with `sh` against a scratch bare origin and checkout and stubs for
|
||||
`systemctl`, `curl`, `npm`, `upstream-admin` and `sleep`: up to date, update order (stop, snapshot, merge, start: the tree is old at the stop and new at the start), `npm ci --ignore-scripts` only when the lock
|
||||
changed, `--test` (isolated copy, via a stub `runuser`), missing tools, dirty tree, credentials in the URL (and the ssh / `@`-in-path URLs that are allowed), detached HEAD, non-fast-forward, concurrent run, `--dry-run`, failing or unverifiable
|
||||
backup, unhealthy new version (rollback, migrations warning, dependency restore), red tests, a rollback that does not recover (exit 3), `PORT` from the
|
||||
env file. `sh -n`, `bash --posix -n` and `zsh -n` pass; `shellcheck` and `dash` were not available on the dev machine. **Not run:** the script on
|
||||
the real box, against real systemd, a real `npm ci` / `npm test`, or a real `/healthz`.
|
||||
|
||||
Updating **without git** (rsync from a workstation, the way section 3 first installed it) still works; do the same by hand:
|
||||
|
||||
```sh
|
||||
systemctl stop upstream # 1. stop FIRST: the old process lazily loads modules from the tree
|
||||
upstream-admin backup /var/lib/upstream/backups --keep 14 # 2. snapshot of the stopped database
|
||||
rsync -a --delete --exclude node_modules --exclude .git --exclude data ./ root@<lxc>:/opt/upstream/ # 3. new code (from your workstation)
|
||||
cd /opt/upstream && npm ci --omit=dev --ignore-scripts && chown -R root:root /opt/upstream # 4. dependencies, ownership
|
||||
systemctl start upstream # 5. migrations apply at boot
|
||||
journalctl -u upstream -n 30 # 6. "applied migrations: ..." then the listen banner
|
||||
curl -i http://127.0.0.1:8080/healthz
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -114,7 +114,8 @@ Movement types: scan, raid, attack, reinforce, settle, takeover, transport (reso
|
|||
target sees an incoming movement with ETA and origin (type is hidden; a successful scan reveals it). Movements
|
||||
can be recalled within the first 90 s.
|
||||
|
||||
Returning units carry loot and come back at the same speed. Units cannot be re-routed while out.
|
||||
Returning units carry loot and come back at the same speed. The one-time Hardware bonus of an incumbent site is delivered in full even
|
||||
onto a full store (stock above the hall size is kept, it only stops growing): a reward that cannot be earned twice never vanishes at the door. Units cannot be re-routed while out.
|
||||
|
||||
## Combat
|
||||
|
||||
|
|
@ -126,8 +127,12 @@ Resolved at arrival, in the event queue, in order. Deterministic given the input
|
|||
spread proportionally across unit types. On a win with exploit kits, one chosen building loses
|
||||
`floor(kits/20)` levels (min 1 if kits ≥ 5).
|
||||
- Raid: both sides lose a fraction only: `losses = ratio^1.5 * 0.5`, so raids are for loot, not for killing.
|
||||
- Loot: winner takes `min(carry, available)` from Fiber/Hardware/Capital evenly, never from Power. Rack hall
|
||||
hides 10% per level up to 50% from raids (the "cold spare" cache).
|
||||
- Loot: winner takes `min(carry, available)` from Fiber/Hardware/Capital evenly, never from Power, **and never more than the
|
||||
raiders' home Rack hall can bank when they are back** (room = hall size minus the stock projected to that moment; a resource with
|
||||
no room is skipped and its share goes to the others). What is not taken stays with the victim and the report lists it as "Left
|
||||
behind" (`lootLeft`). Room already promised to other return legs still on the road to that POP (earlier raids, bounced shipments) is
|
||||
subtracted first, so several raids from one home cannot all count on the same free room; stock that production or a delivery adds on the
|
||||
way is not predicted (BALANCE.md S6). Rack hall hides 10% per level up to 50% from raids (the "cold spare" cache).
|
||||
- Takeover: on a winning full attack with an M&A team present, loyalty drops by `rand(15, 30)` points. At ≤ 0 the
|
||||
POP changes owner, loyalty resets to 25 and grows +1/h. Capital POP (the player's chosen one) cannot be taken
|
||||
over; it can be destroyed to zero loyalty and left. A player's last POP cannot be taken over either.
|
||||
|
|
@ -165,9 +170,12 @@ pump-feeding. Accepting an offer spawns two transport movements. Direct transpor
|
|||
- An offer is "give `giveAmount` of `giveRes` for `wantAmount` of `wantRes`, within `maxDistance` tiles", posted from one POP that has
|
||||
an Internet exchange. Each side must fit ONE transport link (1..1000) and the two amounts differ by at most 1:2:
|
||||
`give <= 2 x want` and `want <= 2 x give` (count-based, the resources are not weighted). The resources must differ.
|
||||
- The offered amount is **escrowed**: it leaves the POP when the offer is posted. Cancelling or expiry (48 h / world speed) credits it back
|
||||
to the POP **capped by the Rack hall** (`trade.refund`, review fix R1: stock already above the cap stays, a refund never lifts it further). If
|
||||
the POP's store filled up meanwhile, the clipped part is destroyed without a notice (BALANCE.md S2, open); otherwise nothing is created or lost.
|
||||
- The offered amount is **escrowed**: it leaves the POP when the offer is posted, but **it keeps its room in the Rack hall**: while the
|
||||
offer is open that resource stops filling at hall size minus the escrow (`rules.storageCapOf`; the HUD shows the lower cap). Cancelling
|
||||
or expiry (48 h / world speed) therefore always fits: nothing is lost, and the escrow is no extra storage (review fix R1 stays true: a
|
||||
refund never lifts stock above the hall size). The only case that can still clip a refund is a Rack hall that was shot down below stock +
|
||||
escrow meanwhile; then the part that does not fit is lost and a `trade_refund_clipped` notification says how much (BALANCE.md S2).
|
||||
A delivery of the traded goods onto a full store still loses the overflow and says so (`cargoLost`, as for every transport); accept refuses up front when that is projected.
|
||||
- **Reach:** a POP sees and takes offers of other operators within `min(offer.maxDistance, 10 x Internet exchange level)` tiles. The poster
|
||||
cannot take their own offer.
|
||||
- **Links:** an open offer holds one transport link of the poster's POP in reserve (open offers + running transports + returning carriers
|
||||
|
|
@ -175,7 +183,8 @@ pump-feeding. Accepting an offer spawns two transport movements. Direct transpor
|
|||
- **Accepting** (one transaction): the acceptor's payment leaves their POP as a transport to the poster's POP (needs a free link and the
|
||||
resources there), the escrow leaves the poster's POP as a transport to the acceptor's POP; both arrive after `distance / 12 tiles/h /
|
||||
world speed`. The offer is `accepted`, then `completed` when both have been delivered. A delivery above the receiver's Rack hall cap
|
||||
loses the overflow and says so (the existing transport rule). If the poster's POP is taken over while the offer is open, the offer
|
||||
loses the overflow and says so (the existing transport rule), and accepting is refused (`no_room_for_goods`) when the acceptor's hall is projected
|
||||
to have no room for the goods at arrival (production and cargo already on the way to that POP counted; a projection, not a promise). If the poster's POP is taken over while the offer is open, the offer
|
||||
ends (`void`) and the escrow stays in the POP.
|
||||
|
||||
## Incumbent (NPC)
|
||||
|
|
@ -197,16 +206,33 @@ stays with the site. Landing sites cannot be settled, only taken.
|
|||
80% of the map radius, at least 6 tiles apart, never in the free centre. They exist from the start (spawning and settling refuse them),
|
||||
the tile reads `backbone` from day 100 / speed (`rules.tileAt(seed, radius, x, y, ageDays)`; without the age argument terrain is unchanged).
|
||||
- **A site is not a POP** (DECISIONS E1): it has a holder alliance, a Backbone node level, a stockpile of Fiber/Hardware/Capital and at most
|
||||
one level in progress. No units can stand there, so a site is defended by a static value only:
|
||||
`defence = incumbentDefence(seed, x, y, age) x 12 x (1 + 0.03 x node level)`. At day 100 that is about 40 000 with no node, 160 000 at
|
||||
level 100 (a Script crew attacks with 40).
|
||||
- **Taking:** `scan` and `attack` only (no raid: the stockpile would be lootable; no takeover, no reinforce, no settle). The attacker must be in
|
||||
one level in progress. Its defence is a static value plus a **garrison** (below):
|
||||
`static = incumbentDefence(seed, x, y, age) x M x (1 + 0.03 x node level)` with M = 12 while nobody holds the site (the opening scramble)
|
||||
and M = 2 once an alliance does (`ENDGAME.defenceMult`, `ENDGAME.heldDefenceMult`; DECISIONS E6). At day 100 an unheld site is about
|
||||
40 000, a held one about 7 000 at node level 0 and 28 000 at level 100 (a Script crew attacks with 40).
|
||||
- **Garrison** (E6): members of the holding alliance (nobody else) can `reinforce` a site they hold: the units move in, count in its defence at
|
||||
their owner's research, and keep drawing power from THEIR OWN POP (a site has no power budget; offline POP = offline units, decommission
|
||||
takes them out of the garrison too). They leave by `POST /backbone/:id/withdraw` (owner only, any time), automatically when their owner
|
||||
leaves or is kicked from the alliance, when the alliance disbands, or when the POP they belong to is taken over (a return movement each time),
|
||||
and they die when the site is taken. A static + garrison defence is fought like a POP: a lost attack kills (attack/defence)^1.5 of the
|
||||
garrison, so the next wave in arrival order faces less; the static part loses nothing, so the last wave alone must beat static + what
|
||||
is left. That is what makes a held site contestable by several members (a single POP's army tops out around 60 000 attack), and why
|
||||
`heldDefenceMult` is small: static defence must stay below what one POP can send or a built-up site would be out of reach again.
|
||||
- **Capture shield:** a site that changed hands cannot be attacked for `ENDGAME.captureShieldHours` (72 world hours = 3 world days, / speed):
|
||||
attacks are refused when sent (`site_shielded`) and turned back if the site was taken while they were on the road. Scans and garrisoning
|
||||
are allowed. Without it a light static defence made sites flip every few hours in bot runs; 24 h still flipped them every ~1.7 real days
|
||||
at 3x (BALANCE.md section 5).
|
||||
- **Limit of the static rule:** `incumbentDefence` grows 4 % of its base per world day, so a held level-100 site's static part is ~51 000
|
||||
at world age 240 and ~68 000 at age 330, past what one POP can send (~60 000). The "static below one army" rule has an expiry date
|
||||
(real day ~85 in a 3x world); then only a garrison already worn down by waves can be finished, and a holder with no garrison is the only one beatable.
|
||||
- **Taking:** `scan` and `attack` only (no raid: the stockpile would be lootable; no takeover, no settle; `reinforce` only for the holder, above). The attacker must be in
|
||||
an alliance, and may not be in the holder's alliance or in a NAP / confederation with it (checked when sent and again on arrival, units come
|
||||
home otherwise). A full attack with attack > defence wins: the attacker's alliance holds the site. No loot, the site loses nothing, the
|
||||
survivors drive home. Level, stockpile and a running build stay with the site. A holder that disbands leaves the site to the incumbent
|
||||
(level kept).
|
||||
- **Feeding the node:** members of the holder alliance send resources by transport (`POST /backbone/:id/ship`, same links, 1000 per link, 12
|
||||
tiles/h). On arrival they join the stockpile if the sender's alliance still holds the site, otherwise they ride home. A ledger records
|
||||
- **Feeding the node:** members of the holder alliance send resources by transport (`POST /backbone/:id/ship`, same links, 1000 per link x the
|
||||
world speed, 12 tiles/h). On arrival they join the stockpile if the sender's alliance still holds the site, otherwise they ride home (`backbone_ship_bounced`). The sender's Rack hall can have refilled while the shipment was away: what then does
|
||||
not fit is destroyed and reported with exact amounts (`movement_returned.cargoLost`); no room is reserved for it (BALANCE.md S6). A ledger records
|
||||
who sent what.
|
||||
- **Building:** level L (1..100) costs `4000 x 1.045^(L-1)` of each resource (level 100: 312 301; about 7.2 million of each in total) and
|
||||
takes `2 h x 1.025^(L-1) / world speed` (level 100: 23 h; about 36 days of world time in total, one level at a time). The cost is paid from
|
||||
|
|
|
|||
88
docs/NEXT.md
88
docs/NEXT.md
|
|
@ -8,33 +8,35 @@ WebSocket push); stage 7 is partly done (bot harness + first balance pass, admin
|
|||
playtested by humans, and has never run on the real target (Debian LXC + systemd + nginx Proxy Manager).**
|
||||
|
||||
Runnable and checked just now:
|
||||
- `npm test`: 208 tests pass in about 7 s (rules as pure functions, commands/events/scheduler with a fake clock, REST over HTTP with every
|
||||
- `npm test`: 264 tests pass in about 8 s (this tree) (rules as pure functions, commands/events/scheduler with a fake clock, REST over HTTP with every
|
||||
response checked against its schema, push with a real `ws` client, client logic, bot harness, admin CLI). `npm run openapi` leaves
|
||||
`docs/openapi.json` unchanged (it is in sync with the route table: 68 paths).
|
||||
- `node tools/bot.js --players 50 --days 14 --speed 1`: about 3 s, `INVARIANTS OK`. `node tools/admin.js help` works.
|
||||
- The deploy path from DEPLOY.md in a scratch directory, without systemd: first boot (migrations, world), `/healthz`, signup, a build,
|
||||
`admin.js` status/worlds/users/inspect/events/replay/backup/verify-backup/ban/grant, SIGTERM + restart (state kept), SIGKILL + restart
|
||||
after a build fell due (caught up in order), restore of a snapshot into a fresh `DB_PATH`.
|
||||
- `npm run e2e` (`e2e/run.js`, Playwright): 61 checks pass (re-run after B4, 54 s).
|
||||
- `npm run e2e` (`e2e/run.js` + `e2e/flows.js`, Playwright): 163 checks pass in about 137 s (smoke, units, movements + reports, reconnect, alliance + messages, trade, end game, nb, PWA); `E2E_SLOW=1` adds the 60 s polling-fallback suite. See "E2E" below.
|
||||
|
||||
Never run: real devices, Safari/iOS, a Proxmox LXC, a unit under systemd, the backup timer firing, nginx Proxy Manager (WebSocket upgrade,
|
||||
idle timeouts, real client IPs), Let's Encrypt, a restore on the real box, load with many real sockets, any human player. Node 22.13 (the
|
||||
stated minimum) was not run, only 24.21.
|
||||
|
||||
Known gaps, consolidated (the sections below have the detail and the reasoning):
|
||||
- **Balance:** the first hour of a player who plays it all is limited by the 750 starting stock (about 12 builds), not by build time; a bigger stock was measured and not adopted (B4). nothing is tuned beyond B1, B2 and the B4 early-level build discount (BALANCE.md). Open: a 3x world's end game is as long as a 1x world's; after the opening days
|
||||
nobody can contest a built-up landing site (no garrisons, E1); raid loot is split evenly and destroyed on overflow (S4); trade escrow
|
||||
refunds are clipped at the Rack hall cap without a notice (S2); the capital runs out of things to build long before the backbone opens;
|
||||
- **Balance:** the first hour of a player who plays it all is limited by the 750 starting stock (about 12 builds), not by build time; a bigger stock was measured and not adopted (B4). nothing is tuned beyond B1, B2 and the B4 early-level build discount (BALANCE.md). The end game follows world speed since B7 (3x: 29 to 35 days after the sites open, was 77 to 98) and a held landing site can be contested since E6 (garrisons, a
|
||||
light static defence for held sites, a 72 h capture shield); both are first guesses measured with bots on two seeds (BALANCE.md B7 and E6), no human has played them, the static
|
||||
defence outgrows what one POP can send around world age 280, and the bots do not react to `backbone_incoming`. Open: (S2 and S4, trade refunds clipped and loot/incumbent bonus destroyed on overflow, are fixed by B6: escrow keeps its room in the Rack hall, loot is limited to what home can bank; transport deliveries onto a full store, and a bounced backbone shipment that finds the hall refilled, still lose the overflow, reported with exact `cargoLost`; several raids from one home no longer share the same free room, S6; trade accept is refused with `no_room_for_goods` when the projected hall has no room); the capital runs out of things to build long before the backbone opens;
|
||||
the bots are not humans.
|
||||
- **Game rules not built:** cancelling training, sitters, night protection, a command to choose a new capital, power draw for units in
|
||||
transit, alliance rename/description, trade order book / price history / counter-offers, multi-link trade deals.
|
||||
- **Server:** no `backbone_open` push (sites are created lazily, E2); no `incoming` for confederates and no `town` hint for reinforcing
|
||||
owners; token revocation reaches an open socket only at the next 30 s ping; tokens never expire and there is no change-password route; no APNs/FCM
|
||||
sender; `reports.id` can be reused after a full cleanup (S3, low); no recovery sweeper if an `arrive`/`return` handler ever throws (R1);
|
||||
HTTP connections per IP are not capped; admin `end-world` is a flag flip without ranking snapshot (DEPLOY.md section 6).
|
||||
HTTP connections per IP are not capped.
|
||||
- **Client:** no service worker (no offline mode), no light theme, no unit icons or battle simulator, no sound/system notifications; a few
|
||||
one-tap destructive actions without confirmation; unread-badge state is partly in localStorage; ended-world locking is a DOM sweep.
|
||||
- **Docs:** `docs/workflows/` (planned stage workflows, CLAUDE.md layout) is empty: no stage workflow was ever written there.
|
||||
Found by the e2e and NOT fixed: after switching language live, screens that were already drawn keep ~15 English `aria-label`s (map zoom/label, refresh buttons, tab groups; visible
|
||||
text is fine, a reload fixes it); an alliance message raises the More badge by 2 (the alerts feed and the unread message are both summed; by design of the badge, perhaps not intended).
|
||||
- **Docs:** `docs/workflows/` has a short note per stage (written after the fact from NEXT and the git history; NEXT stays authoritative).
|
||||
- **Not run in a browser:** takeover/capture flows, the confederation `alliedIncoming` view, real devices (see the client sections).
|
||||
|
||||
## Done
|
||||
|
|
@ -117,8 +119,8 @@ a phone profile (markup in a message stays text, counter/over-limit, 429 countdo
|
|||
move sheet, name-taken error, nb). Not run: real devices, Safari, Playwright suite, a long-list scroll test (>100 ranks), accepting an
|
||||
invite when the alliance is full, alliances at the size cap.
|
||||
Gaps: alliance rename/description and note editing have no UI (server has edit-note); no operator profile page; blocking needs an existing
|
||||
conversation or message (the API takes an operator id and there is no name lookup); no live refresh (push is not wired, screens refetch
|
||||
on open and on manual refresh); the alliance screen does not auto-refresh countdowns' targets after they pass; `App.state.operator.alliance`
|
||||
conversation or message (the API takes an operator id and there is no name lookup); no live refresh (push is not wired for the alliance screen, which refetches
|
||||
on open and on manual refresh; Messages follows the `message` push since the e2e pass); the alliance screen does not auto-refresh countdowns' targets after they pass; `App.state.operator.alliance`
|
||||
is refreshed from `/me` after alliance changes but is stale if you are kicked while away until the screen is opened.
|
||||
|
||||
## Client: military, expansion, WebSocket
|
||||
|
|
@ -197,7 +199,7 @@ Built (More group; strings in `strings/{trade,world,alerts}.js`, en + nb):
|
|||
minute. Confederate Carol gets no push for `alliedIncoming` (known server gap): it shows when the Moves screen is opened or the poll runs, and never in her badge.
|
||||
Found and fixed in the client: `report` pushes now also refetch movements (the incoming banner used to linger up to a few seconds after the arrival).
|
||||
Not done / not claimed:
|
||||
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the full Playwright suite (only the smoke e2e exists), long lists (offers > 25 per
|
||||
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the combat/takeover/diplomacy flows in a browser, long lists (offers > 25 per
|
||||
filter paged only up to what the sweep seeded).
|
||||
- Ended-world locking is a DOM sweep, not per-button wiring: a new primary/danger button that is NOT a game command must carry `data-keep`. Messages, ranking and
|
||||
settings screens are exempt by selector. Open send/trade sheets that were opened before the end stay usable until the next DOM change or a refused command.
|
||||
|
|
@ -209,6 +211,41 @@ Not done / not claimed:
|
|||
- Server bug found and fixed (tiny): `POST /reports/:id/share` threw a 500 when no `reportCleanup` event was pending (`ensureCleanup` needs `ctx.enqueue`);
|
||||
`reportShare` now wraps its ctx with `ctxOf`, regression test `test/report-share-cleanup.test.js` (failed before).
|
||||
|
||||
## E2E (`e2e/`, run with `npm run e2e`)
|
||||
`e2e/run.js` (smoke suites: desktop, phone, layout, push) and `e2e/flows.js` (feature flows) boot the real server in-process (temp SQLite, real clock, `WORLD_SPEED` 4000 or 1) and drive
|
||||
headless Chromium through `playwright-core`; `e2e/lib.js` holds the shared plumbing (`bootServer`, `newPage` with console/HTTP error capture, `hurryMovement` / `hurryEvents`).
|
||||
Default run: 163 checks, about 137 s, no console error or failed request tolerated; every page gets a default action timeout of 8 s (`lib.js`), the smoke suites included. `node e2e/run.js <suite...>` runs named suites; `slow` only by name or `E2E_SLOW=1`.
|
||||
- **units**: train 2 script crews through the sheet (cost preview scales, queue row with count and countdown, count pill), the batch completes (event moved up), units appear in the home list and
|
||||
the database, an unaffordable train is explained and disabled, hosted reinforcements are listed and "send home" removes them and starts the return.
|
||||
- **movements**: scan and raid from the Moves screen send dialog (coordinates, type, unit picker, preview, send), both in the outgoing list with countdown and recall button; the defender's page gets
|
||||
the banner and the Moves badge by push (type and units hidden), both arrive, report badges on both sides, the Reports list (unread, then read on open, server read flag), the raid and scan report
|
||||
sheets, the defender-side report.
|
||||
- **reconnect**: the page's socket is closed and new ones refused; a raid launched in the gap is not shown; on reconnect a NEW socket opens and the missed raid appears (refetch on ready); a second raid
|
||||
then shows by push within 6 s with the socket open and no reload.
|
||||
- **alliance**: found (button disabled until valid), invite by name, accept on the other page, a broadcast written in Messages > Alliance, the unread badge on the other page by push, the feed row
|
||||
(unread, sender), mark read, a second broadcast appearing live.
|
||||
- **trade**: post (escrow), the offer on the taker's Offers tab, Take with the POP picker, both legs in flight (moved up past the 10 minute minimum latency), goods swapped, `completed` on both
|
||||
"mine" tabs, an alert.
|
||||
- **endgame** (own world backdated to day 100.5): banner "appear in" + how-it-works before, "open" + 7 site cards after, the held site is `mine` with Manage, others show scan/attack, a non-member
|
||||
sees no Manage; the Manage sheet, ship 300 fiber (toast, transport row marked as a site shipment, stock drops), it lands and the stockpile and ledger show it.
|
||||
- **nb**: live switch after every screen was drawn in English (visible text), reload and fresh render (text, aria-label, placeholder, title), nav labels, dynamic keys (`err.*` in the train sheet,
|
||||
`send.reason.*`), raw-key detector, English-leftover detector, and a check that no multi-word nb string is a verbatim copy of its English text. The same detector sweeps pages that hold real
|
||||
data at the end of the movements, alliance, trade and endgame flows (reports and sheets, alliance tabs, messages tabs, trade tabs, site manage sheet and dialogs).
|
||||
- **pwa**: manifest link, `application/manifest+json`, display standalone, start_url inside scope and serving the shell, theme colours equal to the meta tag, every icon 200 + image type + PNG
|
||||
dimensions equal to the declared sizes, a maskable icon, apple-touch-icon, no service worker.
|
||||
- **slow**: `WebSocket` removed from the page; the raid is not shown within 8 s, then shows by polling (59 s in the run, worst case about 60 s), no reload, socket never open.
|
||||
How the checks were shown to be able to fail (each mutation applied, the named suite run, reverted): units queue never drawn (units), home list never drawn (units), reports never marked read
|
||||
(movements), manifest served as octet-stream (pwa), no refetch on socket ready (reconnect), no reconnect scheduling (reconnect), alliance accept sends decline (alliance), trade accept with a wrong POP
|
||||
(trade), open banner never drawn and ship endpoint misspelt (endgame), a copy-pasted English string in the nb table (nb), polling interval removed (slow); the nb detector additionally runs a planted raw
|
||||
key, a planted English string and a deleted nb string on the live page, and a calibration run in English (it must see >= 8 English strings on the POP screen). Message push: the push check failed
|
||||
on the tree before the fix below.
|
||||
Real app bugs found: (1) `{type:'message'}` push was received and ignored (the unread badge and the open Messages list only moved on the 60 s poll or a tab switch): `messages.js` now refetches the unread
|
||||
count and the visible inbox / alliance feed / open thread on that hint (regression: alliance flow, fails without it); (2) the "New" button of the Messages header stayed English after a live language
|
||||
switch (built once in `render()`): now set in `onShow` (regression: nb flow, "switched live"). Not fixed, see the gaps above: stale aria-labels after a live switch; More badge double counts a message.
|
||||
Not covered: takeover/capture, diplomacy moves, confederation `alliedIncoming`, rankings content, reports share to the alliance folder, settings devices list, Firefox/WebKit, real devices.
|
||||
Caveats: flights and trade legs are moved up with `UPDATE movements/events` + `scheduler.arm()`, not by waiting; the end-game world is made 100.5 days old by moving `worlds.start_at` and
|
||||
the 7 site rows come from `ensureSites` (what the first scan or attack does) with the holder written by SQL; the 60 s slow suite is not in the default run.
|
||||
|
||||
## Stage 6 (server half): WebSocket push
|
||||
Built: `/ws` on the game's HTTP server (`server/push.js` transport, `server/pushHooks.js` routing), contract in `docs/PROTOCOL.md`.
|
||||
Auth as first message (`ready` / close 4401), Origin check (`net.originAllowed`), per-IP cap `MAX_CONN_PER_IP` (HTTP 429), 1 KB frames,
|
||||
|
|
@ -250,13 +287,15 @@ Not done / not claimed:
|
|||
- **Nothing here is balanced.** Defence multiplier 12 (+3% per level), node cost 4000 x 1.045^(L-1) (about 7.2 M of each resource in total),
|
||||
node time 2 h x 1.025^(L-1) (about 36 world days), 48 h offer ttl, 10 tiles of reach per exchange level, 500-per-side offers: first guesses,
|
||||
no bot run when written (now there is one: BALANCE.md section 5 says an 18-member alliance needs 55 to 78 days after the sites open with 1000 per link, and does not finish in 175 days with 500).
|
||||
- **No garrison at landing sites** (E1): defence is static, holders cannot station units. If the first world shows the race is decided by who
|
||||
hits first, the next step is a small `site_units` table with reinforce-to-site and defenders in `landing.js`.
|
||||
- **Garrisons at landing sites** (E6, migration 005 `site_stationed`, `server/military/garrison.js`, `POST /backbone/:id/withdraw`): built and tested (`test/endgame-garrison.test.js`,
|
||||
`test/client-garrison.test.js`), bots garrison and assault (`tools/bot/endgame.js`, `--no-contest` turns it off). Not built / not claimed: no `captureLevelLoss`
|
||||
(a taken site keeps its node level), no sitter, `tools/admin.js inspect-town` does not list garrison units, the site sheet was not opened in a real browser, a holder cannot send
|
||||
a member's units away, confederates cannot garrison (members only).
|
||||
- No `backbone_open` push at the moment the sites appear unless something touches a site first (E2); clients see the phase by polling status.
|
||||
- Trade: no multi-link deals (each side <= 500), no price history or order book, no counter-offers, no notification when a new offer appears
|
||||
in reach, offers are not hidden from enemies, the escrow of a taken-over POP goes to the conqueror.
|
||||
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); `tools/admin.js end-world` only flips the status (no snapshot, no event cancellation) and `reset-world`
|
||||
wipes a world's rows; neither runs the real `worldEnd` event (see DEPLOY.md section 6); several winners are impossible by design.
|
||||
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); `tools/admin.js end-world` now runs the real `worldEnd` handler (snapshot, escrow back, events cancelled; ops part below); `reset-world`
|
||||
wipes a world's rows without it (DEPLOY.md section 6); several winners are impossible by design.
|
||||
- The ranking snapshot is the same numbers as `/rankings`, computed once; `/rankings/*` after the end still compute live from the frozen state.
|
||||
- Client for all of this: see "Client: trade, end game, alerts" above.
|
||||
|
||||
|
|
@ -273,18 +312,25 @@ Server fix found by the harness: bounced shipments reported no overflow (`events
|
|||
Tests: `test/bot-run.test.js` (12 players x 6 days twice, identical stats, invariants, the checks catch tampering, a fast world reaches the end game),
|
||||
`test/bot-server-fixes.test.js`.
|
||||
Not done / not claimed: **the game is not balanced**; the bots are not humans (no reinforcement, recall, messages, sitters; fixed sittings). Open
|
||||
items from the pass: a 3x world's end game is as long as a 1x world's (shipping is per sitting; `capacityPerLink x speed` needs the client to stop
|
||||
reading the constant); trade escrow refunds are clipped at the Rack hall cap silently; raid loot is split evenly over resources and destroyed on overflow;
|
||||
the capital runs out of things to build ~50 days before the backbone opens at 4 sittings a day; a built-up landing site is out of reach of any
|
||||
single-POP army (no garrisons, E1), so there is no fight for a site after the first days.
|
||||
items from the pass: (a 3x world's end game being as long as a 1x world's is fixed by B7, `rules.transportCapacity`); (trade escrow refund clipping and loot destruction on overflow were fixed afterwards by B6, BALANCE.md section 9);
|
||||
the capital runs out of things to build ~50 days before the backbone opens at 4 sittings a day; (a built-up landing site being out of reach of any single-POP army is
|
||||
answered by E6: garrisons and waves, BALANCE.md section 5).
|
||||
|
||||
## Stage 7 (ops part): admin CLI, deploy files
|
||||
Built: `tools/admin.js` (status, migrate, worlds, create-world, end-world, users, operators, ban/unban/revoke-tokens, inspect-operator/-town, events,
|
||||
replay-events [--simulate], backup/verify-backup (VACUUM INTO, verified, pruned), reset-world, grant), `deploy/` (service, backup service + timer,
|
||||
`upstream-admin` wrapper), `docs/DEPLOY.md`. Tests: `test/admin-cli.test.js`. Run by hand on 2026-10-11 in a scratch directory: see "Status at a glance".
|
||||
Not done / not claimed: nothing of it has run under systemd or on Debian 13 (DEPLOY.md lists what was and was not run); no load test with real sockets;
|
||||
world lifecycle through the CLI is partial (above); no scheduled "create next world".
|
||||
Added later: `end-world` runs the real `worldEnd` event handler (final ranking snapshot so `/worlds/:id/results` is available, trade escrow back,
|
||||
the world's other pending events cancelled, `world_ended` notifications; overdue events of that world are processed first; refuses without `--yes`),
|
||||
quiet on EPIPE (`admin.js ... | head`); `deploy/update.sh` (git fast-forward update on the box: tools checked up front, service STOPPED before the tree changes (review R2), verified snapshot of the stopped db, `npm ci --ignore-scripts` only when the lock
|
||||
changed, optional `--test` on a `git archive` copy as the service user, health check, rollback to the old rev, `--dry-run`); `deploy/upstream-offsite` + `.service`/`.timer` (off-box copy of the newest
|
||||
verified snapshot to `OFFSITE_DEST`, skipped unless configured). Tests: `test/admin-endworld.test.js`, `test/deploy-update.test.js` (stubbed systemctl/curl/npm),
|
||||
`test/deploy-offsite.test.js` (local directory as destination; needs rsync; scp was removed in R2).
|
||||
Not done / not claimed: nothing of it has run under systemd or on Debian 13 (DEPLOY.md lists what was and was not run); `update.sh` and the off-site
|
||||
copy were run only against stubs / a local directory (no real ssh, rrsync, systemd, runuser, npm ci or /healthz; shellcheck and dash were not available); a migration cannot be rolled back by
|
||||
`update.sh` (it prints the snapshot to restore); `end-world` cannot repair a world ended by the old flag-flip version (no snapshot); the notification
|
||||
rows the CLI writes are not pushed by a running server; no load test with real sockets; no scheduled "create next world".
|
||||
|
||||
## Not done
|
||||
- Stage 7 remainder: balance passes beyond B1, B2 and B4 with the open items above, a real world lifecycle (start, natural end, reset) driven from the CLI,
|
||||
load test over HTTP/WebSocket, the full e2e suite and a human playtest. Everything else in CLAUDE.md "Working in stages" is built.
|
||||
load test over HTTP/WebSocket, e2e for takeover/capture/diplomacy/confederation views, and a human playtest. Everything else in CLAUDE.md "Working in stages" is built.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ One socket per device is enough; a user may have several (phone + desktop), each
|
|||
| `{"type":"pong","serverTime":n}` | answer to `ping` | same |
|
||||
| `{"type":"town","townId":n}` | POP `n` (yours) changed: build/train/research done, resources spent, units arrived, returned or died, attacked, ownership changed, a command from another device | refetch `GET /towns/:id` (if on screen) |
|
||||
| `{"type":"incoming","townId":n,"arriveAt":n}` | a movement from another operator was launched at your POP `townId`, arrives at `arriveAt`. Type and origin hidden on purpose (could be a scan, a raid, reinforcements or a transport). | show a warning with a countdown, refetch `GET /movements` for the details the API allows |
|
||||
| `{"type":"notification","id":n,"kind":"..."}` | a row was added to your notifications. `kind` is `notifications.type`: `build_done`, `train_done`, `research_done`, `incoming`, `report`, `message`, `alliance_message`, `alliance_invite`, `town_lost`, `town_gained`, `transport_arrived`, `movement_returned`, `units_offline`, ... (the list grows, treat unknown kinds as generic) | bump the unread badge, `GET /notifications` |
|
||||
| `{"type":"notification","id":n,"kind":"..."}` | a row was added to your notifications. `kind` is `notifications.type`: `build_done`, `train_done`, `research_done`, `incoming`, `report`, `message`, `alliance_message`, `alliance_invite`, `town_lost`, `town_gained`, `transport_arrived`, `movement_returned`, `units_offline`, `trade_refund_clipped`, `backbone_incoming`, `garrison_arrived`, `garrison_released`, ... (the complete list with payloads is "Notification types" at the end of docs/API.md; the list grows, treat unknown kinds as generic) | bump the unread badge, `GET /notifications` |
|
||||
| `{"type":"report","id":n}` | a battle or scan report with id `n` is ready for you | `GET /reports/:id` or refresh the list |
|
||||
| `{"type":"message","id":n}` | a direct or alliance message with id `n` arrived for you (not sent to its sender) | refresh the inbox |
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ S: {"type":"pong","serverTime":1767236401000}
|
|||
|
||||
| Source | Hint |
|
||||
| ------ | ---- |
|
||||
| any `notifications` row (`scheduler.notify`, after the transaction committed) | `notification`; plus `incoming` / `report` / `message` for kinds `incoming` / `report` / `message`, `alliance_message`; plus `town` for kinds that change a POP whose owner may differ from the event's POP (`town_lost`, `town_gained`, `transport_arrived`, `transport_delivered`, `movement_returned`, `reinforcements_sent_home`) |
|
||||
| any `notifications` row (`scheduler.notify`, after the transaction committed) | `notification`; plus `incoming` / `report` / `message` for kinds `incoming` / `report` / `message`, `alliance_message`; plus `town` for kinds that change a POP whose owner may differ from the event's POP (`town_lost`, `town_gained`, `transport_arrived`, `transport_delivered`, `movement_returned`, `reinforcements_sent_home`, `garrison_arrived`, `garrison_released`) |
|
||||
| a finished event (`scheduler.onEvent`) | `town` to the owner of `events.town_id` (build, train, research, power check) and of both ends of the movement for `arrive` / `return` |
|
||||
| a committed command (`commands.hooks.onCommand`) | `town` to the owner of the POP named in `townId`, `fromTownId`, `hostTownId`, `ownerTownId` or the new POP of `joinWorld`; for `recallMovement` both ends of the movement |
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
"info": {
|
||||
"title": "UPSTREAM API",
|
||||
"version": "1.0.0",
|
||||
"description": "Generated by tools/gen-openapi.js from server/routes. Every response carries serverTime; errors use the { error: { code, message, details } } envelope. Codes: bad_request, validation_failed, unauthorized, invalid_credentials, forbidden, not_found, method_not_allowed, conflict, request_in_progress, idempotency_key_reuse, payload_too_large, rate_limited, internal_error, signup_closed, username_taken, world_full, unknown_building, not_buildable, max_level, requirements_not_met, already_queued, queue_full, not_enough_resources, peering_office_required, already_in_alliance, not_in_alliance, alliance_name_taken, alliance_tag_taken, alliance_full, invite_expired, leader_must_transfer, notes_full, diplomacy_invalid, diplomacy_pending, proposal_exists, proposal_expired, unknown_unit, not_researchable, not_enough_units, units_offline, invalid_target, target_protected, protection_active, out_of_range, footprint_too_low, cannot_takeover, recall_expired, capacity_exceeded, no_transport_link, trade_ratio, offer_closed, own_offer, trade_out_of_range, world_ended, backbone_closed"
|
||||
"description": "Generated by tools/gen-openapi.js from server/routes. Every response carries serverTime; errors use the { error: { code, message, details } } envelope. Codes: bad_request, validation_failed, unauthorized, invalid_credentials, forbidden, not_found, method_not_allowed, conflict, request_in_progress, idempotency_key_reuse, payload_too_large, rate_limited, internal_error, signup_closed, username_taken, world_full, unknown_building, not_buildable, max_level, requirements_not_met, already_queued, queue_full, not_enough_resources, peering_office_required, already_in_alliance, not_in_alliance, alliance_name_taken, alliance_tag_taken, alliance_full, invite_expired, leader_must_transfer, notes_full, diplomacy_invalid, diplomacy_pending, proposal_exists, proposal_expired, unknown_unit, not_researchable, not_enough_units, units_offline, invalid_target, target_protected, protection_active, out_of_range, footprint_too_low, cannot_takeover, recall_expired, capacity_exceeded, no_transport_link, trade_ratio, offer_closed, own_offer, trade_out_of_range, no_room_for_goods, world_ended, backbone_closed"
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
|
|
@ -2885,7 +2885,7 @@
|
|||
},
|
||||
"/backbone/{id}/ship": {
|
||||
"post": {
|
||||
"summary": "Send resources from one of your POPs to a landing site your alliance holds (a transport: Internet exchange links, 500 each)",
|
||||
"summary": "Send resources from one of your POPs to a landing site your alliance holds (a transport: Internet exchange links, 1000 each at world speed 1, times the world speed)",
|
||||
"tags": [
|
||||
"world"
|
||||
],
|
||||
|
|
@ -3004,6 +3004,116 @@
|
|||
}
|
||||
}
|
||||
},
|
||||
"/backbone/{id}/withdraw": {
|
||||
"post": {
|
||||
"summary": "Call units of one of your POPs home from a landing site's garrison (default: all of them). Only their owner can; works whoever holds the site now. Station units with POST /movements type reinforce at the site's x,y (members of the holding alliance only)",
|
||||
"tags": [
|
||||
"world"
|
||||
],
|
||||
"operationId": "postBackboneIdWithdraw",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"fromTownId"
|
||||
],
|
||||
"properties": {
|
||||
"fromTownId": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"units": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"description": "defaults to the whole group"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"bearer": []
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/GarrisonWithdrawn"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Error codes: unauthorized",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Error codes: not_found, unknown_unit",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error codes: conflict, not_enough_units, world_ended",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Error codes: idempotency_key_reuse, validation_failed",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error codes: internal_error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/diplomacy/proposals/{proposalId}": {
|
||||
"delete": {
|
||||
"summary": "Withdraw a proposal your alliance made (needs diplomacy)",
|
||||
|
|
@ -7109,7 +7219,7 @@
|
|||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error codes: capacity_exceeded, no_transport_link, not_enough_resources, offer_closed, own_offer, trade_out_of_range, world_ended",
|
||||
"description": "Error codes: capacity_exceeded, no_room_for_goods, no_transport_link, not_enough_resources, offer_closed, own_offer, trade_out_of_range, world_ended",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
|
|
@ -7850,6 +7960,26 @@
|
|||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
"escrow": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"fiber": {
|
||||
"type": "number"
|
||||
},
|
||||
"hardware": {
|
||||
"type": "number"
|
||||
},
|
||||
"capital": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"fiber",
|
||||
"hardware",
|
||||
"capital"
|
||||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
"military": {
|
||||
"$ref": "#/components/schemas/TownMilitary"
|
||||
}
|
||||
|
|
@ -7870,7 +8000,8 @@
|
|||
"buildings",
|
||||
"queue",
|
||||
"queueSlots",
|
||||
"bonus"
|
||||
"bonus",
|
||||
"escrow"
|
||||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
|
|
@ -9717,6 +9848,35 @@
|
|||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"garrisoned": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"siteId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"x": {
|
||||
"type": "integer"
|
||||
},
|
||||
"y": {
|
||||
"type": "integer"
|
||||
},
|
||||
"units": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"description": "unit id -> count"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"siteId",
|
||||
"x",
|
||||
"y",
|
||||
"units"
|
||||
],
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
|
|
@ -9724,7 +9884,8 @@
|
|||
"online",
|
||||
"offlineSince",
|
||||
"stationedHere",
|
||||
"stationedAway"
|
||||
"stationedAway",
|
||||
"garrisoned"
|
||||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
|
|
@ -10181,6 +10342,10 @@
|
|||
"type": "integer",
|
||||
"nullable": true
|
||||
},
|
||||
"shieldUntil": {
|
||||
"type": "integer",
|
||||
"nullable": true
|
||||
},
|
||||
"level": {
|
||||
"type": "integer"
|
||||
},
|
||||
|
|
@ -10234,6 +10399,7 @@
|
|||
"holder",
|
||||
"takenBy",
|
||||
"takenAt",
|
||||
"shieldUntil",
|
||||
"level",
|
||||
"maxLevel",
|
||||
"progress",
|
||||
|
|
@ -10370,13 +10536,17 @@
|
|||
},
|
||||
"canAttack": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"canReinforce": {
|
||||
"type": "boolean"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"holder",
|
||||
"canBuild",
|
||||
"canShip",
|
||||
"canAttack"
|
||||
"canAttack",
|
||||
"canReinforce"
|
||||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
|
|
@ -10410,6 +10580,69 @@
|
|||
],
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"defence": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"static": {
|
||||
"type": "number"
|
||||
},
|
||||
"garrison": {
|
||||
"type": "number"
|
||||
},
|
||||
"total": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"static",
|
||||
"garrison",
|
||||
"total"
|
||||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
"garrison": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"ownerTownId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"townName": {
|
||||
"type": "string",
|
||||
"nullable": true
|
||||
},
|
||||
"operator": {
|
||||
"type": "object",
|
||||
"nullable": true,
|
||||
"additionalProperties": true
|
||||
},
|
||||
"units": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"online": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"power": {
|
||||
"type": "number"
|
||||
},
|
||||
"mine": {
|
||||
"type": "boolean"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"ownerTownId",
|
||||
"townName",
|
||||
"operator",
|
||||
"units",
|
||||
"online",
|
||||
"power",
|
||||
"mine"
|
||||
],
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
|
|
@ -10419,6 +10652,39 @@
|
|||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
"GarrisonWithdrawn": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"serverTime": {
|
||||
"type": "integer"
|
||||
},
|
||||
"movementId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"siteId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"fromTownId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"units": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"arriveAt": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"serverTime",
|
||||
"movementId",
|
||||
"siteId",
|
||||
"fromTownId",
|
||||
"units",
|
||||
"arriveAt"
|
||||
],
|
||||
"additionalProperties": true
|
||||
},
|
||||
"BackboneBuildStarted": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
|
@ -10842,6 +11108,10 @@
|
|||
"status": 409,
|
||||
"description": "That POP is too far from the offer (its max distance or your Internet exchange reach)."
|
||||
},
|
||||
"no_room_for_goods": {
|
||||
"status": 409,
|
||||
"description": "Your Rack hall will not have room for the goods when they arrive; make room (spend, or raise the hall) and accept again."
|
||||
},
|
||||
"world_ended": {
|
||||
"status": 409,
|
||||
"description": "This world has ended: it can still be read, but nothing can be changed."
|
||||
|
|
|
|||
23
docs/workflows/README.md
Normal file
23
docs/workflows/README.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
# Stage workflows
|
||||
|
||||
One short note per stage of CLAUDE.md "Working in stages": goal, done-when, what was actually built, what is open. They were
|
||||
written after the fact (2026-10-11) from `docs/NEXT.md`, `docs/DECISIONS.md`, `docs/BALANCE.md` and the git history, so they
|
||||
describe what happened, not what was once planned. The authoritative status is `docs/NEXT.md`; if a note here disagrees, NEXT wins
|
||||
and the note is stale.
|
||||
|
||||
A stage is done when `npm test` passes, the smoke e2e passes, the docs (API, PROTOCOL, DESIGN, NEXT) match the code and the commit
|
||||
message says honestly what was built, tested and NOT tested (CLAUDE.md).
|
||||
|
||||
| Stage | Note | Commits |
|
||||
|---|---|---|
|
||||
| 0 Skeleton | [stage-0-skeleton.md](stage-0-skeleton.md) | b56b138 |
|
||||
| 1 Economy | [stage-1-economy.md](stage-1-economy.md) | b56b138, 249818a (client) |
|
||||
| 2 World | [stage-2-world.md](stage-2-world.md) | b56b138, 249818a (client) |
|
||||
| 3 Military | [stage-3-military.md](stage-3-military.md) | 249818a, b18645d |
|
||||
| 4 Expansion | [stage-4-expansion.md](stage-4-expansion.md) | 249818a, b18645d |
|
||||
| 5 Social | [stage-5-social.md](stage-5-social.md) | 249818a, b18645d, 931f59e, d84b0c9 |
|
||||
| 6 Push and polish | [stage-6-push-polish.md](stage-6-push-polish.md) | b18645d, 931f59e, cc0524d |
|
||||
| 7 Ops and balance | [stage-7-ops-balance.md](stage-7-ops-balance.md) | 931f59e, cc0524d, bf7af06, 9104480 and later |
|
||||
|
||||
Note: the work did not follow the stage order exactly. Stages 0-2 went in one commit, 3-5 in the next, and the end game and trade
|
||||
(planned inside stage 5 / 7) arrived with the client work. The notes list the real commits.
|
||||
22
docs/workflows/stage-0-skeleton.md
Normal file
22
docs/workflows/stage-0-skeleton.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Stage 0: skeleton
|
||||
|
||||
**Goal:** a server that boots, stores state in SQLite, runs a persistent event queue and answers a documented REST API, before any
|
||||
game rule exists.
|
||||
|
||||
**Done when:** repo layout in place; `server/db.js` (driver wrapper, transactions, checksummed migrations) and `server/clock.js`
|
||||
(the only place that reads time); `scheduler.js` with catch-up after restart; router, error envelope, auth with hashed bearer
|
||||
tokens, `/healthz`; `docs/openapi.json` generated and checked against the route table; systemd unit, backup timer, DEPLOY.md.
|
||||
|
||||
## Built (b56b138)
|
||||
- `node:sqlite` behind `server/db.js` (D1); migrations `NNN_name.sql` applied in a transaction each and refused if edited later.
|
||||
- `Scheduler`: events processed strictly in `(due_at, id)` order, one transaction per event, a throwing handler marks the event
|
||||
`failed` and the queue moves on; `catchUp()` before the listener opens; outbox so push only leaves after commit (stage 6).
|
||||
- Router with `Idempotency-Key`, per-IP/per-token rate limits (login/signup stricter), 32 KB bodies, scrypt passwords, opaque
|
||||
tokens stored hashed, strict CSP static server (NETWALL's `net.js`/`static.js`).
|
||||
- `tools/gen-openapi.js` + a test that fails when a route and `openapi.json` disagree (D7).
|
||||
- Deploy files, DEPLOY.md and the admin CLI were added at stage 7 (see there).
|
||||
|
||||
## Open
|
||||
- First commit had a manual smoke run only; unit tests arrived with each later stage.
|
||||
- Never run: a unit under systemd, the backup timer firing on its own, Debian 13 with a real Node 22.13 (only 24.21 was used).
|
||||
- Tokens never expire and there is no change-password route; revocation reaches an open socket at the next 30 s ping.
|
||||
21
docs/workflows/stage-1-economy.md
Normal file
21
docs/workflows/stage-1-economy.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Stage 1: economy
|
||||
|
||||
**Goal:** one POP per operator with lazily evaluated resources, buildings with levels, a build queue and storage caps; a minimal
|
||||
client (POP view, build menu, countdowns).
|
||||
|
||||
**Done when:** `rules.resourcesAt(town, now)` is the only way to read a stock; every quantity that grows is `(amount, rate,
|
||||
updatedAt)` (D3: one `towns.res_at`); build/cancel/rename commands validate and apply in one transaction; `buildDone` is an event.
|
||||
|
||||
## Built
|
||||
- Four resources (Fiber, Hardware, Capital, Power as a battery, D4), resource fields by slot (D8), infrastructure (Core router,
|
||||
Rack hall, Battery bank, ...), build queue with a second slot unlocked by Core router level (B1: level 3, was 10), cancel.
|
||||
- `public/js/data.js` holds all numbers; `rules.js` all formulas and loads in browser and Node.
|
||||
- Client (249818a): login/signup, POP screen with live resource bar ticked from the server clock, build sheet with live
|
||||
affordability, countdowns, power panel, en + nb, PWA manifest and icons.
|
||||
- Later balance (BALANCE.md): B4 early-level build discount (levels 1-3 take x0.5/x0.67/x0.83), B5 start stock 1000.
|
||||
- Fix G1: `buildDone` adds one level to what the building is *now* (test written first, failed before).
|
||||
|
||||
## Open
|
||||
- Nothing is balanced (bots only, 2 seeds for B4/B5); the first hour is limited by the start stock, not build time (B4/B5).
|
||||
- The capital runs out of things to build long before the backbone opens (BALANCE section 5).
|
||||
- No service worker, so no offline mode; no light theme.
|
||||
18
docs/workflows/stage-2-world.md
Normal file
18
docs/workflows/stage-2-world.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Stage 2: world
|
||||
|
||||
**Goal:** a seeded map, spawn placement, neutral land, a viewport query and a canvas map.
|
||||
|
||||
**Done when:** `rules.tileAt(seed, radius, x, y)` is deterministic; new operators land on a spawn ring; `GET /map?x&y&r` returns
|
||||
a window; the client map pans, pinches and culls tiles; every game row carries `world_id` (multi-world from day one).
|
||||
|
||||
## Built
|
||||
- First world is 101 x 101 (radius 50, D6), seed random at first boot; `worlds` is data, `create-world` makes more (stage 7).
|
||||
- Rural areas are held by proximity in v1 (D5), not by a separate tile ownership model.
|
||||
- `GET /map/tile`, chunked `GET /map` cache on the client, tile info sheet, `js/render.js` canvas (pan, pinch, wheel, keyboard).
|
||||
- Seven landing sites are derived from the seed (`rules.backboneSites`) and excluded from spawn and settling from day 0.
|
||||
- `POST /me/join` (9104480) lets an account without a POP found one in a running world after `reset-world`.
|
||||
|
||||
## Open
|
||||
- Map canvas has no inertia/fling.
|
||||
- `/me` exposes the world seed, which the client ignores.
|
||||
- Joining a second world was only tested on the default-world path.
|
||||
22
docs/workflows/stage-3-military.md
Normal file
22
docs/workflows/stage-3-military.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Stage 3: military
|
||||
|
||||
**Goal:** training queues, movements (attack, raid, reinforce, scout, return), combat at arrival, loot, reports, incoming warnings.
|
||||
|
||||
**Done when:** every future thing is an `events` row; combat resolves only inside the event queue in `(due_at, id)` order; the
|
||||
client sees incoming attacks without reload; a determinism test replays a fight identically.
|
||||
|
||||
## Built (249818a server, b18645d client)
|
||||
- 10 unit types and research in `data.js`/`rules.js`; `trainDone` per batch, sequential per building; `researchDone`.
|
||||
- Movements: scan, raid, attack, takeover, reinforce, settle, transport; latency = distance / slowest unit; recall for 90 s; return
|
||||
legs with loot; arrival re-validates everything and bounces (S3-4).
|
||||
- Combat: firewall vs DDoS rigs, exploit kits on a chosen building, Rack hall cache, losses; reports are one row with many
|
||||
recipients, 14-day cleanup (S3-3); beginner protection both directions (S3-7); power: offline units, decommission after 24 h (S3-1).
|
||||
- Client: Units, Moves, Reports screens, the send dialog, incoming banner and badge, map movement lines.
|
||||
- Review round 1 (d84b0c9, DECISIONS R1): proto smuggling in `validate.js`, trade-leg recall, escrow cap, rate limits, rankings DoS.
|
||||
|
||||
## Open
|
||||
- Training cannot be cancelled; no sitters, no night protection; units in transit draw no power.
|
||||
- Nothing balanced: unit stats, costs and research curves are first guesses (BALANCE section 4: raiding profitable per raid but not
|
||||
a winning strategy at equal attention; takeover expensive enough).
|
||||
- No garrisons at landing sites (E1): after the opening days nobody can contest a built-up site.
|
||||
- Takeover/capture flows and the confederation `alliedIncoming` view have no browser run.
|
||||
19
docs/workflows/stage-4-expansion.md
Normal file
19
docs/workflows/stage-4-expansion.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# Stage 4: expansion
|
||||
|
||||
**Goal:** found new POPs, conquer others, multi-POP UI.
|
||||
|
||||
**Done when:** a Rollout crew founds a POP on a chosen wild slot; a hostile takeover moves loyalty to zero and flips owner with the
|
||||
capital and last-POP protections; the UI switches between POPs.
|
||||
|
||||
## Built (249818a server, b18645d client)
|
||||
- Settle command with wild-slot choice; footprint gate counts the operator's total (S3-8); takeover with loyalty (S3-5);
|
||||
incumbent (legacy telco) sites with static defence growing with world age and a one-time Hardware bonus; +10% research speed
|
||||
per incumbent site held.
|
||||
- Moving units between your own POPs (S3-9); transport links (S3-6).
|
||||
- Client: POP switcher in the resource bar, expansion card on the POP screen, settle through the send dialog, red ring on POPs that
|
||||
something is heading for, `refreshTowns` after a settle/takeover.
|
||||
|
||||
## Open
|
||||
- No command to choose a new capital; a captured POP keeps its footprint.
|
||||
- The Hostile takeover button stays enabled on a capital/last POP (the client cannot know; the server refuses and the UI shows it).
|
||||
- Settle and takeover resolution were exercised by fast-forwarding movement times in the DB, not by waiting in a browser.
|
||||
21
docs/workflows/stage-5-social.md
Normal file
21
docs/workflows/stage-5-social.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Stage 5: social
|
||||
|
||||
**Goal:** alliances, roles, messaging, diplomacy, marketplace and resource transport.
|
||||
|
||||
**Done when:** an alliance can be founded, grown, governed and dissolved; diplomacy states change through events; messages and
|
||||
rankings work; trade moves resources between POPs and players without creating or losing any.
|
||||
|
||||
## Built
|
||||
- Migration 003: alliances with roles and a stored size cap (S5-1), diplomacy (war, neutral, NAP, confederation; 24 h / speed pact
|
||||
cancel via the `diploChange` event, S5-2), membership in two tables with one writer (S5-3), messages with per-recipient rows,
|
||||
DB-backed rate limit and sanitising (S5-5/6), rankings computed per request with a 5 s footprint cache (S5-7/R1).
|
||||
- Migration 004 (b18645d): Internet exchange trade (T1): offers with escrow, one link per side, 1:2 ratio band, accept = two
|
||||
transports in one transaction, conservation asserted in tests; shared report folder (T2); `alliedIncoming` (G2).
|
||||
- Client (b18645d, 931f59e): alliance, messages, rankings, trade (Exchange) screens, `SocUI`, all player text via `textContent`.
|
||||
|
||||
## Open
|
||||
- Alliance rename/description and note editing have no UI; no operator profile page; no sitter accounts; no message retention job
|
||||
beyond the report/notification pruning.
|
||||
- Trade: no order book, price history, counter-offers, multi-link deals, or "new offer in reach" notification; escrow refunds are
|
||||
clipped at the Rack hall cap without a notice (S2); the escrow of a taken-over POP goes to the conqueror.
|
||||
- The `SOCIAL` numbers (limits, TTLs, role table) are first guesses.
|
||||
21
docs/workflows/stage-6-push-polish.md
Normal file
21
docs/workflows/stage-6-push-polish.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Stage 6: push and polish
|
||||
|
||||
**Goal:** WebSocket push, a notifications table, PWA, layout matrix, i18n nb/en.
|
||||
|
||||
**Done when:** the game is fully playable with push disconnected; hints leave only after the transaction that caused them
|
||||
committed; the layout holds on phone portrait/landscape and desktop; every notification type and error code has en + nb text.
|
||||
|
||||
## Built
|
||||
- `/ws` (b18645d): auth as the first message, Origin check, per-IP cap, 1 KB frames, token bucket, ping/pong with token re-check,
|
||||
graceful 1001 on shutdown; hints `town`, `incoming`, `notification`, `report`, `message` (docs/PROTOCOL.md). Post-commit outbox (S6-1);
|
||||
revocation polled, not pushed (S6-2); hints merged per tick (S6-3).
|
||||
- Client `ws.js`: backoff 1..60 s, close-code handling, refetch after every `ready`; poll fallback (45 s down, 3 min up). Measured in
|
||||
headless Chromium: incoming banner 214 ms after launch; fallback about 52 s.
|
||||
- i18n en + nb with parity tests over every error `CODE` and every notification type (`test/client-alerts.test.js`).
|
||||
- Smoke e2e (cc0524d): `e2e/run.js`, playwright-core, 61 checks, desktop, phone touch, layout matrix on 5 viewports.
|
||||
|
||||
## Open
|
||||
- No service worker (no offline mode), no light theme, no sound or system notifications, no APNs/FCM sender.
|
||||
- Never run behind nginx Proxy Manager (upgrade headers, idle timeouts, real client IPs); real devices and Safari never run.
|
||||
- Hint gaps: no `incoming` for confederates, no `town` hint for reinforcing owners, no `backbone_open` push (E2).
|
||||
- Unread-badge state partly in localStorage; ended-world locking is a DOM sweep, not per-button wiring.
|
||||
24
docs/workflows/stage-7-ops-balance.md
Normal file
24
docs/workflows/stage-7-ops-balance.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
# Stage 7: ops and balance
|
||||
|
||||
**Goal:** bot-driven balance passes, an admin CLI, a world lifecycle (start, end, reset), load test with bots, full e2e.
|
||||
|
||||
**Done when (CLAUDE.md):** `tools/bot.js` runs N bots for X simulated days in seconds and balance claims cite a run; `tools/admin.js`
|
||||
creates, ends and resets worlds; the deploy runs on the real target; a human has played a world.
|
||||
|
||||
## Built
|
||||
- `tools/bot.js` + `tools/bot/*` (931f59e): 50 bots x 14 days in about 3 s, 170 days in about 140 s, real server in-process with a
|
||||
fake clock; exact resource and unit conservation, exit 1 when an invariant breaks. `docs/BALANCE.md` holds method and every run.
|
||||
- Tuned with before/after runs: B1 second build slot at Core router 3, B2 transport 1000 per link, B4 early-level build discount,
|
||||
B5 start stock 1000 (bf7af06). Server fix found by the harness: bounced shipments reported no overflow (B3).
|
||||
- Admin CLI (status, migrate, worlds, create/end/reset-world, users, ban, inspect, events, replay-events, backup/verify-backup,
|
||||
grant), deploy units, backup timer, DEPLOY.md. `end-world` now runs the real `worldEnd` handler (final ranking, escrow back,
|
||||
events cancelled); quiet on a closed stdout pipe.
|
||||
- Ops scripts: `deploy/update.sh` (backup, fast-forward, health check, rollback), `deploy/upstream-offsite.{service,timer}`
|
||||
(off-box copy of the newest verified snapshot). Tests with stubs: `test/deploy-update.test.js`, `test/deploy-offsite.test.js`.
|
||||
|
||||
## Open
|
||||
- **Not balanced.** Bots are not humans. A 3x world's end game is as long as a 1x world's; raid loot splits evenly and is destroyed
|
||||
on overflow; no fight for a built-up landing site (E1); the capital runs out of builds before the backbone opens.
|
||||
- No load test over HTTP/WebSocket with many real sockets; the full e2e suite beyond the smoke run; no scheduled "create next world".
|
||||
- Never run: Node 22.13 (the stated minimum), the update script or the off-site copy against real systemd/ssh, the backup timer on
|
||||
its own, nginx Proxy Manager, a restore on the real box.
|
||||
Loading…
Add table
Add a link
Reference in a new issue