Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

State Complexes of Gridworlds

This bare-bones repository contains two Python files:

  •, a GUI made using Kivy for the creation of small, simple gridworlds; and
  •, a script which will take the saved gridworld from the GUI and create a cubical complex.

You will also find a WorldBuilder.kv file. This is just a GUI builder file. You shouldn't need to edit it or the file for general usage (unless you want to add features - which you are very welcome to!).


After cloning the repository, install dependencies using:

pip install -r requirements.txt

Assuming these are all installed correctly, you should be good to go. This repo was tested with Python 3.7.4, Kivy 1.11.1, and NetworkX 2.3.


Gridworld Builder



A small GUI window should open.

You should see a grid of grey cells labelled with (1, 1) in the top-left and ending in (10, 10) in the bottom-right. These 100 cells are assignable, individual cells within your gridworld. By default, all gridworld cells are unassigned and therefore do not exist. To assign them to be part of the gridworld, simply click on the desired cells. Doing so after initial loading will assign them to the gridworld area.

By default, all area cells are assumed to be unoccupied, meaning an agent or object could in the future occupy it. If you don't want an area cell to be able to be occupied, you need to then assign it to be a wall. To do this, click the Options button at the bottom of the GUI. Now click the wall button (it will become highlighted), and now click the Grid View button at the bottom of the GUI to go back to the grid world builder. Now clicking with your cursor in area cells will assign them as a wall cell. For the purposes of the script, it is important that the entire gridworld area is bordered by wall cells on all sides (this is especially important for grid worlds which include objects).

If you wish for there to be an agent (or multiple agents) in your gridworld, set their starting position(s) to an unoccupied area cell by going into the options menu and clicking Start, then returning to the grid view and assigning those cells. You may also set goal and object cells in the same way by clicking Goal or Object in the options menu.

There are two more important rules for using the

  1. Only unoccupied area cells may have the additional assignments of object, start, or goal - but never more than one of these assignments!
  2. It is a bit buggy. Please be patient with it, and avoid changing cell assignments back-and-forth too much.

Once you are happy with the gridworld you've constructed, click the Create & Save World Graph in the options menu. This will create a number of files in your local directory which will used by the script.

State Complex Builder

To quote Anakin Skywalker: this is where the fun begins.

If you run this script as-is, will proceed to:

  • load your created gridworld from its local directory
  • construct an undirected graphical representation of this gridworld using networkx
  • plot the graph
  • construct a state complex of the graph using two generators (described below), using networkx
  • plot a two-dimensional projection of the state complex
  • take a random walk of n=50 steps through the state complex, plotting each step and then creating an animated GIF of this random walk

All plots should be automatically saved in your local directory.

The two generators which uses are:

  1. An agent (A) can move to adjacent cell in the gridworld if it is empty (E), i.e.

A - E


E - A

  1. An agent (A) can push or pull an object if there is empty space (E) behind the object (O) (for pushing) or behind the agent (for pulling), and where Ws (wildcards) represent cells of any other type, i.e.

A - O - E

W - W - W


E - A - O

W - W - W

(and vice-versa)

Of course, if you wish to do more than just the above, you will need to dig into the code a bit. I may in the future make this whole repo into something more user-friendly, but for now this is it. I hope that comments within the code and a few Google searches are enough to tide you through, but if not and you require any assistance, please feel free to contact me via GitHub :)


For more information on state complexes, especially cubical complexes (which by the nature of gridworlds, we are building here), I recommend reading

R. Ghrist & V. Peterson (2007) The geometry and topology of reconfiguration Advances in Applied Mathematics 38:302–323

And for information about gridworlds and their broad importance to AI research as toy examples, I suggest reading

J. Leike et al. (2017) AI Safety Gridworlds arXiv:1711.09883v2


Tool for creating simple gridworlds and their state complexes





No releases published


No packages published