The GVG-AI Framework


Forward Model and State Observation

This page contains information about the functions that the controller can use to query the state of the game every game cycle. All these functions are from the class StateObservation. Its methods are grouped in the following tabs by the part of the game state that is being queried:

Advancing and copying the state:

The state observation is given to the agent, as an object of the class StateObservation, as a tool to query the game state, and therefore have some information to decide the next action to take. It also includes a Forward Model that allows the agent to advance the game state (by simulating that an action is taken) and copy it. These are the two methods that allow this:

Forward Model functions: (StateObservation class), advancing and copying the state.
void advance(Types.ACTIONS action) Advances the state using the action passed as the move of the agent. It updates all entities in the game. It modifies the object 'this' to represent the next state after the action has been executed and all entities have moved. Note: stochastic events will not be necessarily the same as in the real game.
StateObservation copy() Returns an exact copy of the state observation object.
Querying the state of the game:

Some functions can be used to retrieve information of the current state of the game. StateObservation provides information about the game (score, winner, game tick, available actions). See the most important function:

State Observation functions: (StateObservation class), querying the game.
double getGameScore() Gets the score of the game at this observation.
int getGameTick() Returns the game tick of this particular observation.
Types.WINNER getGameWinner() Indicates if there is a game winner in the current observation. Possible values are Types.WINNER.PLAYER_WINS, Types.WINNER.PLAYER_LOSES and Types.WINNER.NO_WINNER.
Dimension getWorldDimension() Returns the world dimensions, in pixels.
int getBlockSize() Indicates the width in pixels of a sprite in the game.
boolean isGameOver() Indicates if the game is over or if it hasn't finished yet.
Information about the state of the Avatar:

Some functions can be used to retrieve information of the current state of the avatar. StateObservation provides information about the the avatar (position, resources, speed orientation). See here the most important functions:

State Observation functions: (StateObservation class), querying the Avatar.
ArrayList<Types.ACTIONS> getAvailableActions() Returns the actions that are available in this game for the avatar.
Vector2d getAvatarPosition() Returns the position of the avatar. If the game is finished, this returns Types.NIL.
double getAvatarSpeed() Returns the speed of the avatar. If the game is finished, this returns 0.
Vector2d getAvatarOrientation() Returns the orientation of the avatar. If the game is finished, this returns Types.NIL.
HashMap<Integer, Integer> getAvatarResources() Returns the resources in the avatar's possession. As there can be resources of different nature, each entry is a key-value pair where the key is the resource ID, and the value is the amount of that resource type owned. It should be assumed that there might be other resources available in the game, but the avatar could have none of them. If the avatar has no resources, an empty HashMap is returned.
Information about events happened in the game:

It is also possible to retrieve the events (collisions) that happened during the game up to this point in time. This also includes collisions of sprites created by the avatar (such as shots, or swords) with other sprites:

State Observation functions: (StateObservation class), querying the events.
TreeSet<Event> getEventsHistory() This method retrieves a list of events that happened so far in the game. In this context, events are collisions of the avatar with other sprites in the game. Additionally, the list also contains information about collisions of a sprite created by the avatar (usually by using the action Types.ACTIONS.ACTION_USE) with other sprites. The list is ordered asc. by game step.
Information about other sprites in the game:

The rest of the functions of the StateObservation class can be used to retrieve information of the current state of the game. This class provides information about the game (score, winner, game tick, available actions), the avatar (position, resources, speed orientation) and past events. The other information the StateObservation class provides revolves around Observation objects. An Observation is an object that represents a sprite on the screen, and it contains information about its position, ID, unique type of sprite and category (if it is an NPC, static, resource, etc. object). These observations can be accessed in two different ways:

  • Observation grid: The observations can be accessed via (x,y) coordinates, retrieving a list of observations present in a given position. Note that the same observation can occupy more than one grid cell. See the "getObservationGrid()" method below.
  • Observation lists: Observations can be also retrieved via their category (see the "getXXXPositions()" methods below). This allows to obtain all observations of a given category (i.e. NPCs), and optionally they can be returned sorted by distance to a arbitrary position passed by parameter.
The Observation objects are persisitent. This is, the same Java object will represent the same Observation both in the grid and in the list, and also in different time steps. Here are the most important methods of StateObservation:

State Observation functions: (StateObservation class), querying the observations.
ArrayList<Observation>[][] getObservationGrid() Returns a grid with all observations in the level, accessible by the x,y coordinates of the grid. Each grid cell has a width and height of getBlockSize() pixels. Each cell contains a list with all observations in that position. Note that the same observation may occupy more than one grid cell.
ArrayList<Observation>[] getNPCPositions()
ArrayList<Observation>[] getNPCPositions(Vector2d)
Returns a list of observations of NPC in the game. As there can be NPCs of different type, each entry in the array corresponds to a sprite type. Every ArrayList contains a list of objects of type Observation. Each Observation holds the position, sprite type id and sprite id of that particular sprite. If a vector is passed as parameter, the observations are returned in ascending order according to the distance to that point.
ArrayList<Observation>[] getImmovablePositions()
ArrayList<Observation>[] getImmovablePositions(Vector2d)
Returns a list of observations of immovable sprites in the game. As there can be immovable sprites of different type, each entry in the array corresponds to a sprite type. Every ArrayList contains a list of objects of type Observation. Each Observation holds the position, sprite type id and sprite id of that particular sprite. If a vector is passed as parameter, the observations are returned in ascending order according to the distance to that point.
ArrayList<Observation>[] getMovablePositions()
ArrayList<Observation>[] getMovablePositions(Vector2d)
Returns a list of observations of sprites that move, but are NOT NPCs in the game. As there can be movable sprites of different type, each entry in the array corresponds to a sprite type. Every ArrayList contains a list of objects of type Observation. Each Observation holds the position, sprite type id and sprite id of that particular sprite. If a vector is passed as parameter, the observations are returned in ascending order according to the distance to that point.
ArrayList<Observation>[] getResourcesPositions()
ArrayList<Observation>[] getResourcesPositions(Vector2d)
Returns a list of observations of resources in the game. As there can be resources of different type, each entry in the array corresponds to a sprite type. Every ArrayList contains a list of objects of type Observation. Each Observation holds the position, sprite type id and sprite id of that particular sprite. If a vector is passed as parameter, the observations are returned in ascending order according to the distance to that point.
ArrayList<Observation>[] getPortalsPositions()
ArrayList<Observation>[] getPortalsPositions(Vector2d)
Returns a list of observations of portals in the game. As there can be portals of different type, each entry in the array corresponds to a sprite type. Every ArrayList contains a list of objects of type Observation. Each Observation holds the position, sprite type id and sprite id of that particular sprite. If a vector is passed as parameter, the observations are returned in ascending order according to the distance to that point.
ArrayList<Observation>[] getFromAvatarSpritesPositions()
ArrayList<Observation>[] getFromAvatarSpritesPositions(Vector2d)
Returns a list of observations of sprites created by the avatar (usually, by applying the action Types.ACTIONS.ACTION_USE). As there can be sprites of different type, each entry in the array corresponds to a sprite type. Every ArrayList contains a list of objects of type Observation, and if a vector is passed as a parameter, the list is ordered asc. by distance to the reference passed. Each Observation holds the position, sprite type id and sprite id of that particular sprite.


- Go Home -