name: variant-builder
description: Implement a new variant in Fairy-Stockfish, either as built-in or variants.ini config

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.