# Class Controller

java.lang.Object
it.polimi.ingsw.is25am31.controller.Controller

public class Controller extends Object
The Controller class manages player interactions, communication between clients and the server during the game, and some game logic. It handles player connections, game phases, in-game actions, and the asynchronous dispatcher for updates.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Controller()`
  Constructs a new Controller.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `abandonRace(UUID clientId)`
  Handles a player abandoning the race.
  `int`
  `addClient()`
  Adds a new client to the game, assigning a player ID.
  `void`
  `addComponentToShip(UUID clientId, int x, int y, Component component)`
  Allows a client to add a component to their ship at a specified position.
  `void`
  `addPlayer(UUID clientId, String nickname)`
  Adds a new player to the game with a nickname.
  `void`
  `checkPlayersConnection(int userNum)`
  `void`
  `controllerPing()`
  `void`
  `drawCard(UUID clientId)`
  Allows the leader player to draw a card from the deck.
  `void`
  `drawComponent(UUID clientId)`
  Allows a client to draw a random face-down component.
  `void`
  `drawFaceUpComponent(int id, UUID clientId)`
  Allows a client to draw a specific face-up component from the board.
  `void`
  `drawFromReserved(int index, UUID clientId)`
  Allows a client to draw a component from their reserved components.
  `void`
  `drawSubDeck(UUID clientId, int index)`
  Allows a client to view a sub-deck of cards.
  `void`
  `endAssemblePhase(UUID clientId)`
  Handles the completion of a player's ship assembly phase.
  `void`
  `endCrewPlacingPhase(UUID clientId)`
  Handles the completion of a player's crew placing phase.
  `void`
  `getFaceUpComponentList(UUID clientId)`
  Allows a client to view the list of face-up components on the game board.
  `int`
  `getLeader()`
  `Game`
  `getModel()`
  `String`
  `getPlayerName(UUID id)`
  Gets the nickname of a player given their client ID.
  `void`
  `handleCrewRequest(UUID clientId, int x, int y, AlienColor type)`
  Handles a request to place a crew member or alien in a cabin on a player's ship.
  `void`
  `leaveGame(UUID clientId)`
  Handles a client leaving the game.
  `void`
  `newConnection(VirtualView client, UUID clientId)`
  Handles a new client connection to the game.
  `int`
  `numPlayers()`
  Gets the current number of active players in the game.
  `void`
  `placeRocket(UUID clientId, int position)`
  Handles a player placing their rocket on the game board.
  `void`
  `putComponentBack(Component component, UUID clientId)`
  Allows a client to return a component to the board face-up.
  `void`
  `removeComponent(UUID clientId, int line, int column)`
  Allows a client to remove a component from their ship.
  `void`
  `rollDice(UUID clientId)`
  Rolls dice for card effect resolution.
  `int`
  `runFinalHourglass()`
  `int`
  `runHourglass()`
  `void`
  `setCardContext(UUID clientId, Map<String,Object> parameters)`
  Sets the context for the current card's pre-effect action.
  `void`
  `setEffectContext(UUID clientId, Map<String,Object> parameters)`
  Applies the current card's effect based on provided parameters.
  `void`
  `setMaxPlayers(UUID clientId, int maxPlayers)`
  Sets the maximum number of players for the game.
  `void`
  `showHourglassSecondsLeft(UUID clientId)`
  Helper method to show hourglass seconds left to a client.
  `void`
  `startFinalHourGlass(UUID clientId)`
  `void`
  `startGame(UUID clientId, int level)`
  Starts the game with the specified difficulty level.
  `void`
  `startHourGlass(UUID clientId)`
  `void`
  `stopHourglass()`
  `void`
  `viewShip(UUID clientId, String nickname)`
  Allows a client to view the ship of a specified player.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Controller

    public Controller()
    Constructs a new Controller. Initializes the game model, hourglass, and asynchronous dispatcher.

- ## Method Details

  - ### getPlayerName

    public String getPlayerName(UUID id)
    Gets the nickname of a player given their client ID.
    Parameters:
      `id` - The UUID of the client.
    Returns:
      The nickname of the player, or null if not found.

  - ### numPlayers

    public int numPlayers()
    Gets the current number of active players in the game.
    Returns:
      The number of active clients.

  - ### newConnection

    public void newConnection(VirtualView client, UUID clientId)
    Handles a new client connection to the game. Assigns a player ID and sends connection responses.
    Parameters:
      `client` - The VirtualView representing the client.
      `clientId` - The ID of the client.

  - ### setMaxPlayers

    public void setMaxPlayers(UUID clientId, int maxPlayers)
    Sets the maximum number of players for the game. This can only be done by the first player.
    Parameters:
      `clientId` - The ID of the client attempting to set the max players.
      `maxPlayers` - The desired maximum number of players (2-4).
    Throws:
      `IllegalStateException` - if the client is not the first player.
      `IllegalArgumentException` - if maxPlayers is out of the valid range.

  - ### startGame

    public void startGame(UUID clientId, int level)
    Starts the game with the specified difficulty level. This can only be done by the first player.
    Parameters:
      `clientId` - The ID of the client attempting to start the game.
      `level` - The game difficulty level (1 or 2).
    Throws:
      `IllegalArgumentException` - if the level is not 1 or 2.

  - ### leaveGame

    public void leaveGame(UUID clientId)
    Handles a client leaving the game. Notifies other players and updates client lists.
    Parameters:
      `clientId` - The ID of the client leaving.

  - ### getModel

    public Game getModel()
    Returns:
      The Game model instance.

  - ### getLeader

    public int getLeader()
    Returns:
      The ID of the leader player.

  - ### addClient

    public int addClient()
    Adds a new client to the game, assigning a player ID.
    Returns:
      The assigned player ID, or -1 if the maximum number of players has been reached.

  - ### addPlayer

    public void addPlayer(UUID clientId, String nickname) throws NameErrorException
    Adds a new player to the game with a nickname.
    Parameters:
      `clientId` - The ID of the client.
      `nickname` - The desired nickname for the player.
    Throws:
      `NameErrorException`

  - ### endAssemblePhase

    public void endAssemblePhase(UUID clientId) throws Exception
    Handles the completion of a player's ship assembly phase. Updates player states and transitions to the flight phase if all players are ready for Level 1.
    Parameters:
      `clientId` - The ID of the client that has ended the assembling phase.
    Throws:
      `Exception`

  - ### placeRocket

    public void placeRocket(UUID clientId, int position) throws Exception
    Handles a player placing their rocket on the game board. This is only for Level 2 games.
    Parameters:
      `clientId` - The ID of the client placing the rocket.
      `position` - The desired starting position for the rocket.
    Throws:
      `RuntimeException` - if the player cannot place their rocket at this time.
      `Exception`

  - ### endCrewPlacingPhase

    public void endCrewPlacingPhase(UUID clientId) throws Exception
    Handles the completion of a player's crew placing phase. This is only for Level 2 games. Updates player states and transitions to the flight phase if all players are ready.
    Parameters:
      `clientId` - The ID of the client that has ended the crew placing phase.
    Throws:
      `Exception`

  - ### viewShip

    public void viewShip(UUID clientId, String nickname) throws Exception
    Allows a client to view the ship of a specified player.
    Parameters:
      `clientId` - The ID of the client requesting to view a ship.
      `nickname` - The nickname of the player whose ship is to be viewed.
    Throws:
      `RuntimeException` - if the specified player nickname is not found.
      `Exception`

  - ### drawComponent

    public void drawComponent(UUID clientId) throws Exception
    Allows a client to draw a random face-down component.
    Parameters:
      `clientId` - The ID of the client drawing the component.
    Throws:
      `Exception`

  - ### getFaceUpComponentList

    public void getFaceUpComponentList(UUID clientId) throws Exception
    Allows a client to view the list of face-up components on the game board.
    Parameters:
      `clientId` - The ID of the client requesting the list.
    Throws:
      `Exception`

  - ### putComponentBack

    public void putComponentBack(Component component, UUID clientId) throws Exception
    Allows a client to return a component to the board face-up.
    Parameters:
      `component` - The component to be returned.
      `clientId` - The ID of the client returning the component.
    Throws:
      `Exception`

  - ### drawFaceUpComponent

    public void drawFaceUpComponent(int id, UUID clientId) throws Exception
    Allows a client to draw a specific face-up component from the board.
    Parameters:
      `id` - The ID of the component to draw.
      `clientId` - The ID of the client drawing the component.
    Throws:
      `Exception`

  - ### drawFromReserved

    public void drawFromReserved(int index, UUID clientId) throws Exception
    Allows a client to draw a component from their reserved components. This is only for Level 2 games.
    Parameters:
      `index` - The index of the reserved component to draw.
      `clientId` - The ID of the client drawing the component.
    Throws:
      `IllegalStateException` - if the game is Level 1.
      `Exception`

  - ### removeComponent

    public void removeComponent(UUID clientId, int line, int column) throws Exception
    Allows a client to remove a component from their ship.
    Parameters:
      `clientId` - The ID of the client removing the component.
      `line` - The row of the component to remove.
      `column` - The column of the component to remove.
    Throws:
      `Exception`

  - ### addComponentToShip

    public void addComponentToShip(UUID clientId, int x, int y, Component component) throws Exception
    Allows a client to add a component to their ship at a specified position.
    Parameters:
      `clientId` - The ID of the client adding the component.
      `x` - The row where the component will be added.
      `y` - The column where the component will be added.
      `component` - The component to add.
    Throws:
      `IllegalStateException` - if the component cannot be added at this time.
      `Exception`

  - ### drawSubDeck

    public void drawSubDeck(UUID clientId, int index)
    Allows a client to view a sub-deck of cards.
    Parameters:
      `clientId` - The ID of the client viewing the sub-deck.
      `index` - The index of the sub-deck.

  - ### showHourglassSecondsLeft

    public void showHourglassSecondsLeft(UUID clientId) throws Exception
    Helper method to show hourglass seconds left to a client.
    Parameters:
      `clientId` - The ID of the client to update.
    Throws:
      `Exception`

  - ### runFinalHourglass

    public int runFinalHourglass()

  - ### runHourglass

    public int runHourglass()

  - ### stopHourglass

    public void stopHourglass()

  - ### drawCard

    public void drawCard(UUID clientId) throws Exception
    Allows the leader player to draw a card from the deck.
    Parameters:
      `clientId` - The ID of the client drawing the card.
    Throws:
      `Exception`

  - ### handleCrewRequest

    public void handleCrewRequest(UUID clientId, int x, int y, AlienColor type) throws Exception
    Handles a request to place a crew member or alien in a cabin on a player's ship.
    Parameters:
      `clientId` - The ID of the client making the request.
      `x` - The row of the target cabin.
      `y` - The column of the target cabin.
      `type` - The color of the alien to place (NONE for a crew member).
    Throws:
      `Exception`

  - ### setCardContext

    public void setCardContext(UUID clientId, Map<String,Object> parameters) throws Exception
    Sets the context for the current card's pre-effect action.
    Parameters:
      `clientId` - The ID of the player calling the method.
      `parameters` - A map with parameters useful to set card context.
    Throws:
      `Exception`

  - ### setEffectContext

    public void setEffectContext(UUID clientId, Map<String,Object> parameters) throws Exception
    Applies the current card's effect based on provided parameters. Handles player eliminations.
    Parameters:
      `clientId` - The ID of the player applying the effect.
      `parameters` - Parameters required by the card's effect.
    Throws:
      `Exception`

  - ### abandonRace

    public void abandonRace(UUID clientId) throws Exception
    Handles a player abandoning the race. Updates player status and checks if the game is over.
    Parameters:
      `clientId` - The ID of the client abandoning the race.
    Throws:
      `Exception`

  - ### rollDice

    public void rollDice(UUID clientId) throws Exception
    Rolls dice for card effect resolution.
    Parameters:
      `clientId` - The ID of the client rolling the dice.
    Throws:
      `Exception`

  - ### controllerPing

    public void controllerPing()

  - ### checkPlayersConnection

    public void checkPlayersConnection(int userNum) throws Exception
    Throws:
      `Exception`

  - ### startHourGlass

    public void startHourGlass(UUID clientId) throws Exception
    Throws:
      `Exception`

  - ### startFinalHourGlass

    public void startFinalHourGlass(UUID clientId) throws Exception
    Throws:
      `Exception`