Run the MMO Project server, database, and client locally

By the end of this guide you will have a locally running MMO Project server connected to a PostgreSQL database, with a Godot 4 desktop client successfully logged in and rendering the game world. You will be able to move your character, interact with your inventory and equipment, and observe live NPC and remote-player updates — all driven by the authoritative C#/.NET 8 backend.

Prerequisites

Before you begin, make sure the following tools are installed and available on your PATH:

.NET 8 SDK — required to build and run the prototype server
PostgreSQL 14 or later — the server connects to a local instance by default
Godot 4.x (desktop, Mono build) — the client is a Godot 4 GDScript project; the shell scripts expect the binary under tools/godot/
git — to clone the repository

Steps

Clone the repository

Clone the project from GitHub and enter the repository root. All subsequent commands in this guide are run from that root unless stated otherwise.

git clone https://github.com/TaylorZaneKirk/MMO-Project.git
cd MMO-Project

Apply the database schema

Create the mmo_project_proto database and apply all ten migration scripts in order. Each script is additive and must be run in sequence.

createdb mmo_project_proto
psql -d mmo_project_proto -f prototype/sql/001_initial_schema.sql
psql -d mmo_project_proto -f prototype/sql/002_equipment_schema.sql
psql -d mmo_project_proto -f prototype/sql/003_item_equipment_metadata.sql
psql -d mmo_project_proto -f prototype/sql/004_leg_item_definitions.sql
psql -d mmo_project_proto -f prototype/sql/005_food_item_definitions.sql
psql -d mmo_project_proto -f prototype/sql/006_ground_items_schema.sql
psql -d mmo_project_proto -f prototype/sql/007_ground_item_visibility_notifications.sql
psql -d mmo_project_proto -f prototype/sql/008_skill_equipment_schema.sql
psql -d mmo_project_proto -f prototype/sql/009_hand_asset_slot_alignment.sql
psql -d mmo_project_proto -f prototype/sql/010_runtime_revision_streams.sql

The migrations define tables for accounts, sessions, characters, map presence, character stats, item definitions, inventory, equipment, ground items, and runtime revision streams.

Configure the server

The server reads its configuration from prototype/server/appsettings.json. The file ships with defaults suitable for a local development setup:

{
  "Prototype": {
    "ProtocolVersion": "v1",
    "SessionIdleTimeoutMinutes": 30,
    "DroppedItemPrivateVisibilitySeconds": 180,
    "MovementDebugEnabled": false,
    "MaxIncomingMessageBytes": 65536
  },
  "ConnectionStrings": {
    "PrototypeDatabase": "Host=localhost;Port=5432;Database=mmo_project_proto;Username=postgres;Password=8921"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Edit the PrototypeDatabase connection string to match your local PostgreSQL credentials if they differ from the defaults above. Do not commit production credentials to the repository.

Start the server

Start the .NET backend from the prototype/server directory:

cd prototype/server
dotnet run

Once the server is up, verify both health endpoints:

# Application health
curl http://localhost:5000/health
# {"status":"ok","service":"prototype-server"}

# Database connectivity
curl http://localhost:5000/health/db
# {"status":"healthy","database":"PrototypeDatabase"}

If /health/db returns a 503, check that PostgreSQL is running and that the connection string in appsettings.json is correct.

Launch the Godot client

From the repository root, run the client launch script. It starts the Godot 4 runtime pointed at prototype/client and streams all output to a log file:

./tools/run-godot-client.sh

Runtime logs are written to prototype/client/logs/godot-runtime.log. To open the project in the Godot editor instead, use:

./tools/run-godot-editor.sh

Editor logs are written to prototype/client/logs/godot-editor.log.

The application opens on the LoginScreen. Enter the credentials for a seeded account in your local database and press Login.After a successful login the client automatically:

Loads the account character and receives a character_id from the server
Sends an enter-world request and receives the authoritative world entry response
Transitions to the GameScreen, which renders the 3×3 chunk world centered on your character’s position

From the GameScreen you can click to move, open the right-side HUD to view your status bars, inventory slots, and equipment slots, and observe NPC and remote-player presence driven by live server updates.

Dev-only debug endpoints are available when the server runs in Development mode (the default for dotnet run). These endpoints allow direct inspection and seeding of account, session, character stats, inventory, equipment, and item definition state without going through the game client:

GET /debug/accounts/{accountName} — look up an account record
POST /debug/login — perform a login and receive a session token
POST /debug/accounts/password — set a password hash for an account
POST /debug/sessions/{accountName} — create a session directly for an account
POST /debug/characters/{accountName}/stats — seed character stat values
POST /debug/characters/{accountName}/inventory/{slotIndex} — seed an inventory slot
POST /debug/characters/{accountName}/equipment/{slotId} — seed an equipment slot
POST /debug/items/{itemId} — upsert an item definition

These endpoints are not registered in Production mode.

Use ./tools/validate-godot-client.sh for headless validation of the Godot scene tree. Validation output is written to prototype/client/logs/godot-headless-validation.log, making it suitable for CI checks without a display server.

Introduction

Modernization

Run the MMO Project server, database, and client locally

Prerequisites

Steps

Build docs developers (and LLMs) love

Introduction

Modernization

Documentation Index

​Prerequisites

​Steps

Build docs developers (and LLMs) love

Prerequisites

Steps