SmartMUD is a framework-driven reimagining of a classic Multi-User Dungeon (MUD). It's built in .NET and powered by Microsoft Orleans for distributed grains and state management. The system is designed to support both web and telnet clients, integrate with GitHub Models for AI-driven content generation, and provide modular frameworks for combat, worldbuilding, crafting, guilds, factions, and communication.
- .NET 8.0 SDK (version 8.0.119 or later)
- Git
- Your favorite IDE (Visual Studio, VS Code, Rider, etc.)
# Clone the repository
git clone https://github.com/SamMRoberts/SmartMUD.git
cd SmartMUD
# Restore dependencies
dotnet restore
# Build the solution
dotnet build
# Run tests
dotnet test
# Start the host application (from the Host project directory)
cd src/SmartMUD.Host
dotnet runSmartMUD/
├── src/ # Source code
│ ├── SmartMUD.Core/ # Core domain models and interfaces
│ ├── SmartMUD.Orleans/ # Orleans grains and clustering
│ ├── SmartMUD.Host/ # Application host and startup
│ ├── SmartMUD.Network/ # Telnet/WebSocket servers (planned)
│ ├── SmartMUD.Persistence/ # Database and storage (planned)
│ └── SmartMUD.AI/ # AI integration (planned)
├── tests/ # Test projects
│ ├── SmartMUD.Core.Tests/
│ ├── SmartMUD.Orleans.Tests/
│ ├── SmartMUD.Integration.Tests/
│ └── SmartMUD.Simulation.Tests/
├── docs/ # Documentation
├── .github/ # GitHub workflows and settings
└── SmartMUD.sln # Solution file
# Restore packages
dotnet restore
# Build (Debug)
dotnet build
# Build (Release)
dotnet build --configuration Release
# Run all tests
dotnet test
# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"
# Format code (must pass for CI)
dotnet format
# Check formatting without changes
dotnet format --verify-no-changes
# Run security vulnerability check
dotnet list package --vulnerable --include-transitive
# Publish the application
dotnet publish src/SmartMUD.Host --configuration Release --output ./publishSmartMUD uses Cosmos DB for persistent storage in production and development environments. The application automatically configures Orleans grain storage based on the available configuration.
- Development: Uses
developmentdatabase in Cosmos DB - Production: Uses
productiondatabase in Cosmos DB - Local Development: Falls back to in-memory storage when Cosmos DB credentials are not configured
For production deployment, add the following secret to your GitHub repository:
- Go to Settings → Secrets and variables → Actions
- Add a new repository secret:
- Name:
ORLEANS_COSMOSDB_ACCOUNTKEY - Value: Your Cosmos DB account key from Azure
- Name:
The application expects the following configuration structure in appsettings.json:
{
"Orleans": {
"CosmosDB": {
"Endpoint": "https://smartmud.documents.azure.com:443/",
"Database": "development"
}
}
}The AccountKey is injected via environment variables or GitHub secrets:
- Environment Variable:
Orleans:CosmosDB:AccountKey - GitHub Secret:
ORLEANS_COSMOSDB_ACCOUNTKEY
For local development, you can either:
- Use in-memory storage (default): No additional configuration needed
- Use Cosmos DB: Set the environment variable:
export Orleans__CosmosDB__AccountKey="your-cosmos-db-key" dotnet run --project src/SmartMUD.Host
SmartMUD is a framework-driven reimagining of a classic Multi-User Dungeon (MUD). It’s built in .NET and powered by Microsoft Orleans for distributed grains and state management. The system is designed to support both web and telnet clients, integrate with GitHub Models for AI-driven content generation, and provide modular frameworks for combat, worldbuilding, crafting, guilds, factions, and communication.
- Framework first: deterministic, testable systems form the backbone.
- AI as an extender: LLMs generate content (rooms, classes, NPCs, quests, mechanics), but all output passes through validation layers before entering the world.
- Modularity: Every system should be pluggable and replaceable.
- Persistence & scale: Worlds must persist reliably across sessions and scale across Orleans grains.
- Safety & accessibility: Guardrails, moderation, content filters, and screen-reader–friendly output are mandatory.
- Repo & CI scaffold (FR-0-01)
- Orleans cluster bootstrap (FR-0-02)
- Persistence v1 (schemas, migrations, snapshot/restore) (FR-0-03)
- Event bus & plugin system (FR-0-04)
- Observability baseline (logs, metrics, tracing, health) (FR-0-05)
- Deterministic RNG utilities (NFR-0-06)
- Telnet server (MCCP, GMCP/MSDP/ATCP) (FR-1-01)
- Web client shell via WebSockets (FR-1-02)
- Authentication & sessions (passwordless/OAuth) (FR-1-03)
- Rate limiting & backpressure (FR-1-04)
- Permissions & roles (FR-1-05, optional)
- Command parser v1 + fuzz tests (NFR-1-06)
- World graph schema & loader (FR-2-01)
- Game tick scheduler & time-of-day (FR-2-02)
- Entity model baseline (players, rooms, items) (FR-2-03)
- Pathfinding utilities (A*) (FR-2-04)
- Content DSL v1 (FR-2-05, optional)
- In-game builder/editor (FR-2-06, optional)
- Multi-channel chat (local, tell, guild, faction, global) (FR-3-01)
- Formatting & accessibility pipeline (FR-3-02)
- Moderation hooks (mute, ban, report, logs) (FR-3-03)
- Social graph skeleton (FR-3-04, optional)
- Turn & action model (FR-4-01)
- Damage & mitigation math (FR-4-02)
- Status effects framework (FR-4-03)
- Threat & leashing system (FR-4-04)
- Automated balance harness (NFR-4-05)
- Deterministic combat replays (NFR-4-06)
- Faction reputation (FR-5-01)
- Guild system (FR-5-02)
- Crafting framework (FR-5-03)
- Resource nodes (FR-5-04)
- Status/UI affordances (encumbrance, fatigue, buffs) (FR-5-05, optional)
- GitHub Models integration (FR-6-01)
- Validation gates (schema, safety, balance) (NFR-6-02)
- Provenance tagging (NFR-6-03)
- Dry-run world & approval workflow (NFR-6-04)
- AI generators pack (rooms, classes, NPCs, abilities, recipes) (FR-6-05, optional)
- Currency & vendors (FR-7-01)
- Quest framework (objectives, prerequisites, branching) (FR-7-02)
- AI quest authoring (FR-7-03, optional)
- LiveOps controls (feature flags, kill switches, runtime config) (NFR-8-01)
- Multitenancy & shard isolation (NFR-8-02)
- Load & chaos testing (NFR-8-03)
- Testing: Unit tests for all modules, simulation tests for combat & world rules, fuzz testing for parser & network.
- Security: Server authority, input sanitization, rate limiting, role-based permissions.
- Accessibility: Screen-reader compatibility, configurable text output, high-contrast color modes.
- Documentation: Golden-path guides, content DSL reference, contributor guidelines.
- DEMO-A (Phase 3): Connect → chat → move → build a room.
- DEMO-B (Phase 4): Duel arena with deterministic replays.
- DEMO-C (Phase 5): Gather → craft → equip → defeat a tougher mob.
- DEMO-D (Phase 6): AI generate zone/class → validate → publish → play.
When helping with this project, you should:
- Treat the framework as primary and AI as an extension layer.
- Map any new features or ideas to the correct phase and requirement type (FR/NFR/Demo).
- Suggest tests and validation steps for every feature.
- Respect the .NET + Orleans tech stack.
- Keep tone curious, playful, and pragmatic — highlight weird or philosophical angles where useful.
- Avoid over-engineering; build minimal vertical slices that prove end-to-end playability.
- Do not output copyrighted song lyrics or claim to modify external services directly.
- When generating GitHub artifacts, output YAML/Markdown/JSON in the required formats so they can be committed or imported.