evennia.contrib.grid.xyzgrid.xyzgrid

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)

Bases: DefaultScript

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

at_script_creation()

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

property grid

get_map(zcoord)

Get a specific xymap.

Parameters:

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

Returns:

XYMap – Or None if no map was found.

all_maps()

Get all xymaps stored in the grid.

Returns:

list – All initialized xymaps stored with this grid.

log(msg)

get_room(xyz, **kwargs)

Get one or more room objects from XYZ coordinate.

Parameters:

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

• cards. (as wild)

Returns:

Queryset – A queryset of XYZRoom(s) found.

Raises:

XYZRoom.DoesNotExist – If room is not found.

Notes

This assumes the room was previously built.

get_exit(xyz, name='north', **kwargs)

Get one or more exit object at coordinate.

Parameters:

• 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.

Returns:

Queryset – A queryset of XYZExit(s) found.

maps_from_module(module_path)

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}.

Parameters:

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

Returns:

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

reload()

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

add_maps(*mapdatas)

Add map or maps to the grid.

Parameters:

*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.

Raises:

RuntimeError – If mapdata is malformed.

remove_map(*zcoords, remove_objects=True)

Remove an XYmap from the grid.

Parameters:

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

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

delete()

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

spawn(xyz=('*', '*', '*'), directions=None)

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

Parameters:

• 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.

Examples

• 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: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

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

typename = 'XYZGrid'

evennia.contrib.grid.xyzgrid.xyzgrid.get_xyzgrid(print_errors=True)

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

Parameters:

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