use clap::{Parser, Subcommand};
use scrabble::board::Board;
use scrabble::endgame::EndgameSolver;
use scrabble::eval::{EvalContext, Evaluator, LeaveTable, StaticEvaluator, Unseen};
use scrabble::formats::Gcg;
use scrabble::game::{Game, Turn};
use scrabble::lexicon::Lexicon;
use scrabble::movegen::MoveGenerator;
use scrabble::rack::Rack;
use scrabble::rules::{Alphabet, BoardLayout, GameConfig};
use scrabble::sim::{SimOptions, Simulator};
use scrabble::train::{head_to_head, train_leaves, TrainOptions};
use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::ExitCode;
use std::time::Instant;
#[derive(Parser)]
#[command(name = "scrabble", version, about, long_about = None)]
struct Cli {
#[command(subcommand)]
command: Command,
}
#[derive(Subcommand)]
enum Command {
Build {
words: PathBuf,
#[arg(short, long)]
out: PathBuf,
#[arg(long, default_value_t = 15)]
max_length: usize,
},
Analyze {
#[arg(short, long)]
lexicon: PathBuf,
#[arg(short, long)]
rack: String,
#[arg(short, long)]
board: Option<PathBuf>,
#[arg(short, long, default_value_t = 15)]
top: usize,
#[arg(long)]
sim: bool,
},
Endgame {
#[arg(short, long)]
lexicon: PathBuf,
#[arg(short, long)]
board: PathBuf,
#[arg(short, long)]
rack: String,
#[arg(short, long)]
opponent: String,
#[arg(long, default_value_t = 8_000_000)]
budget: u64,
},
Play {
#[arg(short, long)]
lexicon: PathBuf,
#[arg(short, long, default_value_t = 0)]
seed: u64,
#[arg(long)]
sim: bool,
#[arg(long)]
gcg: Option<PathBuf>,
#[arg(short, long)]
verbose: bool,
},
Anagram {
#[arg(short, long)]
lexicon: PathBuf,
rack: String,
#[arg(long, default_value_t = 2)]
min_length: usize,
},
TrainLeaves {
#[arg(short, long)]
lexicon: PathBuf,
#[arg(short, long)]
out: PathBuf,
#[arg(short, long, default_value_t = 2000)]
games: usize,
#[arg(long, default_value_t = 4)]
max_leave: usize,
#[arg(long, default_value_t = 30)]
min_samples: usize,
},
Compare {
#[arg(short, long)]
lexicon: PathBuf,
#[arg(long)]
leaves: Option<PathBuf>,
#[arg(short, long, default_value_t = 200)]
games: usize,
#[arg(long)]
vs_greedy: bool,
},
Bench {
#[arg(short, long)]
lexicon: PathBuf,
},
}
fn main() -> ExitCode {
match run(Cli::parse()) {
Ok(()) => ExitCode::SUCCESS,
Err(e) => {
eprintln!("scrabble: {e}");
ExitCode::FAILURE
}
}
}
type Fallible = Result<(), Box<dyn std::error::Error>>;
fn run(cli: Cli) -> Fallible {
let config = GameConfig::standard();
match cli.command {
Command::Build {
words,
out,
max_length,
} => build(&config, &words, &out, max_length),
Command::Analyze {
lexicon,
rack,
board,
top,
sim,
} => analyze(&config, &lexicon, &rack, board.as_deref(), top, sim),
Command::Endgame {
lexicon,
board,
rack,
opponent,
budget,
} => endgame(&config, &lexicon, &board, &rack, &opponent, budget),
Command::Play {
lexicon,
seed,
sim,
gcg,
verbose,
} => play(&config, &lexicon, seed, sim, gcg.as_deref(), verbose),
Command::Anagram {
lexicon,
rack,
min_length,
} => anagram(&config, &lexicon, &rack, min_length),
Command::TrainLeaves {
lexicon,
out,
games,
max_leave,
min_samples,
} => train(&config, &lexicon, &out, games, max_leave, min_samples),
Command::Compare {
lexicon,
leaves,
games,
vs_greedy,
} => compare(&config, &lexicon, leaves.as_deref(), games, vs_greedy),
Command::Bench { lexicon } => bench(&config, &lexicon),
}
}
fn load_lexicon(config: &GameConfig, path: &Path) -> Result<Lexicon, Box<dyn std::error::Error>> {
let bytes = std::fs::read(path)?;
if bytes.starts_with(b"SLEX") {
let lexicon = Lexicon::from_bytes(&bytes)?;
return Ok(lexicon);
}
let text = String::from_utf8(bytes)?;
let words = filter_words(&text, 15);
eprintln!(
"note: compiling {} words from {}; run `scrabble build` once to skip this",
words.len(),
path.display()
);
Ok(Lexicon::from_words(&config.alphabet, words)?
.with_name(path.file_stem().unwrap_or_default().to_string_lossy()))
}
fn filter_words(text: &str, max_length: usize) -> Vec<String> {
let mut words: Vec<String> = text
.lines()
.map(str::trim)
.filter(|w| (2..=max_length).contains(&w.chars().count()))
.filter(|w| w.bytes().all(|b| b.is_ascii_alphabetic()))
.map(|w| w.to_ascii_uppercase())
.collect();
words.sort_unstable();
words.dedup();
words
}
fn load_board(
config: &GameConfig,
path: Option<&Path>,
) -> Result<Board, Box<dyn std::error::Error>> {
match path {
None => Ok(Board::new(&config.layout)),
Some(p) => {
let text = std::fs::read_to_string(p)?;
Ok(Board::parse(&config.layout, &config.alphabet, &text)?)
}
}
}
fn parse_rack(alphabet: &Alphabet, s: &str) -> Result<Rack, Box<dyn std::error::Error>> {
Rack::parse(alphabet, s).map_err(|c| format!("{c:?} is not a tile").into())
}
fn build(config: &GameConfig, words: &Path, out: &Path, max_length: usize) -> Fallible {
let text = std::fs::read_to_string(words)?;
let list = filter_words(&text, max_length);
if list.is_empty() {
return Err(format!("{} contained no usable words", words.display()).into());
}
println!("compiling {} words...", list.len());
let started = Instant::now();
let lexicon = Lexicon::from_words(&config.alphabet, list)?
.with_name(out.file_stem().unwrap_or_default().to_string_lossy());
let elapsed = started.elapsed();
std::fs::write(out, lexicon.to_bytes())?;
println!(
" dawg {:>9} nodes {:>7.1} MiB",
lexicon.dawg().node_count(),
mib(lexicon.dawg().size_bytes())
);
println!(
" gaddag {:>9} nodes {:>7.1} MiB",
lexicon.gaddag().node_count(),
mib(lexicon.gaddag().size_bytes())
);
println!(
"written to {} in {:.2}s",
out.display(),
elapsed.as_secs_f64()
);
Ok(())
}
fn analyze(
config: &GameConfig,
lexicon: &Path,
rack: &str,
board: Option<&Path>,
top: usize,
sim: bool,
) -> Fallible {
let lexicon = load_lexicon(config, lexicon)?;
let board = load_board(config, board)?;
let rack = parse_rack(&config.alphabet, rack)?;
println!("{}", board.display(&config.layout, &config.alphabet));
println!("\nrack: {}\n", rack.to_text(&config.alphabet));
if sim {
let unseen = Unseen::new(config, &board, &rack);
let mut simulator = Simulator::new(config, SimOptions::default());
let results = simulator.run(&board, &rack, &lexicon, unseen.len().saturating_sub(7), 0);
if results.is_empty() {
println!("no legal plays");
return Ok(());
}
println!(
"{:<4} {:<22} {:>6} {:>9} {:>9} {:>7}",
"#", "play", "score", "equity", "sim", "±95%"
);
for (i, r) in results.iter().take(top).enumerate() {
println!(
"{:<4} {:<22} {:>6} {:>9.1} {:>9.1} {:>7.1}",
i + 1,
play_label(&r.play, &config.alphabet),
r.play.score(),
r.static_equity,
r.mean,
r.margin_of_error()
);
}
return Ok(());
}
let evaluator = StaticEvaluator::new();
let mut generator = MoveGenerator::new(config);
let unseen = Unseen::new(config, &board, &rack);
let ctx = EvalContext {
config,
board: &board,
lexicon: &lexicon,
rack: &rack,
bag_remaining: unseen.len().saturating_sub(config.rack_size),
spread: 0,
};
let mut plays: Vec<_> = generator
.generate(&board, &rack, &lexicon)
.iter()
.map(|&p| (p, evaluator.equity(&ctx, &p)))
.collect();
if plays.is_empty() {
println!("no legal plays");
return Ok(());
}
plays.sort_unstable_by(|a, b| b.1.total_cmp(&a.1));
println!(
"{:<4} {:<22} {:>6} {:>8} {:>9}",
"#", "play", "score", "leave", "equity"
);
for (i, (play, equity)) in plays.iter().take(top).enumerate() {
let leave = play.leave(&rack).unwrap_or_default();
println!(
"{:<4} {:<22} {:>6} {:>8} {:>9.1}",
i + 1,
play_label(play, &config.alphabet),
play.score(),
leave.to_text(&config.alphabet),
equity
);
}
println!("\n{} legal plays", plays.len());
Ok(())
}
fn endgame(
config: &GameConfig,
lexicon: &Path,
board: &Path,
rack: &str,
opponent: &str,
budget: u64,
) -> Fallible {
let lexicon = load_lexicon(config, lexicon)?;
let board = load_board(config, Some(board))?;
let mover = parse_rack(&config.alphabet, rack)?;
let other = parse_rack(&config.alphabet, opponent)?;
println!("{}", board.display(&config.layout, &config.alphabet));
println!(
"\nto move: {} opponent: {}\n",
mover.to_text(&config.alphabet),
other.to_text(&config.alphabet)
);
let started = Instant::now();
let mut solver = EndgameSolver::new(config).with_budget(budget);
let result = solver.solve(&board, &mover, &other, &lexicon);
let elapsed = started.elapsed();
match &result.best {
Some(play) => println!("best: {}", play_label(play, &config.alphabet)),
None => println!("best: pass"),
}
println!("spread: {:+}", result.spread);
println!(
"{} in {:.2}s over {} positions",
if result.exact {
"solved exactly"
} else {
"budget exhausted, result is a lower bound"
},
elapsed.as_secs_f64(),
result.nodes
);
Ok(())
}
fn play(
config: &GameConfig,
lexicon: &Path,
seed: u64,
sim: bool,
gcg: Option<&Path>,
verbose: bool,
) -> Fallible {
let lexicon = load_lexicon(config, lexicon)?;
let mut generator = MoveGenerator::new(config);
let mut simulator = Simulator::new(config, SimOptions::fast());
let evaluator = StaticEvaluator::new();
let mut game = Game::new(config.clone(), &["north", "south"], seed);
while !game.is_over() {
let side = game.to_move();
let rack = *game.current_rack();
let bag_remaining = game.bag().len();
let chosen = if sim {
simulator.best(game.board(), &rack, &lexicon, bag_remaining, 0)
} else {
let ctx = EvalContext {
config,
board: game.board(),
lexicon: &lexicon,
rack: &rack,
bag_remaining,
spread: 0,
};
generator
.generate(game.board(), &rack, &lexicon)
.iter()
.map(|&p| (p, evaluator.equity(&ctx, &p)))
.max_by(|a, b| a.1.total_cmp(&b.1))
.map(|(p, _)| p)
};
let turn = match chosen {
Some(play) => Turn::Place(play),
None if bag_remaining >= config.min_exchange_bag => Turn::Exchange(rack),
None => Turn::Pass,
};
let label = match &turn {
Turn::Place(p) => play_label(p, &config.alphabet),
Turn::Exchange(t) => format!("exchange {}", t.to_text(&config.alphabet)),
Turn::Pass => "pass".to_string(),
};
let score = game.apply(turn, &lexicon)?;
println!(
"{:<6} {:<9} {:<24} {:>4} ({})",
game.players()[side].name,
rack.to_text(&config.alphabet),
label,
score,
game.players()[side].score
);
if verbose {
println!(
"{}\n",
game.board().display(&config.layout, &config.alphabet)
);
}
}
println!(
"\n{}",
game.board().display(&config.layout, &config.alphabet)
);
println!();
for player in game.players() {
println!("{:<6} {:>5}", player.name, player.score);
}
match game.winner() {
Some(w) => println!("\n{} wins", game.players()[w].name),
None => println!("\na tie"),
}
if let Some(path) = gcg {
let transcript = Gcg::from_game(&game, &config.alphabet);
std::fs::write(path, transcript.to_text())?;
println!("transcript written to {}", path.display());
}
Ok(())
}
fn anagram(config: &GameConfig, lexicon: &Path, rack: &str, min_length: usize) -> Fallible {
let lexicon = load_lexicon(config, lexicon)?;
let rack = parse_rack(&config.alphabet, rack)?;
let mut words: Vec<String> = lexicon
.anagrams(&rack)
.iter()
.filter(|w| w.len() >= min_length)
.map(|w| lexicon.decode(&config.alphabet, w))
.collect();
words.sort_by(|a, b| b.len().cmp(&a.len()).then_with(|| a.cmp(b)));
for word in &words {
println!("{word}");
}
eprintln!("{} words", words.len());
Ok(())
}
fn train(
config: &GameConfig,
lexicon: &Path,
out: &Path,
games: usize,
max_leave: usize,
min_samples: usize,
) -> Fallible {
let lexicon = load_lexicon(config, lexicon)?;
let options = TrainOptions {
games,
max_leave,
min_samples,
..TrainOptions::default()
};
let started = Instant::now();
let report = train_leaves(config, &lexicon, options, |done| {
if done % 100 == 0 || done == games {
print!("\r {done}/{games} games");
let _ = std::io::stdout().flush();
}
});
println!(
"\rplayed {} games in {:.1}s",
games,
started.elapsed().as_secs_f64()
);
println!(" {} turns observed", report.observations);
println!(" {:.1} mean points per turn", report.mean_turn_score);
println!(
" {} distinct leaves seen, {} with at least {min_samples} samples",
report.distinct_leaves, report.kept
);
if report.kept == 0 {
return Err(
"no leave cleared the sample threshold; play more games or lower --min-samples".into(),
);
}
std::fs::write(out, report.table.to_bytes())?;
println!("written to {}", out.display());
Ok(())
}
fn compare(
config: &GameConfig,
lexicon: &Path,
leaves: Option<&Path>,
games: usize,
vs_greedy: bool,
) -> Fallible {
let lexicon = load_lexicon(config, lexicon)?;
let games = (games / 2) * 2;
if games == 0 {
return Err("need at least two games, since they are played in mirrored pairs".into());
}
let challenger = match leaves {
Some(path) => {
let bytes = std::fs::read(path)?;
let table = LeaveTable::from_bytes(&bytes)
.ok_or_else(|| format!("{} is not a leave table", path.display()))?;
println!("player A: leave table with {} entries", table.len());
StaticEvaluator::with_leaves(table)
}
None => {
println!("player A: built-in heuristic");
StaticEvaluator::new()
}
};
let baseline = if vs_greedy {
println!("player B: greedy, highest score only");
StaticEvaluator::greedy()
} else {
println!("player B: built-in heuristic");
StaticEvaluator::new()
};
let started = Instant::now();
let report = head_to_head(config, &lexicon, &challenger, &baseline, games, 0xA11CE);
println!(
"\n{} mirrored games in {:.1}s",
games,
started.elapsed().as_secs_f64()
);
println!(
" A {} - {} B, {} tied",
report.a_wins, report.b_wins, report.ties
);
println!(" win rate {:.1}%", report.win_rate() * 100.0);
println!(" mean spread {:+.1} per game", report.mean_spread);
Ok(())
}
fn bench(config: &GameConfig, lexicon: &Path) -> Fallible {
let started = Instant::now();
let lexicon = load_lexicon(config, lexicon)?;
println!(
"lexicon {} words, {:.1} MiB, loaded in {:.2}s",
lexicon.word_count(),
mib(lexicon.size_bytes()),
started.elapsed().as_secs_f64()
);
let mut generator = MoveGenerator::new(config);
let mut board = Board::new(&config.layout);
let mut game = Game::new(config.clone(), &["a", "b"], 1);
for _ in 0..8 {
let Some(play) = game
.legal_plays(&mut generator, &lexicon)
.iter()
.max_by_key(|p| p.score())
.copied()
else {
break;
};
if game.apply(Turn::Place(play), &lexicon).is_err() {
break;
}
}
board.clone_from(game.board());
println!(
"\n{:<10} {:>7} {:>11} {:>13}",
"rack", "plays", "per call", "plays/sec"
);
for text in ["AEINRST", "AEIOUUV", "QJXZKWV", "AEINRS?"] {
let rack = parse_rack(&config.alphabet, text)?;
let count = generator.generate(&board, &rack, &lexicon).len();
for _ in 0..20 {
generator.generate(&board, &rack, &lexicon);
}
let iterations = 200u32;
let started = Instant::now();
for _ in 0..iterations {
std::hint::black_box(generator.generate(&board, &rack, &lexicon).len());
}
let per = started.elapsed().as_secs_f64() / iterations as f64;
println!(
"{:<10} {:>7} {:>10.1}us {:>13.0}",
text,
count,
per * 1e6,
count as f64 / per
);
}
Ok(())
}
fn play_label(play: &scrabble::movegen::Play, alphabet: &Alphabet) -> String {
format!(
"{} {}",
play.coord().format(play.direction()),
play.word_text(alphabet)
)
}
fn mib(bytes: usize) -> f64 {
bytes as f64 / (1 << 20) as f64
}
#[allow(dead_code)]
fn custom_layout(text: &str) -> Result<BoardLayout, Box<dyn std::error::Error>> {
Ok(BoardLayout::parse("custom", text)?)
}