Phosphorite

Phosphorite turns your table into a live sci-fi space station bridge: a retro terminal emulator where every player can experience a living spacecraft that evolves as you play. You can run it from a laptop or host it on a dedicated server, and start playing right away.

It lets a Game Master craft a fully controllable and cinematic player experience: live telemetry to monitor, fictional file systems to untangle, broadcasts and private comms, and AI‑powered NPCs - all interacting in real time between game master and players.

Phosphorite includes:

• telemetry simulations with warnings and alarms
• a full terminal app with files, scripts, and customizable commands
• configurable LLM chat agents with custom endpoints/models
• live messaging and broadcast overlays
• tactical maps with layers and markers
• rich theme presets and visual effects
• ... and many more awesome features!

Support This Project

While this is not my day job, a lot of time and effort went into building Phosphorite. If you find it useful for your games, consider buying me a coffee! Your support helps me dedicate more time to improving Phosphorite and creating more awesome open-source tools like this one.

Quick Launch

Note: The launcher binaries are unsigned (code signing certificates are not free, and this is a hobby project), so your OS may show a security warning on first launch; you can safely dismiss it. The full source code is public if you'd like to verify it yourself, and Docker is always an alternative if you prefer not to run unsigned binaries.

1. Download the latest archive from GitHub Releases.
2. Extract it anywhere on your machine.
3. Start the single GUI launcher entry point for your OS:
   • Windows: Phosphorite Launcher.exe
   • macOS: Phosphorite Launcher.app
   • Linux: extracted launcher binary

From the launcher UI you can set ports, start/stop each service, start/stop all services, and copy the LAN addresses for players.

Running with Docker

cp .env.example .env   # if you haven't already
docker compose up --build

The compose file builds images and exposes the same configurable ports.

Features

The game includes a substantial number of features, and I did my best to make both the GM and Player interfaces as straightforward as possible. Most interface elements can be hovered over with the mouse to display a short explanation of their purpose and usage. This is not intended as a replacement for proper documentation, on which I am still working and will eventually release.

For a tutorial focused on how to start and run a game with Phosphorite, please see docs/tutorial.md.

Game Time

Control the in‑universe clock and keep every client in sync. The GM can pause, resume, set, advance, or roll back time (era/day/hour/minute/second), and telemetry simulations tick along with it.

Characters

Create player logins, manage bios and narrative hooks, and monitor player activity (current app, section, last activity) in real time. You can also toggle whether a character has access to comms.

Temporary Visual Effects

Layer cinematic effects onto a player’s terminal at any moment: break their screen, make it flicker, have their text glitch. Great for jump scares, damage events, and narrative beats.

Messaging

In‑universe mailing system. The GM can send messages to any recipients, and players can compose their own messages to other characters (if enabled). The GM can monitor and control all conversation (which is awesome if you like to gaslight your players).

Broadcasts

Push full‑screen, time‑limited broadcasts to selected players: either a text transmission or an image. Perfect for alerts, mission updates, or atmospheric interludes.

Apps

Apps are the main building blocks of Phosphorite. The GM can create, reorder, and customize apps, and set which players can access each one. Each app category has a different purpose, and provides a different interface to both the GM and the players:

Text

Contains a simple long‑form text payload (AKA lore drop).

Image

Contains a single image payload (under 3 MB).

Logbook

Build time‑stamped log entries (severity‑coded) and let players browse by time to find out what happened in the past.

Map

Create tactical maps with layers and markers. Players can cycle layers client‑side while you update the scene live.

Telemetry

Define monitoring groups with numerical and textual parameters. Values simulate toward targets with some noise, and clients show them in real-time along their nominal/warning/critical state.

Terminal

Build a faux filesystem, add custom commands, and decide whether each command auto‑responds or requires a manual response from the GM.

AI chat

Configure one or more chat presets (based on OpenAI API) and let players speak with in‑world agents. The GM can review interaction history.

Each agent has access to public information (telemetry readings, log entries) and private information (character narrative hooks and their comms). Please note that AI agents can easily spiral into extreme hallucinations when told they are an NPC on board of a fictional space station, so I suggest to use this with caution!

Themes

Tune the player terminal look and feel: color palette, gradients, glows, typography, and cinematic overlays. Includes multiple presets and a preview of what the players will see.

Exporting and Importing Game Data

Export or import snapshots of your games. The gamestate panel lets you pick exactly which information to include in your exports and imports, preview data, and restore. Please note that any import will overwrite the current contents of the affected sections!

Architecture

Phosphorite is composed by three services that talk to each other in real-time:

• the backend, which helps keeping everything in sync (Express + Socket.IO API with a SQLite database and TypeScript)
• the Game Master dashboard (Vite + React) gives full control over the simulation
• the Player Terminal (Vite + React) offers a terminal-like interface for players to interact with

Each package is independent; the root package.json only coordinates installs and scripts.

Troubleshooting

• Ports busy: edit .env with free ports or stop conflicting processes.
• Database locked: stop all running backends and delete backend/data/phosphorite.db (it will be recreated, but game data will be lost).
• WebSocket errors: ensure the backend is reachable at the host/port the clients proxy to (PHOS_BACKEND_ORIGIN if set).

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Inspired by redhg/phosphor - a brilliant implementation of a terminal for running The Haunting of Ypsilon 14.