141 lines
4.4 KiB
Markdown
141 lines
4.4 KiB
Markdown
# Rats with Gats Remote Play (`pirats`)
|
|
|
|
A web-based remote play companion app for the tabletop roleplaying game **Rats with Gats** (where players roleplay as space-faring pirate rats, or "Pi-Rats"). The application manages lobbies, character creation, card mechanics, scene phases, obstacles, challenges, and player voting.
|
|
|
|
It is built with **FastAPI**, **SQLModel** (SQLite database), **Jinja2 templates**, and **HTMX** for dynamic, real-time page updates.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Game Lobby:** Create games and join as players via a unique game ID.
|
|
- **Character Creation:**
|
|
- Fill out the character profile (appearance, smell, catchphrase).
|
|
- Delegate custom "Like/Hate" relationship questionnaire cards to other crewmates (answering them for each other!).
|
|
- Draft three "Secret Pirate Techniques" which are automatically shuffled and swapped among players.
|
|
- Bind swapped techniques to Face Cards (Jack, Queen, King) for play.
|
|
- **Dynamic Card Mechanics:**
|
|
- Automated 54-card deck shuffling and card drawing.
|
|
- Automatically matches card suits to thematic obstacles (Clubs for combat, Spades for stealth/cunning, Hearts for social/morale, Diamonds for nautical/athletics).
|
|
- **Scene Management:**
|
|
- Assign roles (Pi-Rats or "The Deep" narrator).
|
|
- Dynamic challenge creation linking multiple active obstacles.
|
|
- Automatically handles card matching colors/values, automatic success when playing Face Card techniques, and Joker card triggers to discard/replace obstacles.
|
|
- **Between-Scenes Voting:**
|
|
- Vote on crewmates to rank up.
|
|
- Toggle personal objectives (Get a Gat, Earn a Name, Die like a Pirate).
|
|
|
|
---
|
|
|
|
## Installation & Running
|
|
|
|
This project supports standard Python package tools as well as Nix flakes.
|
|
|
|
### Option 1: Standard Python Installation
|
|
|
|
#### Prerequisites
|
|
- Python >= 3.9
|
|
- Virtual environment tool (optional but recommended)
|
|
|
|
#### 1. Setup Virtual Environment (Optional)
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
#### 2. Install Package
|
|
Install the package and its dependencies in editable mode:
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
#### 3. Run the App
|
|
Launch the FastAPI server using the installed package entrypoint:
|
|
```bash
|
|
pirats --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
Alternatively, run it with `uvicorn`:
|
|
```bash
|
|
uvicorn pirats.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
Once running, access the web UI at [http://localhost:8000](http://localhost:8000).
|
|
|
|
---
|
|
|
|
### Option 2: Using Nix Flakes
|
|
|
|
If you use the Nix package manager, this repository provides a complete environment.
|
|
|
|
#### 1. Enter the Development Shell
|
|
Includes Python, all runtime dependencies, and testing tools (`pytest`):
|
|
```bash
|
|
nix develop
|
|
```
|
|
|
|
#### 2. Run the Application
|
|
Run the package directly from the flake:
|
|
```bash
|
|
nix run . -- --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
#### 3. Build the Application Package
|
|
```bash
|
|
nix build .
|
|
```
|
|
The executable will be located in `./result/bin/pirats`.
|
|
|
|
---
|
|
|
|
## Deploying as a NixOS Service
|
|
|
|
The Nix flake exposes a NixOS module that configures the application to run as a systemd service with appropriate sandboxing.
|
|
|
|
Add this flake to your system configuration and configure the service:
|
|
|
|
```nix
|
|
services.pirats = {
|
|
enable = true;
|
|
host = "127.0.0.1";
|
|
port = 8000;
|
|
databasePath = "/var/lib/pirats/rats_with_gats.db";
|
|
openFirewall = false; # Set to true to open ports in the firewall
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
|
|
Tests are written using `pytest`.
|
|
|
|
### Running with Pip
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
### Running with Nix
|
|
```bash
|
|
nix develop --command pytest
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
pirats/
|
|
├── pyproject.toml # Python package metadata and dependencies
|
|
├── flake.nix # Nix package, dev shell, and NixOS service module
|
|
├── tests/ # Unit and integration tests
|
|
│ └── test_game.py # Game logic and CRUD database test suites
|
|
└── src/
|
|
└── pirats/ # Core Python package
|
|
├── main.py # FastAPI routes, HTTP endpoints, CLI entrypoint
|
|
├── crud.py # Core database CRUD, game mechanics, and transitions
|
|
├── models.py # SQLModel database tables (Game, Player, Obstacle, Challenge, Vote)
|
|
├── cards.py # Playing card parser, deck setups, and obstacle definitions
|
|
├── templates/ # Jinja2 HTML pages and HTMX snippets
|
|
└── static/ # CSS styles and frontend assets
|
|
```
|