Playtest on the live world: first hour feels a bit slow. B4: levels 1-3 of any building take x0.5/x0.67/x0.83 of the time (FORMULAS.earlyLevels/earlyTimeFactor, off at earlyLevels 0). Builds at 1 h (4 sittings/day) 8.9 -> 11.4, at 24 h 16.5 -> 20.4; mid game moves ~1 day head start (default mix), more for 2 sittings/day. B5: start stock 750 -> 1000 (measured separately: mid game unchanged, 60-min first sitting 12.1 -> 15.4 builds at 1 h). Numbers in docs/BALANCE.md. Tested: npm test 208/208, openapi check, npm run e2e 61/61 (before B5), 50x30-day bot run INVARIANTS OK after B5. NOT tested: humans (bots only, 2 seeds), B4+B5 combined beyond one run, e2e does not exercise the discount (runs at 4000x speed). Not claimed: balanced. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
264 lines
20 KiB
Markdown
264 lines
20 KiB
Markdown
# 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 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. 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 **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.
|
||
- **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 (the default is already 101², radius 50; is that right for 50 players? untested with real players).
|