sharp-mud

____ _ __ __ _ _ ____ / ___|| |__ __ _ _ __ _ __ | \/ | | | | _ \ \___ \| '_ \ / _` | '__| '_ \| |\/| | | | | | | | ___) | | | | (_| | | | |_) | | | | |_| | |_| | |____/|_| |_|\__,_|_| | .__/|_| |_|\___/|____/ |_|

A modern C#/.NET reimagining of a classic MUD (Multi-User Dungeon) — faithful to the genre's feel while built with current .NET architecture.

Alpha — not yet stable. Pre-1.0, no SemVer compatibility guarantees between releases yet; APIs, package boundaries, and persisted-data shape can all still change. Also currently pinned to a preview .NET 11 SDK (see global.json) — accept that risk, or build against net10.0 only until a stable release lands. Use it, but expect breaking changes.

• SPEC.md — vision and high-level decisions (start here).
• docs/ — detailed per-subsystem design docs. Start with docs/engine-vs-ruleset.md for the entity model (Thing/Behavior composition), then architecture, world model, character, commands, combat, persistence, networking, accounts/auth.

Solution layout

SharpMud.slnx
src/
SharpMud.Engine/ # Thing/Behavior, events, generic behaviors,
# command pipeline, session, tick loop.
# Zero deps on any ruleset.
SharpMud.Hosting/ # generic-host composition helpers, ruleset-agnostic
SharpMud.Persistence/ # EF Core repositories, provider-agnostic
SharpMud.Persistence.Sqlite/ # SQLite provider
SharpMud.Persistence.DynamoDb/ # DynamoDB provider
SharpMud.Adapters.Cli/ # local stdin/stdout session adapter
SharpMud.Adapters.Telnet/ # raw TCP session adapter + listener
SharpMud.Ruleset.Rpg/ # reusable RPG combat/encounter scaffolding (ADR-0008)
SharpMud.Ruleset.Basic/ # minimal concrete leaf ruleset built on Ruleset.Rpg (ADR-0008)
SharpMud/ # meta-package (Engine + Hosting + Persistence only - ADR-0007)
samples/
SharpMud.Samples.Classic/ # D&D-flavored sample ruleset + composition root
tests/
SharpMud.Engine.Tests/
SharpMud.Hosting.Tests/
SharpMud.Persistence.Tests/
SharpMud.Adapters.Cli.Tests/
SharpMud.Adapters.Telnet.Tests/
SharpMud.Ruleset.Rpg.Tests/
SharpMud.Ruleset.Basic.Tests/
SharpMud.Samples.Classic.Tests/

Building & testing

dotnet build SharpMud.slnx
dotnet test SharpMud.slnx

Running

dotnet run --project samples/SharpMud.Samples.Classic # local single-player CLI
dotnet run --project samples/SharpMud.Samples.Classic -- --telnet [port] # telnet server, default port 4000

Using SharpMud as a library

src/ publishes as NuGet packages (SharpMud.Engine, SharpMud.Hosting, SharpMud.Persistence(.Sqlite/.DynamoDb), SharpMud.Adapters.Cli/ .Telnet, SharpMud.Ruleset.Rpg/.Basic), plus a SharpMud meta-package pulling in the engine-level core (Engine/Hosting/Persistence) — you still add a persistence provider, a transport, and a ruleset explicitly, per ADR-0007. See docs/getting-started.md for the fastest path to a running game (SharpMud.Ruleset.Basic) or building your own ruleset on SharpMud.Ruleset.Rpg's combat scaffolding. samples/SharpMud.Samples.Classic is a full, richer reference consumer — see how a ruleset composes against the packages. See ADR-0006 for the design.

Containerized

docker build -t sharpmud .
docker run -p 4000:4000 sharpmud # telnet server (container default)

See docs/deployment.md for runtime configuration (env vars, mode selection) and current limitations.