Getting Started

Getting Started

This guide gets you from a fresh clone to a running build and passing test suite.

---

Prerequisites

Requirement	Version	Notes
.NET SDK	10.0+	Required for all projects
Git	Any recent	—
VS Code	Any	Recommended, with C# Dev Kit extension
Docker	Optional	Required only for the database when running the Server locally

---

Clone the Repository

git clone --recurse-submodules https://github.com/KungRaseri/RealmEngine.git
cd RealmEngine

The --recurse-submodules flag also pulls the wiki submodule at ./wiki.

---

Build

Pick the solution that matches what you're working on:

# Engine libraries only (fastest) — no Avalonia required
dotnet build RealmEngine.slnx

# Client + Server (Avalonia required)
dotnet build Veldrath.slnx

# Tooling (RealmForge editor)
dotnet build RealmForge.slnx

# Everything
dotnet build Realm.Full.slnx

---

Run Tests

# Engine libraries — fast, no UI
dotnet test RealmEngine.slnx

# Client tests (headless Avalonia, excludes interactive UI tests)
dotnet test Veldrath.Client.Tests --filter "Category!=UI"

# Full suite, excluding interactive UI tests
dotnet test Realm.Full.slnx --filter "Category!=UI"

All tests should pass with 0 failures. The suite covers ~8,500+ tests across six projects.

---

Run with Coverage

dotnet test Realm.Full.slnx --filter "Category!=UI" `
  --collect "XPlat Code Coverage" `
  --settings coverage.runsettings `
  --results-directory coverage-results

A coverage.cobertura.xml file will be written to coverage-results/. You can generate an HTML report with ReportGenerator:

dotnet tool install --global dotnet-reportgenerator-globaltool
reportgenerator -reports:"coverage-results/*/coverage.cobertura.xml" -targetdir:CoverageReport -reporttypes:Html
# Open CoverageReport/index.html

---

VS Code Setup

The repository includes pre-configured VS Code tasks and launch configs.

• Build: Ctrl+Shift+B (runs dotnet build RealmEngine.slnx)
• Debug: F5 (launches with integrated terminal for ANSI color support)
• Run tests: Use the Testing panel or run one of the test-* tasks via Ctrl+Shift+P → Tasks: Run Task

---

Run the Multiplayer Stack Locally

The server requires a PostgreSQL database. The easiest way is Docker:

# Start just the database
docker compose up postgres -d

# Then build and run the server
dotnet run --project Veldrath.Server

# In a second terminal, run the client
dotnet run --project Veldrath.Client

---

Project Structure at a Glance

RealmEngine/
├── RealmEngine.Core/       # Game logic — Features/, Generators/, Services/
├── RealmEngine.Data/       # EF Core repositories — ContentDbContext + GameDbContext
├── RealmEngine.Shared/     # Shared models and abstractions
├── Veldrath.Server/    # ASP.NET Core game server
├── Veldrath.Client/    # Avalonia UI desktop client
├── RealmForge/             # Avalonia DB content editor for game entities
├── [Project].Tests/        # One test project per library/app
├── docs/                   # Full documentation (also on GitHub Pages)
├── scripts/                # Build, package, and deploy scripts
└── wiki/                   # This wiki (git submodule)

---

Next Steps

• Read the Game Design Document for a full system overview
• Browse the full documentation for architecture details, standards, and API specs
• Check Contributing if you want to submit changes