Welcome to the Daemon18xx game engine documentation! This directory contains comprehensive guides, API references, and examples for working with the 18XX board game engine.
- Quickstart Guide - Get up and running in 5 minutes
- Architecture Overview - High-level system design
- Game Concepts - 18XX game rules and terminology
- API Reference - Complete API documentation
- Frontend Integration Guide - Building UIs with the engine
- Move Types Reference - All available moves and validation
- Examples - Code examples and tutorials
- Historical Price Tracking - Track stock price changes
- Logging & Debugging - Structured logging and game history
- Phase Validation - Game phase transitions
- Special Powers - Private company powers
- Loans & Bankruptcy - Financial mechanics
- Terrain Costs - Track laying costs
Start with the Quickstart Guide to understand the basics, then explore Game Concepts to learn 18XX terminology.
Read the Frontend Integration Guide and API Reference to build your UI.
Check out the Architecture Overview and browse the Examples directory.
See Logging & Debugging for troubleshooting tools.
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
Game phases are separate "minigames" that receive state as parameters, making the engine perfect for web APIs and distributed systems.
Complete price history, move history, and phase transitions are tracked for debugging, analysis, and replay.
Comprehensive move validation ensures games follow rules correctly, with detailed error messages.
Clean API design makes it easy to build web UIs, mobile apps, or desktop clients.
Easy to add new variants, special powers, and game mechanics without modifying core code.
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
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()}")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_creationCurrent status: 233 tests passing ✅
- Create config file in
app/config/yourvariant.py - Define companies, stock market, and rules
- Add variant-specific tests
- Document in
docs/variants/yourvariant.md
- Implement feature in appropriate module
- Write comprehensive tests (aim for 10+ tests)
- Update relevant documentation
- Submit PR with clear description
- 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
Report issues at: https://github.com/jmahmood/Daemon18xx/issues
For questions about game rules or implementation, see:
- Game Concepts for rules
- API Reference for implementation
- Examples for code samples
[Include license information here]
Built with ❤️ for the 18XX gaming community.
Navigation: