8000 Daemon18xx/docs/README.md at 1830 · jmahmood/Daemon18xx · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
186 lines (133 loc) · 5.6 KB

README.md

File metadata and controls

186 lines (133 loc) · 5.6 KB

Daemon18xx Documentation

Welcome to the Daemon18xx game engine documentation! This directory contains comprehensive guides, API references, and examples for working with the 18XX board game engine.

Documentation Overview

Getting Started

Developer Guides

Features

Variants

  • 1830 - Robber Barons variant
  • 1846 - Race for the Midwest
  • 1889 - Shikoku variant

Quick Links

For New Users

Start with the Quickstart Guide to understand the basics, then explore Game Concepts to learn 18XX terminology.

For Frontend Developers

Read the Frontend Integration Guide and API Reference to build your UI.

For Game Engine Developers

Check out the Architecture Overview and browse the Examples directory.

For Debugging

See Logging & Debugging for troubleshooting tools.

What is Daemon18xx?

Daemon18xx is a Python-based game engine for 18XX railway games. It provides:

  • ✅ Stateless Architecture - Suitable for web/API deployment
  • ✅ Multiple Variants - 1830, 1846, 1889 fully implemented
  • ✅ Comprehensive Testing - 233+ tests, all passing
  • ✅ Phase-Based Design - Modular minigames for each phase
  • ✅ Advanced Features - Loans, terrain costs, bankruptcy, special powers
  • ✅ Developer Tools - Logging, history tracking, phase validation

Key Features

⚡ Stateless Minigame Architecture

Game phases are separate "minigames" that receive state as parameters, making the engine perfect for web APIs and distributed systems.

📊 Historical Tracking

Complete price history, move history, and phase transitions are tracked for debugging, analysis, and replay.

🔒 Validation System

Comprehensive move validation ensures games follow rules correctly, with detailed error messages.

🎨 Frontend-Ready

Clean API design makes it easy to build web UIs, mobile apps, or desktop clients.

🧩 Extensible

Easy to add new variants, special powers, and game mechanics without modifying core code.

Architecture Highlights

Game State (Immutable)
    ↓
Minigame Validates Move
    ↓
Minigame Mutates State
    ↓
Phase Transition Check
    ↓
New Minigame (if needed)

Each game phase is a self-contained "minigame" that validates moves, mutates state, and determines the next phase. This design enables:

  • Easy testing (test each minigame independently)
  • Clear separation of concerns
  • Simplified debugging
  • Parallelizable operations

Example Usage

from app.state import Game

# Start a new game
game = Game.start(
    players=['Alice', 'Bob', 'Charlie'],
    variant='1830'
)

# Make moves
from app.minigames.PrivateCompanyInitialAuction.minigame_buy import BuyPrivateCompanyMove

move = BuyPrivateCompanyMove(
    player_id=game.current_player.id,
    company_id="C&O"
)

success = game.performedMove(move)

if success:
    print(f"Move successful! Next player: {game.current_player.name}")
else:
    print(f"Move failed: {game.errors()}")

Testing

Run the complete test suite:

# All tests
python -m unittest discover app/unittests -v

# Specific test file
python -m unittest app.unittests.test_PriceHistory -v

# Single test
python -m unittest app.unittests.test_PriceHistory.PriceHistoryEntryTests.test_entry_creation

Current status: 233 tests passing ✅

Contributing

Adding a New Variant

  1. Create config file in app/config/yourvariant.py
  2. Define companies, stock market, and rules
  3. Add variant-specific tests
  4. Document in docs/variants/yourvariant.md

Adding a New Feature

  1. Implement feature in appropriate module
  2. Write comprehensive tests (aim for 10+ tests)
  3. Update relevant documentation
  4. Submit PR with clear description

Coding Standards

  • Type hints for all public APIs
  • Docstrings for all classes and public methods
  • Tests for all new functionality
  • Logging for important operations
  • Validation for all user input

Support

Issues & Bugs

Report issues at: https://github.com/jmahmood/Daemon18xx/issues

Questions

For questions about game rules or implementation, see:

License

[Include license information here]

Credits

Built with ❤️ for the 18XX gaming community.


Navigation:

0