What if the variant can't be implemented with variants.ini?

Proceed with code changes: add new config options in variant.h, parse them in parser.cpp, implement the rules in the position/move generation logic, and integrate the variant via variant.cpp or variants.ini as required.

How do I test a new variant?

Use the stockfish UCI interface, set the option UCI_Variant to your variant, start from position startpos, and run perft tests (e.g., go perft 1). Also run ./stockfish check variants.ini if you used configuration.

How can I ensure correctness and stability?

Run tests/perft.sh after changes, verify starting-position moves match expectations, and incrementally test specific rules with isolated scenarios before full game testing.

variant-builder

Scanned

npx machina-cli add skill fairy-stockfish/skills/variant-builder --openclaw

Files (1)

SKILL.md

3.0 KB

Implement the rules of a given chess variant in Fairy-Stockfish either by implementing the rule changes directly in the code, or by writing a variants.ini configuration in order to load the rules of the game at runtime.

Process

Phase 1: Understand requirements

Understand the rules of the game that is to be implemented
Read the documentation in the default variants.ini to understand if the rules can be fully implemented with only variants.ini configuration
If configuration is not sufficient, define the set of new configuration options that are missing in order to be able to configure the variant

Phase 2: Implementation

If the game can be implemented via configuration, just write a variants.ini config for the given variant unless it is specifically requested to make it a built-in variant. In that case the variant should be added in variant.cpp.

If the set of configuration options is not sufficient to implement the variant, then implement the set of missing configuration options you identified. Usually changes required include:

Add the new config option in variant.h, add it to the config parser in parser.cpp, and document it in the default variants.ini
Add the variant either via variants.ini or variant.cpp
Depending on what the feature requires
- Add a wrapper function in position.h if the variant property is accessed outside of the position class
- Add required properties of the board representation in StateInfo or the Position class to store the state of the new feature in the position.
- Update do_move and undo_move to implement any changes to the board state that is caused by the new rule.
- Update movegen.cpp if the new rule allows new move options or prohibits some
- Update Position::pseudo_legal to be consistent with the changes in movegen.cpp.
- Update Position::legal if there are any additional new constraints to move validation that can not be covered in move generation directly.
- Update Position::gives_check if the new rule impacts detection of checks on kings.
As an optional follow-up it might make sense to update the evaluation function in evaluate.cpp if the rule significantly impacts game play. Usually makes sense if something was added to the board representation.

Phase 3: Testing

If the variant was implemented via variants.ini, then validate the configuration using e.g. ./stockfish check variants.ini. Read the output and address warnings and errors related to the variant.

If any code changes were done, recompile the engine, run it and do first testing on the variant, e.g.,

uci
setoption name UCI_Variant value myvariant
position startpos
d
go perft 1
ucinewgame

This should allow to check if the starting position looks correct and whether basic move generation works.

Furthermore running tests/perft.sh is important to check if the new rule implementation broke move generation for any existing variants.

Source

git clone https://github.com/fairy-stockfish/skills/blob/main/skills/variant-builder/SKILL.mdView on GitHub

Overview

This skill explains how to implement a chess variant in Fairy-Stockfish, either by embedding the rules in code or loading them via variants.ini at runtime. It covers understanding the variant's rules, evaluating whether they can be configured, and outlining the required implementation steps. The result is a working, testable variant with proper documentation and testing.

How This Skill Works

First assess the variant requirements and whether they can be fully expressed with variants.ini. If config-only, write a variants.ini entry; if not, implement missing configuration options and correspondingly modify code (variant.h, parser.cpp, variant.cpp, move generation, and position handling) to support the new rules. Finally, compile, run tests (including uci tests and perft), and document the setup in the default variants.ini.

When to Use It

You want to add a new chess variant using a runtime variants.ini configuration rather than changing code.
The variant's rules can be expressed entirely through existing or newly added configuration options in variants.ini.
The variant requires changes that cannot be captured by configuration alone, necessitating code updates (e.g., new board state, move rules, or evaluation logic).
You need to validate the variant with stockfish check variants.ini and basic move generation tests.
You plan to test the variant interactively via UCI (e.g., set UCI_Variant, startpos, go perft 1) to verify correct behavior.

Quick Start

Step 1: Decide if the variant can be implemented via variants.ini or requires code changes.
Step 2: If config-only, draft a variants.ini entry and run ./stockfish check variants.ini to validate.
Step 3: If code changes are needed, implement new options (variant.h, parser.cpp), update move generation and position logic, recompile, and test with UCI and perft.

Best Practices

Clearly scope the variant rules before implementation to decide between config-only vs code changes.
Start with a variants.ini draft and validate feasibility early.
If coding, add the new options to variant.h and wire through the parser and default variants.ini.
Keep move generation and position updates consistent with the new rules (do_move, undo_move, pseudo_legal, legal, gives_check).
Document the variant thoroughly in the default variants.ini and include perft expectations.

Example Use Cases

Add a new variant by writing a variants.ini entry to load its rules at runtime.
Implement a built-in variant by adding logic in variant.cpp to enforce unique move rules.
Introduce a new config option for a board feature, add it to parser.cpp, and expose it via the variants.ini.
Test with ./stockfish check variants.ini to ensure syntax and rule loading are correct.
Launch an interactive session: uci, setoption name UCI_Variant value myvariant, position startpos, d, go perft 1.

Frequently Asked Questions

Add this skill to your agents