An immersive spaceship bridge console for tabletop RPG campaigns.
Starship HUD is a web application that gives your tabletop spaceship a real bridge console interface. Players see station-specific displays with live status indicators, alerts, and controls. The GM controls the narrative behind the scenes—triggering damage, spawning contacts, and scripting dramatic moments. Your ship becomes a character with moods, damage states, and evolving conditions.
Getting Starship HUD running takes about 5 minutes.
You need Docker installed on your computer. Docker runs the application in a container—think of it as a self-contained package that has everything the app needs.
New to Docker? Download Docker Desktop for Windows, Mac, or Linux. Install it, start it, and you're ready.
-
Download the project
Clone the repository (or download and extract the ZIP):
git clone <repository-url> cd starship-hud
-
Start the application
docker compose up -d
The first time you run this, Docker will download and build everything. This takes a few minutes. Subsequent starts are nearly instant.
-
Open your browser
Go to
http://localhost:7891You'll see the demo ship, ISV Constellation, ready to explore.
That's it! The application comes pre-loaded with a demo ship so you can start exploring immediately.
# Stop the application
docker compose down
# Start it again
docker compose up -d
# View logs if something seems wrong
docker compose logs -fAs the GM, you control the ship behind the scenes:
- Design custom panels for each bridge station using 22 different widgets
- Script dramatic moments with the scenario system—trigger damage cascades, spawn contacts, send distress calls
- Control systems in real-time through the admin panel
- Send transmissions that appear on player consoles
See the GM Guide for a complete walkthrough.
As a player, you interact with an immersive bridge console:
- Monitor your station through dedicated panels (Engineering, Helm, Operations, etc.)
- See live status updates with color-coded indicators and alerts
- Complete tasks that appear when systems need attention
- Track contacts with threat indicators and detailed dossiers
See the Player Guide to understand the interface.
Starship HUD comes with a demo ship, but it's designed to be yours:
- Use as much or as little as you want—start with one panel or build out the whole bridge
- Create panels for your crew's roles—not every game needs the same stations
- Build scenarios for your campaign—the drama engine adapts to your story
- Define your own systems—track whatever matters for your ship
The demo ship is a starting point. Delete it and build your own, or modify it to fit your setting.
- Installation Guide — Detailed setup including Unraid deployment
- First Run — What to do after installation
- GM Guide — Running sessions and managing the ship
- Player Guide — Understanding the bridge console
- Panels — Designing and building panels
- Widgets — Reference for all 22 widget types
- Scenarios — Scripting dramatic moments
- Status States — The visual language of ship status
- Data Model — How objects relate to each other
Want to contribute or run from source? See CONTRIBUTING.md for development setup instructions.
The short version: you'll need Node.js 20+, Python 3.12+, and uv. Run just setup then just dev.
This project is in early development and feedback is welcome!
- Found a bug? Open an issue on GitHub
- Have a feature idea? Start a discussion
- Questions? Check the documentation or open a discussion
Private project for tabletop gaming use.