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:

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.
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.

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:

# 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

# Run 335+ FastAPI & SQLAlchemy test suite
PYTHONPATH=. /home/daddy/agp/venv/bin/pytest backend/tests

Building Release Binaries

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

README.md

ModBison