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
24 KiB
DESIGN.md
Working title: UPSTREAM. First-pass design. Every number here is a starting point for the bot balance
passes in stage 7, not a promise. Formulas are the contract; constants live in public/js/data.js.
Pitch
You are a regional network operator with one POP on a map full of rivals. Build out the POP, connect the countryside, peer with friends, raid and take over competitors, and be in the alliance that finishes the Tier-1 backbone first. Slow by design: a world runs for months, and a session is a few minutes a few times a day. Everything that takes time can be queued, and nothing happens that you weren't warned about.
Tone: light and nerdy, like NETWALL. Jargon is used correctly and never explained in the UI beyond a tooltip. No real companies, products, people or AS numbers.
Core loop
- Resources accrue while you're away (capped by storage).
- Spend them on building levels (one build queue, slow) and units (training queue).
- Send units somewhere: scout, raid, attack, reinforce, settle, take over. Travel time ("latency") is the pacing mechanic: a raid across the map takes hours, and the target is warned.
- Reports tell you what happened. Repeat.
Mid game adds more POPs, alliances and trade. Late game is the backbone race.
World
- Square tile map, default 101 x 101 (radius 50, coordinates -50..50;
WORLD_DEFAULTS.mapRadius, DECISIONS D6), one tile = one site. World config sets size, speed (1x, 2x, 3x), start time and a planned end. - Tile types: empty land, rural area (bonus tile), incumbent site (NPC), backbone landing site (appears late, see End game), player POP.
- Spawn: new operators get a POP placed randomly in an expanding ring around the centre so early joiners are central and the map fills outward. Minimum spacing 3 tiles from any other POP.
- Each operator gets a fictional AS number from a reserved range on signup; it's a display name, nothing more.
- Beginner protection: 72 h (divided by world speed), no attacks in or out. Ends early if you attack.
Resources
Four resources, all per POP:
| Resource | Produced by | Used for |
|---|---|---|
| Fiber | Cable yard | Most buildings, cheap units |
| Hardware | Supply depot | Advanced buildings, strong units |
| Capital | Sales office | Everything a bit; the raid currency |
| Power | Substation | Upkeep: every building level and unit draws it |
Fiber, Hardware and Capital accumulate and are capped by the Rack hall. Power does not accumulate: it is a rate. Net power = substation output − building draw − unit draw. A Battery bank holds a buffer that drains while net power is negative and refills while positive. When the buffer hits zero, units go offline (no attack or defence value, cannot move) starting with the most expensive; after 24 h offline they are decommissioned. Nothing else breaks: buildings keep working. This replaces "starvation" with something you can see coming.
Each POP has 18 resource slots around it: 4 fixed to each production type plus 2 wild slots the player assigns at founding. Rural areas held nearby add a +25% bonus to one resource type each (max 3 per POP).
Production
output(L) = base * growth^(L-1) * speed * bonuses, per hour, with base = 6, growth = 1.25 (level 1 → 6,
level 10 → 44, level 20 → 420). Substation uses the same curve for power output in watts-as-points.
Current amount is always computed, never stored as "now": amount = min(cap, stored + rate * (now − updatedAt)).
Buildings
One build slot per POP, a second from Core router 3 (FORMULAS.secondQueueCoreLevel, BALANCE.md B1). The Core router level shortens all build times. Level cap 20 for most buildings.
| Building | Role |
|---|---|
| Core router | Required for everything. Build time ÷ (1 + 0.04·L). Unlocks the second queue slot at 3 (was 10, BALANCE.md B1). |
| Rack hall | Storage cap for Fiber/Hardware/Capital: cap(L) = 1000 * 1.22^(L-1). |
| Battery bank | Power buffer: buf(L) = 200 * 1.22^(L-1) points. |
| Firewall | Defence multiplier 1 + 0.03·L. DDoS rigs reduce it during attacks. |
| NOC | Trains defensive units. Training time ÷ (1 + 0.03·L). |
| Ops lab | Trains offensive units and siege. Requires Research lab 3. |
| Research lab | Unlocks unit types and upgrades (each upgrade: +5% attack or defence for one unit type). |
| Internet exchange | Trade: list offers, accept offers, send resources. Level sets number of transport links. |
| Peering office | Create/join an alliance. Level sets alliance size you can found (10 + 2·L). |
| Rollout depot | Trains Rollout crews (settlers) and M&A teams. Requires Core router 10. |
| Backbone node | Only on backbone landing sites. The end-game building (see below). |
Costs: cost(L) = base_cost * 1.28^(L-1) per resource. Times: time(L) = base_time * 1.16^(L-1) * early(L) / corerouter / speed, where early(L) is 0.5, 0.67, 0.83 for levels 1 to 3 and 1 from level 4 (FORMULAS.earlyLevels / earlyTimeFactor, BALANCE.md B4: the first levels are quick so the first hour is not a wait). Base costs/times per building in data.js. Every building level adds 1 power draw per level
(resource producers 0, so expansion is never power-negative on its own).
Footprint: every building level produces footprint points per day (1 + L/5). Founding or taking over a POP
requires a footprint threshold that grows with POP count: need(n) = 500 * n^1.8 for the n-th extra POP.
Units
Stats per unit: attack, defence, speed (tiles/hour at 1x), carry (loot), power draw, cost, training time, required research. Two defence values would add depth (vs crews / vs automated); start with one and revisit.
| Unit | Trained in | Role |
|---|---|---|
| Port scanner | NOC | Scout. Fast, no carry. Scanner vs scanner decides if the scan succeeds and whether the target learns who scanned. |
| SOC analyst | NOC | Cheap defender, weak attacker. |
| Blue team | NOC | Strong defender, slow. |
| Honeypot | NOC | Defender that cannot move. High defence, cheap upkeep. |
| Script crew | Ops lab | Cheap attacker, good carry. The raid unit. |
| Botnet | Ops lab | Fast attacker, big carry, high power draw. |
| DDoS rig | Ops lab | Siege vs Firewall: each rig lowers the effective firewall level during that battle. |
| Exploit kit | Ops lab | Siege vs buildings: damages a chosen building level on a win. |
| Rollout crew | Rollout depot | Three found a new POP on an empty tile. Consumed. |
| M&A team | Rollout depot | Lowers customer loyalty on a winning attack. Max one per attack. |
Upkeep is power draw per unit, counted at the POP the unit is stationed in (reinforcements draw from the host).
Movements
Movement types: scan, raid, attack, reinforce, settle, takeover, transport (resources), return.
latency = distance / (slowest speed * world speed) with Euclidean distance in tiles; minimum 10 min. The
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. 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
Resolved at arrival, in the event queue, in order. Deterministic given the inputs and the world seed.
A = Σ attack(units) * research,D = (Σ defence(units in POP, incl. reinforcements) * research + 10) * firewall(L_eff)whereL_eff = max(0, L − rigs/10).- Full attack: the losing side loses everything; the winning side loses
(loser/winner)^1.5of its strength, spread proportionally across unit types. On a win with exploit kits, one chosen building losesfloor(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, 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. - Scan:
scanners_attvsscanners_def; if attackers outnumber, report shows units and resources (buildings at 2:1). Defender always gets a report that a scan happened; identity only if their scanners win.
Reports: every participant gets one. Reports are stored for 14 days, can be shared to the alliance.
Expansion and footprint
Three Rollout crews plus footprint threshold found a new POP on an empty tile; distance from an own POP ≤ 15. A new POP starts at level 0 everything and 1 h of resources. Takeover requires the same footprint threshold.
Alliances and diplomacy
- Alliance: name, tag, up to size cap. Roles: leader, diplomat, officer, member. Shared report folder, pinned notes, member list with last online and POP count.
- Diplomacy states between alliances: war, neutral, non-aggression pact, confederation (can reinforce each other, see each other's incoming). Pacts take 24 h to cancel.
- Messages: player-to-player and alliance broadcast, plain text, 2000 chars, basic rate limit.
- Shared report folder (server): a member puts one of their own reports (any type) into the alliance's folder (
shareReport); every member reads it (viewSharedReports), the sharer or leader/officer (unshareReport) takes it out. Sharing pushes the report's expiry out to 14 days from the share (it is one row for everybody) and it goes with the report or the alliance. - Seeing each other's incoming (server): members of one alliance and of confederated alliances get
alliedIncominginGET /movements: movements heading for a partner's POP, origin and ETA only (type, units and cargo hidden), except traffic from operators who are partners of the target themselves (friendly).
Trade
The Internet exchange lists offers "give X of A for Y of B, max distance Z". Ratio bounded 1:2 to stop pump-feeding. Accepting an offer spawns two transport movements. Direct transports to own POPs or to any player (e.g. alliance support) use the same links. Transport links: level of the exchange, capacity 1000 each (500 before BALANCE.md B2).
Clarified (what the server does).
- An offer is "give
giveAmountofgiveResforwantAmountofwantRes, withinmaxDistancetiles", 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 wantandwant <= 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, 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 atrade_refund_clippednotification 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 <= links); accepting converts the reservation into the real transport. Direct transports see the reservation as a busy link.
- 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 isaccepted, thencompletedwhen both have been delivered. A delivery above the receiver's Rack hall cap 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)
The legacy telco. Holds incumbent sites spread over the map with large static defences that scale with world age. They never attack. Taking one gives a one-time Hardware bonus and a permanent +10% research speed. In the end game they hold the backbone landing sites.
End game
At day 100 (÷ speed), 7 backbone landing sites appear at fixed positions, held by the incumbent with heavy defence. Taking one lets the owning alliance build the Backbone node there, levels 1–100, each level costing far more than anything else and requiring resources shipped in from members (transport). Level 100 = that alliance wins and the world ends two days later with a final ranking. Backbone nodes can be attacked and taken; the level stays with the site. Landing sites cannot be settled, only taken.
Clarified (what the server does). World age is in world days (real days x speed). All numbers below are first guesses, no bot run.
- Sites:
rules.backboneSites(seed, radius): 7 fixed positions, one per sector of the circle (jittered), on plain land between 35% and 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 readsbackbonefrom 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. 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
reinforcea 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 byPOST /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 whyheldDefenceMultis 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:
incumbentDefencegrows 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:
scanandattackonly (no raid: the stockpile would be lootable; no takeover, no settle;reinforceonly 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 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 takes2 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 the stockpile when the level starts; any holder withbackboneBuildmay start it. - Winning: when a level completes and the node is at level 100, the holder at that moment wins (once per world) and the world ends two world
days later (
worlds.end_at). The winner is final: losing the node during those two days does not change it. If a finished node is taken while nobody held it, the new holder wins. - Ending: the
worldEndevent stores a ranking snapshot (operators by footprint, alliances by the sum, top attackers and defenders by battle points, winner, the sites), sets the statusended, and cancels everything still pending in that world. An ended world refuses every game command withworld_ended; reading (map, reports, rankings, town views, status, results) and chatting (messages, marking reports read) keep working.
Rankings throughout: operators by footprint, alliances by sum, attackers/defenders by points from battles.
Fairness and anti-frustration
- Multi-accounting: one account per person; sitter feature (give a friend read/limited-write access) instead.
- No real-money anything. No speed-ups for sale. The game is a hobby project.
- Night: no night protection in v1; revisit after the first world.
- New players in a running world spawn in the outer ring with protection; worlds are expected to be re-run.
Client views (web, same for mobile)
POP view (buildings + queue), Resource view (slots), Map (pan/zoom, tile info, send dialog), Units (train,
station, movements list), Reports, Messages, Alliance, Exchange, Rankings, Profile/settings. Every countdown is
computed from serverTime.
Stage 3/4 clarifications (what the server does, where DESIGN.md was silent)
- Training/research: training time = unit time x count / (1 + 0.03 x level of the training building) / world speed; batches of one building queue one after another. Research cost = 8 x the unit's cost x 1.35^(level-1), time 30 min x 1.3^(level-1) / (1 + 0.03 x lab level); research level n needs Research lab n + 2.
- Roles per movement: scan = port scanners only; raid = attackers and defenders (no siege); attack = + DDoS rigs and exploit kits; takeover = + M&A teams (at least one); reinforce = anything that moves; settle = exactly three Rollout crews. Honeypots never move.
- Combat: formulas as above; ties go to the defender; a unit group loses
round(n x fraction)per type. Raid: BOTH sides lose0.5 x (weaker/stronger)^1.5whoever wins. Defenders are home crews plus each reinforcement group (own research each), counted only while online. The cold-spare cache applies to raids only; a full attack takes loot from the whole stock. Loot is split evenly over Fiber, Hardware, Capital, leftovers going to the others, capped by the survivors' carry. Exploit kits count by survivors. - Scan:
savssd= scanners x (1 + 5% per defence-research level of port_scanner). Success needssa > sd;detailisbasic(units, resources) andfullat 2:1 (+ buildings, loyalty, the target's outgoing movements with their types). A failed scan loses all scanners and reveals the scanner to the target; a successful one loses0.5 x (sd/sa)^1.5. - Incumbent site defence:
600 x (1 +- 25% per site, seeded) x (1 + 4% x world days), world days = real days x speed; sites are scanned or attacked, never raided or taken over, and never fight back. - Power: when the battery is empty and net power is negative, all units in that POP are offline; after 24 h / speed the most expensive are decommissioned until the draw fits.
- Transport: 12 tiles/h, 1000 per link, links = Internet exchange level; a link is busy until the empty carriers are back.
- Protection and recall: see S3-4 and S3-7 in DECISIONS.md; the recall window is 90 s of real time (not divided by world speed).
Open questions
- One or two defence stats per unit?
- Research as a tree or a flat list of upgrades?
- Should rural areas be contested (takeable from each other) or just held?
- Night protection and holiday mode.
- World size vs expected players (the default is already 101², radius 50; is that right for 50 players? untested with real players).