Open‑source MUD engine

The modern way to build a classic MUD.

DungeonEngine is a web‑native, single‑binary engine written in Go. Backed by PostgreSQL, exposing a clean JSON API over HTTP & WebSocket, with an embedded web server and beautiful browser client. No legacy telnet.

Get Started Explore Features See Architecture

Written in Go PostgreSQL storage Embedded web server JSON over HTTP & WebSocket Docs‑driven game design Linux · macOS · Windows

# Download a single binary and run
# (Replace with your actual release URL)
$ curl -L https://dungeonengine.com/downloads/dungeonengine_latest_linux_amd64 \
  -o dungeonengine && chmod +x dungeonengine

# Start the embedded web server (default :8080)
$ ./dungeonengine serve \
  --db "postgres://user:pass@localhost:5432/dungeonengine?sslmode=disable"

# Open http://localhost:8080 to visit the browser client

# JSON API example
GET /api/v1/rooms/az-entrance

{
  "id": "az-entrance",
  "name": "Ancient Zigurat — Entrance",
  "exits": [{"dir":"north","to":"az-antechamber"}],
  "coords": {"x": 0, "y": 0, "z": 0},
  "props": {"indoors": true, "safe": true},
  "entities": [
    {"type":"npc","id":"goat-overseer","name":"The Overseer"}
  ]
}

Ctrl+K Open Command Palette Web‑native client Single binary

Why DungeonEngine

A modern take on traditional MUD engines — everything you need, nothing you don't.

Web‑native (no telnet)

First‑class browser client with HTTP/WebSocket JSON APIs. No green‑screen nostalgia required.

Single binary

Ship one executable with an embedded web server. Start building in seconds, not days.

PostgreSQL first

Battle‑tested relational storage for worlds, entities, inventories, and logs.

Docs‑driven design

Worlds and game logic described in human‑readable JSON/Markdown. Document, diff, and version with Git.

Scales with you

Start solo. Scale to shards and zones behind load balancers as your world grows.

Real‑time UX

Low‑latency updates via WebSocket events for movement, chat, and combat logs.

Architecture at a glance

Simple, reliable components — easy to deploy anywhere.

Why Go?

Goroutines make concurrency simple; channels make it safe. A tiny runtime footprint lets us ship a single static binary with an embedded HTTP/WebSocket stack and migrations built in. Cross‑compile for Linux, macOS, Windows — zero external runtime.

Why PostgreSQL?

Relational queries are perfect for inventories, rooms, logs, and analytics. Strong migrations, indexes, and JSONB for flexible props — all in one durable engine that scales from a $5 VPS to multi‑node clusters.

Quick Start

Download a single binary, point to Postgres, and go.

1) Configure database

Set DATABASE_URL for convenience:

export DATABASE_URL=postgres://user:pass@localhost:5432/dungeonengine?sslmode=disable

Docker example

docker run --name pg -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres:16

2) Start the server

Run the embedded server; migrations run automatically:

./dungeonengine serve --host 0.0.0.0 --port 8080

Systemd service (Ubuntu)

[Unit]
Description=DungeonEngine
After=network-online.target

[Service]
Type=simple
User=www-data
Environment=DATABASE_URL=postgres://user:pass@localhost:5432/dungeonengine?sslmode=disable
ExecStart=/srv/dungeonengine/dungeonengine serve --host 0.0.0.0 --port 8080
Restart=on-failure

[Install]
WantedBy=multi-user.target

3) Open the browser

Visit http://localhost:8080 and create your first world.

# Create a room via JSON API
curl -X POST http://localhost:8080/api/v1/rooms \
  -H 'Content-Type: application/json' \
  -d '{
    "id":"well-of-worlds",
    "name":"The Well of the Worlds",
    "coords":{"x":0,"y":0,"z":-1},
    "props":{"safe":true,"indoors":false}
  }'

World format (excerpt)

Game design lives alongside your code as JSON/Markdown — easy to diff, review, and version.

{
  "rooms": [
    { "id": "town-square", "name": "Town Square", "coords": {"x":10,"y":10,"z":0},
      "exits": [ {"dir":"north","to":"tavern"}, {"dir":"down","to":"well-mouth"} ]
    }
  ],
  "npcs": [
    { "id": "goat-overseer", "name": "The Overseer", "desc": "An old goat standing upright." }
  ]
}

Performance & Footprint

Small binary. Low memory. Concurrency that just works.

Binary size

Typical release (Linux amd64) ~ 15–25 MB stripped, static.

Memory

Idle server ~ 20–40 MB; scales with connected players and zones.

Latency

WebSocket events broadcast in sub‑millisecond on local networks.

Sample `go build` flags

go build -trimpath -ldflags "-s -w -X main.version=$VERSION" ./cmd/dungeonengine

Modules & Systems

Composable systems to build the world you imagine.

Zones & Rooms

3D coordinate maps or classic exits. Safe rooms, PvP flags, instance support.

Entities & Inventory

Players, NPCs, items, containers. Queryable via JSON API; indexed in Postgres.

Chat & Channels

Global, zone, party, tell. Moderation hooks and rate limiting built in.

Combat & Skills

Turn or tick-driven. Effects, cooldowns, status, logs streamed in real time.

Scripting

Event hooks (enter/leave/kill/use). JSON-defined with optional plugin shims.

Auth & Roles

Players, builders, admins. OAuth for web, tokens for tooling/CI.

FAQ

Is it really telnet‑free?

Yes. DungeonEngine is built for the web era. A first‑class browser client speaks JSON over HTTP/WebSocket. You can still build CLI tools if you like — but the default experience is modern.

What about hosting?

Run it anywhere: local dev, a $5 VPS, or containers/orchestrators. It's a single binary with an embedded server; point it at Postgres and go.

License?

Open source. Choose the license that fits your goals (MIT/Apache‑2 are popular). Update the link in the header when you publish the repo.

Can I import existing worlds?

Yes. Worlds are described as JSON/Markdown. Importers for popular formats can translate rooms, exits, and NPCs to DungeonEngine schemas.

Offline or LAN play?

Absolutely. The server is self‑contained; you can run DungeonEngine entirely offline for classrooms, game jams, or local retro nights.

Telemetry?

None by default. Opt‑in only and fully documented if you choose to enable basic anonymous metrics.