Stage 0-2 server spine: db, scheduler, REST, auth, economy, map
Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map + spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused. Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet. NOT done: military, expansion, social, client, push, deploy docs, bots/admin. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
parent
9fa76d53a8
commit
b56b13880e
39 changed files with 4450 additions and 0 deletions
193
docs/DESIGN.md
Normal file
193
docs/DESIGN.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
# 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue