Kyndill

Kyndill is a Rust Tablut agent for the University of Bologna AI Fundamentals Tablut Challenge.

The Name and General Introduction

The name "Kyndill" was originally meant as a pun. In norse language, it can be translated as "Candle" or "Torch". The project's original end milestone was to implement PyTorch-based tooling to explore deep learning approaches to Tablut.

However, due to time constraints and limitations posed by the challenge's VM, it was deemed more reasonable to focus on minimax with alpha-beta pruning, accelerated greatly with help from a compact state representation and techniques that literature finds particularly useful in perfect-knowledge games (and are standard in chess engines): transposition tables and killer/history ordering bias.

A Genetic Algorithm weight tuner based on grouped-crossover with bounded mutation was also introduced but rather late. This limited tuning time (18 hours) after debugging the tuner itself, and with limitations regarding the tuning process (20 seconds timeout per move, match-based against V4 black heuristics and only for white weights).

What it's made of

The final runtime wants to keep things compact and deterministic:

• official protocol framing and JSON message handling;
• typed board, role, turn, pawn, and action models;
• validated movement, local apply, capture, and trusted terminal helpers;
• compact u128 search state with packed moves and incremental hashing;
• deterministic alpha-beta with iterative deepening, transposition table and killer/history ordering;
• deterministic minimax alpha-beta search with iterative deepening;
• transposition table using compact-state hashes, stored depth, score bounds, and best-move hints;
• move ordering bias affected by tactical ordering, killer/history bonuses and TT memoization bonuses
• V4 runtime profile:
  • White evaluator tuned with GA based on grouped-crossover with bounded mutation and elitism;
  • Asymmetric V4 evaluator/order path for Black, manually tuned and judged strong enough (not GA-tuned yet due to time constraints);

Build

cargo build --release

Run

Launcher shape:

./runmyplayer.sh WHITE 60 127.0.0.1
./runmyplayer.sh BLACK 60 127.0.0.1

CLI contract:

<role> <timeout_secs> <server_ip> [--output basic|silent] [--heuristic v4|v4-previous]

Defaults:

• --output silent
• --heuristic v4

Output modes

./runmyplayer.sh WHITE 60 127.0.0.1 --output basic

Supported values are silent and basic; off and none are accepted aliases for silent. silent prints no per-turn diagnostics. basic writes one compact line to stderr after each own move, including move, depth, nodes, elapsed time, score, timeout/fallback flags, root diagnostics, and V4 White simple-score fields when available. silent ia to be used for normal matches; diagnostic output is for local inspection and searching ways to improve heuristics.

The runtime sends only locally validated legal actions. If search cannot finish a depth before the budget expires, Kyndill falls back to a deterministic legal move instead of sending an invalid action.

Test

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all

Focused checks:

cargo test installed_ga_candidate
cargo test white_simple
cargo test v4_black
cargo test match_ga

Offline GA Tuning Tools

The repository keeps optional offline tuning tools for WhiteSimpleWeights. They are not required to build or run the player.

Example smoke command:

cargo run --release --bin v4_white_match_ga -- \
  --run-id local_ga_smoke \
  --budget-seconds 600 \
  --workers 1 \
  --seed 177826 \
  --population 16 \
  --elitism 3 \
  --move-timeout 5 \
  --opponents v4_black \
  --resume

The match GA uses grouped crossover, bounded mutation, elitism, and resume/checkpointing. It evaluates candidate White weights in internal sparring and writes artifacts for candidate validation. The official runtime only uses static installed weights.

See docs/optimization.md.

Further Reading

• Architecture
• Heuristics history and final V4 design
• Offline GA optimizer

Project Layout

• src/protocol, src/runtime, src/agent: official protocol and turn loop.
• src/legal: movement, apply, capture, and trusted terminal helpers.
• src/search/compact_state.rs: compact board representation, movegen, apply, and hashing.
• src/search/engine/: iterative deepening, alpha-beta, TT integration, root scoring, and runtime diagnostics.
• src/search/eval/: V4 Black, V4Previous, and shared compact analysis.
• src/search/order.rs: deterministic tactical ordering.
• src/search/white_simple.rs: installed White simple evaluator and tunable weight model.
• src/bin/v4_white_match_ga.rs: offline match-based GA optimizer.