Automated generation of variant description

ianfab commented 4 years ago

In order to automatically generate descriptions of variants:

[x] Implement skeleton of functionality to get rule description.
[ ] Write text templates to be added conditionally and rendered with values depending on variant configuration.
[ ] Implement functionality to display description in a GUI (if possible).

Branch: https://github.com/ianfab/Fairy-Stockfish/tree/rules

notruck commented 4 years ago

Where will the user be reading the output, console window? Will the GUIs be able to display it somehow?

On the console, a command like "rules shogun" might work, but I don't know whether UCI allows something like that.

ianfab commented 4 years ago

Probably the console window at least at first, but there might also be options to show it in the GUI. E.g. in xboard there are commands like telluser to show text to the user.

Are you Untitled?

notruck commented 4 years ago

I see. That should work reasonably well.

Yes, it's me. :)

We can preface the output with something like:

[The following is an auto-generated description of the external/custom variant based on the rules configured in the variants.ini file. If the variant author has provided those rules elsewhere, we recommend reading that instead.] ....... ...... ...... [End of auto-generated variant description.]

ianfab commented 4 years ago

I have not even tried this feature of winboard yet though, but I think this is something for later, since once we have the generated string we can play around what to do with it.

I am more wondering about how to generate the text or how to define the templates. Let us take the pawn as an example. I just use some arbitrary syntax for now to describe the placeholders and conditions of rules: [if pawn in pieceTypes](Pawn: The pawn can move one square forward and capture one square diagonally forward. [if doubleStep](From rank [placeholder:doubleStepRank], pawns can move two squares forward.) On rank [placeholder:promotionRank] pawns promote to [placeholder:promotionPieceTypes]. Pawn promotion is [mandatoryPawnPromotion?](mandatory:optional).)

Or what is your idea of how the text would depend on the rules?

notruck commented 4 years ago

I haven't actually thought that far yet. But what I was thinking of is quite similar though, syntax-wise.

I was going with a concise intro, describing the board size, which variant it might be related to, which piece types there are, what constitute the win/draw conditions, what a stalemate means in this variant etc.

ianfab commented 4 years ago

Regarding the syntax I am quite open, I am not even sure whether the conditions should be part of the template or rather directly be part of the code. I did not really think about this yet, but I hope I will find some time for that until the weekend.

notruck commented 4 years ago

We can include the following paragraph to the instructions somewhere:

Fairy-Stockfish now includes an experimental feature to generate verbose descriptions of the variants as configured in the 'variants.ini' file. Please use this feature with an abundance of caution. The output is NOT an authoritative description of the variant's actual/intended rules! Rather, it will be generated on-the-fly from the last-loaded config, and the accuracy is therefore completely dependent on whatever custom rules someone had set up manually. It is only meant to provide a quick way to check how those rules currently stand. Please note that you may need to re-load the 'variants.ini' file to reflect the latest changes you have made and saved since the last time you loaded it!

notruck commented 4 years ago

We can sandwich the output between a header and a footer:

[The following is an auto-generated description of the external $CustomVariant based on the rules as configured in the variants.ini file. If the variant author has published those rules elsewhere, we highly recommend reading that instead.] .... .... .... [End of auto-generated variant description. If you find something odd, please check the config settings first. Please report problems at https://github.com/ianfab/Fairy-Stockfish/issues ]

notruck commented 4 years ago

A reasonable output might look like:

Usage: rules -$CustomVariant
e.g., rules -shogun

Example output:

(simulated mock-up text)

Shogun is a chess variant played on a board of 8 x 8 squares.

(optional text diagram based on the startFen)

The goal is to win by delivering a checkmate to your opponent's King.

Shogun is indicated as a related variant of the Crazyhouse family and may bear similarities with Crazyhouse.

The pieces that you capture will go to your pocket, making them available to be dropped back into the game as your own pieces in the future. Dropping a piece counts as a turn. Dropped pieces can give check or deliver checkmate. The pieces must be dropped outside of the promotion zone. Promoted pieces lose their promoted status when captured.

Shogun uses the following pieces: King, Queen, Rook, Bishop, Knight, Pawn, Mortar (Chancellor), Archbishop, General (Centaur), Captain (Commoner), and Duchess (Ferz).

Each player can only have one of the following pieces on the board at a time: Queen, Mortar (Chancellor), Archbishop, General (Centaur).

The promotion zone in Shogun is the 6th rank and beyond.

Pawns can promote to Captain (Commoner) upon reaching the promotion zone. Promotion is optional.

In addition to the pawn, the following pieces can also promote: Knight -> General (Centaur) Bishop -> Archbishop Rook -> Mortar (Chancellor) Duchess (Ferz) -> Queen Piece promotion is optional. Pieces can promote when moving into, or moving out of the promotion zone.

Movements of the pieces:

King : Moves and captures as the standard FIDE King (one square in any direction).

Queen : Moves and captures as the standard FIDE Queen.

[and so on ...]

notruck commented 4 years ago

Incomplete work-in-progress below, I thought I should check with you first before trying to complete all the text templates.

$CustomVariant is a chess variant played on a board of $maxRank x $maxFile squares.

(optionally we could try to show a text diagram based on the $startFen)

The goal is to (if $checkmateValue = win, then ) win by checkmating your opponent's $kingType.

(if $stalemateValue = win, then ) Alternatively, the game can also be won by stalemating your opponent's $kingType.

(if $bareKingvalue = win , then ) Alternatively, the game can also be won by "baring the $kingType," capturing all of your opponent's pieces, leaving them with only a lone $kingType.

(if $extinctionValue = win , then ) Alternatively, the game can also be won by eliminating $extinctionPieceType from the board.

(if $flagPiece is specified), Alternatively, the game can be also won by moving the $flagPiece to $whiteFlag / $blackFlag) square(s).

Inheritance (if used)

$ChildVariant is indicated as a related variant of the $ParentVariant family and may bear similarities with $ParentVariant.

$CustomVariant uses the following $[PieceType] ... (list them all) both given names and internal names perhaps.

(if $promotionLimit is defined, ) ...

(if $promotedPieceType is defined, ) ... The following pieces can promote:

Movements of the Pieces

(still working on them)

ianfab commented 4 years ago

Thanks, sounds all reasonable, especially the example for shogun is very helpful. A few comments from my side:

It is more consistent with other commands in SF to not use a dash in front of the variant name when used as an argument, e.g., rules shogun.
Using full names of pieces would only be possible for the built-in names like chancellor, not for aliases like Mortar, unless we add options to specify names of pieces. For the beginning it should be easier to start with something like Rook (R) -> Chancellor (M, +R) which can be derived from existing attributes.
Game end rules that can have multiple results (like checkmateValue, extinctionValue, etc.) should ideally use generic formulations that work independent of the result, e.g., something like (if king in piecetypes and checking) Checkmating the opponent's king leads to a $-checkmateValue for the the player who delivered the checkmate. (The conditions I put there are to avoid explaining checkmate for variants like antichess. I used -checkmateValue, because all the game end conditions are defined from the perspective of the player who has the move when the condition triggers, i.e., usually the losing side)

ianfab commented 4 years ago

I have a suggestion to speed this up. I do not know how familiar you are with C++ or the SF code, but I (or you if you like) could prepare a branch with a skeleton of the functionality just printing a stub instead of the description, and you could then open pull requests against this branch.

Since the function that generates the string would be quite isolated, e.g., just a function that takes a variant object as an input and returns a string, not much specific knowledge of SF code is needed. You could then always immediately try out how your description looks like, and with the code suggestion feature in PRs we could more interactively improve it instead of exchanging ideas with pseudo-code. What do you think?

notruck commented 4 years ago

Yeah, please start the branch. I know very little about coding, having only done some basic stuff in R and bash script. But I think I can follow along, especially if you start off with a few examples.

ianfab commented 4 years ago

Ok, sure, I can of course provide help when needed and since it probably anyway will get a bit repetitive after a few options, it should be doable even without much C++ knowledge. I hope I can get the skeleton ready still today.

ianfab commented 4 years ago

@notruck I prepared the branch rules. For quick testing you can e.g. use something like below. Normally, you should not need to change anything except for the function at the bottom of variant.cpp which creates a stream of the variant description: https://github.com/ianfab/Fairy-Stockfish/commit/a01ea032f774aafdc5baf9ef34922393ba6fb93e#diff-f7de8f5b7fa5ff4a6ad29cdb2a56b98f. For now I simply included the diagram that is normally used for debug output, the technical stuff like hash-key can be removed later.

echo "rules shogun" | ./stockfish load variants.ini

Fairy-Stockfish 120120 64 BMI2 by F. Fichter
Shogun is a chess variant played on a board of 8 x 8 squares.

 +---+---+---+---+---+---+---+---+
 | r | n | b |+d | k | b | n | r |   []
 +---+---+---+---+---+---+---+---+
 | p | p | p | p | p | p | p | p |
 +---+---+---+---+---+---+---+---+
 |   |   |   |   |   |   |   |   |
 +---+---+---+---+---+---+---+---+
 |   |   |   |   |   |   |   |   |
 +---+---+---+---+---+---+---+---+
 |   |   |   |   |   |   |   |   |
 +---+---+---+---+---+---+---+---+
 |   |   |   |   |   |   |   |   |
 +---+---+---+---+---+---+---+---+
 | P | P | P | P | P | P | P | P |
 +---+---+---+---+---+---+---+---+
 | R | N | B |+D | K | B | N | R | * []
 +---+---+---+---+---+---+---+---+

Fen: rnb+dkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNB+DKBNR[] w KQkq - 0 1
Sfen: rnb+dkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNB+DKBNR b - 1
Key: 053A8A5C026D342B
Checkers: 

# Game end

Checkmating the opponent's king leads to a win for the the player who delivered the checkmate.

Stalemate is adjudicated as a draw for player who can not move.

fairy-stockfish / Fairy-Stockfish

Automated generation of variant description #65

Inheritance (if used)

Movements of the Pieces