evennia.contrib.grid.wilderness.wilderness¶
Wilderness system
Evennia contrib - titeuf87 2017
This contrib provides a wilderness map. This is an area that can be huge where the rooms are mostly similar, except for some small cosmetic changes like the room name.
Usage¶
This contrib does not provide any new commands. Instead the default py command is used.
A wilderness map needs to created first. There can be different maps, all with their own name. If no name is provided, then a default one is used. Internally, the wilderness is stored as a Script with the name you specify. If you don’t specify the name, a script named “default” will be created and used.
py from evennia.contrib.grid import wilderness; wilderness.create_wilderness()
Once created, it is possible to move into that wilderness map:
py from evennia.contrib.grid import wilderness; wilderness.enter_wilderness(me)
All coordinates used by the wilderness map are in the format of (x, y) tuples. x goes from left to right and y goes from bottom to top. So (0, 0) is the bottom left corner of the map.
Customisation¶
The defaults, while useable, are meant to be customised. When creating a new wilderness map it is possible to give a “map provider”: this is a python object that is smart enough to create the map.
The default provider, WildernessMapProvider, creates a grid area that is unlimited in size.
WildernessMapProvider can be subclassed to create more interesting maps and also to customize the room/exit typeclass used.
There is also no command that allows players to enter the wilderness. This still needs to be added: it can be a command or an exit, depending on your needs.
Example¶
To give an example of how to customize, we will create a very simple (and small) wilderness map that is shaped like a pyramid. The map will be provided as a string: a “.” symbol is a location we can walk on.
Let’s create a file world/pyramid.py:
map_str = '''
.
...
.....
.......
'''
from evennia.contrib.grid import wilderness
class PyramidMapProvider(wilderness.WildernessMapProvider):
def is_valid_coordinates(self, wilderness, coordinates):
"Validates if these coordinates are inside the map"
x, y = coordinates
try:
lines = map_str.split("
")
# The reverse is needed because otherwise the pyramid will be
# upside down
lines.reverse()
line = lines[y]
column = line[x]
return column == "."
except IndexError:
return False
def get_location_name(self, coordinates):
"Set the location name"
x, y = coordinates
if y == 3:
return "Atop the pyramid."
else:
return "Inside a pyramid."
def at_prepare_room(self, coordinates, caller, room):
"Any other changes done to the room before showing it"
x, y = coordinates
desc = "This is a room in the pyramid."
if y == 3 :
desc = "You can see far and wide from the top of the pyramid."
room.ndb.active_desc = desc
Note that the currently active description is stored as .ndb.active_desc. When looking at the room, this is what will be pulled and shown.
> Exits on a room are always present, but locks hide those not used for a > location. So make sure to quell if you are a superuser (since the superuser ignores > locks, those exits will otherwise not be hidden)
Now we can use our new pyramid-shaped wilderness map. From inside Evennia we create a new wilderness (with the name “default”) but using our new map provider:
py from world import pyramid as p; p.wilderness.create_wilderness(mapprovider=p.PyramidMapProvider()) py from evennia.contrib import wilderness; wilderness.enter_wilderness(me, coordinates=(4, 1))
Implementation details¶
When a character moves into the wilderness, they get their own room. If they move, instead of moving the character, the room changes to match the new coordinates.
If a character meets another character in the wilderness, then their room merges. When one of the character leaves again, they each get their own separate rooms.
Rooms are created as needed. Unneeded rooms are stored away to avoid the overhead cost of creating new rooms again in the future.
-
evennia.contrib.grid.wilderness.wilderness.
create_wilderness
(name='default', mapprovider=None, preserve_items=False)[source]¶ Creates a new wilderness map. Does nothing if a wilderness map already exists with the same name.
- Parameters
name (str, optional) – the name to use for that wilderness map
mapprovider (WildernessMap instance, optional) – an instance of a WildernessMap class (or subclass) that will be used to provide the layout of this wilderness map. If none is provided, the default infinite grid map will be used.
-
evennia.contrib.grid.wilderness.wilderness.
enter_wilderness
(obj, coordinates=0, 0, name='default')[source]¶ Moves obj into the wilderness. The wilderness needs to exist first and the provided coordinates needs to be valid inside that wilderness.
- Parameters
obj (object) – the object to move into the wilderness
coordinates (tuple), optional) – the coordinates to move obj to into the wilderness. If not provided, defaults (0, 0)
name (str, optional) – name of the wilderness map, if not using the default one
- Returns
bool – True if obj successfully moved into the wilderness.
-
evennia.contrib.grid.wilderness.wilderness.
get_new_coordinates
(coordinates, direction)[source]¶ Returns the coordinates of direction applied to the provided coordinates.
- Parameters
coordinates – tuple of (x, y)
direction – a direction string (like “northeast”)
- Returns
tuple – tuple of (x, y) coordinates
-
class
evennia.contrib.grid.wilderness.wilderness.
WildernessScript
(*args, **kwargs)[source]¶ Bases:
evennia.scripts.scripts.DefaultScript
This is the main “handler” for the wilderness system: inside here the coordinates of every item currently inside the wilderness is stored. This script is responsible for creating rooms as needed and storing rooms away into storage when they are not needed anymore.
-
mapprovider
¶ AttributeProperty.
-
itemcoordinates
¶ AttributeProperty.
-
preserve_items
¶ AttributeProperty.
-
at_script_creation
()[source]¶ Only called once, when the script is created. This is a default Evennia hook.
-
is_valid_coordinates
(coordinates)[source]¶ Returns True if coordinates are valid (and can be travelled to). Otherwise returns False
- Parameters
coordinates (tuple) – coordinates as (x, y) tuple
- Returns
bool – True if the coordinates are valid
-
get_obj_coordinates
(obj)[source]¶ Returns the coordinates of obj in the wilderness.
Returns (x, y)
- Parameters
obj (object) – an object inside the wilderness
- Returns
tuple – (x, y) tuple of where obj is located
-
get_objs_at_coordinates
(coordinates)[source]¶ Returns a list of every object at certain coordinates.
Imeplementation detail: this uses a naive iteration through every object inside the wilderness which could cause slow downs when there are a lot of objects in the map.
- Parameters
coordinates (tuple) – a coordinate tuple like (x, y)
- Returns
[Object, ] – list of Objects at coordinates
-
move_obj
(obj, new_coordinates)[source]¶ Moves obj to new coordinates in this wilderness.
- Parameters
obj (object) – the object to move
new_coordinates (tuple) – tuple of (x, y) where to move obj to.
-
at_post_object_leave
(obj)[source]¶ Called after an object left this wilderness map. Used for cleaning up.
- Parameters
obj (object) – the object that left
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶ Bases:
evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned
-
path
= 'evennia.contrib.grid.wilderness.wilderness.WildernessScript'¶
-
typename
= 'WildernessScript'¶
-
-
class
evennia.contrib.grid.wilderness.wilderness.
WildernessRoom
(*args, **kwargs)[source]¶ Bases:
evennia.objects.objects.DefaultRoom
This is a single room inside the wilderness. This room provides a “view” into the wilderness map. When an account moves around, instead of going to another room as with traditional rooms, they stay in the same room but the room itself changes to display another area of the wilderness.
-
property
wilderness
¶ Shortcut property to the wilderness script this room belongs to.
- Returns
WildernessScript – the WildernessScript attached to this room
-
property
location_name
¶ Returns the name of the wilderness at this room’s coordinates.
- Returns
name (str)
-
property
coordinates
¶ Returns the coordinates of this room into the wilderness.
- Returns
tuple –
- (x, y) coordinates of where this room is inside the
wilderness.
-
at_object_receive
(moved_obj, source_location)[source]¶ Called after an object has been moved into this object. This is a default Evennia hook.
- Parameters
moved_obj (Object) – The object moved into this one.
source_location (Object) – Where moved_obj came from.
-
at_object_leave
(moved_obj, target_location, move_type='move', **kwargs)[source]¶ Called just before an object leaves from inside this object. This is a default Evennia hook.
- Parameters
moved_obj (Object) – The object leaving
target_location (Object) – Where moved_obj is going.
-
set_active_coordinates
(new_coordinates, obj)[source]¶ Changes this room to show the wilderness map from other coordinates.
- Parameters
new_coordinates (tuple) – coordinates as tuple of (x, y)
obj (Object) – the object that moved into this room and caused the coordinates to change
-
get_display_name
(looker, **kwargs)[source]¶ Displays the name of the object in a viewer-aware manner. This is a core evennia hook.
- 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 if this user is privileged to control said object and also its coordinates into the wilderness map.
Notes
This function could be extended to change how object names appear to users in character, but be wary. This function does not change an object’s keys or aliases when searching, and is expected to produce something useful for builders.
-
get_display_desc
(looker, **kwargs)[source]¶ Displays the description of the room. This is a core evennia hook.
Allows the room’s description to be customized in an ndb value, avoiding having to write to the database on moving.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶ Bases:
evennia.objects.objects.DefaultRoom.MultipleObjectsReturned
-
path
= 'evennia.contrib.grid.wilderness.wilderness.WildernessRoom'¶
-
typename
= 'WildernessRoom'¶
-
property
-
class
evennia.contrib.grid.wilderness.wilderness.
WildernessExit
(*args, **kwargs)[source]¶ Bases:
evennia.objects.objects.DefaultExit
This is an Exit object used inside a WildernessRoom. Instead of changing the location of an Object traversing through it (like a traditional exit would do) it changes the coordinates of that traversing Object inside the wilderness map.
-
property
wilderness
¶ Shortcut property to the wilderness script.
- Returns
WildernessScript – the WildernessScript attached to this exit’s room
-
property
mapprovider
¶ Shortcut property to the map provider.
- Returns
MapProvider object –
- the mapprovider object used with this
wilderness map.
-
at_traverse_coordinates
(traversing_object, current_coordinates, new_coordinates)[source]¶ Called when an object wants to travel from one place inside the wilderness to another place inside the wilderness.
If this returns True, then the traversing can happen. Otherwise it will be blocked.
This method is similar how the at_traverse works on normal exits.
- Parameters
traversing_object (Object) – The object doing the travelling.
current_coordinates (tuple) – (x, y) coordinates where traversing_object currently is.
new_coordinates (tuple) – (x, y) coordinates of where traversing_object wants to travel to.
- Returns
bool – True if traversing_object is allowed to traverse
-
at_traverse
(traversing_object, target_location)[source]¶ This implements the actual traversal. The traverse lock has already been checked (in the Exit command) at this point.
- Parameters
traversing_object (Object) – Object traversing us.
target_location (Object) – Where target is going.
- Returns
bool – True if the traverse is allowed to happen
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶ Bases:
evennia.objects.objects.DefaultExit.MultipleObjectsReturned
-
path
= 'evennia.contrib.grid.wilderness.wilderness.WildernessExit'¶
-
typename
= 'WildernessExit'¶
-
property
-
class
evennia.contrib.grid.wilderness.wilderness.
WildernessMapProvider
[source]¶ Bases:
object
Default Wilderness Map provider.
This is a simple provider that just creates an infinite large grid area.
-
room_typeclass
¶ alias of
WildernessRoom
-
exit_typeclass
¶ alias of
WildernessExit
-
is_valid_coordinates
(wilderness, coordinates)[source]¶ Returns True if coordinates is valid and can be walked to.
- Parameters
wilderness – the wilderness script
coordinates (tuple) – the coordinates to check as (x, y) tuple.
- Returns
bool – True if the coordinates are valid
-
get_location_name
(coordinates)[source]¶ Returns a name for the position at coordinates.
- Parameters
coordinates (tuple) – the coordinates as (x, y) tuple.
- Returns
name (str)
-
at_prepare_room
(coordinates, caller, room)[source]¶ Called when a room gets activated for certain coordinates. This happens after every object is moved in it. This can be used to set a custom room desc for instance or run other customisations on the room.
- Parameters
coordinates (tuple) – the coordinates as (x, y) where room is located at
caller (Object) – the object that moved into this room
room (WildernessRoom) – the room object that will be used at that wilderness location
Example
An example use of this would to plug in a randomizer to show different descriptions for different coordinates, or place a treasure at a special coordinate.
-