The grid

This represents the full XYZ grid, which consists of

  • 2D Map-objects parsed from Map strings and Map-legend components. Each represents one Z-coordinate or location.

  • Prototypes for how to build each XYZ component into ‘real’ rooms and exits.

  • Actual in-game rooms and exits, mapped to the game based on Map data.

The grid has three main functions: - Building new rooms/exits from scratch based on one or more Maps. - Updating the rooms/exits tied to an existing Map when the Map string

of that map changes.

  • Fascilitate communication between the in-game entities and their Map.

class evennia.contrib.grid.xyzgrid.xyzgrid.XYZGrid(*args, **kwargs)[source]

Bases: evennia.scripts.scripts.DefaultScript

Main grid class. This organizes the Maps based on their name/Z-coordinate.


What we store persistently is data used to create each map (the legends, names etc)

property grid

Get a specific xymap.


zcoord (str) – The name/zcoord of the xymap.


XYMap – Or None if no map was found.


Get all xymaps stored in the grid.


list – All initialized xymaps stored with this grid.

get_room(xyz, **kwargs)[source]

Get one or more room objects from XYZ coordinate.

  • xyz (tuple) – X,Y,Z coordinate of room to fetch. ‘*’ acts

  • wild cards. (as) –


Queryset – A queryset of XYZRoom(s) found.


XYZRoom.DoesNotExist – If room is not found.


This assumes the room was previously built.

get_exit(xyz, name='north', **kwargs)[source]

Get one or more exit object at coordinate.

  • xyz (tuple) – X,Y,Z coordinate of the room the exit leads out of. ‘*’ acts as a wildcard.

  • name (str) – The full name of the exit, e.g. ‘north’ or ‘northwest’. The ‘*’ acts as a wild card.


Queryset – A queryset of XYZExit(s) found.


Load map data from module. The loader will look for a dict XYMAP_DATA or a list of XYMAP_DATA_LIST (a list of XYMAP_DATA dicts). Each XYMAP_DATA dict should contain {“xymap”: mapstring, “zcoord”: mapname/zcoord, “legend”: dict, “prototypes”: dict}.


module_path (module_path) – A python-path to a module containing map data as either XYMAP_DATA or XYMAP_DATA_LIST variables.


list – List of zero, one or more xy-map data dicts loaded from the module.


Reload and rebuild the grid. This is done on a server reload.


Add map or maps to the grid.


*mapdatas (dict) – Each argument is a dict structure {“map”: <mapstr>, “legend”: <legenddict>, “name”: <name>, “prototypes”: <dict-of-dicts>, “module_path”: <str>}. The prototypes are coordinate-specific overrides for nodes/links on the map, keyed with their (X,Y) coordinate within that map. The **module_path is injected automatically by self.maps_from_module.


RuntimeError – If mapdata is malformed.

remove_map(*zcoords, remove_objects=True)[source]

Remove an XYmap from the grid.

  • *zoords (str) – The zcoords/XYmaps to remove.

  • remove_objects (bool, optional) – If the synced database objects (rooms/exits) should be removed alongside this map.


Clear the entire grid, including database entities, then the grid too.

spawn(xyz='*', '*', '*', directions=None)[source]

Create/recreate/update the in-game grid based on the stored Maps or for a specific Map or coordinate.

  • xyz (tuple, optional) – An (X,Y,Z) coordinate, where Z is the name of the map. ‘*’ acts as a wildcard.

  • directions (list, optional) – A list of cardinal directions (‘n’, ‘ne’ etc). Spawn exits only the given direction. If unset, all needed directions are spawned.


  • xyz=(‘*’, ‘*’, ‘*’) (default) - spawn/update all maps.

  • xyz=(1, 3, ‘foo’) - sync a specific element of map ‘foo’ only.

  • **xyz=(‘*’, ‘*’, ‘foo’) - sync all elements of map ‘foo’

  • **xyz=(1, 3, ‘*’) - sync all (1,3) coordinates on all maps (rarely useful)

  • xyz=(1, 3, ‘foo’), direction=’ne’ - sync only the north-eastern exit

    out of the specific node on map ‘foo’.

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.contrib.grid.xyzgrid.xyzgrid.XYZGrid'
typename = 'XYZGrid'

Helper for getting the grid. This will create the XYZGrid global script if it didn’t previously exist.


print_errors (bool, optional) – Print errors directly to console rather than to log.