From 9b24ddfd7eb5e2bcf4a856971eb06d45fd373b38 Mon Sep 17 00:00:00 2001 From: MatteoPellegrino05 Date: Sun, 19 Apr 2026 18:10:25 +0200 Subject: [PATCH] Add: JavaDoc for Game constructors and game action methods --- .../java/it/polimi/ingsw/gc14/Model/Game.java | 98 ++++++++++++++++++- 1 file changed, 96 insertions(+), 2 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 c03c38f..72842ff 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Game.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Game.java @@ -123,10 +123,21 @@ public class Game implements Serializable { return playersList.stream().filter(x->x.getUserName().equals(Username)).findFirst().orElse(null); } - + /** + * Returns the configured number of players for this game. + * + * @return the configured number of players for this game. + */ public int getNPlayers() { return nPlayers; } + + /** + * Creates a game with the specified number of players. + * + * @param nPlayers the configured number of players for the game. + * @throws IllegalArgumentException if {@code nPlayers < 0} or {@code nPlayers > 5}. + */ public Game(int nPlayers) throws IllegalArgumentException{ if(nPlayers < 0||nPlayers > 5) throw new IllegalArgumentException(); @@ -141,11 +152,24 @@ public class Game implements Serializable { playersList = new ArrayList<>(); OptionalCardQueue = new LinkedList<>(); } + + /** + * Creates a game with 0 configured players. + */ public Game() { this(0); } + /** + * Attempts to add the specified player to the game. + * The operation succeeds only if the configured number of players is not 0, + * the current game stage is {@code WAITING}, and the player is not already present. + * If the number of players reaches the configured maximum, the game is initialized. + * + * @param player the player to add to the game. + * @return {@code true} if the player is successfully added, {@code false} otherwise. + */ public boolean addPlayer(Player player) { if(this.nPlayers==0) { @@ -162,6 +186,12 @@ public class Game implements Serializable { } return true; } + + /** + * Initializes the game after all required players have been added. + * The method creates the appropriate order logic card according to the number of players, + * selects the first current player, and updates the game stage to {@code SLOT_CHOICE}. + */ public void init() { switch (nPlayers) { @@ -182,7 +212,18 @@ public class Game implements Serializable { currentState.GameStageUpdate(GameStages.SLOT_CHOICE); } - //region Cotroller Methods + //region Controller Methods + + /** + * Attempts to assign the slot at the specified index to the specified player. + * The operation succeeds only if the index is valid, the current game stage is {@code SLOT_CHOICE}, + * the specified player is the current player, and the selected slot is not already assigned. + * If the slot is successfully assigned, the next player setup is triggered. + * + * @param player the player performing the slot choice. + * @param slotIndex the index of the selected slot. + * @return {@code true} if the slot choice succeeds, {@code false} otherwise. + */ public boolean SlotChoiceByIndex(Player player, int slotIndex) { if(slotIndex<0 || slotIndex>=slotMap.size()) return false; @@ -206,6 +247,20 @@ public class Game implements Serializable { } //region Drawing Methods + + /** + * Attempts to draw the upper tribe card at the specified index for the specified player. + * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS}, + * the specified player is the current player, at least one upper card draw is still available, + * 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, + * and the number of remaining upper draws is decremented. + * If both upper and lower draws become zero, the next player setup is triggered. + * + * @param player the player performing the draw. + * @param cardIndex the index of the upper tribe card to draw. + * @return {@code true} if the draw succeeds, {@code false} otherwise. + */ public boolean DrawUpperTribeCardByIndex(Player player,int cardIndex) { if( cardIndex<0 || cardIndex >=board.upperListTribe.size()) return false; @@ -232,6 +287,20 @@ public class Game implements Serializable { return true; } + + /** + * Attempts to draw the lower tribe card at the specified index for the specified player. + * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS}, + * the specified player is the current player, at least one lower card draw is still available, + * 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, + * and the number of remaining lower draws is decremented. + * If both lower and upper draws become zero, the next player setup is triggered. + * + * @param player the player performing the draw. + * @param cardIndex the index of the lower tribe card to draw. + * @return {@code true} if the draw succeeds, {@code false} otherwise. + */ public boolean DrawLowerTribeCardByIndex(Player player, int cardIndex) { if( cardIndex<0 || cardIndex >=board.lowerListTribe.size()) return false; @@ -261,6 +330,18 @@ public class Game implements Serializable { } + /** + * Attempts to draw the upper building card at the specified index for the specified player. + * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS}, + * the specified player is the current player, at least one upper card draw is still available, + * and the selected building card can be bought by the player. + * If successful, the building card is removed from the board and the number of remaining upper draws is decremented. + * If both upper and lower draws become zero, the next player setup is triggered. + * + * @param player the player performing the draw. + * @param cardIndex the index of the upper building card to draw. + * @return {@code true} if the draw succeeds, {@code false} otherwise. + */ public boolean DrawUpperBuildingCardByIndex(Player player,int cardIndex) { if( cardIndex<0 || cardIndex >=board.upperListBuilding.size()) return false; @@ -287,6 +368,19 @@ public class Game implements Serializable { return true; } + + /** + * Attempts to draw the lower building card at the specified index for the specified player. + * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS}, + * the specified player is the current player, at least one lower card draw is still available, + * and the selected building card can be bought by the player. + * If successful, the building card is removed from the board and the number of remaining lower draws is decremented. + * If both lower and upper draws become zero, the next player setup is triggered. + * + * @param player the player performing the draw. + * @param cardIndex the index of the lower building card to draw. + * @return {@code true} if the draw succeeds, {@code false} otherwise. + */ public boolean DrawLowerBuildingCardByIndex(Player player,int cardIndex) { if( cardIndex<0 || cardIndex >=board.lowerListBuilding.size()) return false;