Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (107 loc) · 3.64 KB

CONTRIBUTING.md

File metadata and controls

141 lines (107 loc) · 3.64 KB
Raw

Contributing to Ellmud

Thanks for your interest in contributing to Ellmud, a real-time multiplayer MUD/MMORPG with permadeath! This guide will help you get started.

Getting Started

Prerequisites

  • Node.js ≥ 20.0.0 (check .nvmrc)
  • Docker (recommended for PostgreSQL and Redis)
  • Git

Setup

# Clone the repository
git clone https://github.com/dkirby-ms/ellmud.git
cd ellmud

# Use the correct Node version
nvm use

# Install dependencies
npm install

# Start services (PostgreSQL, Redis)
docker compose up -d

# Build all packages
npm run build

# Run the dev server
npm run dev

For detailed setup, see Setup Guide.

Workflow

  1. Pick an issue or create one to discuss your idea first
  2. Create a branch from dev with a descriptive name: 
    git checkout -b feature/my-feature
  3. Make your changes and test them: 
    npm run build
npm run test
npm run lint
  4. Commit with a clear message following Conventional Commits: 
    feat: add new creature type
fix: resolve combat tick timing issue
docs: update player guide
chore: update dependencies
  5. Push and open a pull request against dev
  6. Respond to feedback and keep commits clean

Code Style

  • TypeScript — all code must be typed
  • ESLint — automated linting via npm run lint
  • Formatting — follow existing patterns; no enforced formatter
  • Comments — only for complex logic; avoid obvious comments

Testing

Before submitting a PR:

npm run test          # Run all tests
npm run lint          # Check for linting issues
npm run build         # Ensure code builds

If you add features, please add corresponding tests.

Areas of Contribution

Game Logic & Systems

  • Creature AI and behaviors (state machines, pack mechanics, boss fights)
  • Combat mechanics and balance (abilities, positioning, threat systems)
  • Item system and loot distribution (by zone, by creature type)
  • Progression and skills (leveling mechanics, ability unlocks)
  • Zone design and content (hand-crafted areas, encounters, environmental storytelling)

Client & UI

  • Web client (React) improvements
  • Unity 3D client development and graphics
  • Admin dashboard features and tools
  • Player guide and tutorials
  • Accessibility improvements

Backend & Infrastructure

  • Performance optimizations
  • Database schema improvements
  • API enhancements and WebSocket protocol
  • DevOps and deployment

Documentation

  • Player guides and tutorials
  • Architecture documentation (server, protocol, clients)
  • Zone design specifications and guidelines
  • API reference improvements
  • Setup and troubleshooting

Reporting Bugs

Use the bug report template when opening an issue. Include:

  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Screenshots (if applicable)
  • Environment (OS, Node version, etc.)

Feature Requests

Use the feature request template. Describe:

  • The problem you're solving
  • Your proposed solution
  • Any alternatives you've considered
  • Why this feature matters

Code Review

All PRs require review before merging. Reviewers will check for:

  • ✅ Correctness and logic
  • ✅ Test coverage
  • ✅ Code style and TypeScript best practices
  • ✅ Documentation updates
  • ✅ No breaking changes (unless intended)

Questions?

  • Discord: Join our community server for discussion
  • Discussions: Use GitHub Discussions for questions
  • Issues: Open an issue to report bugs or suggest features

Thanks for contributing! 🎮