🚀 filler-game-engine

A high-performance, protocol-compliant remake of the Filler game engine, written in Rust. This engine was developed to provide a strictly fair competitive environment, deterministic debugging, and a fix for the common "Dead Zone" coordinate bug found in legacy engines.

✨ Why this Engine?

• Fixed "Dead Zone" Bug
  Original engines often include empty padding in pieces, making board edges mathematically unreachable.
  This engine implements a trim_and_build algorithm to ensure 100% of the Anfield is playable.

• Board-Aware Scaling
  Pieces are dynamically scaled based on map dimensions (30% max, clamped 3–9), ensuring strategic depth on all map sizes.

• Deterministic Auditing
  Uses 64-bit seeding for every match. Any game can be perfectly reproduced using the -s flag.

• Built-in Logging
  Automatically generates match_history.csv for win/loss tracking and engine_debug.log for troubleshooting bot crashes.

📂 Project Structure

filler-game-engine/
├── src/
│   ├── game/
│   │   ├── mod.rs                # Module definitions & re-exports
│   │   ├── anfield.rs            # Map parsing and coordinate representation
│   │   ├── piece.rs              # Piece generation & trim_and_build logic
│   │   ├── config.rs             # CLI flag parsing and help menu display
│   │   ├── game_engine.rs        # Core game loop and rule enforcement logic
│   │   └── token.rs              # Player token management
│   ├── process.rs                # Subprocess handling & bot I/O communication
│   └── main.rs                   # Entry point and handshake initialization
├── results/
│    ├── tournament/              # 🏆 Final Evidence
│    │   ├── season1_final.csv    # (Tracked via !)
│    │   └── season1_report.png   # (Tracked via !)
│    └── benchmark/               # 🧪 Development History
│        └── evolution_rinbo.png  # (Tracked via !)
├── scripts/                      # 📊 Python & Shell Audit Suite
├── maps/                         # Standard .txt map files for testing
├── robots/                       # (Ignored via .gitignore - Download via Release)
├── Cargo.toml                    # Rust manifest
├── requirements.txt              # Python manifest
└── match_history.csv             # (Ignored via .gitignore - Local only)

🚀 Getting Started

1. Build from Source

Make sure you have the Rust toolchain installed.

git clone https://github.com/Rinrino/filler-game-engine.git
cd filler-game-engine
cargo build --release

2. Download Assets (Maps & Robots)

To run matches, you need map files and bot executables.

• Option A: Automated Setup (Recommended)

Download the filler-assets.zip and run the setup command for your system:

• 🐧 Linux / WSL:

unzip filler-assets.zip && mv linux_robots robots && chmod +x robots/*

🍎 macOS (Apple Silicon):

unzip filler-assets.zip && mv mac_robots robots && chmod +x robots/*

• Option B: Use your own maps and bots by providing their paths to the flags.

ℹ️ Permission Denied? > If you get a "Permission Denied" error when running a bot, make sure it has execution permissions:
chmod +x ./robots/*

🤖 Included Robots

This engine comes pre-configured to test against:

• Community robots from fellow students.

• Terminator & Bender (Standard curriculum robots)

3. Run a Match

./target/release/game_engine -f [map_path] -p1 [bot1_path] -p2 [bot2_path] [options]

💡 Usage Examples

• Standard Match:

./target/release/game_engine -f maps/map00 -p1 robots/bender -p2 robots/rinbo

• Debug & Diagnostic Mode: (Generates timing statistics and engine_debug.log)

💡 Deterministic Tip: If a bot crashes, find the Seed in the match_history.csv and rerun the match with the -s flag to see the exact board state that caused the failure.

./target/release/game_engine -f maps/map00 -p1 robots/rinbo -p2 robots/megatron -d

4. Command Line Flags

Flag	Required?	Description
-f	Yes	Path to map file
-p1	Yes	Path to Player 1 bot
-p2	Yes	Path to Player 2 bot
-s	No	Seed for reproducible games
-d	No	Enable logging to engine_debug.log
-a	No	Animate board with ANSI refresh
-q	No	Quiet mode (suppress stdout)
-r	No	50ms visual refresh delay
-t <s>	No	Max thinking time in seconds (default: 10)
-h	No	Show help menu

🧠 Core Engine Features

The engine implements the standard Filler protocol with modern stability improvements, deterministic behavior, and enhanced debugging capabilities.

1. Robust Handshake & Process Management

• Performs the canonical $$$ exec p[1|2] handshake
• Runs bots in isolated subprocesses with strict pipe handling and timeout protection
• Remains responsive even if a bot hangs, crashes, or enters an infinite loop

2. Strategic Piece Generation

• Adaptive scaling: Piece size is dynamically calculated as ~30% of board dimensions, clamped to 3×3 – 9×9
• Dead-zone elimination: The trim_and_build algorithm removes all padding (leading/trailing empty rows/columns), enabling full edge utilization without coordinate offsets

3. Strict Rule Enforcement & Fair Scoring

• Enforces exact “one-cell overlap” connectivity and zero-tolerance collision / out-of-bounds checks
• Implements Winner’s Lap: when one player is stuck, the other continues playing until no moves remain, maximizing legitimate territory score

4. Advanced Diagnostics (-d flag)

• High-resolution move timing using std::time::Instant
• Post-match summary includes total thinking time, average turn duration, and per-player statistics
• Captures and preserves bot stderr output and crash information in engine_debug.log
• Maintains complete game state and match history even after bot failure

🤖 Compatible Bots

This engine has been primarily tested and confirmed working with the following student projects:

• Fillbert — Adaptive strategist using center-of-mass targeting and late-game gap filling.

• maximilian — Aggressive proximity attacker. Uses repeated BFS (Breadth-First Search) to minimize distance to the opponent, effectively "hugging" and suffocating the enemy's line of play.

• Megatron — High-reliability bot utilizing Heatmap/BFS to minimize distance to opponent.

• Mochi — Proximity-based attacker using Manhattan distance heatmaps for aggressive pursuit.

• Rinbo — Strategic expansionist. Uses state-machine logic and frontier analysis to optimize territory control and future move availability.

• Standard robots from the 01Founders curriculum (Bender, Terminator, etc.) are also fully supported. Most protocol-compliant bots will work without modification.

⚠️ Community robots are currently provided as Linux-only binaries.

📊 The Analysis Suite

This engine includes a statistical suite to eliminate "luck" from your AI development. By running multiple matches and aggregating results, you can see true performance deltas between versions. Please see 👉 Analysis Suite guide

🤝 Contributing

Contributions are welcome! Whether you want to add a new bot to the benchmark list, report a bug, or suggest an engine feature, please follow these steps:

1. Adding Your Robot to the Benchmarks

If you've built a Filler bot and want it featured in the Included Robots list, follow these steps:

1. Fork the repository
2. Place your compiled binary in the linux_robots or m1_robots/ folder
   → Please name it in lowercase (e.g. myawesomebot)
3. Add a link to your bot's source code in the 🤖 Compatible Bots section of the README
4. Submit a Pull Request with a brief description of your bot's strategy

2. Feature Requests & Bug Reports

If you encounter issues — such as:

• A coordinate edge case that trim_and_build doesn't handle correctly
• Subprocess handling hangs on your operating system
• Any unexpected behavior during replay or tournament runs

Please help us improve by doing the following:

• Open an Issue with a clear description of the bug or feature request
• If possible, provide the Seed (-s) used when the error occurred so I can reproduce it perfectly.

Thank you for contributing to this project!

⚖️ License

This project is licensed under the MIT License.
See the LICENSE file for full details.

👩🏻‍💻 Author

• Rin
  GitHub: @Rinrino

⬆️ Back to Top | 📊 Analysis Suite guide |🏆 Tournament Report