@gamepark/rules-api 6.24.2 → 6.25.0

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();

package/dist/Rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"Rules.js","sourceRoot":"","sources":["../src/Rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Rules.js","sourceRoot":"","sources":["../src/Rules.ts"],"names":[],"mappings":"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"}

package/dist/SecretInformation.d.ts

@@ -1,9 +1,48 @@
 import { HiddenInformation } from './HiddenInformation';
+/**
+ * Some game hide information to the player, and the information is not equally accessible by each player.
+ * For example, when a player knows the cards in their hand, but this information is not available to other players.
+ * The rules of the game need to implement this interface in that case to secure the information.
+ *
+ * It is important not to implement SecretInformation if {@link HiddenInformation} is sufficient, because implementing SecretInformation will create a
+ * distinct notification channel for each player, thus more notifications that necessary if all players have access to the same information.
+ */
 export interface SecretInformation<GameView = any, Move = any, MoveView = any, PlayerId = any> extends HiddenInformation<GameView, Move, MoveView> {
+    /**
+     * In a game with Secret Information, getView is called for spectators only. See {@link HiddenInformation.getView}.
+     */
     getView(): GameView;
+    /**
+     * In a game with Secret Information, getMoveView is called for spectators only. See {@link HiddenInformation.getMoveView}.
+     */
     getMoveView(move: Move): MoveView;
+    /**
+     * Same as {@link HiddenInformation.getView}, but for one player.
+     * @param playerId The player this view will be sent to
+     * @returns the state of the game this player can see
+     */
     getPlayerView(playerId: PlayerId): GameView;
+    /**
+     * Same as {@link HiddenInformation.getMoveView}, but for one player.
+     * @param move A move that happened in the game
+     * @param playerId The player this move view will be sent to
+     * @returns the move with less or more data depending on what to hide or reveal
+     */
     getPlayerMoveView?(move: Move, playerId: PlayerId): MoveView;
+    /**
+     * If some moves played must be entirely keep secret to other players, you can implement this function to prevent the move from being transmitted to
+     * another player as long as necessary.
+     * Useful for game with secret planning for instance.
+     *
+     * @param move A move played by a player
+     * @param playerId Identifier of another player
+     * @return true as long as the move must be kept secret from that player
+     */
     keepMoveSecret?(move: Move, playerId: PlayerId): boolean;
 }
+/**
+ * Type guard for games with secret information
+ * @param rules Rules of the game
+ * @returns true if the game implements {@link SecretInformation}
+ */
 export declare function hasSecretInformation<GameView = any, Move = any, MoveView = any, PlayerId = any>(rules: Object): rules is SecretInformation<GameView, Move, MoveView, PlayerId>;

package/dist/SecretInformation.js

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

package/dist/SecretInformation.js.map

@@ -1 +1 @@
-{"version":3,"file":"SecretInformation.js","sourceRoot":"","sources":["../src/SecretInformation.ts"],"names":[],"mappings":";;;AAqDA,SAAgB,oBAAoB,CAA6D,KAAa;IAC5G,IAAM,IAAI,GAAG,KAA8D,CAAA;IAC3E,OAAO,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU,CAAA;AACjD,CAAC;AAHD,oDAGC"}
+{"version":3,"file":"SecretInformation.js","sourceRoot":"","sources":["../src/SecretInformation.ts"],"names":[],"mappings":";;;AAgDA;;;;GAIG;AACH,SAAgB,oBAAoB,CAA6D,KAAa;IAC5G,IAAM,IAAI,GAAG,KAA8D,CAAA;IAC3E,OAAO,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU,CAAA;AACjD,CAAC;AAHD,oDAGC"}

package/dist/TimeLimit.d.ts

@@ -1,6 +1,28 @@
 import { Rules } from './Rules';
+/**
+ * In games played in real time with a time limit, players start with an amount of time, and more time is added every time it is their turn to play.
+ * Players can be expelled after some time (-1 minute).
+ * This interface allows to control how much extra time is given to players every time it is their turn to play.
+ *
+ * Beginner have up to x1.5 more thinking time, so the time given here must be for "experienced" players.
+ */
 export interface TimeLimit<Game, Move = string, PlayerId = number> extends Rules<Game, Move, PlayerId> {
+    /**
+     * Amount of time given to a player everytime it is their turn to play.
+     * @param playerId Id of the player, if you want to give different time depending on the id for asymmetric games.
+     * @return number of seconds to add to the player's clock
+     */
     giveTime(playerId: PlayerId): number;
+    /**
+     * Amount of time given to a player before the game begins. Default value is 2 minutes.
+     * @param playerId Id of the player, if you want to give different time depending on the id for asymmetric games.
+     * @return starting amount of seconds for each player when the game starts
+     */
     startingTime?(playerId: PlayerId): number;
 }
+/**
+ * Type guard for {@link TimeLimit} interface
+ * @param rules Rules of the game
+ * @returns true if rules implements {@link TimeLimit}
+ */
 export declare function hasTimeLimit<Game, Move, PlayerId>(rules: Rules<Game, Move, PlayerId>): rules is TimeLimit<Game, Move, PlayerId>;

package/dist/TimeLimit.js

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

package/dist/TimeLimit.js.map

@@ -1 +1 @@
-{"version":3,"file":"TimeLimit.js","sourceRoot":"","sources":["../src/TimeLimit.ts"],"names":[],"mappings":";;;AA8BA,SAAgB,YAAY,CAAuB,KAAkC;IACnF,OAAO,OAAQ,KAAyC,CAAC,QAAQ,KAAK,UAAU,CAAA;AAClF,CAAC;AAFD,oCAEC"}
+{"version":3,"file":"TimeLimit.js","sourceRoot":"","sources":["../src/TimeLimit.ts"],"names":[],"mappings":";;;AAyBA;;;;GAIG;AACH,SAAgB,YAAY,CAAuB,KAAkC;IACnF,OAAO,OAAQ,KAAyC,CAAC,QAAQ,KAAK,UAAU,CAAA;AAClF,CAAC;AAFD,oCAEC"}

package/dist/Undo.d.ts

@@ -1,5 +1,23 @@
 import { Action } from './Action';
+/**
+ * The undo feature allow a player to undo some move played during the game.
+ * The move undone is removed from the game history: the new game state results from applying all the remaining moves from the game setup.
+ * Any direct consequences of the move (see {@link Action.consequences}) are also removed.
+ */
 export interface Undo<Move = string, PlayerId = number> {
+    /**
+     * This function allow an action to be undone, by the player that did it.
+     *
+     * @param action The {@link Action} to allow or not to undo.
+     * @param consecutiveActions All the actions that has been played meanwhile by the players
+     * @returns true if the action can be undone
+     */
     canUndo(action: Action<Move, PlayerId>, consecutiveActions: Action<Move, PlayerId>[]): boolean;
 }
+/**
+ * Type guard to know if a game implements the Undo feature.
+ *
+ * @param rules Rules of the game
+ * @returns true if rules implements {@link Undo}
+ */
 export declare function hasUndo<Move, PlayerId>(rules: Object): rules is Undo<Move, PlayerId>;

package/dist/Undo.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasUndo = void 0;
+/**
+ * Type guard to know if a game implements the Undo feature.
+ *
+ * @param rules Rules of the game
+ * @returns true if rules implements {@link Undo}
+ */
 function hasUndo(rules) {
     var test = rules;
     return typeof test.canUndo === 'function';

package/dist/Undo.js.map

@@ -1 +1 @@
-{"version":3,"file":"Undo.js","sourceRoot":"","sources":["../src/Undo.ts"],"names":[],"mappings":";;;AAwBA,SAAgB,OAAO,CAAiB,KAAa;IACnD,IAAM,IAAI,GAAG,KAA6B,CAAA;IAC1C,OAAO,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,CAAA;AAC3C,CAAC;AAHD,0BAGC"}
+{"version":3,"file":"Undo.js","sourceRoot":"","sources":["../src/Undo.ts"],"names":[],"mappings":";;;AAkBA;;;;;GAKG;AACH,SAAgB,OAAO,CAAiB,KAAa;IACnD,IAAM,IAAI,GAAG,KAA6B,CAAA;IAC1C,OAAO,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,CAAA;AAC3C,CAAC;AAHD,0BAGC"}

package/dist/UnpredictableMove.d.ts

@@ -1,6 +1,25 @@
 import { Rules } from './Rules';
+/**
+ * A move is unpredictable for the player when the outcome is not known, ie when the state of the game after applying the move cannot be processed without
+ * the server response.
+ * It is the case for moves with random output (like rolling a die), or revealing hidden information (like drawing a card).
+ *
+ * Game Park offers a smooth experience by executing any move played immediately, without waiting for the server's response, as well as the consequences.
+ * However, it cannot be done for unpredictable moves, so this interface allows to identify which move can be played immediately, or not.
+ */
 export interface UnpredictableMoves<M = any, P = any> {
+    /**
+     * Tell if a move is unpredictable
+     * @param move A move
+     * @param player The player that should predict the move
+     * @returns true if the move outcome is predictable
+     */
     isUnpredictableMove(move: M, player: P): boolean;
     canIgnoreServerDifference?(clientMove: M, serverMove: M): boolean;
 }
+/**
+ * Type guard for {@link UnpredictableMoves} interface
+ * @param rules Rules of the game
+ * @returns true is rules implements {@link UnpredictableMoves}
+ */
 export declare const hasUnpredictableMoves: <G = any, M = any, P = any>(rules: Rules<G, M, P>) => rules is Rules<G, M, P> & UnpredictableMoves<M, P>;

package/dist/UnpredictableMove.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasUnpredictableMoves = void 0;
+/**
+ * Type guard for {@link UnpredictableMoves} interface
+ * @param rules Rules of the game
+ * @returns true is rules implements {@link UnpredictableMoves}
+ */
 var hasUnpredictableMoves = function (rules) { return typeof rules.isUnpredictableMove === 'function'; };
 exports.hasUnpredictableMoves = hasUnpredictableMoves;
 //# sourceMappingURL=UnpredictableMove.js.map

package/dist/UnpredictableMove.js.map

@@ -1 +1 @@
-{"version":3,"file":"UnpredictableMove.js","sourceRoot":"","sources":["../src/UnpredictableMove.ts"],"names":[],"mappings":";;;AA2BO,IAAM,qBAAqB,GAAG,UACnC,KAAqB,IACkC,OAAA,OAAO,KAAK,CAAC,mBAAmB,KAAK,UAAU,EAA/C,CAA+C,CAAA;AAF3F,QAAA,qBAAqB,yBAEsE"}
+{"version":3,"file":"UnpredictableMove.js","sourceRoot":"","sources":["../src/UnpredictableMove.ts"],"names":[],"mappings":";;;AAsBA;;;;GAIG;AACI,IAAM,qBAAqB,GAAG,UACnC,KAAqB,IACkC,OAAA,OAAO,KAAK,CAAC,mBAAmB,KAAK,UAAU,EAA/C,CAA+C,CAAA;AAF3F,QAAA,qBAAqB,yBAEsE"}

package/dist/material/HiddenMaterialRules.d.ts

@@ -4,23 +4,58 @@ import { MaterialItem } from './items';
 import { MaterialGame } from './MaterialGame';
 import { MaterialRules } from './MaterialRules';
 import { MaterialMove, MaterialMoveRandomized, MaterialMoveView } from './moves';
+/**
+ * Implement HiddenMaterialRules when you want to use the {@link MaterialRules} approach with {@link HiddenInformation}.
+ * Using some {@link HidingStrategy} allows to enforce the security of a game with hidden information easily.
+ * If the game has secret information (some players have information not available to others, link cards in their hand), then you
+ * must implement {@link SecretMaterialRules} instead.
+ */
 export declare abstract class HiddenMaterialRules<P extends number = number, M extends number = number, L extends number = number> extends MaterialRules<P, M, L> implements HiddenInformation<MaterialGame<P, M, L>, MaterialMove<P, M, L>, MaterialMove<P, M, L>> {
     private readonly client?;
     constructor(game: MaterialGame<P, M, L>, client?: {
         player?: P | undefined;
     } | undefined);
+    /**
+     * A hiding strategy allows to hide automatically some information about an item when it is at a specific location type.
+     * Usually, we hide the item id (or a part of it).
+     * Example: {[MaterialType.Card]: {[LocationType.Deck]: hideItemId}} will hide the id of the cards in the deck to everybody.
+     * See {@link HidingStrategy}
+     */
     abstract readonly hidingStrategies: Partial<Record<M, Partial<Record<L, HidingStrategy<P, L>>>>>;
-    randomize(move: MaterialMove<P, M, L>): MaterialMove<P, M, L> & MaterialMoveRandomized<P, M, L>;
+    randomize(move: MaterialMove<P, M, L>, player?: P): MaterialMove<P, M, L> & MaterialMoveRandomized<P, M, L>;
     private isRevealingItemMove;
+    /**
+     * Items that can be hidden cannot merge by default, to prevent hidden items to merge only because they have no id.
+     */
     itemsCanMerge(type: M): boolean;
+    /**
+     * Moves that reveal some information (like drawing a card) cannot be predicted by the player.
+     */
     isUnpredictableMove(move: MaterialMove<P, M, L>, player: P): boolean;
+    /**
+     * Moves than reveals an information to someone cannot be undone by default
+     */
     protected moveBlocksUndo(move: MaterialMove<P, M, L>): boolean;
+    /**
+     * @param move A move to test
+     * @returns true if the move revealed something to some player
+     */
     protected moveRevealedSomething(move: MaterialMove<P, M, L>): boolean;
+    /**
+     * With the material approach, we can offer a default working implementation for {@link HiddenInformation.getView}
+     */
     getView(player?: P): MaterialGame<P, M, L>;
     private hideItem;
     private getItemHiddenPaths;
     private itemHasHiddenInformation;
+    /**
+     * To be able to know if a MoveItem cannot be undone, the server flags the moves with a "reveal" property.
+     * This difference must be integrated without error during the callback.
+     */
     canIgnoreServerDifference(clientMove: MaterialMove<P, M, L>, serverMove: MaterialMove<P, M, L>): boolean;
+    /**
+     * With the material approach, we can offer a default working implementation for {@link HiddenInformation.getMoveView}
+     */
     getMoveView(move: MaterialMoveRandomized<P, M, L>, player?: P): MaterialMove<P, M, L>;
     private getMoveItemView;
     private getMoveAtOnceView;
@@ -30,8 +65,21 @@ export declare abstract class HiddenMaterialRules<P extends number = number, M e
     private moveAtOnceWillRevealSomething;
     private getShuffleItemsView;
     private canSeeShuffleResult;
+    /**
+     * Override of {@link MaterialRules.play} that also removes the hidden information from items, for example when a card is flipped face down
+     */
     play(move: MaterialMoveRandomized<P, M, L> | MaterialMoveView<P, M, L>, context?: PlayMoveContext): MaterialMove<P, M, L>[];
 }
+/**
+ * A Hiding Strategy is a function that takes an item and returns a list of path to hide in the item object.
+ * See {@link hideItemId} and {@link hideFront} for 2 hiding strategy frequently used.
+ */
 export type HidingStrategy<P extends number = number, L extends number = number> = (item: MaterialItem<P, L>) => string[];
+/**
+ * Hiding strategy that removes the item id
+ */
 export declare const hideItemId: HidingStrategy;
+/**
+ * Hiding strategy that removes "id.front" from the item (when we have cards with composite ids, back & front)
+ */
 export declare const hideFront: HidingStrategy;

package/dist/material/HiddenMaterialRules.js

@@ -49,27 +49,43 @@ var set_1 = __importDefault(require("lodash/set"));
 var unset_1 = __importDefault(require("lodash/unset"));
 var MaterialRules_1 = require("./MaterialRules");
 var moves_1 = require("./moves");
-var HiddenMaterialRules = (function (_super) {
+/**
+ * Implement HiddenMaterialRules when you want to use the {@link MaterialRules} approach with {@link HiddenInformation}.
+ * Using some {@link HidingStrategy} allows to enforce the security of a game with hidden information easily.
+ * If the game has secret information (some players have information not available to others, link cards in their hand), then you
+ * must implement {@link SecretMaterialRules} instead.
+ */
+var HiddenMaterialRules = /** @class */ (function (_super) {
     __extends(HiddenMaterialRules, _super);
     function HiddenMaterialRules(game, client) {
         var _this = _super.call(this, game) || this;
         _this.client = client;
         return _this;
     }
-    HiddenMaterialRules.prototype.randomize = function (move) {
-        if (this.isRevealingItemMove(move)) {
+    HiddenMaterialRules.prototype.randomize = function (move, player) {
+        if (player !== undefined && this.isRevealingItemMove(move, player)) {
+            // We need to know if a MoveItem has revealed something to the player to prevent the undo in that case.
+            // To know that, we need the position of the item before the move.
+            // To prevent having to recalculate the game state before the move, we flag the move in the database with "reveal: {}".
+            // This flag indicate that something was revealed to someone.
+            // We use the "randomize" function because is the where we can "preprocess" the move and transform it after checking it is legal and before it is saved.
             return __assign(__assign({}, move), { reveal: {} });
         }
         return _super.prototype.randomize.call(this, move);
     };
-    HiddenMaterialRules.prototype.isRevealingItemMove = function (move) {
-        var _this = this;
-        return ((0, moves_1.isMoveItem)(move) && this.game.players.some(function (player) { return _this.moveItemWillRevealSomething(move, player); })) ||
-            ((0, moves_1.isMoveItemsAtOnce)(move) && this.game.players.some(function (player) { return _this.moveAtOnceWillRevealSomething(move, player); }));
+    HiddenMaterialRules.prototype.isRevealingItemMove = function (move, player) {
+        return ((0, moves_1.isMoveItem)(move) && this.moveItemWillRevealSomething(move, player))
+            || ((0, moves_1.isMoveItemsAtOnce)(move) && this.moveAtOnceWillRevealSomething(move, player));
     };
+    /**
+     * Items that can be hidden cannot merge by default, to prevent hidden items to merge only because they have no id.
+     */
     HiddenMaterialRules.prototype.itemsCanMerge = function (type) {
         return !this.hidingStrategies[type];
     };
+    /**
+     * Moves that reveal some information (like drawing a card) cannot be predicted by the player.
+     */
     HiddenMaterialRules.prototype.isUnpredictableMove = function (move, player) {
         var _this = this;
         if ((0, moves_1.isMoveItem)(move)) {
@@ -91,12 +107,22 @@ var HiddenMaterialRules = (function (_super) {
             return _super.prototype.isUnpredictableMove.call(this, move, player);
         }
     };
+    /**
+     * Moves than reveals an information to someone cannot be undone by default
+     */
     HiddenMaterialRules.prototype.moveBlocksUndo = function (move) {
         return _super.prototype.moveBlocksUndo.call(this, move) || this.moveRevealedSomething(move);
     };
+    /**
+     * @param move A move to test
+     * @returns true if the move revealed something to some player
+     */
     HiddenMaterialRules.prototype.moveRevealedSomething = function (move) {
         return ((0, moves_1.isMoveItem)(move) || (0, moves_1.isMoveItemsAtOnce)(move)) && !!move.reveal;
     };
+    /**
+     * With the material approach, we can offer a default working implementation for {@link HiddenInformation.getView}
+     */
     HiddenMaterialRules.prototype.getView = function (player) {
         var _this = this;
         return __assign(__assign({}, this.game), { items: (0, mapValues_1.default)(this.game.items, function (items, stringType) {
@@ -126,6 +152,10 @@ var HiddenMaterialRules = (function (_super) {
     HiddenMaterialRules.prototype.itemHasHiddenInformation = function (type, item, player) {
         return this.getItemHiddenPaths(type, item, player).length > 0;
     };
+    /**
+     * To be able to know if a MoveItem cannot be undone, the server flags the moves with a "reveal" property.
+     * This difference must be integrated without error during the callback.
+     */
     HiddenMaterialRules.prototype.canIgnoreServerDifference = function (clientMove, serverMove) {
         if ((0, moves_1.isMoveItem)(clientMove) && (0, moves_1.isMoveItem)(serverMove)) {
             var reveal = serverMove.reveal, serverMoveWithoutReveal = __rest(serverMove, ["reveal"]);
@@ -133,6 +163,9 @@ var HiddenMaterialRules = (function (_super) {
         }
         return false;
     };
+    /**
+     * With the material approach, we can offer a default working implementation for {@link HiddenInformation.getMoveView}
+     */
     HiddenMaterialRules.prototype.getMoveView = function (move, player) {
         var _this = this;
         if (move.kind === moves_1.MoveKind.ItemMove && move.itemType in this.hidingStrategies) {
@@ -152,8 +185,6 @@ var HiddenMaterialRules = (function (_super) {
         return move;
     };
     HiddenMaterialRules.prototype.getMoveItemView = function (move, player) {
-        if (!move.reveal)
-            return move;
         var revealedPaths = this.getMoveItemRevealedPath(move, player);
         if (!revealedPaths.length)
             return move;
@@ -166,16 +197,16 @@ var HiddenMaterialRules = (function (_super) {
         return moveView;
     };
     HiddenMaterialRules.prototype.getMoveAtOnceView = function (move, player) {
-        if (!move.reveal)
-            return move;
-        var moveView = __assign(__assign({}, move), { reveal: {} });
+        var moveView = __assign({}, move);
         for (var _i = 0, _a = move.indexes; _i < _a.length; _i++) {
             var index = _a[_i];
             var revealedPaths = this.getMoveAtOnceRevealedPath(move, index, player);
             if (!revealedPaths.length)
                 continue;
-            var item = this.material(move.itemType).getItem(index);
+            if (!moveView.reveal)
+                moveView.reveal = {};
             moveView.reveal[index] = {};
+            var item = this.material(move.itemType).getItem(index);
             for (var _b = 0, revealedPaths_2 = revealedPaths; _b < revealedPaths_2.length; _b++) {
                 var path = revealedPaths_2[_b];
                 (0, set_1.default)(moveView.reveal[index], path, (0, get_1.default)(item, path));
@@ -219,8 +250,14 @@ var HiddenMaterialRules = (function (_super) {
         })) {
             throw new RangeError("You cannot shuffle items with different hiding strategies: ".concat(JSON.stringify(move.indexes.map(function (index) { return _this.getItemHiddenPaths(move.itemType, material.getItem(index), player); }))));
         }
+        // TODO: if we shuffle a hand of items partially hidden, we should send the partially visible information to the client.
+        // Example: It's a Wonderful World with the Extension: the back face of the player's hand are different
+        // => when the hand is shuffled we should see where the expansion cards land.
         return !hiddenPaths.length;
     };
+    /**
+     * Override of {@link MaterialRules.play} that also removes the hidden information from items, for example when a card is flipped face down
+     */
     HiddenMaterialRules.prototype.play = function (move, context) {
         var result = _super.prototype.play.call(this, move, context);
         if (this.client && (0, moves_1.isMoveItem)(move) && this.hidingStrategies[move.itemType]) {
@@ -243,8 +280,14 @@ var HiddenMaterialRules = (function (_super) {
     return HiddenMaterialRules;
 }(MaterialRules_1.MaterialRules));
 exports.HiddenMaterialRules = HiddenMaterialRules;
+/**
+ * Hiding strategy that removes the item id
+ */
 var hideItemId = function () { return ['id']; };
 exports.hideItemId = hideItemId;
+/**
+ * Hiding strategy that removes "id.front" from the item (when we have cards with composite ids, back & front)
+ */
 var hideFront = function () { return ['id.front']; };
 exports.hideFront = hideFront;
 //# sourceMappingURL=HiddenMaterialRules.js.map