Module Contents

class AgentBrain(memorize_for_ticks=None)

An artificial agent whose behaviour can be programmed to be, for example, (semi-)autonomous.


Method called by any world when it starts.

When adding an agent to a matrx.grid_world.GridWorld, through a world builer, you only pass the class of your agent brain, not the actual instance. Instead, this instance is made by the builder when a new world is created and ran. At that point this method is called.

That makes this method the ideal place for any initialization or reset you want your agent brain to do when starting a world or between worlds.

Importantly, this method is called after the builder assigned things to it such as its location, name and object ID. As this method is called afterwards, it allows you to do things related to to those properties.

An example is when you run the same world multiple times. In that case the instance of your agent brain will have attributes with values from the previous run. This method can be used to reset them.

filter_observations(self, state)

Filters the world state before deciding on an action.

In this method you filter the received world state to only those properties and objects the agent is actually supposed to see.

Currently the world returns ALL properties of ALL objects within a certain range(s), as specified by matrx.agents.capabilities.capability.SenseCapability. But perhaps some objects are obscured because they are behind walls and this agent is not supposed to look through walls, or an agent is not able to see some properties of certain objects (e.g. colour).

The adjusted world state that this function returns is directly fed to the agent’s decide function. Furthermore, this returned world state is also fed through the MATRX API to any visualisations.

Override this method when creating a new AgentBrain and you need to filter the world state further.


A state description containing all perceived matrx.objects.env_object.EnvObject and objects inheriting from this class within a certain range as defined by the matrx.agents.capabilities.capability.SenseCapability.

The keys are the unique identifiers, as values the properties of an object. See matrx.objects.env_object.EnvObject for the kind of properties that are always included. It will also contain all properties for more specific objects that inherit from that class.

Also includes a ‘world’ key that describes common information about the world (e.g. its size).


A dictionary similar to state but describing the filtered state this agent perceives of the world.


A future version of MATRX will include handy utility function to make state filtering less of a hassle (e.g. to easily remove specific objects or properties, but also ray casting to remove objects behind other objects)

decide_on_action(self, state)

Contains the decision logic of the agent.

This method determines what action the agent should perform. The matrx.grid_world.GridWorld is responsible for deciding when an agent can perform an action, if so this method is called for each agent and fed with the world state from the filter_observations method.

Two things need to be determined: action name and action arguments.

The action is returned simply as the class name (as a string), and the action arguments as a dictionary with the keys the names of the keyword arguments. See the documentation of that action to find out which arguments.

An argument that is always possible is that of action_duration, which denotes how many ticks this action should take and overrides the action duration set by the action implementation.


A state description as given by the agent’s matrx.agents.agent_brain.AgentBrain.filter_observations() method.


A string of the class name of an action that is also in the action_set class attribute. To ensure backwards compatibility we advise to use Action.__name__ where Action is the intended action.


A dictionary with keys any action arguments and as values the actual argument values. If a required argument is missing an exception is raised, if an argument that is not used by that action a warning is printed. The argument applicable to all action is action_duration, which sets the number ticks the agent is put on hold by the GridWorld until the action’s world mutation is actual performed and the agent can perform a new action (a value of 0 is no wait, 1 means to wait 1 tick, etc.).


A future version of MATRX will include handy utility function to make agent decision-making less of a hassle. Think of a Belief-Desire-Intention (BDI) like structure, and perhaps even support for learning agents.


Provides a dictionary of data for any Logger

This method functions to relay data from an agent’s decision logic (this AgentBrain class) through the GridWorld into a Logger. Here it can be further processed and stored.


A dictionary with keys identifiable names and the data as its value.

send_message(self, message)

Sends a Message from this agent to others

Method that allows you to construct a message that will be send to either a specified agent, a team of agents or all agents.


A message object that needs to be send. Should be of type Message. It’s to_id can contain a single recipient, a list of recipients or None. If None, it is send to all other agents.

is_action_possible(self, action, action_kwargs)

Checks if an action would be possible.

This method can be called from the AgentBrain to check if a certain action is possible to perform with the current state of the GridWorld. It requires as input an action name and its arguments (if any), same as the decide_on_action method should return.

This method does not guarantees that if the action is return by the brain it actually succeeds, as other agents may intervene.


The name of an Action class.


A dictionary with keys any action arguments and as values the actual argument values.


True if the action can be performed, False otherwise.


An ActionResult object containing the success or failure of the action, and (if failed) the reason why.

create_context_menu_for_other(self, agent_id_who_clicked, clicked_object_id, click_location)

Generate options for a context menu for a specific object/location that a user NOT controlling this human agent opened.

Thus: another human agent selected this agent, opened a context menu by right clicking on an object or location. This function is called. It should return actions, messages, or other info for what this agent can do relevant to that object / location. E.g. pick it up, move to it, display information on it, etc.

Example usecase: tasking another agent that is not yourself, e.g. to move to a specific location.

For the default MATRX visualization, the context menu is opened by right clicking on an object. This function should generate a list of options (actions, messages, or something else) which relate to that object or location. Each option is in the shape of a text shown in the context menu, and a message which is send to this agent if the user actually clicks that context menu option.


The ID of the (human) agent that selected this agent and requested for a context menu.


A string indicating the ID of an object. Is None if the user clicked on a background tile (which has no ID).


A list containing the [x,y] coordinates of the object on which the user right clicked.


A list containing context menu items. Each context menu item is a dict with a ‘OptionText’ key, which is the text shown in the menu for the option, and a ‘Message’ key, which is the message instance that is sent to this agent when the user clicks on the context menu option.