matrx.world_builder.WorldBuilder

class WorldBuilder(shape, tick_duration=0.5, random_seed=1, simulation_goal=1000, run_matrx_api=True, run_matrx_visualizer=False, visualization_bg_clr='#C2C2C2', visualization_bg_img=None, verbose=False)

Used to create one or more worlds according to a single blueprint.

Methods

add_agent(self, location, list], …)

Adds a single agent to the world’s blueprint.

add_agent_prospect(self, location, agent, …)

Adds an agent to the world’s blueprint given a probability.

add_area(self, top_left_location, width, …)

Adds an area of tiles/surface.

add_collection_goal(self, name, …[, …])

Adds a goal to the world to collect objects and drop them in a specific area.

add_goal(self, world_goal[, overwrite])

Appends a WorldGoal to the worlds this builder creates.

add_human_agent(self, location, agent[, …])

Adds an agent that can be controlled by a human user.

add_line(self, start, end, name[, …])

Adds a line of objects to the blueprint.

add_logger(self, logger_class[, …])

Adds a data logger to the world’s blueprint.

add_multiple_agents(self, agents, locations)

Add multiple agents to the world.

add_multiple_objects(self, locations[, …])

Add several objects to the blueprint.

add_object(self, location, name[, …])

Adds an environment object to the blueprint.

add_object_prospect(self, location, name, …)

Adds an object to the blueprint with a certain probability.

add_room(self, top_left_location, width, …)

Adds a rectangular room withs walls and doors.

add_smoke_area(self, top_left_location, …)

Adds a smoke-like area.

add_team(self, agent_brains, tuple], …[, …])

Adds multiple agents as a single team.

get_room_locations(room_top_left, …)

Returns the locations within a room, excluding walls.

get_world(self)

Create a single world using the blueprint of this builder.

startup(self[, media_folder])

Start the API and default visualization.

stop(self)

Stops the running API and default visualisation gracefully.

worlds(self, nr_of_worlds)

A Generator of worlds.

With the constructor you can set a number of general properties and from the resulting instance you can call numerous methods to add new objects and/or agents.

Parameters
shapetuple or list

Denotes the width and height of the world you create.

tick_durationfloat (optional, default 0.5)

The duration of a single ‘tick’ or loop in the game-loop of the world you create.

random_seedint, (optional, default 1)

The master random seed on which all objects, agents and worlds are seeded. Should be a positive non-zero integer.

simulation_goalWorldGoal, int, list or tuple (optional, default 1000)

The goal or goals of the world, either a single WorldGoal, a list of such or a positive non-zero integer to denote the maximum number of ‘ticks’ the world(s) has to run.

run_matrx_api: bool (optional, default True)

Whether to run the API. This API is used to connect the default MATRX visualizer or a custom one.

run_matrx_visualizerbool (optional, default False)

Whether to run the default MATRX visualizer, this requires the API to be run. When set to True, it starts the visualization that is accessible through http://localhost:3000.

visualization_bg_clrstring (optional, default “C2C2C2”)

The color of the world when visualized using MATRX’ own visualisation server. A string representation of hexadecimal color.

visualization_bg_imgstring (optional, None)

An optional background image of the world when visualized using MATRX’ own visualisation server. A string of the path to the image file. When None, no background image is used.

verbosebool (optional, False)

Whether the subsequent created world should be verbose or not.

Raises
ValueError

On an incorrect argument. The exception specifies further what argument and what is erroneous about it.

Examples

This creates a WorldBuilder that creates world of a certain size (here 10 by 10);

>>> from matrx.world_builder import WorldBuilder
>>> builder = WorldBuilder(shape=(10, 10))

To create a WorldBuilder with a black background, a tick duration as fast as possible and with a different master random seed;

>>> from matrx.world_builder import WorldBuilder
>>> builder = WorldBuilder(shape=(10, 10), random_seed=42, tick_duration=-1, visualization_bg_clr="#000000")

Methods

add_agent(self, location, list], …)

Adds a single agent to the world’s blueprint.

add_agent_prospect(self, location, agent, …)

Adds an agent to the world’s blueprint given a probability.

add_area(self, top_left_location, width, …)

Adds an area of tiles/surface.

add_collection_goal(self, name, …[, …])

Adds a goal to the world to collect objects and drop them in a specific area.

add_goal(self, world_goal[, overwrite])

Appends a WorldGoal to the worlds this builder creates.

add_human_agent(self, location, agent[, …])

Adds an agent that can be controlled by a human user.

add_line(self, start, end, name[, …])

Adds a line of objects to the blueprint.

add_logger(self, logger_class[, …])

Adds a data logger to the world’s blueprint.

add_multiple_agents(self, agents, locations)

Add multiple agents to the world.

add_multiple_objects(self, locations[, …])

Add several objects to the blueprint.

add_object(self, location, name[, …])

Adds an environment object to the blueprint.

add_object_prospect(self, location, name, …)

Adds an object to the blueprint with a certain probability.

add_room(self, top_left_location, width, …)

Adds a rectangular room withs walls and doors.

add_smoke_area(self, top_left_location, …)

Adds a smoke-like area.

add_team(self, agent_brains, tuple], …[, …])

Adds multiple agents as a single team.

get_room_locations(room_top_left, …)

Returns the locations within a room, excluding walls.

get_world(self)

Create a single world using the blueprint of this builder.

startup(self[, media_folder])

Start the API and default visualization.

stop(self)

Stops the running API and default visualisation gracefully.

worlds(self, nr_of_worlds)

A Generator of worlds.

__init__(self, shape, tick_duration=0.5, random_seed=1, simulation_goal=1000, run_matrx_api=True, run_matrx_visualizer=False, visualization_bg_clr='#C2C2C2', visualization_bg_img=None, verbose=False)

With the constructor you can set a number of general properties and from the resulting instance you can call numerous methods to add new objects and/or agents.

Parameters
shapetuple or list

Denotes the width and height of the world you create.

tick_durationfloat (optional, default 0.5)

The duration of a single ‘tick’ or loop in the game-loop of the world you create.

random_seedint, (optional, default 1)

The master random seed on which all objects, agents and worlds are seeded. Should be a positive non-zero integer.

simulation_goalWorldGoal, int, list or tuple (optional, default 1000)

The goal or goals of the world, either a single WorldGoal, a list of such or a positive non-zero integer to denote the maximum number of ‘ticks’ the world(s) has to run.

run_matrx_api: bool (optional, default True)

Whether to run the API. This API is used to connect the default MATRX visualizer or a custom one.

run_matrx_visualizerbool (optional, default False)

Whether to run the default MATRX visualizer, this requires the API to be run. When set to True, it starts the visualization that is accessible through http://localhost:3000.

visualization_bg_clrstring (optional, default “C2C2C2”)

The color of the world when visualized using MATRX’ own visualisation server. A string representation of hexadecimal color.

visualization_bg_imgstring (optional, None)

An optional background image of the world when visualized using MATRX’ own visualisation server. A string of the path to the image file. When None, no background image is used.

verbosebool (optional, False)

Whether the subsequent created world should be verbose or not.

Raises
ValueError

On an incorrect argument. The exception specifies further what argument and what is erroneous about it.

Examples

This creates a WorldBuilder that creates world of a certain size (here 10 by 10);

>>> from matrx.world_builder import WorldBuilder
>>> builder = WorldBuilder(shape=(10, 10))

To create a WorldBuilder with a black background, a tick duration as fast as possible and with a different master random seed;

>>> from matrx.world_builder import WorldBuilder
>>> builder = WorldBuilder(shape=(10, 10), random_seed=42, tick_duration=-1, visualization_bg_clr="#000000")

Methods

__init__(self, shape[, tick_duration, …])

With the constructor you can set a number of general properties and from the resulting instance you can call numerous methods to add new objects and/or agents.

add_agent(self, location, list], …)

Adds a single agent to the world’s blueprint.

add_agent_prospect(self, location, agent, …)

Adds an agent to the world’s blueprint given a probability.

add_area(self, top_left_location, width, …)

Adds an area of tiles/surface.

add_collection_goal(self, name, …[, …])

Adds a goal to the world to collect objects and drop them in a specific area.

add_goal(self, world_goal[, overwrite])

Appends a WorldGoal to the worlds this builder creates.

add_human_agent(self, location, agent[, …])

Adds an agent that can be controlled by a human user.

add_line(self, start, end, name[, …])

Adds a line of objects to the blueprint.

add_logger(self, logger_class[, …])

Adds a data logger to the world’s blueprint.

add_multiple_agents(self, agents, locations)

Add multiple agents to the world.

add_multiple_objects(self, locations[, …])

Add several objects to the blueprint.

add_object(self, location, name[, …])

Adds an environment object to the blueprint.

add_object_prospect(self, location, name, …)

Adds an object to the blueprint with a certain probability.

add_room(self, top_left_location, width, …)

Adds a rectangular room withs walls and doors.

add_smoke_area(self, top_left_location, …)

Adds a smoke-like area.

add_team(self, agent_brains, tuple], …[, …])

Adds multiple agents as a single team.

get_room_locations(room_top_left, …)

Returns the locations within a room, excluding walls.

get_world(self)

Create a single world using the blueprint of this builder.

startup(self[, media_folder])

Start the API and default visualization.

stop(self)

Stops the running API and default visualisation gracefully.

worlds(self, nr_of_worlds)

A Generator of worlds.