Project: Creative (GitHub Copilot) - Mud | microsoft/agentsleague

Track

Creative Apps (GitHub Copilot)

Project Name

Single player AI MUD. A flash back to the harmony of dialtones and BBS.

GitHub Username

@idusortus

Repository URL

https://github.com/idusortus/agentsleague-idusortus-MUD

Project Description

The Gates of Ash — Elevator Pitch

What Is It?

A single-player, AI-powered text-based MUD (Multi-User Dungeon) where every world is unique.

Pick a theme — medieval fantasy, sci-fi, western, cosmic horror, or anything you dream up. Choose a tone, difficulty, and world size. An AI World Builder generates the entire dungeon, then an AI Game Master narrates your adventure in real time. You type natural language. The game understands you.

The Problem It Solves

Classic text adventures are limited by what their authors pre-wrote. Modern AI text games hallucinate — the AI invents items you don't have, forgets rules, and breaks immersion by being inconsistent.

The Gates of Ash solves both problems at once.

How It Works

The system separates the two things AI is bad at (rules, math, state) from the one thing it's great at (narrative prose):

Player types:  "I draw my blade and charge the hellhound!"
                         │
              ┌──────────▼──────────────┐
              │   C# Orchestrator       │  ← deterministic, no LLM
              │   • Validates the blade │
              │     is in inventory     │
              │   • Rolls d100 attack   │
              │   • Applies damage      │
              └──────────┬──────────────┘
                         │  [RESULT: success, rolled 34 vs 55%, dealt 10 damage]
              ┌──────────▼──────────────┐
              │   GitHub Copilot SDK    │  ← the narrator
              │   Game Master (LLM)     │
              └──────────┬──────────────┘
                         │
Player sees: "Your rusted blade catches the hellhound across its flank.
              Three burning eyes fix on you with primal rage — it is
              wounded but not broken."

The AI never decides what happens. It only describes what C# already determined. This means the rules are always enforced and the story is always atmospheric.

The Tech Stack

.NET 10 console application
GitHub Copilot SDK (GitHub.Copilot.SDK v0.1.26) — two sessions: World Builder (generates worlds) + Game Master (narrates gameplay)
Microsoft.Extensions.AI for tool/function definitions (12 total tools across both sessions)
Spectre.Console — rich terminal UI with selection menus, tables, spinners, Figlet text
Percentage-based D&D-inspired mechanics — every skill is a 0–99% chance, resolved with a d100 roll

The Setting

Whatever you want it to be. Choose from 9 curated themes — Medieval Fantasy, Sci-Fi, Western, Gothic Horror, Post-Apocalyptic, Noir Detective, Mythological, Steampunk, Cosmic Horror — or type your own. The AI generates a complete, playable world with rooms, NPCs, items, puzzles, and a win condition. The Gates of Ash (the original hand-crafted hellscape dungeon) remains as a built-in fallback.

Why It's Interesting

This is a proof of concept for a new architecture pattern: AI as narrator, not as rules engine. The two concerns are separated cleanly, which means:

The game is trustworthy — it never lies about what you have or what happened
The game is extensible — add new rooms, NPCs, and items without touching the AI layer
The AI layer is replaceable — swap Copilot for any LLM without changing game logic

Current State (Phase 1 ✅ / Phase 2 ✅)

Phase 1: A fully playable 5-room dungeon. Single player. In-memory state. The architecture is proven.

Phase 2: Dynamic world generation — complete. Players choose theme, tone, difficulty, and world size. A dedicated World Builder AI generates entire playable worlds via 3-phase tool-calling (combined populate+finalize for Quick/Standard worlds, batched 4-phase for Epic/Marathon). Spectre.Console rich terminal UI. Copilot SDK activity logging. GameMaster session auto-recovery. --test-worldgen CLI smoke test. Default model: claude-opus-4.6 (both World Builder and Game Master).

The proof: AI can generate entire game worlds that are mechanically sound and narratively compelling — on demand, from a text prompt. Tested and verified: 4 rooms, 4 NPCs, 4 items, exits, and a win condition generated in ~65 seconds.

Demo Video or Screenshots

Primary Programming Language

C#/.NET

Key Technologies Used

Copilot
GitHub Copilot SDK
C#
Spectre

Submission Type

Individual

Team Members

@idusortus and @githubcopilot

Submission Requirements

My project meets the track-specific challenge requirements
My repository includes a comprehensive README.md with setup instructions
My code does not contain hardcoded API keys or secrets
I have included demo materials (video or screenshots)
My project is my own work with proper attribution for any third-party code
I agree to the Code of Conduct
I have read and agree to the Disclaimer
My submission does NOT contain any confidential, proprietary, or sensitive information
I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

Quickstart Guide

Get The Gates of Ash running locally in under 5 minutes.

Prerequisites

Requirement	Version	Notes
.NET SDK	10.0+	Download
GitHub account	—	With an active Copilot subscription
Git	any	For cloning

Copilot subscription: A personal GitHub Copilot subscription is sufficient. The game uses the GitHub.Copilot.SDK which authenticates via your locally installed GitHub Copilot CLI. No API keys required.

Step 1: Authenticate with GitHub Copilot

The GitHub.Copilot.SDK reads your GitHub token from one of these environment variables (first match wins):

Variable	Priority	Notes
`COPILOT_GITHUB_TOKEN`	1st	Recommended for explicit API tokens
`GH_TOKEN`	2nd	Export from `gh auth token` if using GitHub CLI
`GITHUB_TOKEN`	3rd	Set automatically in GitHub Actions

Option A — Use the GitHub CLI (simplest for local dev)

# Install
winget install GitHub.cli   # Windows
brew install gh              # macOS

# Authenticate
gh auth login

# Export the token to GH_TOKEN env var (IMPORTANT — the SDK needs this!)
export GH_TOKEN=$(gh auth token)

Important: gh auth login stores your token in the OS keyring, not as an environment variable. The GitHub.Copilot.SDK requires the token to be explicitly exported as GH_TOKEN before running the game. Re-run the export command in each new terminal session, or add it to your shell profile (.bashrc, .zshrc, etc.) to persist it.

Option B — Set a Personal Access Token explicitly

Go to github.com/settings/tokens and generate a classic token (no special scopes needed — just a valid GitHub auth token is sufficient)
Copy .env.example → .env and paste your token:
```
COPILOT_GITHUB_TOKEN=gho_your_token_here
```

Load it in your shell before running:

# PowerShell
$env:COPILOT_GITHUB_TOKEN = "gho_your_token_here"

# Or load from .env
Get-Content .env | ForEach-Object { $k,$v = $_ -split '=',2; [System.Environment]::SetEnvironmentVariable($k.Trim(), $v.Trim()) }

Security: Never commit .env — it is in .gitignore. Never hardcode tokens in source files.

Step 2: Clone and Restore

git clone <repository-url>
cd copilot-orchestrator
cd MudGame
dotnet restore

Step 3: Build

dotnet build

Expected output:

Build succeeded.
    0 Warning(s)
    0 Error(s)

Step 4: Run

dotnet run

You'll see the Figlet title screen:

  __  __ _   _ ____
 |  \/  | | | |  _ \
 | |\/| | | | | | | |
 | |  | | |_| | |_| |
 |_|  |_|\___/|____/

  An AI-generated text adventure
  SDK log: logs/copilot-sdk-2026-02-28-143001.log

Troubleshooting: "You are not authorized to use this Copilot feature"

If you see this error:

System.InvalidOperationException: Session error: You are not authorized to use this Copilot feature, 
it requires an enterprise or organization policy to be enabled.

The issue: The GH_TOKEN environment variable is not set. The GitHub.Copilot.SDK cannot find your token.

The fix: Re-export GH_TOKEN in your terminal and try again:

# In bash/zsh
export GH_TOKEN=$(gh auth token)
dotnet run

# In PowerShell
$env:GH_TOKEN = gh auth token
dotnet run

A personal GitHub Copilot subscription is sufficient — you do not need an enterprise account. If the error persists after setting GH_TOKEN, verify your Copilot subscription at github.com/settings/copilot.

Step 5: Configure Your World

The setup wizard guides you through world configuration using arrow-key menus:

Choose a theme — Medieval Fantasy, Sci-Fi, Western, Gothic Horror, Post-Apocalyptic, Noir Detective, Mythological, Steampunk, Cosmic Horror, or type a custom theme
Choose a tone — Serious, Light, Irreverent, Caustic, Psychotic, Heroic, or Melancholic
Choose difficulty — Easy, Medium, Hard, or Probably Not Gonna Win
Choose world size — Quick (3-5 rooms), Standard (7-10), Epic (15-20), Marathon (30+)
(Easy only) Choose AI models — optionally select which models power the World Builder and Game Master

Step 6: Create Your Character

Name your character — or press Enter to be "The Nameless One"
Roll or use the standard array — select via arrow-key menu
Pick 4 proficient skills — select from grouped skill list (navigate with arrow keys, space to toggle)
Confirm or reroll

The AI World Builder then generates your world (themed loading spinner indicates progress). If generation fails, the game falls back to the built-in Gates of Ash dungeon.

Playing the Game

Type natural language. The AI Game Master will interpret your intent and call the appropriate game tools automatically. Some examples:

You type	What happens
`look around`	Describes the room, exits, items, and NPCs
`go north` / `move east`	Moves your character
`take the rusted sword`	Picks up an item (may require a skill check)
`attack the hellhound`	Initiates combat with your best weapon
`talk to the spirit`	Opens NPC dialogue
`use healing salve`	Consumes an item from your inventory
`inventory`	Lists what you're carrying
`status`	Shows your HP and stats
`help`	Displays available commands
`quit`	Exits the game

Tip: You don't have to use exact command syntax. "I pick up the sword" and "grab sword" both work. The AI handles natural language understanding, while C# handles rule enforcement.

Generated Worlds

Every playthrough generates a unique world based on your configuration choices. The AI creates rooms, connects them with exits, populates them with NPCs and items, sets locks and keys, and defines a win condition — all via tool-calling.

World sizes:

Size	Rooms	Approx. Play Time
Quick	3-5	10-15 minutes
Standard	7-10	30-45 minutes
Epic	15-20	1-2 hours
Marathon	30+	3+ hours

Fallback: The Gates of Ash

If world generation fails, the game falls back to a built-in 5-room dungeon:

         [Ruined Chapel]
               |
             south
               |
[Charred Gateway] ──east──> [Bone-Strewn Courtyard] ──east──> [Warden's Cell*]
                                                                      |
                                                                    south
                                                                      |
                                                              [The Hellmouth]

* = locked door (requires the Iron Key)

Running the World Generation Smoke Test

To validate that AI world generation works end-to-end:

dotnet run -- --test-worldgen

This runs a Quick/Easy/Medieval Fantasy world generation without the interactive UI or game loop. It validates:

At least 3 rooms created
Starting room (room_1) exists
Rooms have exits
NPCs and items were placed
A win condition was set

Expected output on success:

Rooms:     4
NPCs:      4
Items:     4
Exits:     YES
room_1:    YES
Win cond:  YES

PASS — World generation succeeded!

Running the Headless Logic Test (No LLM Required)

To validate that the C# game logic works without needing a live Copilot session:

Temporarily add this to the top of Program.cs:

MudGame.Scenarios.TestDungeon.RunTest();
return;

Then:

dotnet run

This runs a scripted playthrough of the built-in Gates of Ash dungeon and prints pass/fail results for each game system.

Troubleshooting

Problem	Fix
`NETSDK1045: does not support targeting .NET 10.0`	Install .NET 10 SDK from dot.net
`CopilotClient` throws on startup	Ensure you're authenticated: `gh auth login`
LLM doesn't respond / hangs	Check that Copilot CLI is installed and that your subscription is active
Build error about `SystemMessageConfig`	Ensure you have `GitHub.Copilot.SDK` v0.1.26+

Project Structure

MudGame/
├── MudGame.csproj              # .NET 10, Copilot SDK + Extensions.AI + Spectre.Console
├── Program.cs                  # Entry point — wizard, character creation, world gen, game loop
├── CharacterCreation.cs        # Interactive character wizard (Spectre.Console)
├── Models/                     # CharacterSheet, Room, Item, Npc, GameEvent, Enums,
│                               #   WorldConfig, WinCondition
├── Engine/
│   ├── SkillCheckEngine.cs     # d100-under resolution, crits, advantage, contests
│   └── CombatEngine.cs         # Attack rolls, damage, NPC counter-attacks
├── State/
│   ├── GameState.cs            # In-memory game state + win condition checking
│   └── RoomGraph.cs            # Gates of Ash fallback dungeon
├── Orchestrator/
│   └── GameOrchestrator.cs     # Deterministic C# action dispatcher
├── Tools/
│   └── GameTools.cs            # Gameplay tool definitions (AIFunctionFactory)
├── Session/
│   └── GameMasterSession.cs    # Copilot SDK session — parameterized by WorldConfig, auto-recovery
├── WorldBuilder/
│   └── WorldBuilderSession.cs  # 3-phase world generation via Copilot SDK (4-phase for Epic/Marathon)
│   ├── WorldBuilderTools.cs    # 6 world-building tools (create_room, set_exit, etc.)
│   └── WorldBuilderPrompts.cs  # System prompt + phase-specific prompts
├── Logging/
│   └── CopilotLogger.cs        # SDK activity tracing to logs/
├── Scenarios/
│   └── TestDungeon.cs          # Headless integration test
└── UI/
  ├── ConsoleRenderer.cs      # Spectre.Console styled output
  └── GameSetupWizard.cs      # World configuration wizard (theme, tone, difficulty, size)

Technical Highlights

Didn't write a line of code. Fed it an idea, provided a little guidance, and checked in on it from time to time.

First time 'using' GithubCopilot SDK and I feel it has lots of potential especially for BYOK. Had some fancier implementations for this in mind but the universe had other plans in mind.

Challenges & Learnings

Could really use some more ascii/text dazzle. It was a bit more fly before adding Spectre. Time's tight though - you can do that with a prompt :)

The largest problem was getting the agents to find a sane way to implement the LLM world generation. My orchestration (Thanks Burke!) suite had a really hard time with it. The prompt that got me past the hurdle:

Perhaps you're overcomplicating the world generation.

Find a simpler more robust way to do it. We managed to get to phase 3/4: populating rooms (batch 1/2).

For a quick dungeon this should not be terribly complicated. I don't understand why it is taking so long to generate the world.

Take a close look at what we have in place and task your agents out to solve th eproblem we've been facing.

When complete, attempt to run the game and enter default settings to get to the world building process. Or, you know, set up some tests for just the world building process so we can get it to work.

Keep iterating until the thing works without defaulting to Gates of Ash.

I believe in you!

Contact Information

idusortus@gmail.com

Country/Region

United States

Project: Creative (GitHub Copilot) - Mud

Description