# ModBison (Project & Agent Guidelines)

> **CRITICAL REBRANDING NOTICE**
> - **Game Name**: **ModBison** (formerly `agp-game`).
>   - "ModBison" represents a play on game modification and the 1960s British "mod" subculture, adhering to the user's "bison" project naming convention (e.g. host machine `cloudbison`, Windows client machine `pinkbison`, social platform `WiseBison`).
> - **In-Game Currency**: **Buffalo Chips** (formerly `Credits` / `CR`).
>   - Named playfully after bison poop. Displayed throughout all UI menus, wallet, marketplace, and creator payout screens as "Buffalo Chips".
> - **Git Repository**:
>   - Local clone path: `/home/daddy/modbison` (symlinked as `/home/daddy/agp-game-dev` for backwards compatibility).
>   - Gitea repository name: `modbison`
>   - Clone URL: `http://localhost:3000/daddy/modbison.git`
>   - Web UI: `https://git.cloudbison.duckdns.org/daddy/modbison`
> - **Binaries & Exports**:
>   - Windows: `modbison.exe` (legacy alias `agp-game.exe` maintained for backwards compatibility)
>   - Linux: `modbison.x86_64`

---

## Architecture Overview

1. **Client**: Godot 4.6.2 (GDScript).
   - Headless engine binary located at `~/godot/godot`.
   - Export presets defined in `export_presets.cfg`.
   - Main scenes in `res://scenes/` (`main_menu.tscn`, `world_3d.tscn`, `wallet_ui.tscn`, `marketplace_ui.tscn`, `selling_payout_ui.tscn`, etc.).
   - Scripts in `res://scripts/`.

2. **Backend**: FastAPI + SQLAlchemy (asyncpg) + Alembic in `backend/`.
   - Python environment: `/home/daddy/agp/venv` (or project `.venv`).
   - Runtime game server supervisor allocates headless Godot instances per active world session under `/tmp/modbison-game-servers`.

3. **Orchestration & Playtesting (`/home/daddy/agp`)**:
   - PM Dashboard: `http://localhost:7070` (`agp-dashboard.service`).
   - Checkpoint system: `pm/checkpoint_ops.py` controls playtest instances (`PC1` through `PC5`).
   - Current active checkpoint: **PC5** (backend on `http://192.168.58.138:28005`, postgres on `25545`).
   - Building Windows package: `PYTHONPATH=. /home/daddy/agp/venv/bin/python3 -c "import pm.checkpoint_ops as ops; ops.build_exe('PC5')"`

4. **Testing Protocols**:
   - Headless smoke tests: `AGP_API_BASE_URL=http://127.0.0.1:28005 ~/godot/godot --headless --path . --script res://scripts/smoke_test_<name>.gd`
   - Fast checkpoint tests: `PYTHONPATH=. /home/daddy/agp/venv/bin/python3 scripts/run_checkpoint_tests.py --skip-backend --filter <keyword>`
   - Backend pytest: `PYTHONPATH=. /home/daddy/agp/venv/bin/pytest backend/tests`