docs: expand README with comprehensive architecture, features, and controls
checkpoint / checkpoint (push) Successful in 5m59s
checkpoint / checkpoint (push) Successful in 5m59s
This commit is contained in:
@@ -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).
|
||||
> **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`)
|
||||
Reference in New Issue
Block a user