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

Multi-Room Zones

• Zone Expansion: Expanded dLand into multi-room zones
• Zone Navigation: /goto and /map for zone exploration
• Zone-Specific Content: Different resources and NPCs per zone
• Zone Persistence: Zone state saved to data/zones/

Server Hang Fixes (2026-04-18)

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

See dmud/TESTING.md for full debugging guide.