Open-Source, Decentralized, Persistent Airline Management MMO on Nostr
ACARS is a real-world aviation simulation where players build and operate virtual airlines competing on actual routes worldwide. Built for millions of concurrent players with a fully deterministic, client-side game engine backed by the decentralized Nostr protocol.
- Deterministic Game Engine — O(1) macro-economic formulas (Gravity Model, QSI) for route demand and market share
- Fixed-Point Arithmetic — No floating-point drift; all financial calculations are cross-platform deterministic
- Nostr Integration — Decentralized identity via NIP-07, airline state stored as signed events with NIP-33 Snapshot Rollups for instant cross-device sync and state recovery.
- Relay-Backed Snapshots — Game state is compressed and attested via NIP-33 to avoid replaying thousands of historical events on every load.
- Real Airport Data — 6,072 airports from OpenFlights with population, GDP, and seasonal tags
- Interactive Globe — MapLibre GL map with virtualized airport selection
- Fleet Management — Purchase (BUY/LEASE), aircraft depreciation, and structural condition tracking
- Operations Ledger — Detailed financial event history persistent on Nostr (revenue/cost breakdowns)
- Maintenance System — Aircraft grounding based on wear-and-tear (Condition < 20%) or flight hours (>600h)
- Economic Safety Net — Chapter 11 bankruptcy status to pause operations during severe financial distress
- Suggested Pricing — Distance-aware fare intelligence with "Fix to Suggested" optimization shortcuts
- Route Scheduling — Real-time aircraft assignment and automated flight operations
- Corporate mechanics (IPO, M&A, stock trading, dividends)
- Alliance system with codeshares
- 3D CesiumJS cockpit view
- Procedural audio engine ("the music of your network")
- Bitcoin/Lightning monetization (Zaps, P2E pools)
┌──────────────┐
│ apps/web │ React 19 + Vite
│ (UI Layer) │
└──────┬───────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ @acars/map │ │ @acars/store │ │ @acars/nostr │
│ MapLibre GL │ │ Zustand │ │ NDK Adapter │
└──────────────┘ └──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ @acars/core │ │ @acars/data │
│ Pure Math │ │ Static Data │
│ Zero Deps │ │ Airports │
└──────────────┘ └──────────────┘
- No Central Database — All game state is a deterministic reduction of Nostr events
- 1:1 Real-Time — Game time equals UTC time; a 7-hour flight takes 7 real hours
- O(1) Math — Macro-economic formulas instead of passenger-by-passenger simulation
- Fixed-Point Only — Prevents floating-point desync across clients
- Virtualized UI — All lists use
@tanstack/react-virtualfor scale
- Node.js 20+
- pnpm 9+
- Optional: a NIP-07 browser extension (nos2x, Alby, or Nostr Connect). Not required — the app has a one-click guest-key onboarding flow that generates an in-browser keypair so you can play immediately (back it up later to secure the account).
# Clone the repository
git clone https://github.com/anabelle/acars.pub.git
cd acars
# Install dependencies
pnpm install
# Start development server
pnpm devOpen http://localhost:5173 and connect your Nostr extension to create your airline.
pnpm dev # Start web app in development mode
pnpm build # Build all packages
pnpm test # Run all workspace tests (one pass)
pnpm test:run # Run all workspace tests once (alias of test)
pnpm test:coverage # Run tests with coverage thresholds enforced
pnpm lint # Lint all packages
pnpm typecheck # Type-check all packages
pnpm clean # Remove all build artifactsThe web application can be built as a native Android app using Capacitor.
cd apps/web
pnpm run build # 1. Build the production web bundle
npx cap sync android # 2. Sync the web bundle into the Android project
npx cap open android # 3. Open Android Studio to build the .aab/.apkacars/
├── apps/
│ ├── web/ # React 19 frontend (TanStack Router)
│ │ └── src/
│ │ ├── app/ # Global app setup (Providers, Router)
│ │ ├── routes/ # TanStack Router file-based routes
│ │ ├── shared/ # Reusable UI (buttons, cards, layout)
│ │ └── features/ # Feature modules (fleet, network, etc.)
├── packages/
│ ├── core/ # Pure game engine (zero dependencies)
│ │ └── src/
│ │ ├── fixed-point.ts # Currency arithmetic
│ │ ├── demand.ts # Gravity model
│ │ ├── qsi.ts # Market share allocation
│ │ ├── finance.ts # Revenue & costs
│ │ ├── fleet.ts # Depreciation & book value
│ │ └── ...
│ ├── data/ # Static data catalogs
│ │ └── src/
│ │ ├── airports.ts # 6,072 airports
│ │ └── aircraft.ts # 35 aircraft models
│ ├── map/ # MapLibre GL components
│ │ └── src/Globe.tsx # Interactive globe with routes
│ ├── nostr/ # Nostr I/O layer (NDK)
│ └── store/ # Zustand state management
├── docs/
│ ├── DESIGN_PRINCIPLES.md # Gameplay vision & UI targets
│ ├── ECONOMIC_MODEL.md # Math behind demand, QSI, costs
│ ├── CORPORATE_MODEL.md # Wall Street mechanics (M&A, IPOs)
│ ├── FLEET_MANAGER_PLAN.md # Aircraft lifecycle
│ ├── MONETIZATION_MODEL.md # Bitcoin/Lightning revenue
│ ├── SCALABILITY.md # Map/rendering scaling strategy
│ └── ROADMAP.md # Development phases
├── .agent/ # Agent development coordination
└── AGENTS.md # AI agent onboarding guide
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite, TypeScript |
| State | Zustand |
| Map | MapLibre GL |
| Virtualization | @tanstack/react-virtual |
| Networking | Nostr (NDK) |
| Identity | NIP-07 (nos2x, Alby) |
| Testing | Vitest |
| Package Manager | pnpm workspaces |
Demand = K × (Pop_A^α × Pop_B^β × GDP_A^γ × GDP_B^δ) / Distance^θ
Where:
- K = 5.995e-7 (tuned against BOG routes)
- α, β = 0.8 (population exponents)
- γ = 0.6, δ = 0.3 (GDP exponents)
- θ = 1.0 (distance decay, linear)
Airlines compete on: price, frequency, travel time, stops, service quality, and brand reputation. Each factor is weighted differently for economy, business, and first-class passengers.
- Revenue: Ticket sales + ancillary ($20/pax)
- Costs: Fuel, crew, maintenance, airport fees, navigation, leasing, overhead
See docs/ECONOMIC_MODEL.md for full specification.
We welcome contributions! Please read:
AGENTS.md— Engineering rules and constraintsdocs/AGENT_DEVELOPMENT_PARADIGM.md— Branching, linting, testing guidelines
Every feature must answer: "If 10,000 players fire this event simultaneously, will it break the math, melt the DOM, or desync the Nostr state?"
| Document | Purpose |
|---|---|
| DESIGN_PRINCIPLES.md | Gameplay vision, engagement loops, sensory design |
| ECONOMIC_MODEL.md | Gravity model, QSI, fixed-point costs |
| CORPORATE_MODEL.md | IPOs, M&A, bankruptcy, stock mechanics |
| FLEET_MANAGER_PLAN.md | Aircraft depreciation, maintenance, commonality |
| MONETIZATION_MODEL.md | Bitcoin/Lightning revenue streams |
| SCALABILITY.md | Map/rendering scaling + NIP-33 snapshot rollups |
| UI_ARCHITECTURE.md | Frontend stack, cross-platform, tycoon density |
| AGENT_DEVELOPMENT_PARADIGM.md | Multi-agent coordination and safety contracts |
| RESEARCH_SOURCES.md | Bibliography and reference sources |
| ROADMAP.md | Development phases and milestones |
- Issues: use GitHub Issues for bugs and feature requests
- Security: see
SECURITY.md - Code of Conduct: see
CODE_OF_CONDUCT.md
Screenshots and short clips will be added as the UI stabilizes. If you'd like to contribute media, please open a PR with assets in docs/media.
MIT
The Prime Directive: Every commit must respect the millions-scale constraint. No O(N²) loops. No floating-point money. No central database. The game state must be reproducible from the Nostr event log alone.