@gamepark/rules-api 6.24.2 → 6.24.3

package/dist/Action.d.ts

@@ -1,3 +1,10 @@
+/**
+ * An action is a move played by a player, with the consequences that resulted from it.
+ * @property id Unique identifier for the action (see {@link Undo})
+ * @property playerId Identifier of the player which played the move at the origin of the action
+ * @property move Move at the origin of the action
+ * @property consequences All the move that automatically happened after the move was played
+ */
 export type Action<Move = any, PlayerId = any> = {
     id?: string;
     playerId: PlayerId;

package/dist/Bot.d.ts

@@ -1,12 +1,33 @@
 import { RulesCreator } from './Rules';
+/**
+ * A Bot is a player controlled by a machine for a game.
+ * Used to replace players that quit a game, or for opponents in tutorials.
+ * Could be used to create AI players.
+ */
 export declare abstract class Bot<Game = any, Move = any, Player = any> {
     protected player: Player;
     protected constructor(player: Player);
+    /**
+     * When to bot run, it must return a list of moves to execute given the current game state.
+     * @param game Current game state
+     * @returns The moves that the bot plays
+     */
     abstract run(game: Game): Move[];
 }
+/**
+ * A random bot picks a random move to play amongst all the legal moves.
+ * Most board games can list efficiently all the legal moves all the time, which allows to have random bot to replace any missing opponent.
+ */
 export declare class RandomBot<Game = any, Move = any, Player = any> extends Bot {
     private Rules;
     constructor(Rules: RulesCreator<Game, Move, Player>, player: Player);
     run(game: Game): Move[];
+    /**
+     * The legal moves for this player at this game state.
+     * Can be overridden if you need to further restrict the moves you want the bot to play.
+     *
+     * @param game The game state
+     * @protected
+     */
     protected getLegalMoves(game: Game): Move[];
 }

package/dist/Bot.js

@@ -16,14 +16,23 @@ var __extends = (this && this.__extends) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RandomBot = exports.Bot = void 0;
-var Bot = (function () {
+/**
+ * A Bot is a player controlled by a machine for a game.
+ * Used to replace players that quit a game, or for opponents in tutorials.
+ * Could be used to create AI players.
+ */
+var Bot = /** @class */ (function () {
     function Bot(player) {
         this.player = player;
     }
     return Bot;
 }());
 exports.Bot = Bot;
-var RandomBot = (function (_super) {
+/**
+ * A random bot picks a random move to play amongst all the legal moves.
+ * Most board games can list efficiently all the legal moves all the time, which allows to have random bot to replace any missing opponent.
+ */
+var RandomBot = /** @class */ (function (_super) {
     __extends(RandomBot, _super);
     function RandomBot(Rules, player) {
         var _this = _super.call(this, player) || this;
@@ -42,6 +51,13 @@ var RandomBot = (function (_super) {
                 return [moves[Math.floor(Math.random() * moves.length)]];
         }
     };
+    /**
+     * The legal moves for this player at this game state.
+     * Can be overridden if you need to further restrict the moves you want the bot to play.
+     *
+     * @param game The game state
+     * @protected
+     */
     RandomBot.prototype.getLegalMoves = function (game) {
         return new this.Rules(game).getLegalMoves(this.player);
     };

package/dist/Bot.js.map

@@ -1 +1 @@
-{"version":3,"file":"Bot.js","sourceRoot":"","sources":["../src/Bot.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAOA;IACE,aAAgC,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAC9C,CAAC;IAQH,UAAC;AAAD,CAAC,AAVD,IAUC;AAVqB,kBAAG;AAgBzB;IAAqE,6BAAG;IACtE,mBAAoB,KAAuC,EAAE,MAAc;QACzE,YAAA,MAAK,YAAC,MAAM,CAAC,SAAA;QADK,WAAK,GAAL,KAAK,CAAkC;;IAE3D,CAAC;IAED,uBAAG,GAAH,UAAI,IAAU;QACZ,IAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAA;QACtC,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;YACrB,KAAK,CAAC;gBACJ,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAA;gBACrF,OAAO,EAAE,CAAA;YACX,KAAK,CAAC;gBACJ,OAAO,KAAK,CAAA;YACd;gBACE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IASS,iCAAa,GAAvB,UAAwB,IAAU;QAChC,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACxD,CAAC;IACH,gBAAC;AAAD,CAAC,AA5BD,CAAqE,GAAG,GA4BvE;AA5BY,8BAAS"}
+{"version":3,"file":"Bot.js","sourceRoot":"","sources":["../src/Bot.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAEA;;;;GAIG;AACH;IACE,aAAgC,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAC9C,CAAC;IAQH,UAAC;AAAD,CAAC,AAVD,IAUC;AAVqB,kBAAG;AAYzB;;;GAGG;AACH;IAAqE,6BAAG;IACtE,mBAAoB,KAAuC,EAAE,MAAc;QACzE,YAAA,MAAK,YAAC,MAAM,CAAC,SAAA;QADK,WAAK,GAAL,KAAK,CAAkC;;IAE3D,CAAC;IAED,uBAAG,GAAH,UAAI,IAAU;QACZ,IAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAA;QACtC,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;YACrB,KAAK,CAAC;gBACJ,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAA;gBACrF,OAAO,EAAE,CAAA;YACX,KAAK,CAAC;gBACJ,OAAO,KAAK,CAAA;YACd;gBACE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACO,iCAAa,GAAvB,UAAwB,IAAU;QAChC,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACxD,CAAC;IACH,gBAAC;AAAD,CAAC,AA5BD,CAAqE,GAAG,GA4BvE;AA5BY,8BAAS"}

package/dist/Competitive.d.ts

@@ -1,12 +1,57 @@
 import { Rules } from './Rules';
+/**
+ * In a competitive board game, players can be ranked at the end of the game.
+ * If the game relies on scores and tie-breakers, implement {@link CompetitiveScore}. Otherwise, implement {@link CompetitiveRank}
+ */
 export type Competitive<Game = any, Move = any, PlayerId = any> = CompetitiveScore<Game, Move, PlayerId> | CompetitiveRank<Game, Move, PlayerId>;
+/**
+ * Interface for any Competitive game that rank players based on their scores (and potential tie-breakers).
+ */
 export interface CompetitiveScore<Game = any, Move = any, PlayerId = any> extends Rules<Game, Move, PlayerId> {
+    /**
+     * Compute the score of a player at the end of the game
+     * @param playerId Identifier of a player
+     * @returns The score of the player
+     */
     getScore(playerId: PlayerId): number;
+    /**
+     * The tie-breaker function if the rules of the game includes it.
+     * If players have the same score (see {@link getScore}), this function will be called for both players, with tieBreaker param equals to 1.
+     * If successive tie-breakers exists, it will be called as long as necessary with incremental values for tieBreaker, until the function returns undefined
+     * @param tieBreaker depth of the tie-breaker
+     * @param playerId Identifier of the player
+     * @returns the tie-breaker value for this player, or undefined if no tie-breaker exists at this point
+     */
     getTieBreaker?(tieBreaker: number, playerId: PlayerId): number | undefined;
 }
+/**
+ * Interface to rank players in Competitive games that do not rely exclusively on scores to rank the players when game is over
+ */
 export interface CompetitiveRank<Game = any, Move = any, PlayerId = any> extends Rules<Game, Move, PlayerId> {
+    /**
+     * Rank two players when game is over (see {@link Array.sort})
+     *
+     * @param playerA Player A to compare
+     * @param playerB player B to compare
+     * @returns A positive number if B beats A, a negative number if A beats B, 0 in case of an equality
+     */
     rankPlayers(playerA: PlayerId, playerB: PlayerId): number;
 }
+/**
+ * Type guard to identify if a game's Rule is Competitive or not.
+ * @param rules game's Rule
+ * @returns true if the game is competitive
+ */
 export declare function isCompetitive<Game, Move, PlayerId>(rules: Rules<any, any, PlayerId>): rules is Competitive<Game, Move, PlayerId>;
+/**
+ * Type guard to identify if a game's Rule provide scores for players.
+ * @param rules game's Rule
+ * @returns true if the game is competitive with scores
+ */
 export declare function isCompetitiveScore<Game, Move, PlayerId>(rules: Rules<any, any, PlayerId>): rules is CompetitiveScore<Game, Move, PlayerId>;
+/**
+ * Type guard to identify if a game's Rule can rank the players.
+ * @param rules game's Rule
+ * @returns true if the game is competitive with ranking (used when scores are not available)
+ */
 export declare function isCompetitiveRank<Game, Move, PlayerId>(rules: Rules<any, any, PlayerId>): rules is CompetitiveRank<Game, Move, PlayerId>;

package/dist/Competitive.js

@@ -1,14 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCompetitiveRank = exports.isCompetitiveScore = exports.isCompetitive = void 0;
+/**
+ * Type guard to identify if a game's Rule is Competitive or not.
+ * @param rules game's Rule
+ * @returns true if the game is competitive
+ */
 function isCompetitive(rules) {
     return isCompetitiveScore(rules) || isCompetitiveRank(rules);
 }
 exports.isCompetitive = isCompetitive;
+/**
+ * Type guard to identify if a game's Rule provide scores for players.
+ * @param rules game's Rule
+ * @returns true if the game is competitive with scores
+ */
 function isCompetitiveScore(rules) {
     return typeof rules.getScore === 'function';
 }
 exports.isCompetitiveScore = isCompetitiveScore;
+/**
+ * Type guard to identify if a game's Rule can rank the players.
+ * @param rules game's Rule
+ * @returns true if the game is competitive with ranking (used when scores are not available)
+ */
 function isCompetitiveRank(rules) {
     return typeof rules.rankPlayers === 'function';
 }

package/dist/Competitive.js.map

@@ -1 +1 @@
-{"version":3,"file":"Competitive.js","sourceRoot":"","sources":["../src/Competitive.ts"],"names":[],"mappings":";;;AAiDA,SAAgB,aAAa,CAAuB,KAAgC;IAClF,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAA;AAC9D,CAAC;AAFD,sCAEC;AAOD,SAAgB,kBAAkB,CAAuB,KAAgC;IACvF,OAAO,OAAQ,KAAgD,CAAC,QAAQ,KAAK,UAAU,CAAA;AACzF,CAAC;AAFD,gDAEC;AAOD,SAAgB,iBAAiB,CAAuB,KAAgC;IACtF,OAAO,OAAQ,KAA+C,CAAC,WAAW,KAAK,UAAU,CAAA;AAC3F,CAAC;AAFD,8CAEC"}
+{"version":3,"file":"Competitive.js","sourceRoot":"","sources":["../src/Competitive.ts"],"names":[],"mappings":";;;AA4CA;;;;GAIG;AACH,SAAgB,aAAa,CAAuB,KAAgC;IAClF,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAA;AAC9D,CAAC;AAFD,sCAEC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAuB,KAAgC;IACvF,OAAO,OAAQ,KAAgD,CAAC,QAAQ,KAAK,UAAU,CAAA;AACzF,CAAC;AAFD,gDAEC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAuB,KAAgC;IACtF,OAAO,OAAQ,KAA+C,CAAC,WAAW,KAAK,UAAU,CAAA;AAC3F,CAAC;AAFD,8CAEC"}

package/dist/Eliminations.d.ts

@@ -1,5 +1,22 @@
+/**
+ * @deprecated
+ * When It's a Wonderful World was implemented, we wanted to be able to remove completely a player from the game:
+ * if a players quit or is ejected, instead of being replaced by a random bot, he no longer plays, and we do not deal cards to him.
+ * We had to know when a player was ejected, so this interface was created to provide a custom move automatically played when the player leaves.
+ *
+ * However, we could work out this feature without this extra interface, by doing this:
+ * 1. allow a custom "Quit" move everytime necessary in the legal moves
+ * 2. implement a custom {@link Bot} for the game that plays the "Quit" move by default if available
+ *
+ * Choose this solution instead of implementing the deprecated Eliminations interface if necessary.
+ */
 export interface Eliminations<Move = string, PlayerId = number> {
     isEliminated(playerId: PlayerId): boolean;
     giveUpMove?(playerId: PlayerId): Move | undefined;
 }
+/**
+ * Type guard for {@link Eliminations} interface
+ * @param rules Rules of a game
+ * @returns true if the Rules implements {@link Eliminations}
+ */
 export declare function hasEliminations<Move, PlayerId>(rules: Object): rules is Eliminations<Move, PlayerId>;

package/dist/Eliminations.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasEliminations = void 0;
+/**
+ * Type guard for {@link Eliminations} interface
+ * @param rules Rules of a game
+ * @returns true if the Rules implements {@link Eliminations}
+ */
 function hasEliminations(rules) {
     var test = rules;
     return typeof test.isEliminated === 'function';

package/dist/Eliminations.js.map

@@ -1 +1 @@
-{"version":3,"file":"Eliminations.js","sourceRoot":"","sources":["../src/Eliminations.ts"],"names":[],"mappings":";;;AAuBA,SAAgB,eAAe,CAAiB,KAAa;IAC3D,IAAM,IAAI,GAAG,KAAqC,CAAA;IAClD,OAAO,OAAO,IAAI,CAAC,YAAY,KAAK,UAAU,CAAA;AAChD,CAAC;AAHD,0CAGC"}
+{"version":3,"file":"Eliminations.js","sourceRoot":"","sources":["../src/Eliminations.ts"],"names":[],"mappings":";;;AAkBA;;;;GAIG;AACH,SAAgB,eAAe,CAAiB,KAAa;IAC3D,IAAM,IAAI,GAAG,KAAqC,CAAA;IAClD,OAAO,OAAO,IAAI,CAAC,YAAY,KAAK,UAAU,CAAA;AAChD,CAAC;AAHD,0CAGC"}

package/dist/GameSetup.d.ts

@@ -1,6 +1,20 @@
+/**
+ * Each game must provide the initial game state when a new game is created.
+ * Create a class that implements this interface to provide it.
+ * The constructor must not have any arguments (see {@link GameSetupCreator}).
+ */
 export interface GameSetup<Game = any, Options = any> {
+    /**
+     * Create a new game base on the options chosen by the players
+     *
+     * @param options Options of the game (see {@link OptionsSpec})
+     * @returns the initial game state
+     */
     setup(options: Options): Game;
 }
+/**
+ * Creator interface for {@link GameSetup}.
+ */
 export interface GameSetupCreator<Game = any, Options = any> {
     new (): GameSetup<Game, Options>;
 }

package/dist/HiddenInformation.d.ts

@@ -1,5 +1,27 @@
+/**
+ * Some game hide information from the players, for example when a deck is shuffled and face-down on the table.
+ * In that case, to prevent any cheating, it is mandatory that Game Park server does not expose this information to the players or spectators.
+ * Implement this interface with you Rules class to enforce this security.
+ * If the game does not hide the same information to every player, you need to implement {@link SecretInformation} instead
+ */
 export interface HiddenInformation<GameView = any, Move = any, MoveView = any> {
+    /**
+     * @returns the state of the game without the information that is hidden to the players
+     */
     getView(): GameView;
+    /**
+     * When a move is played, sometime some information inside it must be hidden to the players,
+     * and sometimes the move will reveal information to the player that was previously unavailable
+     * Implement this function to remove or add any such information from the given move
+     *
+     * @param move the Move to transform before sending it to the players
+     * @returns the state of the game without the information that is hidden to the players
+     */
     getMoveView(move: Move): MoveView;
 }
+/**
+ * Type guard for games with hidden information
+ * @param rules Rules of the game
+ * @returns true if the game implements {@link HiddenInformation}
+ */
 export declare function hasHiddenInformation<GameView = any, Move = any, MoveView = any>(rules: Object): rules is HiddenInformation<GameView, Move, MoveView>;

package/dist/HiddenInformation.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasHiddenInformation = void 0;
+/**
+ * Type guard for games with hidden information
+ * @param rules Rules of the game
+ * @returns true if the game implements {@link HiddenInformation}
+ */
 function hasHiddenInformation(rules) {
     var test = rules;
     return typeof test.getView === 'function' && typeof test.getMoveView === 'function';

package/dist/HiddenInformation.js.map

@@ -1 +1 @@
-{"version":3,"file":"HiddenInformation.js","sourceRoot":"","sources":["../src/HiddenInformation.ts"],"names":[],"mappings":";;;AA4BA,SAAgB,oBAAoB,CAA6C,KAAa;IAC5F,IAAM,IAAI,GAAG,KAAoD,CAAA;IACjE,OAAO,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU,CAAA;AACrF,CAAC;AAHD,oDAGC"}
+{"version":3,"file":"HiddenInformation.js","sourceRoot":"","sources":["../src/HiddenInformation.ts"],"names":[],"mappings":";;;AAuBA;;;;GAIG;AACH,SAAgB,oBAAoB,CAA6C,KAAa;IAC5F,IAAM,IAAI,GAAG,KAAoD,CAAA;IACjE,OAAO,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU,CAAA;AACrF,CAAC;AAHD,oDAGC"}

package/dist/LocalMovePreview.d.ts

@@ -1,4 +1,18 @@
+/**
+ * This interface allows to keep a move played only on the player's side.
+ * It is convenient to allow the player to "preview" the results of their action before validating it.
+ */
 export interface LocalMovePreview<Move = any> {
+    /**
+     * Function called on client side after a move is played, before it is sent to the server
+     * @param move The move that was played
+     * @return true if the move must not be sent to the server
+     */
     previewMove(move: Move): boolean;
 }
+/**
+ * Type guard for {@link LocalMovePreview} interface
+ * @param rules The game's rules
+ * @return true if the rules implements {@link LocalMovePreview}
+ */
 export declare function hasLocalMovePreview<Move = any>(rules: Object): rules is LocalMovePreview<Move>;

package/dist/LocalMovePreview.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasLocalMovePreview = void 0;
+/**
+ * Type guard for {@link LocalMovePreview} interface
+ * @param rules The game's rules
+ * @return true if the rules implements {@link LocalMovePreview}
+ */
 function hasLocalMovePreview(rules) {
     return typeof rules.previewMove === 'function';
 }

package/dist/LocalMovePreview.js.map

@@ -1 +1 @@
-{"version":3,"file":"LocalMovePreview.js","sourceRoot":"","sources":["../src/LocalMovePreview.ts"],"names":[],"mappings":";;;AAkBA,SAAgB,mBAAmB,CAAa,KAAa;IAC3D,OAAO,OAAQ,KAAgC,CAAC,WAAW,KAAK,UAAU,CAAA;AAC5E,CAAC;AAFD,kDAEC"}
+{"version":3,"file":"LocalMovePreview.js","sourceRoot":"","sources":["../src/LocalMovePreview.ts"],"names":[],"mappings":";;;AAaA;;;;GAIG;AACH,SAAgB,mBAAmB,CAAa,KAAa;IAC3D,OAAO,OAAQ,KAAgC,CAAC,WAAW,KAAK,UAAU,CAAA;AAC5E,CAAC;AAFD,kDAEC"}

package/dist/RandomMove.d.ts

@@ -1,4 +1,21 @@
+/**
+ * Some moves have a random output. This random output must be processed by the server, otherwise players could cheat.
+ * Also, the random output must be saved alongside the move in order to be able to replay the game consistently.
+ * (Another solution would have been to use a seed for the random number generator, but this feature was not available with Javascript Math.random).
+ * Therefore, the move must be played and validated without the random output, then the random output must be processed and added to the move.
+ * This interface must be implemented in order to add the random output to the moves that requires it.
+ */
 export interface RandomMove<Move = any, RandomizedMove = any> {
+    /**
+     * Add the random output to a move when necessary
+     * @param move A move just played that might need to be randomized
+     * @returns the move with the random output (or unchanged move if it is not a random move)
+     */
     randomize(move: Move): Move & RandomizedMove;
+    /**
+     * The signature of {@link Rules.play} changes a little bit: the moves are always randomized before they are played
+     * @param move The move to execute, always randomized first
+     * @returns the consequences of the move (not randomized yet)
+     */
     play(move: Move & RandomizedMove): Move[];
 }

package/dist/Rules.d.ts

@@ -1,16 +1,129 @@
+/**
+ * The Rules class is the basic minimal API to implement when adapting a board game on Game Park.
+ * It has the ability to tell whether it is a player's turn to play, what moves are legal, what happens when a move is played, and when the game is over.
+ *
+ * @typeparam Game - Data structure of the game state
+ * @typeparam Move - Data structure of a game move
+ * @typeparam PlayerId - type of the player's identifiers. Usually a number or a numeric enum.
+ */
 export declare abstract class Rules<Game = any, Move = any, PlayerId = any> {
+    /**
+     * The state of the game
+     */
     game: Game;
+    /**
+     * Construct a new instance of the Rules to work on a game state
+     * @param game the state of the game to work on
+     */
     constructor(game: Game);
+    /**
+     * A shortcut for this.game for backward compatibility
+     */
     get state(): Game;
+    /**
+     * The delegation allows to split the rules in smaller and simpler parts.
+     * Override this method to delegate the behavior of the other method to another Rules class.
+     *
+     * @return the Rule you want to delegate the current game behavior to
+     */
     delegate(): Rules<Game, Move, PlayerId> | undefined;
+    /**
+     * The delegation allows to split the rules in smaller and simpler parts.
+     * Default behavior call {@link delegate} and returns either an empty array, or an array with the delegate if any.
+     * Override this method to delegate the behavior of the other method to multiple Rules class.
+     *
+     * @return an array of Rules to delegate the current game behavior to
+     */
     delegates(): Rules<Game, Move, PlayerId>[];
+    /**
+     * Implement this to tell at any point in the game which player is active or not.
+     * When it's a player's turn, his thinking time decreases.
+     * A player whose turn it's not can have authorised moves, so this method is not sufficient to prevent a player from playing.
+     * Supports delegation: it returns true if any {@link delegates} return true.
+     *
+     * @param playerId - Identifier of a player
+     * @returns true if it is this player's turn to play
+     */
     isTurnToPlay(playerId: PlayerId): boolean;
+    /**
+     * When only one player is active at a time, you can implement this method instead of "isTurnToPlay" to tell which player is active.
+     * Supports delegation: if any {@link delegates} returns an active player, it will return it.
+     *
+     * @return @typeParam PlayerId - The identifier of the active player
+     */
     getActivePlayer(): PlayerId | undefined;
+    /**
+     * This method allows the Game Park server to authorise only valid moves in accordance with the game rules.
+     * The default behavior calls {@link getLegalMoves}, and returns true when at least one move is equal.
+     * Supports delegation with {@link delegates}. A move is legal if it is legal for at least one delegate.
+     *
+     * @param playerId - Identifier of a player
+     * @param move - a Move to control
+     * @returns true if the move can be played by this player
+     */
     isLegalMove(playerId: PlayerId, move: Move): boolean;
+    /**
+     * This method lists all the moves that are legal for a given player.
+     * This is optional but convenient: it is used by {@link isLegalMove}, {@link Bot} and many UI features from @gamepark/react-game to automatically
+     * highlight what can be done on the screen.
+     * Beware of the size of the list however: if the game offers to many legal moves, you might have to fall back to implementing {@link isLegalMove} and a
+     * custom {@link Bot}.
+     *
+     * Supports delegation with {@link delegates}: by default it will return all the legal moves of each delegate.
+     *
+     * @param playerId - Identifier of a player
+     * @returns the list of the moves
+     */
     getLegalMoves(playerId: PlayerId): Move[];
+    /**
+     * When some game state require automatic actions to be taken by the players, you can return a list of moves to play played automatically.
+     * It can be a sequences in the rules where everything is scripted for instance (no choices left for players).
+     *
+     * @deprecated because of the lifecycle of this method, the game state must never be modified inside it. However, it is a very common mistake, so
+     * this method should not be used at all: use {@link play} method to return the automatic moves.
+     *
+     * Supports delegation with {@link delegates}: by default it will return all the automatic moves of each delegate.
+     *
+     * @returns the list of the moves that must be played automatically
+     */
     getAutomaticMoves(): Move[];
+    /**
+     * Executes a move on current game state.
+     * This method is the only one that should mutate the state of the game.
+     * When a move is played by a player, or automatically played as a consequence of another move, it will be played by this method, independently on Game Park
+     * server and on every player or spectator clients. It can also be replayed in replay or undo features.
+     *
+     * A move should not change a lot the game state: instead, this method should return new moves to play as consequences.
+     * Dividing moves into small parts with consequences is key to producing step-by-step animations in the UI.
+     *
+     * see {@link https://en.wikipedia.org/wiki/Command_pattern}
+     *
+     * Supports delegation with {@link delegates}: by default it will play the move on each delegate, and return all the consequences.
+     *
+     * @param move - the Move to execute on the game state
+     * @param context - context of execution: see {@link PlayMoveContext}
+     * @returns A list of moves that should be immediately played as consequences of this move
+     */
     play(move: Move, context?: PlayMoveContext): Move[];
+    /**
+     * This method must return true when the game is over.
+     *
+     * Supports delegation with {@link delegates}: by default it will return true if there is at least one delegate, and every delegate returns true.
+     * Default behavior returns true if playersIds is provided, and it is not {@link isTurnToPlay} for any player - however this behavior is deprecated.
+     *
+     * @param playerIds - All the player ids in the game. Do not use (deprecated).
+     * @returns true if game is over
+     */
     isOver(playerIds?: PlayerId[]): boolean;
+    /**
+     * Implement this method when some moves output cannot be predicted on the client side.
+     * Unpredictable moves will not be proceeded by the client, which will wait for the server's response.
+     * Examples: rolling dices, drawing a card
+     *
+     * @param move a move that is going to be played
+     * @param player the player that played this move, or the move that triggered it as a consequence
+     * @returns true if the move cannot be predicted from the player point of view
+     */
     isUnpredictableMove?(move: Move, player: PlayerId): boolean;
 }
 export interface RulesCreator<Game = any, Move = any, Player = number> {
@@ -18,6 +131,12 @@ export interface RulesCreator<Game = any, Move = any, Player = number> {
         player?: Player;
     }): Rules<Game, Move, Player>;
 }
+/**
+ * The context when a move is played.
+ */
 export type PlayMoveContext = {
+    /**
+     * true if move is only played locally on a player's client
+     */
     local?: boolean;
 };

package/dist/Rules.js

@@ -6,24 +6,61 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rules = void 0;
 var isEqual_1 = __importDefault(require("lodash/isEqual"));
 var Eliminations_1 = require("./Eliminations");
-var Rules = (function () {
+/**
+ * The Rules class is the basic minimal API to implement when adapting a board game on Game Park.
+ * It has the ability to tell whether it is a player's turn to play, what moves are legal, what happens when a move is played, and when the game is over.
+ *
+ * @typeparam Game - Data structure of the game state
+ * @typeparam Move - Data structure of a game move
+ * @typeparam PlayerId - type of the player's identifiers. Usually a number or a numeric enum.
+ */
+var Rules = /** @class */ (function () {
+    /**
+     * Construct a new instance of the Rules to work on a game state
+     * @param game the state of the game to work on
+     */
     function Rules(game) {
         this.game = game;
     }
     Object.defineProperty(Rules.prototype, "state", {
+        /**
+         * A shortcut for this.game for backward compatibility
+         */
         get: function () {
             return this.game;
         },
         enumerable: false,
         configurable: true
     });
+    /**
+     * The delegation allows to split the rules in smaller and simpler parts.
+     * Override this method to delegate the behavior of the other method to another Rules class.
+     *
+     * @return the Rule you want to delegate the current game behavior to
+     */
     Rules.prototype.delegate = function () {
         return;
     };
+    /**
+     * The delegation allows to split the rules in smaller and simpler parts.
+     * Default behavior call {@link delegate} and returns either an empty array, or an array with the delegate if any.
+     * Override this method to delegate the behavior of the other method to multiple Rules class.
+     *
+     * @return an array of Rules to delegate the current game behavior to
+     */
     Rules.prototype.delegates = function () {
         var delegate = this.delegate();
         return delegate ? [delegate] : [];
     };
+    /**
+     * Implement this to tell at any point in the game which player is active or not.
+     * When it's a player's turn, his thinking time decreases.
+     * A player whose turn it's not can have authorised moves, so this method is not sufficient to prevent a player from playing.
+     * Supports delegation: it returns true if any {@link delegates} return true.
+     *
+     * @param playerId - Identifier of a player
+     * @returns true if it is this player's turn to play
+     */
     Rules.prototype.isTurnToPlay = function (playerId) {
         var rules = this.delegates();
         if (rules.some(function (rules) { return rules.isTurnToPlay(playerId); })) {
@@ -31,6 +68,12 @@ var Rules = (function () {
         }
         return playerId === this.getActivePlayer();
     };
+    /**
+     * When only one player is active at a time, you can implement this method instead of "isTurnToPlay" to tell which player is active.
+     * Supports delegation: if any {@link delegates} returns an active player, it will return it.
+     *
+     * @return @typeParam PlayerId - The identifier of the active player
+     */
     Rules.prototype.getActivePlayer = function () {
         for (var _i = 0, _a = this.delegates(); _i < _a.length; _i++) {
             var delegate = _a[_i];
@@ -40,6 +83,15 @@ var Rules = (function () {
         }
         return;
     };
+    /**
+     * This method allows the Game Park server to authorise only valid moves in accordance with the game rules.
+     * The default behavior calls {@link getLegalMoves}, and returns true when at least one move is equal.
+     * Supports delegation with {@link delegates}. A move is legal if it is legal for at least one delegate.
+     *
+     * @param playerId - Identifier of a player
+     * @param move - a Move to control
+     * @returns true if the move can be played by this player
+     */
     Rules.prototype.isLegalMove = function (playerId, move) {
         var rules = this.delegates();
         if (rules.some(function (rules) { return rules.isLegalMove(playerId, move); })) {
@@ -53,15 +105,64 @@ var Rules = (function () {
         }
         return false;
     };
+    /**
+     * This method lists all the moves that are legal for a given player.
+     * This is optional but convenient: it is used by {@link isLegalMove}, {@link Bot} and many UI features from @gamepark/react-game to automatically
+     * highlight what can be done on the screen.
+     * Beware of the size of the list however: if the game offers to many legal moves, you might have to fall back to implementing {@link isLegalMove} and a
+     * custom {@link Bot}.
+     *
+     * Supports delegation with {@link delegates}: by default it will return all the legal moves of each delegate.
+     *
+     * @param playerId - Identifier of a player
+     * @returns the list of the moves
+     */
     Rules.prototype.getLegalMoves = function (playerId) {
         return this.delegates().flatMap(function (rules) { return rules.getLegalMoves(playerId); });
     };
+    /**
+     * When some game state require automatic actions to be taken by the players, you can return a list of moves to play played automatically.
+     * It can be a sequences in the rules where everything is scripted for instance (no choices left for players).
+     *
+     * @deprecated because of the lifecycle of this method, the game state must never be modified inside it. However, it is a very common mistake, so
+     * this method should not be used at all: use {@link play} method to return the automatic moves.
+     *
+     * Supports delegation with {@link delegates}: by default it will return all the automatic moves of each delegate.
+     *
+     * @returns the list of the moves that must be played automatically
+     */
     Rules.prototype.getAutomaticMoves = function () {
         return this.delegates().flatMap(function (rules) { return rules.getAutomaticMoves(); });
     };
+    /**
+     * Executes a move on current game state.
+     * This method is the only one that should mutate the state of the game.
+     * When a move is played by a player, or automatically played as a consequence of another move, it will be played by this method, independently on Game Park
+     * server and on every player or spectator clients. It can also be replayed in replay or undo features.
+     *
+     * A move should not change a lot the game state: instead, this method should return new moves to play as consequences.
+     * Dividing moves into small parts with consequences is key to producing step-by-step animations in the UI.
+     *
+     * see {@link https://en.wikipedia.org/wiki/Command_pattern}
+     *
+     * Supports delegation with {@link delegates}: by default it will play the move on each delegate, and return all the consequences.
+     *
+     * @param move - the Move to execute on the game state
+     * @param context - context of execution: see {@link PlayMoveContext}
+     * @returns A list of moves that should be immediately played as consequences of this move
+     */
     Rules.prototype.play = function (move, context) {
         return this.delegates().flatMap(function (rules) { return rules.play(move, context); });
     };
+    /**
+     * This method must return true when the game is over.
+     *
+     * Supports delegation with {@link delegates}: by default it will return true if there is at least one delegate, and every delegate returns true.
+     * Default behavior returns true if playersIds is provided, and it is not {@link isTurnToPlay} for any player - however this behavior is deprecated.
+     *
+     * @param playerIds - All the player ids in the game. Do not use (deprecated).
+     * @returns true if game is over
+     */
     Rules.prototype.isOver = function (playerIds) {
         var _this = this;
         var delegates = this.delegates();