HammerMUD2

A modern real-time MUD (Multi-User Dungeon) built with Elixir/Phoenix backend, React frontend, and Tauri desktop app.

Project Structure

hammermud2/
├── mudcli/           # Python CLI tool for managing the project
├── realtime/         # Elixir/Phoenix backend server
├── frontend/         # React/TypeScript web frontend
├── desktop/          # Tauri desktop application
├── docs/             # Project documentation
└── logs/             # Application logs

Directory Details

• mudcli/ - Python-based command-line interface for development workflow

  • Manages starting/stopping services
  • Runs tests, linting, and database operations
  • Bootstraps the development environment

• realtime/ - Phoenix backend application

  • WebSocket-based real-time communication
  • User authentication and character management
  • World simulation and chat system
  • PostgreSQL database integration

• frontend/ - React web application

  • Real-time chat interface
  • Character creation and selection
  • Game world visualization
  • Built with TypeScript, Tailwind CSS, and Redux Toolkit

• desktop/ - Tauri desktop wrapper

  • Native desktop experience
  • Wraps the web frontend in a desktop application
  • Cross-platform support (Windows, macOS, Linux)

• docs/ - Project documentation

  • Game design documents
  • API documentation
  • Development guides

Quick Start

Prerequisites

• Python 3.13+ (for mudcli)
• Elixir 1.15+ and Erlang 26+ (for backend)
• Node.js 18+ and npm (for frontend/desktop)
• PostgreSQL (for database)
• Rust (for Tauri desktop app)

Bootstrap the Environment

1. Clone the repository:

   git clone <repository-url>
   cd hammermud2
   

2. Run the bootstrap script:

   ./mcli bootstrap
   

   This will:

   • Install all system dependencies
   • Set up Python virtual environment
   • Install Elixir, Node.js, and Rust dependencies
   • Create and seed the database

3. Start the application:

   ./mcli start
   

   This starts both the backend server and frontend development server.

4. Access the application:

   • Web interface: http://localhost:3000
   • Backend API: http://localhost:4000

Alternative Setup (Manual)

If you prefer manual setup or the bootstrap fails:

1. Install dependencies:

   ./mcli deps
   

2. Set up the database:

   cd realtime
   mix ecto.setup
   cd ..
   

3. Start services:

   ./mcli start
   

Development Commands

The mcli tool provides all necessary development commands:

Service Management

./mcli start           # Start backend and frontend
./mcli stop            # Stop all services
./mcli restart         # Restart all services
./mcli status          # Check service status
./mcli logs            # View service logs
./mcli logs -f         # Follow logs in real-time

Development Tools

./mcli test            # Run all tests
./mcli test --frontend-only  # Run only frontend tests
./mcli test --backend-only   # Run only backend tests
./mcli lint            # Lint and format all code
./mcli lint --check    # Check code style without fixing

Database Operations

./mcli reset-db        # Reset database (removes all user data)

Desktop Application

./mcli desktop         # Start desktop application

Environment Setup

./mcli bootstrap       # Full environment bootstrap
./mcli setup          # Lightweight setup (dependencies only)
./mcli deps           # Install project dependencies

Technology Stack

Backend (realtime/)

• Elixir/Phoenix - Web framework and real-time features
• PostgreSQL - Primary database
• Phoenix LiveView - Real-time UI updates
• WebSockets - Real-time communication
• ExUnit - Testing framework

Frontend (frontend/)

• React 18 - UI framework
• TypeScript - Type safety
• Vite - Build tool and dev server
• Tailwind CSS - Styling
• Redux Toolkit - State management
• Vitest - Testing framework

Desktop (desktop/)

• Tauri - Desktop application framework
• Rust - Systems programming language
• WebView - Renders the React frontend

CLI Tool (mudcli/)

• Python 3.13 - CLI implementation
• Click - Command-line interface framework
• Black/Flake8 - Code formatting and linting

Game Features

• Real-time Chat System - Multi-channel communication
• Character Creation - D&D-inspired character building
• World Navigation - Move through game locations
• User Authentication - Secure account system
• Character Management - Multiple characters per account
• Minimap - Visual world representation

Contributing

1. Set up development environment:

   ./mcli bootstrap
   

2. Make your changes and test them:

   ./mcli test
   ./mcli lint
   

3. Start the application to verify:

   ./mcli start
   

Troubleshooting

Common Issues

1. Services won't start:

   ./mcli status          # Check what's running
   ./mcli stop            # Stop any hung processes
   ./mcli start           # Try starting again
   

2. Database issues:

   ./mcli reset-db        # Reset database (WARNING: removes all data)
   

3. Dependency problems:

   ./mcli deps            # Reinstall dependencies
   

4. Log investigation:

   ./mcli logs -f         # Follow logs to see errors
   

Getting Help

• Check service logs: ./mcli logs
• Verify service status: ./mcli status
• Run the bootstrap again: ./mcli bootstrap
• Check individual service READMEs in their directories

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.