Domino Game Engine

A flexible, testable Rust implementation supporting multiple domino game variants, built with Bevy ECS.

Features

• Multiple Game Variants: Block, Draw, All-Fives, Mexican Train, Chicken Foot, Grid
• Modular Architecture: Separate crates for core logic, rules, and rendering
• Comprehensive Testing: Unit tests, property-based tests, snapshot tests, visual regression tests
• Performance Optimized: Board state caching, parallel move evaluation
• Developer Tooling: CLI tool, debug overlay, replay system, fuzzing harness

Project Structure

crates/
├── domino-core       # Pure Rust game logic (no external deps)
├── domino-rules      # Pluggable game variant definitions
├── domino-bevy       # Bevy ECS integration layer
├── domino-testing    # Shared test utilities and fixtures
├── domino-dev-tools  # Debugging and development utilities
├── domino-perf       # Performance benchmarking and optimization
├── domino-cli        # Command-line interface tool
├── domino-visual-testing  # Visual regression testing
└── domino-app        # Main application binary

Quick Start

Prerequisites

• Rust 1.83+ (2024 edition)
• Cargo

Building

# Build all crates
cargo build

# Build release version
cargo build --release

Running the Application

cargo run --package domino-app

Running Tests

# Run all tests
cargo test

# Run tests for specific crate
cargo test --package domino-core
cargo test --package domino-rules

# Run with output
cargo test -- --nocapture

Generating Documentation

# Generate and open documentation
cargo doc --open --no-deps

Game Variants

Variant	Description	Topology
Block Dominoes	Classic simple game	Chain
Draw Dominoes	Block with draw mechanic	Chain
All-Fives	Score on multiples of 5	Chain
Mexican Train	Multi-player with personal trains	Multi-train
Chicken Foot	Branching at doubles	Tree
Grid Dominoes	2D placement	Grid

Documentation

• Architecture Guide - System design and module overview
• Testing Guide - How to write and run tests
• Adding New Variants - Step-by-step guide for new games

Using the CLI

# Test a specific placement
cargo run --package domino-cli -- test-placement \
  --variant block \
  --board "6-5, 5-3" \
  --tile "3-4" \
  --target "end:5-3:B"

# Find valid moves for a hand
cargo run --package domino-cli -- valid-moves \
  --variant block \
  --hand "3-2, 4-1, 6-6"

# Validate board state
cargo run --package domino-cli -- validate --board-file game.json

Benchmarking

# Run all benchmarks
cargo bench --package domino-perf

# Run specific benchmark
cargo bench --package domino-perf -- valid_placements

License

MIT OR Apache-2.0

Contributing

See ARCHITECTURE.md for design decisions and TESTING_GUIDE.md for testing best practices.