dMUD: The Super Terminal (dmud)

Last Updated: 2026-04-22

The dmud package implements a Super Terminal—a hybrid IRC/RPG/MUD/BBS social ecosystem that serves as the ultimate TUI (Text User Interface) for the dLAN ecosystem.

🌟 The Vision

A seamless blending of work, play, and AI orchestration. It is a "living" terminal where you can:

• Monitor: Check real-time system performance and server dashboards (sys_system).
• Engage: Chat with AI agents (Nikki, Sasha, Oracle) who have physical presence in rooms.
• Play: Engage in RPG mechanics, fishing mini-games, and arcade gambling.
• Socialize: Participate in a multi-user "Partyline" with IRC-style chat and Eggdrop-inspired features.
• Nurture: Adopt, feed, and play with persistent digital pets.
• Idle: Relax with high-frame-rate ASCII screensavers (Matrix, Fish Tank, Starfield).
• Create: Build and customize your own rooms within the virtual world.

🚀 Concurrency & Stability Overhaul (April 2026)

In late April 2026, the dMUD engine underwent a massive stability overhaul (Phases A-D), resolving 20 critical concurrency and performance issues:

• Panic Prevention: Standardized comma-ok type assertions across 15 mini-games and added nil-pointer guards to central Send() and CurrentRoom logic.
• High-Impact Mutex Design: Introduced UsersMu to the Room system, resolving race conditions in chat broadcasting and NPC interactions.
• Non-Blocking Operations: Moved heavy cryptographic operations (bcrypt) outside of global user locks, reducing registration latency from 100ms+ of blocking time to near-zero.
• Deadlock Mitigation: Implemented sync.Once patterns for channel closing and non-blocking channel selects to prevent server hangs during reconnection or high load.

Key Features

• Classic Roots: Full Telnet (Port 7777) support for that authentic BBS/MUD feel.
• Modern Access: A high-performance Web Terminal (Port 7778) powered by xterm.js.
• Agent Bridge: Agents physically spawn into rooms via call_agent to assist or role-play.
• Persistent Economy: Earn Gold and XP through games and quests to level up your character.
• Standalone Mode: AI agents can be disabled for testing - the server runs without Assistant dependencies

📚 Documentation Index

For detailed information on specific dMUD systems, refer to the following guides:

• Command Interface: A guide to navigation, social commands, and room management.
• The Arcade & Economy: Details on mini-games, leveling, Gold, and the item system.
• World & Ambience: Information on ASCII screensavers, the room system, and world persistence.
• Scripting & Quests: Understanding the Quest system, Lua NPC engine, and Agent Bridge.
• Technical Operations: Admin guide for hot-reloading, standalone builds, and server debugging.

Key Files

Testing

The dmud module includes comprehensive testing infrastructure:

• cmd/dmud-bot/: Automated test bot that validates all features
• cmd/dmud-standalone/: Server variant without AI dependencies for CI/CD testing
• dmud/TESTING.md: Full testing documentation with pass/fail tracking

Running Tests

# Build standalone server
go build -tags standalone -o dmud-server.exe ./cmd/dmud-standalone/

# Build test bot
go build -o dmud-bot.exe ./cmd/dmud-bot/

# Run tests (requires server running)
./dmud-bot.exe --standalone

🎮 RPG System Expansion (April 2026)

In April 2026, dMUD received a comprehensive RPG system expansion, adding profession mechanics, pet systems, and enhanced NPC interactions:

Profession System

• Mining & Woodcutting: Implemented idle profession mechanics with resource gathering
• Profession Tools: Added profession-specific tools and resource items
• Weekly Quests: Mayor and Guard NPCs offer weekly profession quests
• Idle Mechanics: Professions progress over time with passive resource generation

Wallet & Inventory

• Wallet Commands: /wallet, /balance, /pay for currency management
• Inventory System: /inventory, /use, /drop for item management
• Item Persistence: Items saved to data/items.json with user ownership
• Trading: /trade command for player-to-player item trading

Pet System

• Pet Adoption: Adopt pets from the tavern with /pet adopt
• Pet Feeding: /pet feed and /pet buyfood for pet care
• Auto-Feed Worker: Background worker automatically feeds hungry pets
• Pet Seller NPC: Tavern NPC sells pet food and accessories
• Pet Stats: Track pet hunger, happiness, and experience

NPC Logic Ecosystem

• NPC Triggers: Full NPC triggers on /use and /trade commands
• Lua Scripting: Enhanced Lua API with give_item function
• Quest Hooks: Quest acceptance script hooks for tool integration
• NPC Shops: Shop NPCs with item purchasing and selling

RPG Dashboard

• Real-Time Dashboard: /rpg command shows live inventory and quest status
• Quest Tracking: Active quests with progress indicators
• Character Stats: Level, XP, Gold, and profession progress
• Quick Actions: Fast access to common RPG commands

Dynamic Room System (Current)

• INI-Driven Rooms: All rooms (system + player-created) defined in dmud/data/rooms/*.ini (64+ files as of late 2026)
• Hot Reload: /reload rooms (or admin API) calls RoomManager.ReloadRooms() which clears and reloads every .ini
• Room Creation Wizard: /room create starts multi-step flow (template → name → description → visibility → link exits); implemented in room_creation.go
• Persistence: savePlayerRoom() writes new player rooms as .ini; loadPlayerRoomsFromINI() loads them at startup
• Core Functions: LoadRoomFromINI(), SaveRoomToINI(), LoadRooms(), connectRooms()

Server Hang Fixes (2026-04-18)

Recent debugging resolved server hangs during reconnection and in NPC rooms:

See source tree file dmud/TESTING.md (not served by the wiki UI at :7779; contains testbot phase assertions and pass/fail history).

📅 June 2026 Additions

Seasonal Event System

• New module: dmud/seasonal.go — seasons, festivals, weather, seasonal stat bonuses, seasonal NPC spawns
• Integration: dmud/events.go gains seasonal/seasonal_start/seasonal_end/weather/festival EventTypes + new actions give_xp, apply_seasonal_bonus, set_weather
• Character Pass: seasonal stat bonuses + seasonal equipment effects (SeasonalStatBonus)
• Bug: holiday_end events re-triggered every minute until 9fe6c6be reset the cooldown marker
• See: Seasonal Events

WoW Classic — Elwynn Forest Realm (themed multi-realm)

• Initial release: 7ca5ec6f — 9 rooms + 8 NPCs, entered via wow_azeroth_gateway
• Expansion: b84e0e53 — 8 new rooms + 7 NPCs + 2 expansion hooks (Westfall, Redridge stubs)
• Architecture: themed multi-realm pattern (commits 693b5583 / 2d896c1d) — each realm is a self-contained set of rooms behind its own portal hub; no implicit blending
• See: WoW Elwynn Realm

Async Command Pipeline (pipeline.go)

• Per-session worker goroutine with bounded buffered channel (cap 16) + non-blocking enqueue + drop-on-full warn
• 30s per-command context timeout — long-running commands abort cleanly
• Atomic response + prompt render — ambient frames can no longer interleave with command output
• See: Async Command Pipeline & Structured Logging

Structured Logging (log/slog)

• New dmud/logger.go — Logger package var + per-component sub-loggers (server/room/user/npc/...) + domain helpers (logRoomEnter, logConnect, ...)
• ~100 log.* calls across 17 files migrated to structured Logger.*
• log.Fatalf → slog.Error everywhere — library code never fatal-exits the parent process
• Bug fix: c3810acd — Logger nil-resolved by initialising it as a package-level var with a no-op init() stub (Go initialises package vars before init(), so the original logServer = logWith("server") line panicked on cold start)

Frontend Polish

• 964dd80c — Fixed /play page keyboard input and disconnect message display
• a26e29d9 — Play tab, world life stats, improved users page (web UI refresh on port 7778)