Skip to content

SectorWars 2102

📖 Reading on GitHub? This repo renders properly as a documentation site at https://sw2102-docs.shouden.us. The grid cards, cross-links, and search bar only work there. Bookmark that link.

Canonical documentation for SectorWars 2102 — a turn-based space-trading game with procedurally generated galaxies, multi-regional governance, and an evolving per-player AI companion.

These docs are the source of truth for Sectorwars2102 (the game code) and sw2102-bang (the world generator). The repo itself lives at sw2102-docs.

First time here?

Skim the Glossary for vocabulary and the Contributing guide for the doc conventions. Then pick a section below.

Design pillars

A handful of constraints shape every system in this repo. They are load-bearing — most architecture decisions trace back to one of these.

  • Static universe; growth only via PayPal-funded region subscriptions. The galaxy does not expand on its own — no procedural new-sector generation at runtime, no in-place region resizing. New territory enters the universe only when a player (or operator) buys a Region Owner subscription, which provisions a new player-owned region and attaches it to the Central Nexus. This is the core monetization-architecture link: subscriptions buy persistent universe state, and the universe's size is a direct function of the subscriber base. Documented in detail in OPERATIONS/multi-regional.md and OPERATIONS/monetization.md.
  • Region is the unified ownership and governance unit. Every sector belongs to exactly one Region; cross-region travel goes through the Central Nexus warp-gate network; per-region governance (taxes, PvP rules, citizenship) is set by the region owner. Per ADR-0001.
  • Documentation is forward-looking; status lives in FEATURES/. The rest of the repo describes the target state in present tense; implementation status lives inline in FEATURES/ via four markers (✅ / 🚧 / 📐 / 🐛). See CONTRIBUTING.md for the full convention.

Sections

  • Features

    What the game does — gameplay, economy, galaxy, planets. The only section that tracks implementation status (✅ / 🚧 / 📐 / 🐛).

  • Systems

    How each subsystem works under the hood: combat resolver, market pricing, turn regeneration, ARIA dialogue, regional governance, bang import.

  • Data Models

    What is persisted: entities, schema, JSONB key shapes, migrations.

  • Architecture

    Where it runs: services, deployment, dev environment, auth, async workers, multi-regional topology.

  • Operations

    Running edges: AI assistant, web UIs, real-time bus, monetization, retention, i18n, bang integration.

  • Foundations

    Glossary, contributing conventions, testing policy, architecture decision records (ADRs).

Reading the status markers

Features is the single source of truth for what's shipped. Every other section describes the target state — "how it should work" — without status badges.

Marker Meaning
✅ Shipped Implemented and behaving as specified.
🚧 Partial Code exists but is incomplete or behind a flag.
📐 Design-only Specified here; no code yet.
🐛 Bug Implemented, but live behaviour diverges from this spec.

API reference

The REST surface is auto-published by the gameserver — there's no mirror here:

  • Swagger UI — <api-host>/docs
  • ReDoc — <api-host>/redoc
  • OpenAPI JSON — <api-host>/openapi.json

The WebSocket protocol is designed in Systems / Realtime Bus. Auth conventions live in Architecture / Auth.

Source repos