# 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 1. Resources accrue while you're away (capped by storage). 2. Spend them on building levels (one build queue, slow) and units (training queue). 3. 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. 4. 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 301 x 301 (coordinates -150..150), 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 queue per POP. 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) / corerouter / speed`. 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. 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)` where `L_eff = max(0, L − rigs/10)`. - Full attack: the losing side loses everything; the winning side loses `(loser/winner)^1.5` of its strength, 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). - 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_att` vs `scanners_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 `alliedIncoming` in `GET /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 `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 without the Rack hall cap (an amount above the cap is kept, it only stops growing), so nothing is created or lost. - **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 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 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 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 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 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 the stockpile when the level starts; any holder with `backboneBuild` may 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 `worldEnd` event stores a ranking snapshot (operators by footprint, alliances by the sum, top attackers and defenders by battle points, winner, the sites), sets the status `ended`, and cancels everything still pending in that world. An ended world refuses every game command with `world_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 lose `0.5 x (weaker/stronger)^1.5` whoever 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:** `sa` vs `sd` = scanners x (1 + 5% per defence-research level of port_scanner). Success needs `sa > sd`; `detail` is `basic` (units, resources) and `full` at 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 loses `0.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 (301² tiles is a lot for 50 players; shrink for the first world).