matrx.objects.standard_objects

Module Contents

class SquareBlock(location, name='Block', visualize_colour='#4286f4', **kwargs)

Bases: matrx.objects.env_object.EnvObject

An example of a simple object with a set of attributes that are always the same. In this case that it is not traversable, and is visualized as a square. Otherwise it takes all default properties from an EnvObject and has not other custom properties.

Parameters
locationtuple

Location of door.

namestring. Optional, default “Block”

Name of block, defaults to “Block”

**kwargs:

Additional properties that should be added to the object.

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class Door(location, is_open=False, name='Door', open_colour='#006400', closed_colour='#640000', **kwargs)

Bases: matrx.objects.env_object.EnvObject

Door base object, can be used to define rooms. An example of an object that is and ordinary EnvObject but has a method on which two Actions depend; OpenDoorAction and CloseDoorAction. This method alters the is_traversable property accordingly.

It also has two colors which the door visualization changes into when open or closed.

Parameters
locationtuple

Location of door.

namestring. Optional, default “Door”

Name of object, defaults to “Door”

open_colourstring. Optional, default “#006400”

Colour when open

closed_colourstring. Optional, default “#640000”

Colour when closed

**kwargs:

Dict of additional properties that should be added to the object as well.

open_door(self)

Opens the door, changes the colour and sets the properties as such.

close_door(self)

Closes the door, changes the colour and sets the properties as such.

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class Wall(location, name='Wall', visualize_colour='#000000', **kwargs)

Bases: matrx.objects.env_object.EnvObject

A simple Wall object. Is not traversable, the colour can be set but has otherwise the default EnvObject property values.

Parameters
locationtuple

The location of the wall.

namestring. Optional, default “Wall”

The name, default “Wall”.

visualize_colour: string. Optional, default “#000000” (black)

A Hex string indicating the colour of the wall.

kwargs: dict (optional)

A dictionary of keyword arguments that can be used to add additional properties

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class AreaTile(location, name='AreaTile', visualize_colour='#8ca58c', visualize_depth=None, visualize_opacity=1.0, **kwargs)

Bases: matrx.objects.env_object.EnvObject

A simple AreaTile object. Is always traversable, not movable, the colour can be set but has otherwise the default EnvObject property values. Can be used to define different areas in the GridWorld.

Parameters
locationtuple

The location of the area.

namestring. Optional, default “AreaTile”

The name, default “AreaTile”.

visualize_colourstring. Optional, default is “#b7b7b7”

hex colour code for tile. default is grey.

visualize_opacityfloat. Optional, default 0.8.

Opacity of the object. By default 0.8

visualize_depthint. Optional, default=101

depth of visualization. By default 101: just above agent and other objects Higher means higher priority.

**kwargsOptional.

Set of additional properties that should be added to the object as well.

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class SmokeTile(location, name='SmokeTile', visualize_colour='#b7b7b7', visualize_opacity=0.8, visualize_depth=101, **kwargs)

Bases: matrx.objects.standard_objects.AreaTile

An object representing one tile of smoke. Is always traversable, not movable, and square shaped. Can be transparent.

Parameters
locationtuple

The location of the area.

nameString. Optional,default:”SmokeTile”

The name, default “SmokeTile”.

visualize_colourstring. Optional, default is “#b7b7b7”

hex colour code for tile. default is grey.

visualize_opacityfloat. Optional, default 0.8.

Opacity of the object. By default 0.8

visualize_depthint. Optional, default=101

depth of visualization. By default 101: just above agent and other objects Higher means higher priority.

kwargs: dict (optional)

A dictionary of keyword arguments that can be used to add additional properties

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class Battery(location, name='Battery', start_energy_level=1.0, energy_decay=0.01)

Bases: matrx.objects.env_object.EnvObject

A simple example of an object with an update_properties method that is called each simulation step. It also has two default properties that are unique to this object; start_energy_level, and energy_decay. These are added as properties by passing them as keyword arguments to the constructor of EnvObject. In addition this constructor also makes a current_enery_level attribute which is also treated as a property by giving it to the EnvObject constructor as well. All other properties are obtained from the defaults.py as defined for all EnvObject, except for the size (which is set to be 0.25) and the colour (which is a shade of green turning to red based on the current_energy_level).

Its update_properties method simply decays the current energy level with the given factor and the colour accordingly.

Parameters
locationlist

The location of the battery.

name: String (optional).

Defaults to ‘Battery’.

start_energy_level: float (optional)

Defaults to 1.0

energy_decay: float (optional)

Defaults to 0.01, meaning the energy decreases with 1% of its current value each simulation step.

update(self, grid_world, state)

Updates the current energy level, changes the property accordingly, and also change the visualization color.

Parameters
grid_world: Gridworld

The state of the world. Not used.

Returns
The new properties: Dict
change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class CollectionTarget(location, collection_objects, collection_zone_name, name='Collection_target')

Bases: matrx.objects.env_object.EnvObject

An invisible object that tells which objects needs collection.

This invisible object is linked to CollectionDropOffTile object(s) and is used by the CollectionGoal to identify which objects should be collected and dropped off at the tiles. This object is just a regular object but contains three additional properties: - collection_objects: See parameter doc. - collection_zone_name: See parameter doc. - is_invisible: A boolean denoting that this object is invisible. This boolean has no effect in MATRX, except to denote that this object is not an actual visible object. - is_drop_off_target: Denotes this object as containing the descriptions of the to be collected objects.

The invisibility is implemented as a block with full opacity, not movable, fully traversable and always below other objects.

Parameters
location(x, y)

The location of this object.

collection_objectsList of dicts

A list of dictionaries, each dictionary in this list represents an object that should be dropped at this location. The dictionary itself represents the property-value pairs these objects should adhere to. The order of the list matters iff the CollectionGoal.in_order==True, in which case the CollectionGoal will track if the dropped objects at this tile are indeed dropped in the order of the list.

collection_zone_namestr

This is the name that links CollectionDropOffTile object(s) to this object. The CollectionGoal will check all of these tiles with this name to check if all objects are already dropped and collected.

namestr (default is “Collection_target”)

The name of this object.

See also

matrx.world_builder.WorldBuilder.add_collection_goal

The handy method in the WorldBuilder to add a collection goal to the world and required object(s).

matrx.goals.goals.CollectionGoal

The CollectionGoal that performs the logic of check that all object(s) are dropped at the drop off tiles.

matrx.objects.standard_objects.CollectionDropOffTile

The tile that represents the location(s) where the object(s) need to be dropped.

Notes

It does not matter where this object is added in the world. However, it is good practice to add it on top of the (or one of them) CollectionDropOffTile object(s). The helper method to create collection areas WorldBuilder.add_collection_goal follows this practice.

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.
class CollectionDropOffTile(location, name='Collection_zone', collection_area_name='Collection zone', visualize_colour='#64a064', visualize_opacity=1.0, **kwargs)

Bases: matrx.objects.standard_objects.AreaTile

An area tile used to denote where one or more objects should be dropped. It is similar to any other AreaTile but has two additional properties that identify it as a drop off location for objects and the name of the drop off. These are used by a CollectionGoal to help find the drop off area in all world objects.

Parameters
location(x, y)

The location of this tile.

namestr (default is “Collection_zone”)

The name of this tile.

collection_area_namestr (default is “Collection_zone”)

The name of the collection zone this collection tile belongs to. It is used by the respective CollectionGoal to identify where certain objects should be dropped.

visualize_colourString (default is “#64a064”, a pale green)

The colour of this tile.

visualize_opacityFloat (default is 1.0)

The opacity of this tile. Should be between 0.0 and 1.0.

kwargs: dict (optional)

A dictionary of keyword arguments that can be used to add additional properties

See also

matrx.world_builder.WorldBuilder.add_collection_goal

The handy method in the WorldBuilder to add a collection goal to the world and required object(s).

matrx.goals.goals.CollectionGoal

The CollectionGoal that performs the logic of check that all object(s) are dropped at the drop off tiles.

matrx.objects.standard_objects.CollectionTarget

The invisible object representing which object(s) need to be collected and (if needed) in which order.

update(self, grid_world, state)

Used to update some properties of this object if needed. For example a ‘status’ property that changes over time. It can also be used to update something in the GridWorld. For example a Fire object that damages other objects in its location.

If you want this functionality, you should create a new object that inherits from this class EnvObject.

This method is called automatically in the game-loop inside a running GridWorld instance.

Parameters
grid_world

The GridWorld instance representing the entire grid world. Can be used to alter itself or others in the world in some way.

change_property(self, property_name, property_value)

Changes the value of an existing (!) property.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

Returns
The new properties.
add_property(self, property_name, property_value)

Adds a new(!) property with its value to the object.

Parameters
property_namestring

The name of the property.

property_value:

The value of the property.

property location(self)

The location of any object is a pythonic property, this allows us to do various checks on it. One of them is the setter that is overridden in AgentAvatar to also transfer all carried objects with it.

Returns
Current Locationtuple

The current location as a tuple; (x, y)

property properties(self)

Returns the custom properties of this object, but also any mandatory properties such as location, name, is_traversable and all visualization properties (those are in their own dictionary under ‘visualization’).

In the case we return the properties of a class that inherits from EnvObject, we check if that class has

Returns
All mandatory and custom properties in a dictionary.