Realms of Idle

A multi-scenario idle RPG where players build interconnected fantasy enterprises—from cozy inns to sprawling empires—in a world where Classes, Levels, and the System govern all.

Inspired by LitRPG and progression fantasy, Realms of Idle rewards both deep focus and broad management across seven unique playstyles.

Overview

Realms of Idle is an offline-first solo play game with scalable multiplayer support. Build your fantasy empire through idle mechanics, strategic decision-making, and meaningful progression.

The Seven Scenarios

Scenario	Core Fantasy	Playstyle
Inn/Tavern	Beloved innkeeper	Social, cozy
Adventurer Guild	Heroic coordinator	Strategic, combat
Monster Farm	Beast tamer	Collection, nurture
Alchemy	Master brewer	Crafting, puzzle
Territory	Domain ruler	Builder, strategy
Summoner	Planar contractor	Collection, risk
Merchant Caravan	Trade prince	Economic, risk

Technology Stack

Core Architecture

• Shared Game Core - Portable Class Library running everywhere
• Client - .NET MAUI (Mobile/Desktop) + Blazor WASM (Web)
• Server - ASP.NET Core + Microsoft Orleans (Azure Container Apps, scale-to-zero)
• Storage - LiteDB (client) / Marten + PostgreSQL (server)
• Testing - xUnit, Reqnroll (BDD), TestContainers, Playwright, NBomber

Key Design Decisions

• Offline Solo Play - Full game experience without network
• Online Multiplayer - Serverless-first, pay only when active
• Shared Logic - Same game code runs client and server
• Event Sourcing - Deterministic replay, conflict-free sync
• LitRPG Authenticity - System notifications, class evolution, skill trees

Development

Prerequisites

• .NET SDK (see global.json for version)
• Node.js 22+ (for tooling)
• Git
• GitHub account with repository admin access (for branch protection)

Getting Started

# Clone the repository
git clone https://github.com/yourusername/realms-of-idle.git
cd realms-of-idle

# Restore dependencies
dotnet restore

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format

MCP Servers (AI Development Tools)

This project uses Model Context Protocol (MCP) servers to enhance AI-assisted development with Claude Code. MCP servers provide capabilities like semantic code search, web search, and context management.

Available MCP Servers

Server	Purpose	Setup Required
context7	Upstash context management for long conversations	None (via npx)
web-search-prime	Web search for API documentation and references	None
zai-mcp-server	Z.ai integration for enhanced AI capabilities	None
grepai	Semantic code search across the codebase	Ollama + index build

Initial Setup

Run the setup script to configure MCP servers:

.\scripts\setup-mcp.ps1

This will:

1. Check Ollama installation
2. Pull the nomic-embed-text model (~275MB)
3. Build the semantic code index for grepai

Manual Setup (if script fails)

1. Install Ollama from ollama.ai

2. Pull the embedding model:

   ollama pull nomic-embed-text

3. Build the grepai index:

   .\.claude\grepai.exe index

Maintaining the Index

The grepai index updates automatically when files change. If search results seem stale, rebuild manually:

.\.claude\grepai.exe index --force

Development Workflow

This project follows strict development standards:

• Git Hooks - Never skip (--no-verify requires explicit permission)
• Linear History - Use rebase, then --ff-only for merges
• Conventional Commits - Follow commitlint configuration
• Feature Branches - Always use git worktrees for isolation
• Branch Protection - Automated CI/CD and PR review requirements

Branch Protection Setup

To set up branch protection for the repository:

# Copy the environment configuration
cp .github.env.example .github.env

# Edit .github.env with your GitHub token
nano .github.env

# Install dependencies and setup branch protection
npm install
npm run branch:setup

# Verify the setup
npm run branch:verify

See docs/BRANCH-PROTECTION.md for detailed documentation.

• TDD - Tests first, then implementation
• Quality Gates - Zero warnings, zero errors, zero test failures

See CLAUDE.md for complete development standards.

Building

# Build all projects
dotnet build

# Run specific project
dotnet run --project src/IdleWorlds.Client.Maui

# Run with hot reload (development)
dotnet watch --project src/IdleWorlds.Client.Maui

Testing

# Run all tests
dotnet test

# Run specific test project
dotnet test tests/IdleWorlds.Core.Tests

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run performance benchmarks
dotnet run --project tests/IdleWorlds.Performance.Tests

Project Structure

realms-of-idle/
├── docs/
│   └── design/           # Game design documents
├── src/
│   ├── IdleWorlds.Core/              # Shared game engine
│   ├── IdleWorlds.Client.Core/       # Shared client logic
│   ├── IdleWorlds.Client.Maui/       # MAUI application
│   ├── IdleWorlds.Server.Api/        # ASP.NET Core API
│   ├── IdleWorlds.Server.Orleans/    # Orleans grains
│   └── IdleWorlds.Shared/            # Client-server contracts
├── tests/
│   ├── IdleWorlds.Core.Tests/        # Unit + BDD tests
│   ├── IdleWorlds.Integration.Tests/ # Integration tests
│   ├── IdleWorlds.E2E.Tests/         # End-to-end tests
│   └── IdleWorlds.Performance.Tests/ # Performance benchmarks
└── deploy/
    ├── infrastructure/     # Infrastructure as Code
    └── docker/             # Container definitions

Documentation

• Game Overview - Complete game design summary
• Tech Stack - Detailed technical architecture
• Testing Strategy - Testing approach and tools
• NPC Design - NPC AI and behavior systems
• Scenario Designs - Individual scenario specifications