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
This commit is contained in:
parent
b56b13880e
commit
249818a7aa
111 changed files with 17472 additions and 13 deletions
90
docs/API.md
90
docs/API.md
|
|
@ -27,4 +27,94 @@ REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`
|
|||
| `GET /map?x&y&r` | rural areas, incumbent sites, POPs in the viewport |
|
||||
| `GET /notifications?after&limit` | durable notification feed (build done, ...) |
|
||||
|
||||
## Social (stage 5, no marketplace/transport yet)
|
||||
|
||||
`worldId` is optional everywhere a caller's operator is needed (default: their oldest operator). Most commands are
|
||||
idempotent where that makes sense and answer `{ changed: false }` when there was nothing to do (leaving twice, kicking someone
|
||||
already gone, accepting an invite twice). `forbidden` carries `details.need` (the missing permission).
|
||||
|
||||
**Alliances.** Roles `leader`, `diplomat`, `officer`, `member`; the permission table is `SOCIAL.permissions` in `data.js`
|
||||
(`GET /alliances/mine` returns the caller's permissions). Founding and joining need a Peering office level >= 1 on one of the
|
||||
operator's POPs (`peering_office_required`). Size cap: `10 + 2 * level` of the founder's best Peering office when founding, stored;
|
||||
it is raised (never lowered) whenever a command runs that depends on it (invite, accept, transfer) if the current leader's best
|
||||
office would give more; reads show the effective cap. One alliance per operator.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /alliances {name, tag}` | found (201); name 3-30 chars, tag 2-5 letters/digits, both unique per world, case-insensitive |
|
||||
| `GET /alliances?q&after&limit`, `GET /alliances/mine`, `GET /alliances/:id` | directory (cursor: id), your alliance + role + permissions, public profile (size, leader, summed footprint, your relation) |
|
||||
| `GET /alliances/:id/members` | members only: role, POP count, footprint, `lastOnline` (newest token use of the user, updated at most once a minute); bounded by the cap, so not paginated (`next` is always null) |
|
||||
| `POST /alliances/:id/invite {operatorId \| name}`, `GET /alliances/:id/invites`, `DELETE /alliances/:id/invites/:inviteId` | invite (201; repeating returns the pending invite with 200), list sent, cancel. Invites expire after 7 days (real time) |
|
||||
| `GET /alliance-invites`, `POST /alliance-invites/:id/accept`, `POST /alliance-invites/:id/decline` | the invitee's side |
|
||||
| `POST /alliances/:id/leave`, `/kick {operatorId}`, `/role {operatorId, role}`, `/transfer {operatorId}`, `/disband` | leaving (the leader must transfer first, or is alone and disbands), kick (only members the actor outranks), set role (leader only), hand over leadership, disband |
|
||||
| `GET/POST /alliances/:id/notes`, `POST/DELETE /alliances/:id/notes/:noteId` | pinned notes (max 10, 1000 chars, plain text) |
|
||||
|
||||
**Diplomacy.** States `war`, `neutral`, `nap`, `confed`. `POST /alliances/:id/diplomacy {targetId, state}` answers with
|
||||
`result`: `applied` (declaring war from neutral takes effect at once), `proposed` (pacts, and peace out of war: the other alliance
|
||||
must accept within 72 h, real time) or `scheduled` (cancelling a pact, or going to war out of one, takes 24 h / world speed:
|
||||
`effectiveAt`, applied by the `diploChange` event). While a change is scheduled the old state holds and further changes between the
|
||||
pair are `diplomacy_pending`; the alliance that started it can take it back. The move table is `SOCIAL.diplomacyMoves`.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `GET /alliances/:id/diplomacy` | members only: relations (with scheduled change), incoming and outgoing open proposals |
|
||||
| `POST /diplomacy/proposals/:proposalId/accept` / `.../decline`, `DELETE /diplomacy/proposals/:proposalId` | answer (receiving alliance) / withdraw (proposing alliance); all need `diplomacy` |
|
||||
| `DELETE /alliances/:id/diplomacy/:otherId/pending` | revoke a scheduled cancel you started |
|
||||
|
||||
Notification types written: `alliance_invite`, `alliance_invite_declined`, `alliance_member_joined`, `alliance_member_left`,
|
||||
`alliance_kicked`, `alliance_role`, `alliance_leader`, `alliance_disbanded`, `diplomacy_proposal`, `diplomacy_declined`,
|
||||
`diplomacy_changed`, `diplomacy_cancel_pending`, `diplomacy_cancel_revoked`, `message`, `alliance_message`.
|
||||
|
||||
**Messages.** Plain text, 1-2000 characters; control characters, bidi overrides and invisible characters are stripped
|
||||
(`server/text.js`) before anything is stored. Lists are newest first and the cursor is the last id of the previous page
|
||||
(`?after=<next>` gives the next, older page). Sending is limited per sender by counting their recent messages (15 DMs / 10 min,
|
||||
60 DMs / h, 20 alliance broadcasts / h, `SOCIAL.messageLimits`): `429 rate_limited` with `details.retryAfter`. Deleting removes only
|
||||
your own copy. A recipient who blocked the sender gets nothing; the sender is not told (`recipients: 0`).
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /messages {toOperatorId \| toName \| toAlliance, text}` | send (201) |
|
||||
| `GET /messages/inbox?unread`, `/messages/outbox`, `/messages/thread/:operatorId`, `/messages/alliance` | lists; the inbox also returns `unread` |
|
||||
| `GET /messages/:id`, `DELETE /messages/:id`, `POST /messages/read {ids \| all}` | one message, delete own copy, mark read |
|
||||
| `GET/POST /messages/blocks`, `DELETE /messages/blocks/:operatorId` | block list (max 100) |
|
||||
|
||||
**Rankings.** `GET /rankings/operators` (footprint, `rules.footprintAt` over the operator's POPs), `/rankings/alliances` (sum over
|
||||
members), `/rankings/battles?by=attack|defense|total` (from `operator_stats`, `available: false` and empty when that table does not
|
||||
exist). The cursor is a rank offset (`next` = ranks already seen). Each response has `total` and `you` (the caller's own entry).
|
||||
|
||||
`GET /me` operators and `GET /map` town owners now carry `alliance: { id, tag, name } | null` next to `allianceId`.
|
||||
|
||||
## Military and expansion (stages 3-4)
|
||||
|
||||
Units are plain `{ unitId: count }` objects with the generic ids of `data.UNITS` (`port_scanner`, `soc_analyst`, `blue_team`,
|
||||
`honeypot`, `script_crew`, `botnet`, `ddos_rig`, `exploit_kit`, `rollout_crew`, `ma_team`); names live in `i18n.js`. `GET /towns/:id`
|
||||
now carries `town.military`: units at home (`online` flag, `offlineSince`), reinforcements standing here and away, the training queue,
|
||||
what can be trained (cost, time, missing requirements), research levels and queue, transport links, and this POP's outgoing/incoming
|
||||
movements. Nothing resolves when you send it: combat, loot and arrival happen in the event queue at the arrival time, and reports and
|
||||
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `transport_arrived`, `units_offline`,
|
||||
`units_decommissioned`, `town_lost`, `town_gained`) tell you afterwards.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /towns/:id/train {unit, count}` | queue a batch (201). Batches of one training building (NOC / Ops lab / Rollout depot) run in order, buildings in parallel; queue limit 8 per building (`queue_full`) |
|
||||
| `POST /towns/:id/research {unit, stat}` | +5% `attack` or `defence` per level for one unit type, one research at a time per POP, level n needs a Research lab of level n + 2 |
|
||||
| `POST /movements {fromTownId, type, toTownId \| x,y, units, ...}` | send `scan`, `raid`, `attack`, `takeover`, `reinforce`, `settle` (201). `type: transport` carries `cargo: {fiber, hardware, capital}` (Internet exchange: level = concurrent transports, 500 each). Extra fields: `target` (building for exploit kits), `wild` (two field types for a new POP), `confirmEndProtection` |
|
||||
| `GET /movements` | your active movements (full detail, `recallableUntil`) and incoming ones from others: origin and ETA only, `type: "unknown"` |
|
||||
| `POST /movements/:id/recall` | turn an outbound movement around within the first 90 s (`recall_expired` after) |
|
||||
| `POST /towns/:id/withdraw {ownerTownId, units?}` | reinforcements in this POP go home (host kicks them out, or their owner calls them back) |
|
||||
| `GET /reports?after&limit&unread`, `GET /reports/:id`, `POST /reports/:id/read`, `POST /reports/read-all` | reports, **newest first**: `after` = id of the last report you have, the next page holds older ones. One shared row per battle, per-user read flag; kept 14 days |
|
||||
| `GET /map/tile?x&y` | public facts about one tile for the send dialog: what is there, owner/protection, distance from each of your POPs, whether you could settle it (`settle.possible/code`) |
|
||||
|
||||
Rules the server enforces on `POST /movements` (error codes in `x-error-codes`): `not_enough_units`, `units_offline` (battery empty),
|
||||
`invalid_target` (`details.reason`: own town, nothing there, pact partner, not allied, occupied tile ...), `target_protected` (beginner
|
||||
protection still running at the arrival time; scans are allowed), `protection_active` (attacking from protected status needs
|
||||
`confirmEndProtection: true` and ends your protection), `cannot_takeover` (last POP), `footprint_too_low` / `out_of_range` (settle and
|
||||
takeover), `capacity_exceeded` / `no_transport_link` (transport). Pact partners (same alliance, NAP, confederation) cannot raid, attack
|
||||
or take over each other; only the same alliance or a confederation may reinforce. The server re-checks target, protection and pact when
|
||||
the movement arrives and bounces it (units come home, a `movement_failed` report says why) if something changed.
|
||||
|
||||
Report types: `raid`, `attack`, `takeover` (the same combat report: outcome, both sides' units and losses, attack/defence values,
|
||||
firewall, loot, siege, takeover/loyalty), `scan` (attacker; intel when it succeeded), `scan_detected` (defender; attacker identity only
|
||||
if the defender's scanners won), `incumbent`, `settle`, `reinforce`, `movement_failed`.
|
||||
|
||||
Later stages append their routes here and to the route table.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue