modbison/docs/checkpoints/PC4.md

Package Checkpoint 4 (PC4) — "A world you can build and be social in"

Status: Complete & Verified. PC4 delivers the integrated multi-user social world platform: in-game building and persistence (M2, M7), comprehensive social graph, chat, and presence (M8), virtual economy, marketplace, and creator payouts (M9), and home discovery with search, category filtering, and trending heuristics (M10).

Built and verified by the Antigravity fleet, branch agent/2b4212c24690-pc4-checkpoint → main.

---

1. What's Real and Verified (scripts/run_checkpoint_tests.py)

Check / Subsystem	Status	Verification Detail
Alembic Migrations (0001 → 0015)	PASS	Hermetic clean run, head revision 0015_add_discovery_metadata
Backend API Test Suite	PASS	100+ tests across auth, worlds, social, chat, wallet, marketplace, discovery
Godot Headless Smoke Tests	PASS	20+ headless smoke suites covering all UIs, network, avatars, economy, discovery
2-Player Multiplayer (run_multiplayer_2p_test.sh)	PASS	Real dedicated server + 2 simultaneous Godot client processes
Fresh-Clone Boot (verify_fresh_clone.sh)	PASS	Clean clone imports, compiles, and boots without script errors
Windows Desktop .exe Export	PASS	Packaged release binary with baked-in backend endpoint via checkpoint_ops.py

---

2. Milestone Capabilities Included

M2 & M7 — World Persistence & In-Game Editor

• Server Persistence: World rooms, chunk coordinates (cx, cy, cz), binary chunk payload codec, chunk revision audit trail.
• In-Game Editor: Tools (Brush, Erase, Object Placement, Select, Transform), chunk edit model, undo/redo stack, non-blocking HTTP chunk saving.

M8 — Social: Friends, Presence, Chat, Groups & Profiles

• Social Graph: Friend requests (pending, accepted, declined), follow/unfollow, bidirectional block enforcement.
• Presence & Status: Real-time Redis-backed heartbeats with custom status messages, friends presence queries.
• Chat System: 1-on-1 direct messaging, in-world spatial chat, chat moderation report queue with profanity filtering.
• Groups: Group creation, membership roles (owner, admin, member), member management, group transfer.
• Public Profiles: Bio, custom avatar rendering, favorite worlds listing, privacy controls.
• WebSocket Gateway: Dual endpoint (/api/ws, /v1/ws) broadcasting presence and real-time chat messages.
• Godot Client & UIs: FriendsPresenceUI, ChatUI, ProfileUI, GroupsUI.

M9 — Economy: Wallets, Marketplace & Creator Payouts

• Wallets & Ledger: Double-entry accounting for balance credits, debits, transfers, and escrow.
• Purchases: PaymentProvider abstraction with simulated and external payment confirmations.
• Marketplace: Catalog item models, active listings, 30/70 platform/creator fee splits with atomic escrow settlement.
• Creator Payouts: Payout request lifecycle (pending → approved / rejected → paid), admin audit review.
• Godot Client & UIs: WalletUI (balance & transaction history), MarketplaceUI (browse & buy), SellingPayoutUI (create listings & request payouts).

M10 — Discovery: Browse, Search & Home Feed

• World Discovery Metadata: Categories, tags (ARRAY with GIN indexing), play count, and last played timestamp.
• Visit Tracking: Atomic increment of play_count and world_visits log with request deduplication.
• Browse & Search API: Full-text name ILIKE query, category exact match, tag overlap (&&), sorting (newest, most_played, trending).
• Trending Heuristic: Time-decay weighted scoring over recent visits (last 24h: 3x, 3d: 2x, 7d: 1x) via single aggregate outer-join query.
• Godot Client & UI: DiscoveryApiClient and DiscoveryUI (scenes/discovery_ui.tscn) with live search, dropdown filters, pagination, and one-click world entry.

---

3. Playtest Guide

1. Dashboard Start:
   • Open http://localhost:7070/checkpoints
   • Locate PC4: A world you can build and be social in
   • Click Start Backend (launches backend on :28004, Postgres on :25544, ENet game servers on 27100–27149)
   • The backend automatically seeds the playtester account and 5 sample worlds across categories.
2. Download & Play:
   • Click Download Windows .exe
   • Launch agp-game.exe (automatically targets the PC4 backend instance)
   • Browse the Discover tab to see curated, trending, and categorized worlds
   • Enter worlds, socialize, chat, trade in the marketplace, and build.