193 lines
12 KiB
Markdown
193 lines
12 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 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`.
|
||
|
||
## 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).
|