evennia.contrib.mapbuilder

Evennia World Builder

Contribution - Cloud_Keeper 2016

Build a map from a 2D ASCII map.

This is a command which takes two inputs:

≈≈≈≈≈ ≈♣n♣≈ MAP_LEGEND = {(“♣”, “♠”): build_forest, ≈∩▲∩≈ (“∩”, “n”): build_mountains, ≈♠n♠≈ (“▲”): build_temple} ≈≈≈≈≈

A string of ASCII characters representing a map and a dictionary of functions containing build instructions. The characters of the map are iterated over and compared to a list of trigger characters. When a match is found the corresponding function is executed generating the rooms, exits and objects as defined by the users build instructions. If a character is not a match to a provided trigger character (including spaces) it is simply skipped and the process continues.

For instance, the above map represents a temple (▲) amongst mountains (n,∩) in a forest (♣,♠) on an island surrounded by water (≈). Each character on the first line is iterated over but as there is no match with our MAP_LEGEND it is skipped. On the second line it finds “♣” which is a match and so the build_forest function is called. Next the build_mountains function is called and so on until the map is completed. Building instructions are passed the following arguments:

x - The rooms position on the maps x axis y - The rooms position on the maps y axis caller - The account calling the command iteration - The current iterations number (0, 1 or 2) room_dict - A dictionary containing room references returned by build

functions where tuple coordinates are the keys (x, y). ie room_dict[(2, 2)] will return the temple room above.

Building functions should return the room they create. By default these rooms are used to create exits between valid adjacent rooms to the north, south, east and west directions. This behaviour can turned off with the use of switch arguments. In addition to turning off automatic exit generation the switches allow the map to be iterated over a number of times. This is important for something like custom exit building. Exits require a reference to both the exits location and the exits destination. During the first iteration it is possible that an exit is created pointing towards a destination that has not yet been created resulting in error. By iterating over the map twice the rooms can be created on the first iteration and room reliant code can be be used on the second iteration. The iteration number and a dictionary of references to rooms previously created is passed to the build commands.

Use by importing and including the command in your default_cmdsets module. For example:

# mygame/commands/default_cmdsets.py

from evennia.contrib import mapbuilder

self.add(mapbuilder.CmdMapBuilder())

You then call the command in-game using the path to the MAP and MAP_LEGEND vars The path you provide is relative to the evennia or mygame folder.

Usage:

@mapbuilder[/switch] <path.to.file.MAPNAME> <path.to.file.MAP_LEGEND>

Switches:

one - execute build instructions once without automatic exit creation. two - execute build instructions twice without automatic exit creation.

Example

@mapbuilder world.gamemap.MAP world.maplegend.MAP_LEGEND @mapbuilder evennia.contrib.mapbuilder.EXAMPLE1_MAP EXAMPLE1_LEGEND @mapbuilder/two evennia.contrib.mapbuilder.EXAMPLE2_MAP EXAMPLE2_LEGEND

(Legend path defaults to map path)

Below are two examples showcasing the use of automatic exit generation and custom exit generation. Whilst located, and can be used, from this module for convenience The below example code should be in mymap.py in mygame/world.

evennia.contrib.mapbuilder.example1_build_forest(x, y, **kwargs)[source]

A basic example of build instructions. Make sure to include **kwargs in the arguments and return an instance of the room for exit generation.

evennia.contrib.mapbuilder.example1_build_mountains(x, y, **kwargs)[source]

A room that is a little more advanced

evennia.contrib.mapbuilder.example1_build_temple(x, y, **kwargs)[source]

A unique room that does not need to be as general

evennia.contrib.mapbuilder.example2_build_forest(x, y, **kwargs)[source]

A basic room

evennia.contrib.mapbuilder.example2_build_verticle_exit(x, y, **kwargs)[source]

Creates two exits to and from the two rooms north and south.

evennia.contrib.mapbuilder.example2_build_horizontal_exit(x, y, **kwargs)[source]

Creates two exits to and from the two rooms east and west.

evennia.contrib.mapbuilder.build_map(caller, game_map, legend, iterations=1, build_exits=True)[source]

Receives the fetched map and legend vars provided by the player.

Parameters
  • caller (Object) – The creator of the map.

  • game_map (str) – An ASCII map string.

  • legend (dict) – Mapping of map symbols to object types.

  • iterations (int) – The number of iteration passes.

  • build_exits (bool) – Create exits between new rooms.

Notes

The map is iterated over character by character, comparing it to the trigger characters in the legend var and executing the build instructions on finding a match. The map is iterated over according to the iterations value and exits are optionally generated between adjacent rooms according to the build_exits value.

class evennia.contrib.mapbuilder.CmdMapBuilder(**kwargs)[source]

Bases: evennia.commands.default.muxcommand.MuxCommand

Build a map from a 2D ASCII map.

Usage:

@mapbuilder[/switch] <path.to.file.MAPNAME> <path.to.file.MAP_LEGEND>

Switches:

one - execute build instructions once without automatic exit creation two - execute build instructions twice without automatic exit creation

Example

@mapbuilder world.gamemap.MAP world.maplegend.MAP_LEGEND @mapbuilder evennia.contrib.mapbuilder.EXAMPLE1_MAP EXAMPLE1_LEGEND @mapbuilder/two evennia.contrib.mapbuilder.EXAMPLE2_MAP EXAMPLE2_LEGEND

(Legend path defaults to map path)

This is a command which takes two inputs: A string of ASCII characters representing a map and a dictionary of functions containing build instructions. The characters of the map are iterated over and compared to a list of trigger characters. When a match is found the corresponding function is executed generating the rooms, exits and objects as defined by the users build instructions. If a character is not a match to a provided trigger character (including spaces) it is simply skipped and the process continues. By default exits are automatically generated but is turned off by switches which also determines how many times the map is iterated over.

key = '@mapbuilder'
aliases = ['@buildmap']
locks = 'cmd:superuser()'
help_category = 'building'
func()[source]

Starts the processor.

lock_storage = 'cmd:superuser()'
search_index_entry = {'aliases': '@buildmap', 'category': 'building', 'key': '@mapbuilder', 'tags': '', 'text': '\n Build a map from a 2D ASCII map.\n\n Usage:\n @mapbuilder[/switch] <path.to.file.MAPNAME> <path.to.file.MAP_LEGEND>\n\n Switches:\n one - execute build instructions once without automatic exit creation\n two - execute build instructions twice without automatic exit creation\n\n Example:\n @mapbuilder world.gamemap.MAP world.maplegend.MAP_LEGEND\n @mapbuilder evennia.contrib.mapbuilder.EXAMPLE1_MAP EXAMPLE1_LEGEND\n @mapbuilder/two evennia.contrib.mapbuilder.EXAMPLE2_MAP EXAMPLE2_LEGEND\n (Legend path defaults to map path)\n\n This is a command which takes two inputs:\n A string of ASCII characters representing a map and a dictionary of\n functions containing build instructions. The characters of the map are\n iterated over and compared to a list of trigger characters. When a match\n is found the corresponding function is executed generating the rooms,\n exits and objects as defined by the users build instructions. If a\n character is not a match to a provided trigger character (including spaces)\n it is simply skipped and the process continues. By default exits are\n automatically generated but is turned off by switches which also determines\n how many times the map is iterated over.\n '}