Package megamek.common.game

Interface IGame

All Known Implementing Classes:
AbstractGame, ASGame, Game, SBFGame, SimulationContext
public interface IGame
Common interface for games with different rule sets, such as Total Warfare, BattleForce, or Alpha Strike.

  • Field Details

  • Method Details

    • getTurn

      @Nullable PlayerTurn getTurn()

    • hasMoreTurns

      default boolean hasMoreTurns()
      Returns:
      True when there is at least one more player turn waiting to be played in the current game phase. //TODO this code from Game is surprising; the last available turn should be at size()-1, but apparently this works

    • getTurnIndex

      int getTurnIndex()
      Returns the current turn index, i.e. the turn that should next be played by the corresponding player.

    • getTurnsList

      List<? extends PlayerTurn> getTurnsList()
      Returns:
      the current list of turns. If you're not the GameManager, don't even think about changing any of the turns.

    • getOptions

      IGameOptions getOptions()

    • getCurrentRound

      int getCurrentRound()
      Returns:
      The current game round, with 0 typically indicating deployment and 1 the first actual game round.

    • setCurrentRound

      void setCurrentRound(int currentRound)
      Sets the current game round to the given round number. See getCurrentRound(). This method can be used in both GameManager and Client.
      Parameters:
      currentRound - The new round number

    • incrementCurrentRound

      void incrementCurrentRound()
      Adds 1 to the current round value. This method is intended for server use only.

    • getPhase

      GamePhase getPhase()
      Returns:
      The current phase of this game.

    • setPhase

      void setPhase(GamePhase phase)
      Sets the current game phase to the given phase. May perform phase-dependent cleanup. This method is intended for the GameManager.
      Parameters:
      phase - The new phase

    • setLastPhase

      void setLastPhase(GamePhase lastPhase)
      Sets the previous game phase to the given phase. This method is intended for the GameManager.
      Parameters:
      lastPhase - The phase to be remembered as the previous phase.

    • receivePhase

      default void receivePhase(GamePhase phase)
      Sets the current game phase to the given phase. May perform phase-dependent cleanup and fire game events. This method is intended for the Client. By default, this method calls setPhase(GamePhase). When overridden, it'll usually make sense to call super(phase).
      Parameters:
      phase - The new phase

    • isCurrentPhasePlayable

      boolean isCurrentPhasePlayable()
      Returns true when the current game phase should be played, meaning it is played in the current type of game and there are possible actions in it in the present game state. The result may be different in other rounds.
      Returns:
      True when the current phase should be skipped entirely in this round
      See Also:

    • shouldSkipCurrentPhase

      default boolean shouldSkipCurrentPhase()
      Returns true when the current game phase should be skipped, either because it is not played at all in the current type of game or because the present game state dictates that there can be no actions in it. The result may be different in other rounds. This is the opposite of isCurrentPhasePlayable().
      Returns:
      True when the current phase should be skipped entirely in this round
      See Also:

    • fireGameEvent

      void fireGameEvent(GameEvent event)
      Fires the given GameEvent, sending the event to all GameListener of this game.
      Parameters:
      event - the game event.

    • addGameListener

      void addGameListener(GameListener listener)
      Adds a GameListener to this game. The GameListener will receive any subsequently fired GameEvents.
      Parameters:
      listener - The GameListener to add

    • removeGameListener

      void removeGameListener(GameListener listener)
      Removes the specified game listener.
      Parameters:
      listener - the game listener.

    • isForceVictory

      boolean isForceVictory()
      Returns:
      Whether there is an active claim for victory.

    • getForces

      Forces getForces()
      Returns:
      The Forces present in this game. Can be empty, but not null.

    • setForces

      void setForces(Forces forces)
      Replaces the game's Forces with the given forces.
      Parameters:
      forces - The new Forces object to use

    • getPlayer

      @Nullable Player getPlayer(int id)
      Parameters:
      id - a player id
      Returns:
      the individual player assigned the id parameter.

    • hasPlayer

      default boolean hasPlayer(int id)
      Parameters:
      id - A player ID
      Returns:
      True when there is a player for the given ID

    • getPlayersList

      List<Player> getPlayersList()
      Returns:
      The current players as a list. Implementations should make sure that this list can be safely modified.

    • addPlayer

      void addPlayer(int id, Player player)
      Adds the given Player to the game with the given game-unique id. // TODO : Can this be made a default method?
      Parameters:
      id - The game-unique id of this player
      player - The Player object

    • setPlayer

      void setPlayer(int id, Player player)
      Sets the given Player to the given game-unique id. // TODO : Is this method useful? Why not use addPlayer that also sets single-blind info?
      Parameters:
      id - The game-unique id of this player
      player - The Player object

    • removePlayer

      void removePlayer(int id)
      Removes the player with the id from the game.
      Parameters:
      id - The player id

    • getNoOfPlayers

      int getNoOfPlayers()
      Returns:
      The current number of active players in the game. This includes observers but not ghosts.

    • getTeams

      List<Team> getTeams()
      Returns:
      The teams in the game. Implementations should make sure that this list can be safely modified.

    • getNoOfTeams

      int getNoOfTeams()
      Returns:
      The number of teams in the game.

    • setupTeams

      void setupTeams()

    • getTeamForPlayer

      @Nullable default Team getTeamForPlayer(Player player)

    • getNextEntityId

      int getNextEntityId()
      Returns:
      The next free ID for InGameObjects (unit/entity/formation/others).

    • getEntitiesOwnedBy

      default int getEntitiesOwnedBy(Player player)
      Returns:
      the number of units owned by the player, regardless of their status, as long as they are in the game.

    • getInGameObject

      default Optional<InGameObject> getInGameObject(int id)
      Returns:
      The InGameObject associated with the given id, if there is one.

    • getOutOfGameUnit

      default Optional<InGameObject> getOutOfGameUnit(int id)
      Returns:
      The InGameObject from those that are out of game (destroyed, fled, never deployed) associated with the given id, if there is one.

    • getEntityFromAllSources

      default InGameObject getEntityFromAllSources(int id)
      looks for an entity by id number even if out of the game

    • getInGameObjects

      List<InGameObject> getInGameObjects()
      Returns:
      A list of all InGameObjects of this game. This list is copied and may be safely modified.

    • getInGameObjects

      default List<InGameObject> getInGameObjects(Collection<Integer> idList)
      Returns:
      A list of all InGameObjects of this game with the given ids. The returned list may be safely modified.

    • replaceUnits

      void replaceUnits(List<InGameObject> units)
      This is a Client-side method to replace or add units that are sent from the server. Adds the given units to the list of units or objects in the current game. When a unit's ID is already present the currently assigned unit will be replaced with the given new one.
      Parameters:
      units - The units to add or use as a replacement for current units.

    • getGraveyard

      List<InGameObject> getGraveyard()
      Returns:
      a list of units that are destroyed or otherwise no longer part of the game. These should have a reason for their removal set.

    • setBoard

      void setBoard(int boardId, Board board)
      Sets the given board as the game's board with the given boardId, possibly replacing the former board of the same id. This method is written with the idea that a game might have more than one board. Game's legacy methods of setBoard() and getBoard() use the boardId 0. This method is meant as a server-side method.
      Parameters:
      boardId - (currently ignored) The boardId to assign to that board
      board - The board to use

    • getBoard

      @Nullable default Board getBoard(int boardId)
      Returns the board with the given boardId or null if the game does not have a board of that boardId.
      Parameters:
      boardId - The board's ID
      Returns:
      The board with the given ID

    • getBoard

      @Nullable default Board getBoard(BoardLocation boardLocation)
      Returns the board of the given location or null if the game does not have a board of that location's boardId.
      Parameters:
      boardLocation - The location
      Returns:
      The board with the given ID

    • getBoards

      Map<Integer,Board> getBoards()
      Returns the complete map of boardIds/boards the game uses. The returned map is an unmodifiable view of the game's map, but not a deep copy, so changes to a board will affect the game.
      Returns:
      The game's boards and their IDs

    • getBoard

      default Board getBoard()
      Returns the game's board. This method internally uses the boardId 0 for every call, see getBoard(int). It can eventually be replaced to allow multiple maps for any type of game.
      Returns:
      The game's board (using ID = 0)

    • receiveBoard

      void receiveBoard(int boardId, Board board)
      Sets the given board as the game's board with the given boardId, possibly replacing the former board of the same id. This method is written with the idea that a game might have more than one board. This method is meant as a client-side method and may fire game events.
      Parameters:
      boardId - (currently ignored) The boardId to assign to that board
      board - The board to use

    • receiveBoards

      void receiveBoards(Map<Integer,Board> boards)
      Sets the given boards as the game's boards, replacing all previous boards. This method is written with the idea that a game might have more than one board. This method is meant as a client-side method and may fire game events.
      Parameters:
      boards - The new boards

    • boardExists

      default boolean boardExists(int boardId)

    • connectBoards

      @Deprecated(since="0.51.0", forRemoval=true) default void connectBoards(int lowerBoardId, int higherBoardId, Coords coords)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • hasEnclosingBoard

      default boolean hasEnclosingBoard(int boardId)
      Returns true when the given Board has an (existing) enclosing Board, i.e. when the given Board occupies one or more hexes of another board of a larger scale. E.g., this is true when there's an atmospheric map for a ground map or a space map for an atmospheric map.
      Parameters:
      boardId - The board's ID
      Returns:
      True when the board is enclosed within another board

    • getEnclosingBoard

      default Optional<Board> getEnclosingBoard(int boardId)

    • onTheSameBoard

      default boolean onTheSameBoard(@Nullable Targetable entity1, @Nullable Targetable entity2)
      Returns:
      True when both given units are not null and reside on the same board. Only checks the board IDs, not the positions (which could be null or invalid).

    • onDirectlyConnectedBoards

      default boolean onDirectlyConnectedBoards(@Nullable Targetable entity1, @Nullable Targetable entity2)
      Returns true when both given units or objects are on directly connected, "adjacent" boards, such as a ground map and its enclosing atmospheric map. Returns false if they are on connected maps that are one or more other maps "apart", such as a ground map and a connected high-altitude map or two ground maps enclosed within a single atmospheric map. Also returns false when the two are on unconnected maps.
      Parameters:
      entity1 - The first unit or object to test
      entity2 - The second unit or object to test
      Returns:
      True when both units or objects are on directly connected boards

    • getBoard

      default Board getBoard(Targetable targetable)
      Parameters:
      targetable - The targetable to check
      Returns:
      The board ID of the board that the given Targetable is on.

    • hasBoardLocationOf

      default boolean hasBoardLocationOf(@Nullable Targetable targetable)
      Returns true if the given targetable is not null and has a position that exists, i.e. its position and board ID are on an actual board. When this returns true, calling getHex for its location will return a non-null hex.
      Parameters:
      targetable - The targetable to check
      Returns:
      True when its location exists and is on a board

    • hasBoardLocation

      default boolean hasBoardLocation(@Nullable BoardLocation boardLocation)
      Returns true if the given boardLocation really exists, i.e. is not null, its board ID is an actual board in the game and its coords are contained in that board. This means that a hex can be found for this boardLocation.
      Parameters:
      boardLocation - The location to test
      Returns:
      True when the location exists and is on a board

    • hasBoardLocation

      default boolean hasBoardLocation(@Nullable Coords coords, int boardId)
      Returns true if the given coords and boardID really exist, are not null, the board ID is an actual board in the game and the coords are contained in that board. This means that a hex can be found for these values, and it will not be null (unless the board data is corrupted).
      Parameters:
      coords - The coords to test
      boardId - The board ID to test
      Returns:
      True when the location exists and is on a board

    • hasBoard

      default boolean hasBoard(@Nullable BoardLocation boardLocation)
      Returns true if the given boardLocation points to an existing board, i.e. its board ID is an actual board in the game. Does not check the location's coords.
      Parameters:
      boardLocation - The location to test
      Returns:
      True when the location is not null and its board exists

    • hasBoard

      default boolean hasBoard(int boardId)
      Returns true if the given bboard ID is an actual board in the game.
      Parameters:
      boardId - The board ID to test
      Returns:
      True when the board exists

    • getHex

      @Nullable default Hex getHex(BoardLocation boardLocation)
      Returns the hex for the given location, i.e. the hex at the coords and on the board ID of the given location. Returns null when the board doesn't exist or when there is no hex at the given coords. The various hasBoardLocation() methods can be used to make sure that a non-null hex can be found.
      Parameters:
      boardLocation - The location to query
      Returns:
      The hex at the given location
      See Also:

    • getHex

      @Nullable default Hex getHex(Coords coords, int boardId)
      Returns the hex for the given location, i.e. the hex at the coords and on the board of the given ID. Returns null when the board doesn't exist or when there is no hex at the given coords.
      Parameters:
      coords - The location's coords
      boardId - The location's board ID
      Returns:
      The hex at the given location
      See Also:

    • getHexOf

      @Nullable default Hex getHexOf(Targetable targetable)
      Returns the hex that the given Targetable is at, i.e. the hex at the position and on the board ID of the given Targetable. Returns null when targetable is null, the board doesn't exist or when there is no hex at its position or the position is null.
      Parameters:
      targetable - The unit or object
      Returns:
      The hex at the position of the Targetable
      See Also:

    • isOnSpaceMap

      default boolean isOnSpaceMap(@Nullable BoardLocation boardLocation)
      Returns true when the given location exists in this game (i.e., is part of a board) and the board it is on is a space board, including high-altitude boards (even atmospheric hexes on such a board).
      Parameters:
      boardLocation - The location to test
      Returns:
      True when the location is part of a space board

    • isOnGroundMap

      default boolean isOnGroundMap(@Nullable BoardLocation boardLocation)
      Parameters:
      boardLocation - The location to check
      Returns:
      True when the location is not null and a valid ground board location

    • isOnGroundMap

      default boolean isOnGroundMap(Targetable targetable)
      Parameters:
      targetable - The target to check
      Returns:
      True when the targetable is considered to be on a ground board (not an atmospheric or space board). This is true for units that are deployed either offboard or on a valid ground board location; for other targets such as hexes or buildings, this is true when on a valid ground board location. This is safe to call regardless of what the position or board ID of the targetable might be.

    • isOnSpaceMap

      default boolean isOnSpaceMap(Targetable targetable)

    • hasConnectedBoard

      @Deprecated(since="0.51.0", forRemoval=true) default boolean hasConnectedBoard(Board board)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • isOnAtmosphericMap

      default boolean isOnAtmosphericMap(BoardLocation boardLocation)

    • isOnAtmosphericMap

      default boolean isOnAtmosphericMap(Targetable targetable)
      Returns true when the given targetable is in a hex of an atmospheric board. Returns false if it is null or has an invalid position (invalid board ID or position not on the board).
      Parameters:
      targetable - The object/unit/target to check
      Returns:
      True when the targetable is on an atmospheric board

    • onConnectedBoards

      default boolean onConnectedBoards(@Nullable Targetable entity1, @Nullable Targetable entity2)
      Returns true when both given units or objects are on boards that are connected at least through a common high altitude map. For two connected maps, an aerospace fighter can reach one from the other, traversing atmospheric and/or high atmospheric maps. Also returns true when both are on the same board.

      When two maps are not connected they're part of different hierarchies of maps and therefore, nothing happening on one can influence the other. It is possible to set up games of such unrelated map clusters, but it is not advisable. Such games could just as well be played separately from each other and suffer a lower chance of MM crashing both...

      Parameters:
      entity1 - The first unit or object to test
      entity2 - The second unit or object to test
      Returns:
      True when both units or objects are on connected boards (or the same board)

    • hasSpaceAndAtmosphericBoards

      default boolean hasSpaceAndAtmosphericBoards()
      Returns:
      True when this game has at least one space board (including high-altitude) and at least one non-space board (low altitude or ground).

    • hasSpaceBoard

      default boolean hasSpaceBoard()
      Returns:
      True when this game has at least one space board (including high-altitude).

    • hasNonSpaceBoard

      default boolean hasNonSpaceBoard()
      Returns:
      True when this game has at least one non-space board (low altitude or ground).

    • hasGroundBoard

      default boolean hasGroundBoard()
      Returns:
      True when this game has at least one ground board.

    • areConnectedBoards

      default boolean areConnectedBoards(int boardId1, int boardId2)
      Returns true when both given boards are connected at least through a common high altitude map. When two boards are connected, a fighter unit can reach one from the other, traversing atmospheric and/or high atmospheric maps. Also returns true if the boards are one and the same.

      When two maps are not connected they're part of different hierarchies of maps and therefore, nothing happening on one can influence the other. It is possible to set up games of such unrelated map clusters, but it is not advisable. Such games could just as well be played separately from each other and suffer a lower chance of MM crashing both...

      Parameters:
      boardId1 - The first board ID
      boardId2 - The second board ID
      Returns:
      True when the given boards are connected at least through a common high atmosphere map

    • getAllEnclosingBoards

      default List<Integer> getAllEnclosingBoards(int boardId)
      Returns a list of IDs of all enclosing boards of the given board. These are at most two other boards; for a ground board, the enclosing atmospheric board (if present) and that one's enclosing high-altitude map (if present). For an atmospheric map, this will be at most the enclosing high-altitude map (if present); for any space map, the returned List will be empty.
      Parameters:
      boardId - The board to find enclosed boards for
      Returns:
      All enclosing boards in the hierarchy of the given board (between zero and two boards)

    • getEnclosingBoard

      @Nullable default Board getEnclosingBoard(Board board)

    • commonEnclosingBoard

      default Optional<Board> commonEnclosingBoard(@Nullable Targetable object1, @Nullable Targetable object2)
      Returns the common enclosing board of the two given units/targets. For two units on the same board, this board is returned. When one unit is on a higher board and the other on a connected lower board (ground is lower than atmospheric is lower than space), the higher of the two is returned. When two units are on ground boards with an atmospheric board connecting the two, the atmospheric board is returned. For a S2O or O2S attack situation, the space board is returned. If any of the two units is null, is not deployed or otherwise off board, not on connected boards, the return value is empty.
      Parameters:
      object1 - The first unit or object
      object2 - The second unit or object
      Returns:
      The "lowest" common enclosing board, if any

    • getNewReport

      ReportEntry getNewReport(int messageId)
      Returns a new ReportEntry with the given report message ID. The ReportEntry subclass returned depends on the implementation in the IGame subclass.
      Parameters:
      messageId - The message ID from report-messages.properties
      Returns:
      A new report of an appropriate type and message

    • scriptedEvents

      List<TriggeredEvent> scriptedEvents()
      Returns:
      All scripted events present in this game. Note that these will typically only be present on the Server side and the Clients will only receive the results of those events.

    • addScriptedEvent

      default void addScriptedEvent(TriggeredEvent event)
      Add a scripted event to this game's scripted events list.
      Parameters:
      event - The new event to add

    • getTeamByPlayer

      @Deprecated(since="0.51.0", forRemoval=true) default Map<Integer,Integer> getTeamByPlayer()
      Deprecated, for removal: This API element is subject to removal in a future version.