Actions

Actions are the “mechanics” of any Griddly game.

A single action defines what happens between two objects (or sets of objects) in an environment.

The source of an action is the object which perfoms a particular action. The destination of an action is the object that is affected by the action.

Lets look at a few examples to make these ideas more concrete!

Step 1 - Movement

We are building the game “Sokoban” so we will first define that the avatar object can move around in empty space. To do that we can define a “move” action as follows:

Actions:
 # Define the move action
 - Name: move
   Behaviours:
   # The agent can move around freely in empty space and over holes
     - Src:
         Object: avatar
         Commands:
           - mov: _dest
       Dst:
         Object: _empty

We have named the above action “move” and defined a single behaviour. The behaviour object contains the Src key with the Object value avatar meaning that we are defing what happens if the avatar object performs the “move” action. We also define the Dst key with the Object value _empty. The _empty keyword is a special object that refers to “empty space”. This action therefore is only executed when the avatar performs an action on an _empty space.

Finally we have Commands object in the Src key. The Commands object contains a list of instructions that will be executed by the Src object. The command we have here is mov: _dest which tells the environment to move the object to the destination of the action. The _dest keyword is another special keyword used in actions which contains the location of the destination of the action.

For more information about possible commands that can be run on either the Src or Dst objects you can refer to the schema docs here

Step 2 - Pushing boxes

To define that we want box objects to move when the avatar object moves into them we can add the following code to our Behaviours list:

# Boxes can move into empty space
- Src:
    Object: box
    Commands:
        - mov: _dest
  Dst:
    Object: _empty

# The agent can push boxes
- Src:
    Object: avatar
    Commands:
        - mov: _dest
  Dst:
    Object: box
    Commands:
        - cascade: _dest

Here we are actually defining two behaviours. The first behaviour is similar to the one in the previous example. We define that the box object has the mechanic allowing it to move into empty space.

The second behaviour we define allows the avatar object to interact with the box object. The mov: _dest command tells avatar to move to the destination location when the action is executed. The box object also needs to be moved in the same direction as the avatar. This can be achieved by applying the same “move” action again, but on the destination object. cascade: _dest re-applies (or cascades) the same action on the destination object, which will move the box!

Note

We have only allowed the box object to “move” into empty space. If the _dest location is not empty, i.e. it contains a wall object or a hole object, the command will not be executed. This will stop also the avatar from moving.

Step 3 - Pushing a box into a hole

Now we can push boxes around in empty space, but we have no defined what will happen if we push the box into a hole object. We want to reward the player and also remove the box object.

# If a box is moved into a hole remove it
     - Src:
         Object: box
         Commands:
           - remove: true
           - reward: 1
       Dst:
         Object: hole

Most of this behaviour is hopefully self-explanatory by this point. There are two new commands introduced here reward: 1 which gives the player a reward of value 1 and remove: true which removes the Src object.

Putting It All Together

In order to put all these actions together, there is only one minor change to make to the first behaviour. We need to add hole to the Dst objects. This adds the ability for avatars to be able to walk on top of hole objects!

So the entire actions section of the game Sokoban looks like this:

Actions:
# Define the move action
- Name: move
  Behaviours:
    # The agent can move around freely in empty space and over holes
    - Src:
        Object: avatar
        Commands:
          - mov: _dest
      Dst:
        Object: [_empty, hole]

    # Boxes can move into empty space
    - Src:
        Object: box
        Commands:
            - mov: _dest
      Dst:
        Object: _empty

    # The agent can push boxes
    - Src:
        Object: avatar
        Commands:
          - mov: _dest
      Dst:
        Object: box
        Commands:
          - cascade: _dest

    # If a box is moved into a hole remove it
    - Src:
        Object: box
        Commands:
          - remove: true
          - reward: 1
      Dst:
        Object: hole