MMO Project is organized around three main components that each own a clearly bounded part of the system. The C#/.NET 8 backend is the single source of truth for all gameplay state: it resolves movement, enforces inventory and equipment rules, manages session lifecycle, and persists every character mutation to PostgreSQL. The Godot 4 client captures player intent, renders the world, and applies authoritative responses from the server — it never mutates game state locally. Between them, a versioned WebSocket JSON protocol (protocol v1) defines the complete message surface that both sides agree on before any implementation begins.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/TaylorZaneKirk/MMO-Project/llms.txt
Use this file to discover all available pages before exploring further.
Repository layout
The repository is divided into focused directories that map directly onto the system’s responsibilities:| Directory | Purpose |
|---|---|
prototype/server/ | C#/.NET 8 authoritative backend: services, handlers, infrastructure, and the WebSocket host |
prototype/client/ | Godot 4 GDScript client: screens, controllers, state store, transport, and actor scenes |
prototype/shared/ | Protocol contracts, world maps, and domain notes shared across both sides |
prototype/sql/ | PostgreSQL migration scripts applied in numeric order to build the prototype schema |
prototype/importer/ | Map import tools and fixtures used to load world data into the database |
prototype/tests/ | Verification scripts and checklists for the prototype checkpoint |
docs/modernization/ | Legacy system specification documents: inventory, protocol catalog, feature parity, security findings, and gameplay rules |
tools/ | Shell scripts for launching and validating the Godot client (run-godot-client.sh, run-godot-editor.sh, validate-godot-client.sh) |
Server layers
The backend is structured in three layers that keep gameplay logic independent from transport and persistence details.| Layer | Directory | Responsibilities |
|---|---|---|
| Application | application/ | Domain services: LoginService, CharacterLoadService, EnterWorldService, MovementService, InventoryItemUseService, InventoryItemDropService, GroundItemPickupService, EquipmentItemUnequipService, ReconnectService, LogoutService, WorldSnapshotService, NpcRuntimeService, CharacterStateCommitService, RuntimeRevisionService, and background workers (ZoneSimulationWorker, GroundItemVisibilityWorker, CharacterWorldStateSaveWorker) |
| Host | host/ | WebSocket endpoint (SessionEndpoint), authenticated message router (AuthenticatedMessageRouter), individual message handlers (MovementMessageHandler, UseInventoryItemHandler, DropInventoryItemHandler, PickupGroundItemHandler, UnequipItemHandler, WorldResyncRequestHandler, LogoutMessageHandler), and session/broadcast infrastructure (AuthenticatedSessionRunner, SessionLifecycleService, SessionHandshakeCoordinator, MapBroadcastService) |
| Infrastructure | infrastructure/ | PostgreSQL repositories (AccountRepository, CharacterRepository, CharacterStatsRepository, CharacterInventoryRepository, CharacterEquipmentRepository, MapPresenceRepository, SessionRepository, GroundItemRepository, RuntimeRevisionRepository), protocol payload mappers, and the database connection (PrototypeDatabase) |
Client layers
The Godot client is organized around runtime ownership boundaries that keep transport, state, and presentation separate.| Directory | Contents |
|---|---|
screens/ | Top-level scene flows: LoginScreen (credential input and login handshake) and GameScreen (world rendering and session wiring) |
screens/game/controllers/ | Controllers scoped to GameScreen: HudController, PlayerInteractionController, LocalPlayerController, InventoryPanelController, EquipmentPanelController, NpcController, ContextMenuController, GroundItemController, and RemotePlayerController |
screens/game/state/ | GameSessionPresenter — classifies raw WebSocket messages and forwards authoritative state into the store; GameStateStore — owns snapshot and delta state for the local player, ground items, NPCs, and remote players, and tracks character_revision and map_revision to detect stale delta streams |
network/ | WebSocket and session transport (session_client.gd) |
session/ | Autoloaded client session state (session_state.gd) — holds the active session token and account identity across scene transitions |
actors/ | Reusable player and NPC composite scenes with layered equipment and direction-aware sprite composition |
world/ | Map view and movement boundary scaffolds, intended to become reusable world presentation code as the prototype matures |
GameSessionPresenter before reaching any controller or renderer. Controllers receive state updates through GameStateStore signals rather than applying raw socket payloads directly. This keeps all revision tracking and duplicate-detection logic in one place.
Design principles
The following principles guide every implementation decision in MMO Project. They are drawn directly from the project’s modernization roadmap and apply equally to server, client, and tooling work.- Treat the legacy system as evidence, not as an architecture template. The original Director 8.5 source is the behavioral specification for the rewrite, not a codebase to port line by line.
- Preserve behavior intentionally; do not preserve vulnerabilities accidentally. Client-authoritative exploits, plaintext passwords, and unauthenticated administrative commands must not be recreated.
- Keep gameplay rules independent from rendering, transport, and persistence. Application services must not depend on WebSocket message shapes or PostgreSQL query details.
- Validate every migrated data format with repeatable import tests. Map data, item definitions, and character records must pass referential-integrity checks before they reach the game.
- Make all economy-changing operations transactional and auditable. Inventory mutations, equip/unequip, drops, pickups, and any future trade or banking operations must be atomic.
- Prefer one playable end-to-end path over many disconnected partial systems. The vertical-slice gate prevents a long, untestable rewrite.
- Keep generated extraction output separate from handwritten modernization code. Legacy extraction artifacts live under
fso-dir-lab/and must not be mixed with authored implementation work. - Do not place secrets, passwords, private keys, or production credentials in the repository. All sensitive configuration is kept out of version control.
Proposed decisions — Godot client, C#/.NET backend, PostgreSQL, WebSocket transport — become confirmed only after prototype validation. The Phase 2 prototype exists specifically to produce that validation evidence before broader implementation work begins.