OpenStars!

A modern web reimagining of Stars! — the legendary 1995 turn-based 4X space strategy game.

The deployed version lives at https://openstars.timgage.co.uk/

What is this?

Stars! was a deeply complex, turn-based, play-by-email space strategy game that kept a devoted community playing for decades. It featured intricate race design, ship customisation, a detailed economic model, and a simultaneous-turn multiplayer system perfectly suited to asynchronous play.

OpenStars! aims to bring those mechanics to a modern web platform — faithful to the depth of the original, but with a contemporary UI and native browser-based multiplayer.

Project Structure

openstars/
├── frontend/                   # React + Vite SPA (TypeScript, Tailwind, shadcn/ui)
│   └── src/
│       ├── components/         # UI components (galaxy map, planet detail, fleet panels…)
│       ├── contexts/           # React contexts (game state, auth)
│       ├── hooks/              # Custom hooks
│       ├── api/                # Typed API client layer
│       └── types/              # Shared TypeScript types
│
├── backend/                    # Python API server (FastAPI, Pydantic, pytest)
│   └── openstars/
│       ├── server/             # FastAPI routes and request handling
│       ├── engine/             # Turn resolution engine (pure, stateless, fully testable)
│       └── models/             # Pydantic game-state models
│
├── docs/
│   ├── docs/prd/               # Product requirement documents (canonical game spec)
│   │   ├── 01-overview.md
│   │   ├── 02-galaxy-map.md
│   │   ├── 03-turn-lifecycle.md
│   │   ├── 10-fleet-movement.md
│   │   ├── 12-economy-and-resources.md
│   │   ├── 80-combat-fundamentals.md
│   │   └── …
│   └── docs/references/        # Original Stars! manual, battle engine notes, terminology
│       └── manual/             # Extracted Stars! manual
│
├── tasks/                      # Dated task files tracking in-progress and completed work
└── docker-compose.yaml

Architecture at a glance

The project follows a strict command-and-resolve model:

• The frontend is a pure order editor — it never runs game logic. Players issue commands (move fleet, set waypoints, queue production) which are collected and sent to the server.
• The backend engine receives all players' orders simultaneously and resolves them in a deterministic pipeline: (previousState, allOrders) → newState. The engine is entirely stateless and has no knowledge of HTTP.
• Clients receive fog-of-war-filtered state — the server is authoritative.

This keeps the engine independently testable and faithful to the original Stars! simultaneous-turn multiplayer model.

Running locally

Service	Command	Port
Backend API	cd backend && ./run.sh	8080
Frontend	cd frontend && npm run dev	5173

No database or external infrastructure required — game state lives in memory during development.

Licence

MIT License — see LICENSE.