matrx.agents.agent_types.human_agent

Module Contents

class HumanAgentBrain(memorize_for_ticks=None, fov_occlusion=False, max_carry_objects=3, grab_range=1, drop_range=1, door_range=1, remove_range=1)

Bases: matrx.agents.agent_brain.AgentBrain

Creates an Human Agent which is an agent that can be controlled by a human.

decide_on_action(self, state, user_input)

Contains the decision logic of the agent.

This method determines what action the human agent will perform. The GridWorld is responsible for deciding when an agent can perform an action again, if so this method is called for each agent. Two things need to be determined, which action and with what 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. An argument that is always possible is that of action_duration, which denotes how many ticks this action should take (e.g. a duration of 1, makes sure the agent has to wait 1 tick).

Note; this function of the human_agent_brain overwrites the

decide_on_action() function of the default agent, also providing the user input.

Parameters

stateState

A state description containing all properties of EnvObject that are within a certain range as defined by self.sense_capability.

user_inputlist

A dictionary containing the key presses of the user, intended for controlling thus human agent.

Returns

action_namestr

A string of the class name of an action that is also in self.action_set. To ensure backwards compatibility you could use Action.__name__ where Action is the intended action.

action_argsdict

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.).

filter_observations(self, state)

All our agent work through the OODA-loop paradigm; first you observe, then you orient/pre-process, followed by a decision process of an action after which we act upon the action.

However, as a human agent is controlled by a human, only the observe part is executed.

This is the Observe phase. In this phase you filter the state further to only those properties the agent is actually SUPPOSED to see. Since the grid world returns ALL properties of ALL objects within a certain range(s), but perhaps some objects are obscured because they are behind walls, or an agent is not able to see some properties an certain objects.

This filtering is what you do here.

Parameters

statedict

A state description containing all properties of EnvObject that are within a certain range as defined by self.sense_capability. It is a list of properties in a dictionary

Returns

filtered_statedict

The filtered state of this agent

filter_user_input(self, user_input)

From the received userinput, only keep those which are actually connected to a specific agent action.

Parameters

user_inputlist

A dictionary containing the key presses of the user, intended for controlling thus human agent.

create_context_menu_for_self(self, clicked_object_id, click_location, self_selected)

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

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. 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.

Parameters

clicked_object_idstr

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

click_locationlist

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

self_selectedbool

Describes if the current human agent being controlled by the user was selected or not before opening the context menu. Depending on this, you might pass back a different context menu in this function. E.g. option 1: no-one selected + right click is the same as self selected + right click: both open the current agent’s context menu. option 2: self selected + right click opens our own context menu, no one selected + right click gives a context menu with commands for the entire TEAM.

Returns

context_menulist

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.

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 for that object / location.

Example usecase: tasking another agent that is not yourself, e.g. to move an object.

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.

Parameters

agent_id_who_clickedstr

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

clicked_object_idstr

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

click_locationlist

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

Returns

context_menulist

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.

initialize(self)

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.

get_log_data(self)

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.

Returns

datadict

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.

Parameters

messageMessage

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.

Parameters

actionstr

The name of an Action class.

action_kwargsdict

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

Returns

succeededbool

True if the action can be performed, False otherwise.

action_resultsActionResult

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