1. Home
  2. Docs
  3. Getting started with MATR...
  4. The Basics
  5. Run a World

Run a World

Here we show how to run a premade world.

The World and its Builder

A core element of MATRX is the World. A World is the thing that contains and tracks the information needed to simulate some agents doing some task in some environment. It is a straightforward finite-state machine, and if that does not mean anything to you: The World tracks how certain actions from agents and objects in the environment affects that same environment.

In MATRX the World is by definition a two-dimensional grid. This readily supports top-down kind of environments. However, you can extend it relatively easy to a more side-scrolling environment or even use it simply a bin for your information and build dashboard on top of this. Although, this is all way more advanced than we need to know at the moment. Let us first dive into the Builder, the creator of Worlds.

MATRX, being object-oriented, follows the design pattern of another of its core elements: The Builder that creates Worlds. This Builder makes it way easier to create something complex as a World. It offers a wide variety of methods that makes it easy for you to add agents, rooms, doors, walls, blocks, background, tiles, and what not. You can view the Builder as the thing that helps you define and contain the blueprint for your World. In fact, the Builder is not limited to creating just one world; it can create many worlds from a single blueprint!

This tutorial shows you how to locate and import a Builder that comes with the MATRX package, then to create a world from it and run it. This is useful to know because one of the core functions of MATRX is to enable the sharing of Worlds and we do so by incorporating them into the MATRX package.

So let’s dive in and go through the motion, step-by-step.

If you can’t wait, see this Github file for the complete tutorial file we make in this tutorial.

Import an out-of-the-box Builder

The code segment below shows how a Builder that comes with MATRX can be imported. All of MATRX’ out-of-the-box builders reside in the matrx.cases package.

from matrx.cases import vis_test

if __name__ == "__main__":
    builder = vis_test.create_builder()

Note: We wrap the code in a “main” block. This is just good practice and we do this throughout all tutorials, but it is not needed for MATRX at all. For more information on this see this Stack answer.

Start the API

Now we have a Builder, we can use it to tell it to start the API:


This will probably print some lines in your console. Don’t worry, these are there to tell you that the API has started and listening for any future World that is running. Next, we create such a World from our Builder and run it.

Create a World

Given an instance of a Builder, we can create a World from it. To do so, given the above code, we do the following:

world = builder.get_world()

This returns one instance of a World as defined by our imported Builder. You may notice that this outputs some lines on your console. These show the progress the Builder has while creating the requested World from its blueprint.

Now let’s see how we can start a World!

Running the World

An instance of the World from a Builder is not doing much yet. You first need to tell it to start running. To do so, we use the following line after all the above:


What this line does is telling that World to connect to the API and start running its game loop that defines the order in which agents, objects and everything that makes up the environment is updated (another neat design pattern from the game industry). We will get to the API in later more advanced tutorials.

As you might notice, MATRX is printing to your console. Something of the lines that the world is paused by the API. This happens because this world enables the standard Visualisation of MATRX which waits for the moment you press the play button! So let’s take a look. Go to this link in your browser:


The Visualisation is a web application that runs locally on port 3000. This can be adjusted, but we come to that. If everything worked out you will see something like this:

This is the start view of the default Visualisation of MATRX. It shows you a simple dropdown menu that allows you to view what all the agents in the worlds perceive. The one you will always have, even if you did not added any agents, is the God Agent.

The God Agent is not really an agent, as it does not take any actions. However, it does perceive everything in the world and provides a unique interaction: The ability to start, pause and stop the World. Click on the dropdown menu and select God. This will open a new browser tab with a view that looks like this:

Note the play and stop buttons on top. If you press the play button you will see that the World start running. This World shows a simple set of agents that navigate between a set of predetermined waypoints and two agents that can be controlled by humans as yourself.

To take control of such a Human Agent, go back to the start view with the dropdown and select one of the two human agents. This opens another new tab. Now try and move the agent around using the WASD keys (W=up, A=left, S=down, D=right).

Congratulations! You just started your first World from an out-of-the-box Builder. You viewed through the eyes of an omniscient agent and took control of a Human Agent. Next, go take a look at this tutorial that explains how to create a new Builder, or take a look at this series of tutorials that shows you how to build the Block Worlds For Teams (BW4T) task with MATRX.

See this Github file for the complete script file we made.

Leave a Reply

Your email address will not be published. Required fields are marked *