01 / Action model

Choose the action representation first

A KataGo-style policy head most naturally outputs one selected point, so a complex move can be decomposed into several selections.

Placement games

Gomoku, Hex, and Go variants are usually simplest: an action selects one empty point. Policy output, legal moves, and board state are almost one-to-one.

Movement games

Xiangqi, Ataxx, and Amazons can be split into selecting a piece and selecting its destination. Amazons adds a third selection for the arrow square. Every stage still chooses one position on the board.

Cost of decomposition

Staging makes one move deeper in the search tree, so state must record the current stage and previously selected points. The benefit is a simpler integration without redesigning the network output as a huge action table.

02 / File map

Core-file checklist

These are the most common modification points. In a specific branch, search for the same filenames or equivalent responsibilities.

Common KataGomo files and checks for a rules integration
Module Common files Change Checks Games Notes
Board state cpp/game/board.h
cpp/game/board.cpp		 Board dimensions, point contents, move execution, first-pass legality, and terminal helpers Random play does not crash; piece counts and boundaries remain correct All games Movement games must retain origin, destination, and stage
Game history cpp/game/boardhistory.h
cpp/game/boardhistory.cpp		 Turn progression, result, repetition, pass/no legal move, score Terminal results remain stable and loop rules match the design All games Many rules bugs hide in history and terminal logic
Rules options cpp/game/rules.h
cpp/game/rules.cpp		 Rules enums, komi/scoring parameters, variant switches, configuration parsing Configurations do not leak into one another Multi-rules branches For one original ruleset, configuration can initially stay minimal
Coordinates & size cpp/game/loc.h
cpp/game/board.h		 Maximum board, coordinate conversion, special locations such as pass/resign Readable GTP/log coordinates and correct rectangular boards Non-standard boards Rectangular boards need extra attention to network input dimensions
Network inputs cpp/neuralnet/nninputs.cpp
cpp/neuralnet/nninputs.h		 Board and global features, history planes, current stage, previous selections Input dimensions match model configuration and agree in training and inference All games Staged games must expose the stage to the network
Action mapping cpp/neuralnet/nninputs.cpp
cpp/search files		 Map policy points to legal actions; handle pass and resign Search samples no illegal points and omits no legal point Staged games Each stage has a different legal set and needs a staged mask
I/O formats cpp/dataio
cpp/command
cpp/program		 Position text, SGF/game records, GTP commands, debug output Replay games, load test positions, and understand logs Games intended for release A prototype can simplify this, but long training must be reproducible

03 / State machine

Implementing staged moves

For a move that first selects a piece and then a destination, a state machine is usually more robust than one monolithic action table.

  1. Add a stage field. Record a stage such as select_piece, select_destination, or select_arrow in board or history state, together with selected origin and intermediate points.
  2. Generate legal points by stage. The first stage selects only movable friendly pieces; the second only destinations legal for that piece; an Amazons third stage only reachable arrow squares. Every stage returns a set of board points.
  3. Change player only after the complete action. Do not switch players or perform a full result check during an intermediate stage. After every sub-step, update the board, clear temporary fields, switch turns, and check the result.
  4. Expose the stage to the network. Add a stage plane or global feature in nninputs.cpp, and encode selected origin/intermediate points as board planes. Otherwise the network cannot distinguish selecting a piece from selecting a destination.
  5. Adapt records and replay. Prefer human-readable complete actions such as a1-c3 or d1-d4-a4 in logs, while internal training data can retain the staged sequence.

04 / Verification

Verification checklist

Rules checks

  • The empty position has the correct number of legal moves.
  • Edges, corners, captures, blocking, forbidden moves, pass, and no-move cases are covered.
  • The winner does not fluctuate after the game has ended.

Training checks

  • Self-play continuously produces data without illegal-move errors.
  • Training reads the data, exports a model, and the next generation loads it.
  • The policy does not put substantial probability on points that are always illegal.

Reproducibility checks

  • Save the rules branch, configuration, board size, and training parameters.
  • A complete game can be replayed from logs or a game record.
  • After changing rules, train from scratch; do not mix old-rules data.

This checklist covers engineering integration. For the complete data and model route, see training AI for a game you invented. Treat the scripts in the selected KataGomo branch as the final authority for concrete parameters.