Upstream/docs/DESIGN.md
jvanvik 249818a7aa Stage 3-5 server (military, expansion, social), web client for stages 1-2, ops/deploy
Built: units/research/training, movements (scan, raid, attack, takeover, reinforce, settle, transport), deterministic
combat resolved in the event queue, reports, power/offline units, founding + conquest + incumbent sites; alliances,
roles, diplomacy (24h pact cancel via events), messages, rankings; vanilla-JS phone-first client (auth, POP, map,
alerts, settings, en/nb); systemd units, backup timer, DEPLOY.md, tools/admin.js.
Tested: npm test 96/96 (fake clock, in-memory db, a few real-HTTP tests); client checked with headless Chromium
screenshots only. NOT done: marketplace/transport trade, client screens for military/social, WebSocket push,
bots/balance, e2e suite. All unit stats and costs are unbalanced first guesses.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
2026-10-11 18:32:36 +02:00

214 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 10. |
| 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.
## 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 500 each.
## 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.
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, 500 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).