From d70ea5a6cdc870da747924ab0923529c621943eb Mon Sep 17 00:00:00 2001 From: MatteoPellegrino05 Date: Mon, 20 Apr 2026 17:35:38 +0200 Subject: [PATCH] Add: JavaDoc for Game optional card and round management methods --- .../java/it/polimi/ingsw/gc14/Model/Game.java | 87 +++++++++++++++++-- 1 file changed, 80 insertions(+), 7 deletions(-) diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Game.java b/src/main/java/it/polimi/ingsw/gc14/Model/Game.java index 69fccdc..7265930 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Game.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Game.java @@ -425,6 +425,21 @@ public class Game implements Serializable { //endregion //region Optional Card Methods + + + /** + * Attempts to pick the upper optional tribe card at the specified index for the specified player. + * The operation succeeds only if the current game stage is {@code OPTIONAL_CARD_EFFECT}, + * the specified player is the current player, the index is valid, + * and the selected tribe card is not an event card. + * If successful, the card is inserted into the player's collection, + * removed from the board, the player is removed from the optional card queue, + * and the next player setup is triggered. + * + * @param player the player performing the optional tribe card pick. + * @param cardIndex the index of the upper optional tribe card to pick. + * @return {@code true} if the operation succeeds, {@code false} otherwise. + */ public boolean PickOptionalTribeCardByIndex(Player player,int cardIndex) { if(currentState.getGameStage() != GameStages.OPTIONAL_CARD_EFFECT){ return false; @@ -447,6 +462,19 @@ public class Game implements Serializable { nextPlayerSetup(); return true; } + + /** + * Attempts to pick the upper optional building card at the specified index for the specified player. + * The operation succeeds only if the current game stage is {@code OPTIONAL_CARD_EFFECT}, + * the specified player is the current player, the index is valid, + * and the selected building card can be bought by the player. + * If successful, the card is removed from the board, the next player setup is triggered, + * and the player is removed from the optional card queue. + * + * @param player the player performing the optional building card pick. + * @param cardIndex the index of the upper optional building card to pick. + * @return {@code true} if the operation succeeds, {@code false} otherwise. + */ public boolean PickOptionalBuildingCard(Player player, int cardIndex) { if(currentState.getGameStage() != GameStages.OPTIONAL_CARD_EFFECT){ return false; @@ -468,6 +496,17 @@ public class Game implements Serializable { return true; } + + /** + * Skips the optional card choice for the specified player. + * The operation succeeds only if the current game stage is {@code OPTIONAL_CARD_EFFECT} + * and the specified player is the current player. + * If successful, the player is removed from the optional card queue + * and the next player setup is triggered. + * + * @param player the player skipping the optional card choice. + * @return {@code true} if the operation succeeds, {@code false} otherwise. + */ public boolean NoOptionalCard(Player player) { if(currentState.getGameStage() != GameStages.OPTIONAL_CARD_EFFECT){ return false; @@ -483,6 +522,23 @@ public class Game implements Serializable { //endregion + /** + * Prepares the next player and updates the game state according to the current game stage. + * If the current stage is {@code SLOT_CHOICE}, the next player is taken from the order logic card. + * If no player is available, the game stage is updated to {@code RESOLVING_ACTIONS} + * and the first assigned slot is selected. + * If the current stage is {@code RESOLVING_ACTIONS}, the current player is pushed back + * into the order logic card, the current slot is freed, and the next assigned slot is selected. + * If no assigned slots remain, the game stage is updated to {@code OPTIONAL_CARD_EFFECT}, + * the optional card queue is built from players owning building cards with effect id equal to 12, + * and the first player in that queue is selected. + * If no player is available for optional card resolution, the game stage is updated to + * {@code RESOLVING_EVENT}; then, if the round number is less than 10, the next round is prepared, + * otherwise event resolution is performed, the game stage is updated to {@code ENDING}, + * and the game is ended. + * If the current stage is {@code OPTIONAL_CARD_EFFECT}, the next player is taken from the optional card queue. + * If no player is available, the game stage is updated to {@code RESOLVING_EVENT}. + */ private void nextPlayerSetup() { if(GameStages.SLOT_CHOICE==currentState.getGameStage()) { Player tempPlayer = orderLogicCard.pull(); @@ -554,7 +610,11 @@ public class Game implements Serializable { } } - + /** + * Resolves all pending event cards if the current game stage is {@code RESOLVING_EVENT}. + * All pending events are activated on the player list. + * Event cards of type {@code SUSTENANCE} are resolved after all other pending events. + */ private void EventResolution() { if(currentState.getGameStage()!= GameStages.RESOLVING_EVENT) @@ -576,6 +636,14 @@ public class Game implements Serializable { } } + + + /** + * Advances the game to the next round. + * The method first resolves pending events. + * If the current round is 10, the game stage is updated to {@code ENDING} and the game is ended. + * Otherwise, the era is updated if the board changes era, and the round number is incremented. + */ private void nextRound() { EventResolution(); @@ -590,6 +658,10 @@ public class Game implements Serializable { } + /** + * Ends the game by applying all final building effects owned by each player + * and updating the game stage to {@code ENDED}. + */ private void endGame() { playersList.forEach( p -> p.buildingCards.stream().filter(x -> x.getEffectType() == EffectType.FINAL). @@ -598,6 +670,13 @@ public class Game implements Serializable { currentState.GameStageUpdate(GameStages.ENDED); } + /** + * Sets the configured number of players for this game. + * The operation succeeds only if the current configured number of players is 0. + * + * @param nPlayers the new configured number of players. + * @return {@code true} if the number of players is updated, {@code false} otherwise. + */ public boolean setNPlayer(int nPlayers) { if(this.nPlayers!=0) @@ -606,10 +685,4 @@ public class Game implements Serializable { return true; } - - - - - - }