# 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
```