# slayhorizon/godot-tiny-mmo architecture

> Architecture diagram of the GitHub repository slayhorizon/godot-tiny-mmo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/slayhorizon/godot-tiny-mmo
- Repository: https://github.com/slayhorizon/godot-tiny-mmo

## Overview

##### Project Type and Purpose
- This is a full-stack, experimental tiny-MMO game built with Godot 4.4.
- It lives in a single repo containing both client and server code.
- It uses a three-tier server architecture (Gateway, Master, World) plus a Godot client.

##### File Structure
- Top-level directories:
- addons/ – Godot plugins (inspector, property editor)
- source/ – the heart of the code:
– client/ (game UI, network client, autoloaded singletons, map objects, local player)
– common/ (shared entities, items, maps, network base classes, utilities)
– gateway_server/ (authentication & routing)
– master_server/ (account management, world/gateway registry, QAD DB)
– world_server/ (instances of maps, chat commands, game logic)
- test_config/ – example .cfg files for launching multiple instances with tags.
- project.godot & README.md – entrypoints and project summary.

##### README for Additional Insights
- It spells out the “Mimic real MMO-style architecture” with Gateway, Master, World servers.
- It highlights custom netcode (WebSocketMultiplayerPeer), shared codebase, separate export presets for client vs. servers.

##### Main Components
a. Client (Browser/Desktop)
– UI Layer: scenes and controls under source/client/ui & gateway/ui
– Local Player & Input (mouse_component, local_player.gd)
– Network Client: WebSocketMultiplayerPeer connecting to Gateway
– Common Entities & Resources for rendering
b. Gateway Server
– Accepts client WebSocket connections
– Performs Authentication & Account Creation (gateway_manager_client)
– Routes clients to Master server
c. Master Server
– Manages persistent account data (master_database, QAD database)
– Maintains world registry (world_manager_server)
– Coordinates between Gateway and World servers
d. World Server(s)
– Hosts one or more map instances (overworld, dungeon entrance, dungeon)
– Runs game logic (entities, health, attacks, chat commands)
– Instance management (instance_manager, instance_server)
– Writes/reads world-specific persistent data (world_database)
e. Shared Database
– QAD (lightweight file or in-memory database) backing Master and World servers
f. Shared Code Library
– source/common – Entities, network base classes, utilities, map templates

##### Relationships and Data Flows
- Client → Gateway: WebSocket handshake, authentication, version check
- Gateway → Master: RPCs for login, account creation, server list
- Master → Gateway: list of world servers with connection details
- Client → World Server: WebSocket connection to assigned world instance
- World Server ↔ World Database: persistent player and map state
- (Optional) World Server ↔ Master: heartbeats, registration

##### Architectural Patterns & Design Principles
- Tiered microservice-style separation: Gateway (auth & routing), Master (coordination), World (game logic)
- Shared code library under source/common for DRY across client & servers
- Autoload singletons for global state (source/client/autoload/events.gd)
- Configuration via tags and .cfg files for flexible multi-instance launches

##### Technologies, Frameworks, and Libraries
- Godot Engine 4.4 (GDScript, scenes, nodes)
- WebSocketMultiplayerPeer for custom netcode
- QAD or simple file-based persistence for server data
- .cfg files and command-line flags for run instances

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client" 
        direction TB
        CM["Client Main"]:::client
        AS["Autoload Singletons"]:::client
        UI["UI Layer"]:::client
        LP["Local Player & Input"]:::client
        NC["Network Client"]:::client
    end

    %% Server Layers
    subgraph "Gateway Server"
        direction TB
        GM["Gateway Main"]:::server
        GL["Gateway Logic"]:::server
        AG["Auth & Routing Client"]:::server
        ET["Expiration Timer"]:::server
    end

    subgraph "Master Server"
        direction TB
        MM["Master Main"]:::server
        AM["Authentication Manager"]:::server
        GR["Gateway Registry"]:::server
        WR["World Registry"]:::server
        MDB["Master Database"]:::db
    end

    subgraph "World Servers"
        direction TB
        WM["World Main"]:::server
        WL["World Logic"]:::server
        IM["Instance Management"]:::server
        CC["Chat Command Handlers"]:::server
        WDB["World Database"]:::db
        WMC["World Manager Client"]:::server
    end

    %% Shared Components
    SC["Shared Code Library"]:::shared
    SDB["Shared DB (QAD)"]:::db

    %% Connections
    CM --> AS
    AS --> UI
    UI --> LP
    LP --> NC
    NC -->|"WebSocket"| GM
    GM --> AG
    AG --> GL
    GL --> ET
    GL --> MM
    MM --> AM
    AM --> MDB
    MM --> GR
    GR --> WR
    WR --> MM
    WR --> WM
    WM --> WL
    WL --> IM
    IM --> CC
    CC --> WDB
    WM --> WMC
    WMC --> WR
    SDB --> MDB
    SDB --> WDB
    SC --> CM
    SC --> GM
    SC --> MM
    SC --> WM

    %% Click Events - Client
    click CM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/client_main.gd"
    click CM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/client_main.tscn"
    click AS "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/autoload/events.gd"
    click UI "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/client/ui"
    click LP "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/local_player/local_player.gd"
    click LP "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/local_player/mouse_component.gd"
    click NC "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/gateway/client/gateway_client.gd"
    click NC "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/client/gateway/client/gateway_client.tscn"

    %% Click Events - Shared Code
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/common"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/common/entities"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/common/network/base_client.gd"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/common/network/base_server.gd"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/common/maps"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/common/maps/map_template/map_template.tscn"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/common/utils"
    click SC "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/common/resources"

    %% Click Events - Gateway Server
    click GM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/gateway_server/gateway_main.gd"
    click GM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/gateway_server/gateway_main.tscn"
    click GL "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/gateway_server/components/gateway_server/gateway_server.gd"
    click AG "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/gateway_server/components/gateway_manager_client.gd"
    click ET "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/gateway_server/components/gateway_server/expiration_timer/expiration_timer.gd"

    %% Click Events - Master Server
    click MM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/master_main.gd"
    click MM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/master_main.tscn"
    click AM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/components/authentication_manager.gd"
    click AM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/resources/account.gd"
    click AM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/resources/account_collection.gd"
    click MDB "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/components/master_database.gd"
    click GR "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/components/gateway_manager_server.gd"
    click WR "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/components/world_manager_server.gd"
    click AM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/master_server/account_collection.tres"

    %% Click Events - World Server
    click WM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/world_main.gd"
    click WM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/world_main.tscn"
    click WL "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/components/world_server.gd"
    click IM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/components/instance_manager.gd"
    click IM "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/components/instance_server.gd"
    click CC "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/world_server/components/chat_command"
    click WDB "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/components/world_database.gd"
    click WMC "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/source/world_server/components/world_manager_client.gd"
    click WDB "https://github.com/slayhorizon/godot-tiny-mmo/tree/main/source/world_server/data"

    %% Click Events - Test Config
    click SDB "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/test_config/client_config.cfg"
    click SDB "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/test_config/gateway_config.cfg"
    click SDB "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/test_config/master_server_config.cfg"
    click SDB "https://github.com/slayhorizon/godot-tiny-mmo/blob/main/test_config/world_server_config.cfg"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064;
    classDef server fill:#E8F5E9,stroke:#1B5E20;
    classDef shared fill:#ECEFF1,stroke:#37474F;
    classDef db fill:#FFF3E0,stroke:#E65100;
```
