modbison/AGENTS.md

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