Add: JavaDoc for Game optional card and round management methods

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;
     }
 
-
-
-
-
-
-
 }