01 / Fit

First decide whether the game fits KataGomo

Checking the fit before tuning saves a great deal of wasted work. The framework is not limited to games such as Go, Gomoku, and Hex that place directly on empty points. It can also handle multi-part moves in Xiangqi, Ataxx, or Amazons by splitting one move into stages—for example, selecting a piece and then its destination.

Best fit

Two-player play on a two-dimensional board, with perfect information and no randomness, where the state determines a result or score. Gomoku variants, Hex variants, connection games, and Go variants usually fit naturally.

Also a good fit

Games that move pieces—Xiangqi, chess, Ataxx, Amazons, Breakthrough, and others—can also be integrated. A common approach splits a compound action into stages so the policy head selects only one board point at a time.

Avoid for a first integration

Randomness, hidden information, and multiplayer games are not fundamentally impossible, but they require much larger changes to KataGo/KataGomo. For a first game, choose a two-player, zero-sum, perfect-information ruleset.

02 / Engine

Turn the rules into a trainable engine

The first task is not tuning a neural network; it is telling the engine exactly what the game is.

1. Choose a nearby branch

Do not begin from an empty project. Find a KataGomo branch whose mechanics resemble the new game: start near Gomoku or Connect6 for connection games, or near a Go variant for capture-based rules.

Prefer a branch from 2023 or later, because its scripts and project structure are usually closer to the current version.

2. Implement the C++ rules

The main locations include board.h/cpp, boardhistory.h/cpp, and nninputs.cpp. The engine needs legal moves, terminal conditions, wins or scoring, repetition, board size, and neural-network inputs.

The Python/PyTorch training code usually does not need changes. If the board lacks all eight rotation/reflection symmetries, inspect and modify the augmentation logic.

Open the rules integration reference →

3. Build and check

Linux and Windows are both supported. Build the engine using the KataGo workflow, then test the rules on small boards, short games, random positions, and hand-authored positions. Check for crashes and correct game termination.

Spend time here. Self-play magnifies a rules bug without limit, and the strength of a model trained on that bug is meaningless.

03 / Pipeline

Arrange the scripts, then start the loop

The standard training.md entry point puts the compiled engine in the scripts directory and runs the training loop. A branch usually keeps its scripts under ./scripts. Place the engine at ./engine/katago; on Linux make the required .so files discoverable, and on Windows do the same for the matching .dll files.

Install PyTorch; on Windows, Git Bash is recommended. After editing the parameters, run run_train.sh or the similarly named script in that branch.

./scripts
  ./engine/katago        # compiled engine with the new rules
  ./selfplay.cfg         # self-play GPU, board, and search settings
  ./run_train.sh         # self-play + train entry point for each generation
  ./train/train.sh       # training parameters
  ./train/shuffle.sh     # data shuffling and retention

04 / Parameters

Parameters you will change most often

Use a small model to verify the rules, scripts, and data flow before increasing the budget.

Model size

Common KataGomo model sizes and suitable training stages
Size Purpose Typical use
b6c96 / b10c128Fast debugVerify rules, scripts, and data flow
b10c256nbtShort runRoughly 1–5 RTX 4090-days and about one million self-play games
b10c384nbtMedium runRoughly 5–20 RTX 4090-days and several million self-play games
b18c384nbt or largerLong runConsider only after the rules are stable and a strong model is the goal

Specify the model name and architecture in the train.sh call inside run_train.sh. Architectures are defined in train/modelconfigs.py. A commonly used suffix is -fson-mish-rvglr-bnh.

GPUs and board size

  • Set batchsize by available memory: small networks can use larger batches; large networks need smaller ones.
  • -multi-gpus 0,1 selects training GPUs. Use 0 or omit it for one GPU.
  • CUDA_VISIBLE_DEVICES selects the GPUs visible to the process.
  • numNNServerThreadsPerModel, gpuToUseThread0, and related entries in selfplay.cfg control the self-play GPUs.
  • -pos-len must match dataBoardLen in selfplay.cfg, or the data dimensions will differ.

05 / Network

A route through neural-network training

Optimize for stability on a short run; evaluate a more ambitious training branch only for the long run.

Short run: default CNN + SGD

When a game is newly integrated, the default CNN + SGD scripts are safer. The engineering path is mature, so a failure is easier to attribute to a rules bug, a data bug, or unsuitable training parameters.

The key: iterative self-play

The decisive factor is not one round of supervised fitting. It is the loop in which the model plays, generates stronger data, and trains its successor. Stabilize that loop during the short run.

Long run: Transformer + Muon

For a long run, evaluate KataGo_Transformer . It uses a Transformer model and the Muon optimizer. It outperformed CNN + SGD in some of this project's long runs, but a new game still needs a paired comparison with equal data, search budget, and match settings.

Why late-stage long runs resemble quasi-supervised learning

Late in training, the AI's move distribution may stop changing in a statistically significant way, and self-play increasingly samples near a high-quality policy. Training can then be approximated as quasi-supervised learning: architecture, optimizer, and sample efficiency matter more, making any advantage of Transformer + Muon easier to observe.

06 / Data

The ratio of self-play to training

For a new game, begin with a stable ratio, watch for overfitting, and scale gradually.

Starting point

For a new game, try -max-games-total 10000 and -samples-per-epoch 1000000: generate 10,000 self-play games per generation, then train on 1,000,000 samples.

samples-per-epoch / max-games-total roughly determines how many times each unit of self-play data is trained. Too high risks overfitting; too low wastes the main cost, self-play.

Overfitting check

When changing -samples-per-epoch, also adjust -keep-target-rows in shuffle.sh; it should usually be slightly larger than -samples-per-epoch.

Watch vloss. The documentation recommends vloss_val - vloss_train < 0.05. If the gap is too large, generate more self-play games or reduce samples trained per generation.

07 / Board size

For a large board, start small

As the board grows, training cost can rise far faster than linearly.

Why not start on the largest board

For conservative planning I separate three effects: network inference grows with area, games usually become longer, and the search per move may need to grow to preserve move quality. Together they can make cost rise much faster than board width. This is a planning heuristic, not a fixed power law for every game.

Before scaling from 13×13 to 19×19, measure moves per game, visits per move, and GPU throughput on a small number of games, then decide whether to expand the training budget.

Recommended: pretrain small, fine-tune large

Train first on a smaller board such as 13×13. After the model reaches a useful level, continue briefly at 19×19 as a fine-tuning stage.

Some fully convolutional networks in the project can initialize 19×19 training from 13×13 weights, but strength and strategy are not guaranteed to transfer. After changing size, first check input dimensions, legal moves, game end, and inference stability; then use target-size self-play and paired matches to decide whether continued training is worthwhile.

08 / Roadmap

An executable roadmap

Split trainability into small, testable stages, so a failure tells you where to return.

  1. Stage 0: freeze the rules. Specify the board, turns, legal moves, wins, draws or loops, forbidden moves, and scoring. For an original game, add hand-authored test positions.
  2. Stage 1: small-network smoke test. Use b6c96 or b10c128 for limited self-play. Verify only that the engine, data, training, model saving, and next-generation loading all work.
  3. Stage 2: short run for trends. Move to b10c256nbt with a declared GPU-hour and game budget. Use fixed-search paired matches to examine strength, first-player effects, and obvious rules flaws. Results depend on the game and hardware; if rules need changes, retrain early.
  4. Stage 3: medium run for strength. Increase self-play and test whether trends from the short run reproduce with a new model and a higher search budget. Win rates may widen, converge, or reverse, so report game count, confidence intervals, color swaps, and model versions.
  5. Stage 4: release a reproducible experiment. Save the model, configuration, rules branch, training logs, and evaluation notes so others can reproduce it and you can continue iterating.

09 / Pitfalls

Common pitfalls

Incomplete rules

Miss one boundary case—legal moves, game end, repetition, no legal move, or a forbidden move—and the AI will treat it as a tactic. Test rules before spending GPU time.

Wrong board symmetries

If the game lacks rotation or reflection symmetry but training still applies all eight augmentations, inequivalent positions are mixed together. Modify the data pipeline.

Training outruns data

Too many samples per generation overfit value loss first. When validation loss separates, generate more self-play or reduce training volume.

Sources: KataGomo README.md and training.md . During an actual run, also open the scripts in the selected branch and verify each setting.