evennia.contrib.grid.xyzgrid.xyzroom

XYZ-aware rooms and exits.

These are intended to be used with the XYZgrid - which interprets the Z ‘coordinate’ as different (named) 2D XY maps. But if not wanting to use the XYZgrid gridding, these can also be used as stand-alone XYZ-coordinate-aware rooms.

class evennia.contrib.grid.xyzgrid.xyzroom.XYZManager(*args, **kwargs)

Bases: evennia.objects.manager.ObjectManager

This is accessed as .objects on the coordinate-aware typeclasses (XYZRoom, XYZExit). It has all the normal Object/Room manager methods (filter/get etc) but also special helpers for efficiently querying the room in the database based on XY coordinates.

filter_xyz(xyz='*', '*', '*', **kwargs)

Filter queryset based on XYZ position on the grid. The Z-position is the name of the XYMap Set a coordinate to ‘*’ to act as a wildcard (setting all coords to * will thus find all XYZ rooms). This will also find children of XYZRooms on the given coordinates.

Kwargs:

xyz (tuple, optional): A coordinate tuple (X, Y, Z) where each element is either

an int or str. The character ‘*’ acts as a wild card. Note that the Z-coordinate is the name of the map (case-sensitive) in the XYZgrid contrib.

**kwargs: All other kwargs are passed on to the query.

Returns

django.db.queryset.Queryset – A queryset that can be combined with further filtering.

get_xyz(xyz=0, 0, 'map', **kwargs)

Always return a single matched entity directly. This accepts no *-wildcards. This will also find children of XYZRooms on the given coordinates.

Kwargs:

xyz (tuple): A coordinate tuple of int or str (not ‘*’, no wildcards are

allowed in get). The Z-coordinate acts as the name (case-sensitive) of the map in the XYZgrid contrib.

**kwargs: All other kwargs are passed on to the query.

Returns

XYRoom – A single room instance found at the combination of x, y and z given.

Raises

• XYZRoom.DoesNotExist – If no matching query was found.

• XYZRoom.MultipleObjectsReturned – If more than one match was found (which should not possible with a unique combination of x,y,z).

class evennia.contrib.grid.xyzgrid.xyzroom.XYZExitManager(*args, **kwargs)

Bases: evennia.contrib.grid.xyzgrid.xyzroom.XYZManager

Used by Exits. Manager that also allows searching for destinations based on XY coordinates.

filter_xyz_exit(xyz='*', '*', '*', xyz_destination='*', '*', '*', **kwargs)

Used by exits (objects with a source and -destination property). Find all exits out of a source or to a particular destination. This will also find children of XYZExit on the given coords..

Kwargs:

xyz (tuple, optional): A coordinate (X, Y, Z) for the source location. Each

element is either an int or str. The character ‘*’ is used as a wildcard - so setting all coordinates to the wildcard will return all XYZExits. the Z-coordinate is the name of the map (case-sensitive) in the XYZgrid contrib.

xyz_destination (tuple, optional): Same as xyz but for the destination of the

exit.

**kwargs: All other kwargs are passed on to the query.

Returns

django.db.queryset.Queryset – A queryset that can be combined with further filtering.

Notes

Depending on what coordinates are set to *, this can be used to e.g. find all exits in a room, or leading to a room or even to rooms in a particular X/Y row/column.

In the XYZgrid, z_source != z_destination means a _transit_ between different maps.

get_xyz_exit(xyz=0, 0, 'map', xyz_destination=0, 0, 'map', **kwargs)

Used by exits (objects with a source and -destination property). Get a single exit. All source/destination coordinates (as well as the map’s name) are required. This will also find children of XYZExits on the given coords.

Kwargs:

xyz (tuple, optional): A coordinate (X, Y, Z) for the source location. Each

element is either an int or str (not *, no wildcards are allowed for get). the Z-coordinate is the name of the map (case-sensitive) in the XYZgrid contrib.

xyz_destination_coord (tuple, optional): Same as the xyz but for the destination of

the exit.

**kwargs: All other kwargs are passed on to the query.

Returns

XYZExit – A single exit instance found at the combination of x, y and xgiven.

Raises

• XYZExit.DoesNotExist – If no matching query was found.

• XYZExit.MultipleObjectsReturned – If more than one match was found (which should not be possible with a unique combination of x,y,x).

Notes

All coordinates are required.

class evennia.contrib.grid.xyzgrid.xyzroom.XYZRoom(*args, **kwargs)

Bases: evennia.objects.objects.DefaultRoom

A game location aware of its XYZ-position.

Special properties:

map_display (bool): If the return_appearance of the room should

show the map or not.

map_mode (str): One of ‘nodes’ or ‘scan’. See return_apperance

for examples of how they differ.

map_visual_range (int): How far on the map one can see. This is a

fixed value here, but could also be dynamic based on skills, light etc.

map_character_symbol (str): The character symbol to use to show

the character position. Can contain color info. Default is the @-character.

map_area_client (bool): If True, map area will always fill the entire

client width. If False, the map area’s width will vary with the width of the currently displayed location description.

map_fill_all (bool): I the map area should fill the client width or not. map_separator_char (str): The char to use to separate the map area from

the room description.

objects = <evennia.contrib.grid.xyzgrid.xyzroom.XYZManager object>

map_display = True

map_mode = 'nodes'

map_visual_range = 2

map_character_symbol = '|g@|n'

map_align = 'c'

map_target_path_style = '|y{display_symbol}|n'

map_fill_all = True

map_separator_char = '|x~|n'

property xyz

property xyzgrid

property xymap

classmethod create(key, account=None, xyz=0, 0, 'map', **kwargs)

Creation method aware of XYZ coordinates.

Parameters

• key (str) – New name of object to create.

• account (Account, optional) – Any Account to tie to this entity (usually not used for rooms).

• xyz (tuple, optional) – A 3D coordinate (X, Y, Z) for this room’s location on a map grid. Each element can theoretically be either int or str, but for the XYZgrid, the X, Y are always integers while the Z coordinate is used for the map’s name.

• **kwargs – Will be passed into the normal DefaultRoom.create method.

Returns

room (Object) – A newly created Room of the given typeclass. errors (list): A list of errors in string form, if any.

Notes

The (X, Y, Z) coordinate must be unique across the game. If trying to create a room at a coordinate that already exists, an error will be returned.

get_display_name(looker, **kwargs)

Shows both the #dbref and the xyz coord to staff.

Parameters

looker (TypedObject) – The object or account that is looking at/getting inforamtion for this object.

Returns

name (str) –

A string containing the name of the object,

including the DBREF and XYZ coord if this user is privileged to control the room.

return_appearance(looker, **kwargs)

Displays the map in addition to the room description

Parameters

looker (Object) – The one looking.

Keyword Arguments

• map_display (bool) – Turn on/off map display.

• map_visual_range (int) – How ‘far’ one can see on the map. For ‘nodes’ mode, this is how many connected nodes away, for ‘scan’ mode, this is number of characters away on the map. Default is a visual range of 2 (nodes).

• map_mode (str) – One of ‘node’ (default) or ‘scan’.

• map_character_symbol (str) – The character symbol to use. Defaults to ‘@’. This can also be colored with standard color tags. Set to None to just show the current node.

Examples

Assume this is the full map (where ‘@’ is the character location):

#----------------#
|                |
|                |
# @------------#-#
|                |
#----------------#

This is how it will look in ‘nodes’ mode with visual_range=2:

@------------#-#

And in ‘scan’ mode with visual_range=2:

|
|
# @--
|
#----

Notes

The map kwargs default to values with the same names set on the XYZRoom class; these can be changed by overriding the room.

We return the map display as a separate msg() call here, in order to make it easier to break this out into a client pane etc. The map is tagged with type=’xymap’.

exception DoesNotExist

Bases: evennia.objects.objects.DefaultRoom.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.DefaultRoom.MultipleObjectsReturned

path = 'evennia.contrib.grid.xyzgrid.xyzroom.XYZRoom'

typename = 'XYZRoom'

class evennia.contrib.grid.xyzgrid.xyzroom.XYZExit(*args, **kwargs)

Bases: evennia.objects.objects.DefaultExit

An exit that is aware of the XYZ coordinate system.

objects = <evennia.contrib.grid.xyzgrid.xyzroom.XYZExitManager object>

property xyzgrid

property xyz

property xyz_destination

classmethod create(key, account=None, xyz=0, 0, 'map', xyz_destination=0, 0, 'map', location=None, destination=None, **kwargs)

Creation method aware of coordinates.

Parameters

• key (str) – New name of object to create.

• account (Account, optional) – Any Account to tie to this entity (unused for exits).

• xyz (tuple or None, optional) – A 3D coordinate (X, Y, Z) for this room’s location on a map grid. Each element can theoretically be either int or str, but for the XYZgrid contrib, the X, Y are always integers while the Z coordinate is used for the map’s name. Set to None if instead using a direct room reference with location.

• xyz_destination (tuple, optional) – The XYZ coordinate of the place the exit leads to. Will be ignored if destination is given directly.

• location (Object, optional) – If given, overrides xyz coordinate. This can be used to place this exit in any room, including non-XYRoom type rooms.

• destination (Object, optional) – If given, overrides xyz_destination. This can be any room (including non-XYRooms) and is not checked for XYZ coordinates.

• **kwargs – Will be passed into the normal DefaultRoom.create method.

Returns

tuple –

A tuple (exit, errors), where the errors is a list containing all found

errors (in which case the returned exit will be None).

exception DoesNotExist

Bases: evennia.objects.objects.DefaultExit.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.DefaultExit.MultipleObjectsReturned

path = 'evennia.contrib.grid.xyzgrid.xyzroom.XYZExit'

typename = 'XYZExit'