# 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: `evennia.scripts.scripts.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

      - wild cards. (as) –

    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: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.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.