s3games.engine

## Class GameState

- java.lang.Object
- - s3games.engine.GameState

-     public class GameState
      extends java.lang.Object

  GameState contains all information that is important for the current game state

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int` | `currentPlayer` the player number on move 1..N
    `java.util.Map<java.lang.String,java.lang.String>` | `elementLocations` for each element name, location name where it currently is placed
    `java.util.Map<java.lang.String,java.lang.Integer>` | `elementOwners` for each element name, the number of player
    `java.util.Map<java.lang.String,java.lang.Integer>` | `elementStates` for each element name, the state number
    `java.util.Map<java.lang.String,java.lang.Integer>` | `elementzIndexes` z-indexes of all the elements
    `java.util.Map<java.lang.String,java.lang.String>` | `locationElements` for each location, content of the element
    `int[]` | `playerScores` scores of all players
    `int` | `winner` -1 until the game has finished, then 0 for draw, or 1..N player number who won

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GameState()` construct a new empty game state
    `GameState(GameSpecification specs, Robot robot)` use this constructor to create a state corresponding to the start of game situation

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.ArrayList<Move>` | `allPossibleMoves()` return a list of moves that can be taken from this state - this includes ALL moves regardless that they are equal (because of irrelevance of locations or same element types)
    `boolean` | `equals(GameState other)` implementation of the equals() method - we ignore irrelevant locations and look only at element types, not the element names
    `boolean` | `equals(java.lang.Object other)` determine if the state is equal to another one - while ignoring irrelevant locations
    `Move` | `findMove(GameState newState)` compares this state with newState, and returns a move that leads from this state to a new state
    `GameState` | `getCopy()` return a copy of this state state
    `int` | `hashCode()` return a hash code for fast hashmap access, remember to call touch() always after state changes
    `boolean` | `moveAllowed(Move move)` verifies all rules, returns true, if the move is allowed, or false if not, does not modify the game state, does not make any followup actions, however executes all conditions of tested rules with all the consequences
    `void` | `moveElement(Move move, GameSpecification specs)` only updates the game state by moving element between two locations, does not test anything, does not apply any rules
    `void` | `performMove(Move move)` performs a move after it has been verified, executes follow-up action of the rule that maximizes the score, adds the score, important: the game is marked finished only if one of the players won, or rules specifically announced draw.
    `java.util.HashSet<Move>` | `possibleMoves()` return a list of moves that can be taken from this states - this includes only DIFFERENT moves, i.e.
    `java.lang.String` | `toString()`
    `void` | `touch()` always call this method after modifying the state

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### elementStates

          public java.util.Map<java.lang.String,java.lang.Integer> elementStates

      for each element name, the state number

    - #### elementLocations

          public java.util.Map<java.lang.String,java.lang.String> elementLocations

      for each element name, location name where it currently is placed

    - #### locationElements

          public java.util.Map<java.lang.String,java.lang.String> locationElements

      for each location, content of the element

    - #### elementOwners

          public java.util.Map<java.lang.String,java.lang.Integer> elementOwners

      for each element name, the number of player

    - #### currentPlayer

          public int currentPlayer

      the player number on move 1..N

    - #### winner

          public int winner

      -1 until the game has finished, then 0 for draw, or 1..N player number who won

    - #### elementzIndexes

          public java.util.Map<java.lang.String,java.lang.Integer> elementzIndexes

      z-indexes of all the elements

    - #### playerScores

          public int[] playerScores

      scores of all players

  - ### Constructor Detail

    - #### GameState

          public GameState()

      construct a new empty game state

    - #### GameState

          public GameState(GameSpecification specs,
                   Robot robot)

      use this constructor to create a state corresponding to the start of game situation

  - ### Method Detail

    - #### getCopy

          public GameState getCopy()

      return a copy of this state state

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      return a hash code for fast hashmap access, remember to call touch() always after state changes
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### touch

          public void touch()

      always call this method after modifying the state

    - #### equals

          public boolean equals(java.lang.Object other)

      determine if the state is equal to another one - while ignoring irrelevant locations
      Overrides:
        `equals` in class `java.lang.Object`

    - #### equals

          public boolean equals(GameState other)

      implementation of the equals() method - we ignore irrelevant locations and look only at element types, not the element names

    - #### findMove

          public Move findMove(GameState newState)

      compares this state with newState, and returns a move that leads from this state to a new state

    - #### allPossibleMoves

          public java.util.ArrayList<Move> allPossibleMoves()
                                                     throws java.lang.Exception

      return a list of moves that can be taken from this state - this includes ALL moves regardless that they are equal (because of irrelevance of locations or same element types)
      Throws:
        `java.lang.Exception`

    - #### possibleMoves

          public java.util.HashSet<Move> possibleMoves()
                                                throws java.lang.Exception

      return a list of moves that can be taken from this states - this includes only DIFFERENT moves, i.e. those leading to not equal() states
      Throws:
        `java.lang.Exception`

    - #### moveAllowed

          public boolean moveAllowed(Move move)
                              throws java.lang.Exception

      verifies all rules, returns true, if the move is allowed, or false if not, does not modify the game state, does not make any followup actions, however executes all conditions of tested rules with all the consequences
      Throws:
        `java.lang.Exception`

    - #### performMove

          public void performMove(Move move)
                           throws java.lang.Exception

      performs a move after it has been verified, executes follow-up action of the rule that maximizes the score, adds the score, important: the game is marked finished only if one of the players won, or rules specifically announced draw. when there are no more moves, you need to determine draw state on your own
      Throws:
        `java.lang.Exception`

    - #### moveElement

          public void moveElement(Move move,
                         GameSpecification specs)

      only updates the game state by moving element between two locations, does not test anything, does not apply any rules