diff --git a/README.md b/README.md index 30a5147..8df1cfc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,129 @@ # ModBison -ModBison (formerly agp-game) - Godot 4 multiplayer game with customizable avatars, world building, social features, and virtual economy (Buffalo Chips). \ No newline at end of file +> **Godot 4 Multiplayer Sandbox Platform** +> Customizable 3D avatars, real-time multiplayer worlds, in-game building tools, social community hubs, and a creator economy powered by **Buffalo Chips**. + +--- + +## 🦬 About ModBison + +**ModBison** (formerly `agp-game`) is a collaborative sandbox game and platform built in Godot 4 and Python FastAPI. + +* **The Name**: "ModBison" is a double play on game modification and the 1960s British "mod" youth subculture, aligning with the host and infrastructure naming convention (`cloudbison`, `pinkbison`, `WiseBison`). +* **The Currency**: **Buffalo Chips** — the in-game virtual currency used for marketplace trading, creator selling, and cash payouts (a playful reference to bison poop). + +--- + +## 🏛️ Architecture Overview + +The platform consists of two integrated environments: + +1. **Client & Game Server (`modbison`)**: + - Built with **Godot 4.6.2** (GDScript). + - Headless Godot dedicated server (`scenes/server.tscn`) spawned per active world session via high ENet ports. + - Dual-platform export configuration: Windows Desktop (`modbison.exe`) and Linux (`modbison.x86_64`). + - Binary chunk streaming and client-side interpolation. + +2. **Backend & Orchestration Platform (`agp`)**: + - **FastAPI** (Python 3.12) REST API with **PostgreSQL** (asyncpg) and **Alembic** migrations. + - **Redis** for real-time presence heartbeats and pub/sub messaging. + - **Game Server Supervisor**: Dynamic headless Godot instance orchestrator allocating runtime servers in `/tmp/modbison-game-servers`. + - **PM Dashboard & Checkpoints**: Live orchestration dashboard running at `http://localhost:7070` managing Package Checkpoints (**PC1** through **PC4**). + +--- + +## ✨ What Has Been Built (Feature Summary) + +### 1. 👤 3D Avatar & Customization Engine +* **Canonical Rig**: 24-bone skeleton supporting attachment sockets for Head, Hair, Face, Chest, Pants, Left/Right Hand, Left/Right Foot, and Accessories. +* **Customization Studio** (`scenes/avatar_customization.tscn`): Full 3D turntable preview, orbit camera controls, slot-based equipment, RGB tint pickers, and backend persistence (`/api/avatar/loadout`). +* **Multiplayer Replication**: Remote players receive complete avatar loadout dictionaries via RPC upon joining, dynamically assembling meshes and materials in real time. +* **Solid Double-Sided Rendering**: Fixed polygon winding order and material setups to ensure characters render fully solid from all camera angles. + +### 2. 🌍 Multiplayer World & Chunk Streaming +* **Dedicated Server Architecture**: Server-authoritative player movement, client prediction, reconciliation, and collision boundaries. +* **Chunk Streaming**: Binary stream encoding/decoding (`chunk_codec.py` / `chunk_data_decoder.gd`) enabling real-time streaming of world geometry, collision boxes, and dynamic props as players explore. +* **Stable Spawn System**: Server-authoritative solid ground anchoring ensuring players never fall into the void upon connection. + +### 3. 🛠️ In-Game World Editor & Sandboxed Scripting +* **Runtime World Editor** (`scripts/editor/`): In-game tool registry, block/prop palette, selection manager, raycast placement/deletion, and undo/redo action stacks. +* **Chunk Persistence** (`chunk_save_service.gd`): Saves player modifications and created structures back to the world backend. +* **Rule-Based Scripting** (`scripts/scripting/`): Sandboxed behavior interpreter (`script_interpreter.gd`, `script_rule.gd`) allowing props to trigger gameplay actions, inventory changes, and spawn events. +* **In-Game HUD Bar**: Hotkey-driven overlay bar giving players instant access to build tools and menus while inside a live world. + +### 4. 👥 Social, Chat & Clans +* **Friends & Presence** (`scenes/friends_presence_ui.tscn`): Friend requests, accept/decline flows, and live online/in-world presence heartbeats via Redis. +* **Multi-Channel Chat** (`scenes/chat_ui.tscn`): Direct messaging (DM), group chat, and spatial in-world chat with automated text filtering (`text_filter.py`). +* **Groups & Clans** (`scenes/groups_ui.tscn`): Group creation, member roles, descriptions, and membership rosters. + +### 5. 💰 Virtual Economy & Creator Payouts +* **In-Game Currency**: **Buffalo Chips** displayed across all menus, wallets, listings, and payout screens. +* **Wallet UI** (`scenes/wallet_ui.tscn`): Live balance display, quick-purchase packs (+100, +500, +1,000, +5,000 Buffalo Chips), and transaction history ledger. +* **Marketplace UI** (`scenes/marketplace_ui.tscn`): Browse items for sale, filter by price in Buffalo Chips, search catalog, and instant purchase with inventory delivery. +* **Creator Selling & Payouts** (`scenes/selling_payout_ui.tscn`): Catalog item listing, price configuration, escrow tracking (Available, In Escrow, Lifetime Earned), and cash payout requests (minimum 100 Buffalo Chips). + +### 6. 🌐 Discovery & Catalog +* **World Discovery UI** (`scenes/discovery_ui.tscn`): Public world browser with search by title, tags, or category. +* **Trending Algorithm**: Decay-weighted play counts ranking popular worlds on the discovery front page. + +--- + +## 🎮 In-Game Controls & Hotkeys + +| Key | Action | +| :--- | :--- | +| **`W` `A` `S` `D`** | Move character | +| **`Space`** | Jump | +| **`Mouse`** | Look / Camera rotation | +| **`T`** or **`Enter`** | Open Chat | +| **`Tab`** or **`F1`** | Open Friends & Social Panel | +| **`F2`** | Toggle In-Game World Editor | +| **`ESC`** | Close current modal / Toggle In-Game HUD Menu | + +--- + +## 🚀 Development, Testing & Builds + +### Automated Smoke Tests (Headless Godot) +All UI panels and client subsystems have headless GDScript smoke tests: +```bash +# Set target backend (e.g. PC4 playtest instance) +export AGP_API_BASE_URL=http://127.0.0.1:28004 + +# Run individual UI & subsystem smoke tests +~/godot/godot --headless --path . --script res://scripts/smoke_test_main_menu_full_flow.gd +~/godot/godot --headless --path . --script res://scripts/smoke_test_marketplace_ui.gd +~/godot/godot --headless --path . --script res://scripts/smoke_test_wallet_ui.gd +~/godot/godot --headless --path . --script res://scripts/smoke_test_selling_payout_ui.gd +~/godot/godot --headless --path . --script res://scripts/smoke_test_avatar_in_world.gd +``` + +### Backend Test Suite +```bash +# Run 335+ FastAPI & SQLAlchemy test suite +PYTHONPATH=. /home/daddy/agp/venv/bin/pytest backend/tests +``` + +### Building Release Binaries +```bash +# Export Linux and Windows binaries +scripts/build.sh + +# Or build pre-configured Windows package for current checkpoint (PC4): +PYTHONPATH=. /home/daddy/agp/venv/bin/python3 -c "import pm.checkpoint_ops as ops; ops.build_exe('PC4')" +``` +Output artifacts: +- Windows: `export/windows/modbison.exe` (or `agp/playtest/PC4/build/windows/modbison.exe`) +- Linux: `export/linux/modbison.x86_64` + +--- + +## 📦 Project Links & Configuration + +* **Gitea Repository**: `http://localhost:3000/daddy/modbison.git` +* **Web Interface**: [https://git.cloudbison.duckdns.org/daddy/modbison](https://git.cloudbison.duckdns.org/daddy/modbison) +* **Active Playtest Instance**: **PC4** + - Backend URL: `http://192.168.58.138:28004` + - Database: PostgreSQL on port `25544` +* **PM Dashboard**: `http://localhost:7070` +* **Working Directory**: `/home/daddy/modbison` (symlinked as `/home/daddy/agp-game-dev`) \ No newline at end of file