s3games.engine

## Class GameRule

- java.lang.Object
- - s3games.engine.GameRule

-     public class GameRule
      extends java.lang.Object

  The GameRule class represents a single rule for game moves: from where, to where, and what can be moved, and under what circumstances, as well as what has to be done as follow-up action and how to adjust the player scores, if the rule was applied. The names of element and locations can contain variables - then these are instantiated with the respective indexes of the element/location where the rule is applied. For example a rule from: loc($X1,$Y1); to: loc($X2,$Y2), element: el($I) will match with any locations named "loc(any_number,any_number)" and any element with name "el(any_number)", and the variables will be filled with the respective indexes for the condition, score, and followup evaluation contexts

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `Expr` | `action` action expression to evaluate, after the rule was applied
    `Expr` | `condition` an expression that must evaluate to true in order for this rule to be applicable
    `Expr` | `currentPlayer` expression evaluating to a number of the player that can make this move
    `Expr` | `element` element to move - expression that evaluates to string or a string with variable reference
    `Expr` | `from` location from where the element can be moved - evaluates to string or a string with variable references
    `java.lang.String` | `name` name of the rule
    `java.util.ArrayList<Expr>` | `scoreAmount` a list of score values to add to each player that is in scorePlayer list in the same index
    `java.util.ArrayList<Expr>` | `scorePlayer` a list of players for whom the score should be updated, if the rule was applied
    `Expr` | `state` state of the element - or an expression returning a number
    `Expr` | `to` location to where the element can be moved - evaluates to string or a string with variable references

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GameRule(java.lang.String name)` construct an empty rule with the specified name

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addScores(Context context)` modify the player scores after this rule was matched
    `java.util.ArrayList<Move>` | `getMatchingMoves(Element el, GameSpecification specs, Context context)` list of moves that can be performed from this state with the element specified in the first argument
    `boolean` | `matches(Move move, Context context)` verifies whether the specified move conforms to this rule in the provided context
    `void` | `performAction(Context context)` perform the follow-up action, after this rule was matched

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

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

- - ### Field Detail

    - #### name

          public java.lang.String name

      name of the rule

    - #### element

          public Expr element

      element to move - expression that evaluates to string or a string with variable reference

    - #### state

          public Expr state

      state of the element - or an expression returning a number

    - #### currentPlayer

          public Expr currentPlayer

      expression evaluating to a number of the player that can make this move

    - #### from

          public Expr from

      location from where the element can be moved - evaluates to string or a string with variable references

    - #### to

          public Expr to

      location to where the element can be moved - evaluates to string or a string with variable references

    - #### condition

          public Expr condition

      an expression that must evaluate to true in order for this rule to be applicable

    - #### scorePlayer

          public java.util.ArrayList<Expr> scorePlayer

      a list of players for whom the score should be updated, if the rule was applied

    - #### scoreAmount

          public java.util.ArrayList<Expr> scoreAmount

      a list of score values to add to each player that is in scorePlayer list in the same index

    - #### action

          public Expr action

      action expression to evaluate, after the rule was applied

  - ### Constructor Detail

    - #### GameRule

          public GameRule(java.lang.String name)

      construct an empty rule with the specified name

  - ### Method Detail

    - #### matches

          public boolean matches(Move move,
                        Context context)
                          throws java.lang.Exception

      verifies whether the specified move conforms to this rule in the provided context
      Throws:
        `java.lang.Exception`

    - #### getMatchingMoves

          public java.util.ArrayList<Move> getMatchingMoves(Element el,
                                                   GameSpecification specs,
                                                   Context context)
                                                     throws java.lang.Exception

      list of moves that can be performed from this state with the element specified in the first argument
      Returns:
        the list or null, if no such moves exist
      Throws:
        `java.lang.Exception`

    - #### addScores

          public void addScores(Context context)
                         throws java.lang.Exception

      modify the player scores after this rule was matched
      Throws:
        `java.lang.Exception`

    - #### performAction

          public void performAction(Context context)
                             throws java.lang.Exception

      perform the follow-up action, after this rule was matched
      Throws:
        `java.lang.Exception`