diff --git a/docs/source/Contribs/XYZGrid.md b/docs/source/Contribs/XYZGrid.md
index 28837f0599..c1b4bc73f0 100644
--- a/docs/source/Contribs/XYZGrid.md
+++ b/docs/source/Contribs/XYZGrid.md
@@ -1,255 +1,1243 @@
 # XYZGrid contribution
 
-This contrib adds a 'coordinate grid' to the game, with rooms that are aware of
-their X, Y, Z coordinate. It also adds shortest-path pathfinding, auto-stepping
-and map visualization.
+```versionadded:: 1.0
+```
 
-The system consists of 2D (XY) maps, where the Z
-coordinate is the name of the map. Each map can be linked together.
+This optional contrib adds a 'coordinate grid' to Evennia. It allows for
+defining the grid as simple ascii maps that are then spawned into rooms that are
+aware of their X, Y, Z coordinates. The system includes shortest-path
+pathfinding, auto-stepping and in-game map visualization (with visibility
+range).
 
-The grid supports 8 cardinal directions (north, northeast, east etc) as well as
-a 'fake' up/down directions (you enter up/down in-game but are actually moving to
-a different XY position on the same map).
-
-An (XY) map is defined as a Python string, using a simple syntax;
 
 ```
-#-#-#-#      #
-|  /         d
-#-#          |   #
-   \         u   |\
-o---#--------#---+-#-#
-|            ^   |/
-|            |   #
-v            |
-#-#-#-#-#----#
-    |x|x|
-    #-#-#-#
+#-#-#-#   #
+|  /      d
+#-#       |   #
+   \      u   |\
+o---#-----#---+-#-#
+|         ^   |/
+|         |   #
+v         |    \
+#-#-#-#-#-# #---#
+    |x|x|     /
+    #-#-#    #-
+```
+
+```
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                                     #---#
+                                    /
+                                   @-
+-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dungeon Entrance
+To the east, a narrow opening leads into darkness.
+Exits: northeast and east
 
 ```
 
-(descriptions of components are found below).
 
-Basically the system will parse this string together with a _legend_ (a mapping
-describing how each symbol of the map behaves) to generate a representation of
-the map that can then be _spawned_ into actual rooms and exits. The map can also
-contain links to other maps this (map transitions).
-
-The generation and maintenance of the map topology (how rooms are placed and
-relate to each other) are maintained entirely from outside of the game.
 
 ## Installation
 
 1. Import and add the `evennia.contrib.commands.XYZGridCmdSet` to the
    `CharacterCmdset` cmdset in `mygame/commands.default_cmds.py`. Reload
-   the server. This makes the `map`, `goto/path` and modified `teleport`  and
+   the server. This makes the `map`, `goto/path` and the modified `teleport` and
    `open` commands available in-game.
-2. Edit `mygame/server/conf/settings.py` and set
+2. Edit `mygame/server/conf/settings.py` and add
 
-        EXTRA_LAUNCHER_COMMANDS['xyzgrid'] = 'evennia.contrib.launchcmd.xyzcommand'
+       EXTRA_LAUNCHER_COMMANDS['xyzgrid'] = 'evennia.contrib.launchcmd.xyzcommand'
 
-3. Run the new `evennia xyzgrid help` for instructions on how to build the grid.
+   and
 
-## Example usage
+       PROTOTYPE_MODULES += [’evennia.contrib.xyzgrid.prototypes’]
 
-After installation, do the following (from your command line, where the
-`evennia` command is available) to install an example grid:
+   This will add the new ability to enter `evennia xyzgrid <option>` on the
+   command line.  It will also make the `xyz_room` and `xyz_exit` prototypes
+   available for use as prototype-parents when spawning the grid.
+3. Run `evennia xyzgrid help` for available options.
 
-    evennia xyzgrid init
-    evennia xyzgrid add evennia.contrib.xyzgrid.map_example
-    evennia xyzgrid list
-    evennia xyzgrid show "the large tree"
-    evennia xyzgrid show "the small cave"
-    evennia xyzgrid build
-    evennia reload
+## Overview
 
-(remember to reload the server after build operations).
+The grid contrib consists of multiple components.
 
-Now you can log into the
-server and do `teleport (3,0,the large tree)` to teleport into the map.
+1. The `XYMap` - This class parses modules with special _Map strings_
+   and _Map legends_ into one Python object. It has helpers for pathfinding and
+   visual-range handling.
+2. The `XYZGrid` - This is a singleton [Script](../Components/Scripts) that
+   stores all `XYMaps` in the game. It is the central point for managing the 'grid'
+   of the game.
+3. `XYZRoom` and `XYZExit`are custom typeclasses that use
+   [Tags](../Components/Tags)
+   to know which X,Y,Z coordinate they are located at. The `XYZGrid` is
+   abstract until it is used to _spawn_ these database entities into
+   something you can actually interract with in the game. The `XYZRoom`
+   typeclass is using its `return_appearance` hook to display the in-game map.
+4. Custom _Commands_ have been added for interacting with XYZ-aware locations.
+5. A new custom _Launcher command_, `evennia xyzgrid <options>` is used to
+   manage the grid from the terminal (no game login is needed).
 
-You can use `open togrid = (3, 0, the large tree)` to open a permanent (one-way)
-exit from your current location into the grid. To make a way back to a non-grid
-location just stand in a grid room and open a new exit out of it:
-`open tolimbo = #2`.
+We'll start exploring these components with an example.
 
-Try `goto view` to go to the top of the tree and `goto dungeon` to go down to
-the dungeon entrance at the bottom of the tree.
+## First example usage
 
-## A note on 3D = 2D + 1D
+After installation, do the following from your command line (where the
+`evennia` command is available):
 
-Since actual 3D movement usually is impractical to visualize in text, most
-action in this contrib takes place on 2-dimenstional XY-planes we refer to as
-_Maps_.  Changing Z-coordinate means moving to another Map. Maps does not need
-be the same size as one another and there is no (enforced) concept of moving
-'up' or 'down' between maps - instead you basically 'teleport' between them,
-which means you can have your characters end up anywhere you want in the next
-map, regardless of which XY coordinate they were leaving from.
+    $ evennia xyzgrid init
 
-If you really want an actual 3D coordinate system, you could make all maps the
-same size and name them `0`, `1`, `2` etc. But most users will want to just
-treat each map as a location, and name the "Z-coordinate" things like `Dungeon
-of Doom`, `The ice queen's palace` or `City of Blackhaven`.
+use `evennia xyzgrid help` to see all options)
+This will create a new `XYZGrid` [Script](../Components/Scripts) if one didn't already exist.
+The `evennia xyzgrid` is a custom launch option added only for this contrib.
 
-Whereas the included rooms and exits can be used for 'true' 3D movement, the more
-advanced tools like pathfinding will only operate within each XY `Map`.
+The xyzgrid-contrib comes with a full grid example. Let's add it:
 
-## Components of the XYgrid
+    $ evennia xyzgrid add evennia.contrib.xyzgrid.example
 
-1. The Map String - describes the topology of a single
-   map/location/Z-coordinate.
-2. The Map Legend - describes how to parse each symbol in the map string to a
-   topological relation, such as 'a room' or 'a two-way link east-west'.
-3. The XYMap - combines the Map String and Legend into a parsed object with
-   pathfinding and visual-range handling.
-4. The MultiMap - tracks multiple maps
-5. Rooms, Exits and Prototypes - custom Typeclasses that understands XYZ coordinates.
-   The prototype describes how to build a database-entity from a given
-   Map Legend component.
-6. The Grid - the combination of prototype-built rooms/exits with Maps for
-   pathfinding and visualization. This is kept in-sync with changes to Map
-   Strings.
+You can now list the maps on your grid:
+
+    $ evennia xyzgrid list
+
+You'll find there are two new maps added. You can find a lot of extra info
+about each map with the `show` subcommand:
+
+    $ evennia xyzgrid show "the large tree"
+    $ evennia xyzgrid show "the small cave"
+
+If you want to peek at how the grid's code, open
+[evennia/contrib/xyzgrid/example.py](api:evennia.contrib.xyzgrid.example).
+(We'll explain the details in later sections).
+
+So far the grid is 'abstract' and has no actual in-game presence. Let's
+spawn actual rooms/exits from it. This will take a little while.
+
+    $ evennia xyzgrid spawn
+
+This will take prototypes stored with each map's _map legend_ and use that
+to build XYZ-aware rooms there. It will also parse all links to make suitable
+exits between locations. You should rerun this command if you ever modify the
+layout/prototypes of your grid. Running it multiple times is safe.
+
+    $ evennia reload
+
+(or `evennia start` if server was not running). This is important to do after
+every spawning operation, since the `evennia xyzgrid` operates outside of the
+regular evennia process. Reloading makes sure all caches are refreshed.
+
+Now you can log into the server. Some new commands should be available to you.
+
+    teleport (3,0,the large tree)
+
+The `teleport` command now accepts an optional (X, Y, Z) coordinate. Teleporting
+to a room-name or `#dbref` still works the same. This will teleport you onto the
+grid. You should see a map-display. Try walking around.
+
+    map
+
+This new builder-only command shows the current map in its full form (also
+showing 'invisible' markers usually not visible to users.
+
+    teleport (3, 0)
+
+Once you are in a grid-room, you can teleport to another grid room _on the same
+map_ without specifying the Z coordinate/map name.
+
+You can use `open` to make an exit back to the 'non-grid', but remember that you
+mustn't use a cardinal direction to do so - if you do, the `evennia xyzgrid spawn`
+will likely remove it next time you run it.
+
+    open To limbo;limbo = #2
+    limbo
+
+You are back in Limbo (which doesn't know anything about XYZ coordinates). You
+can however make a permanent link back into the gridmap:
+
+    open To grid;grid = (3,0,the large tree)
+    grid
+
+This is how you link non-grid and grid locations together. You could for example
+embed a house 'inside' the grid this way.
+
+the `(3,0,the large tree)` is a 'Dungeon entrance'. If you walk east you'll
+_transition_ into "the small cave" map. This is a small underground dungeon
+with limited visibility. Go back outside again (back on "the large tree" map).
+
+    path view
+
+This finds the shortest path to the "A gorgeous view" room, high up in the large
+tree. If you have color in your client, you should see the start of the path
+visualized in yellow.
+
+    goto view
+
+This will start auto-walking you to the view. On the way you'll both move up
+into the tree as well as traverse an in-map teleporter. Use `goto` on its own
+to abort the auto-walk.
+
+When you are done exploring, open the terminal (outside the game) again and
+remove everything:
+
+    $ evennia xyzgrid delete
+
+You will be asked to confirm the deletion of the grid and unloading of the
+XYZGrid script. Reload the server afterwards. If you were on a map that was
+deleted you will have been moved back to your home location.
+
+## Defining an XYMap
+
+For a module to be suitable to pass to `evennia xyzgrid add <module>`, the
+module must contain one of the following variables:
+
+- `XYMAP_DATA` - a dict containing data that fully defines the XYMap
+- `XYMAP_DATA_LIST` - a list of `XYMAP_DATA` dicts. If this exists, it will take
+  precedence. This allows for storing multiple maps in one module.
 
 
-### The Map string
-
-A `Map` represents one Z-coordinate/location. The Map starts out as an text
-string visually laying out one 2D map (so one Z-position). It is created
-manually by the developer/builder outside of the game. The string-map
-has one character per node(room) and descibe how rooms link together. Each
-symbol is linked to a particular abstract Python class which helps parse
-the map-string. While the contrib comes with a large number of nodes and links,
-one can also make one's own.
+The `XYMAP_DATA` dict has the following form:
 
 ```
-MAP = r"""
+XYMAP_DATA = {
+    "zcoord": <str>
+    "map": <str>,
+    "legend": <dict, optional>,
+    "prototypes": <dict, optional>
+    "options": <dict, optional>
+}
 
-+ 0 1 2 3
+```
 
-3 #-#---o
-    v   |
-2   #-# |
-    |x| ^
-1   #-#-#
-   / \
-0 #   #d#
+- `"zcoord"` (str): The Z-coordinate/map name of the map.
+- `"map"` (str): A _Map string_ describing the topology of the map.
+- `"legend"` (dict, optional): Maps each symbol on the map to Python code. This
+  dict can be left out or only partially filled - any symbol not specified will
+  instead use the default legend from the contrib.
+- `"prototypes"` (dict, optional): This is a dict that maps map-coordinates
+  to custom prototype overrides. This is used when spawning the map into
+  actual rooms/exits.
+- `"options"` (dict, optional): These are passed into the `return_appearance`
+  hook of the room and allows for customizing how a map should be displayed,
+  how pathfinding should work etc.
 
-+ 0 1 2 3
+Here's a minimal example of the whole setup:
+
+```
+# In, say, a module gamedir/world/mymap.py
+
+MAPSTR = r"""
+
++ 0 1 2
+
+2 #-#-#
+     /
+1 #-#
+  |  \
+0 #---#
+
++ 0 1 2
+
+
+"""
+# use only defaults
+LEGEND = {}
+
+# tweak only one room. The 'xyz_room/exit' parents are made available
+# by adding the xyzgrid prototypes to settings during installation.
+# the '*' are wildcards and allows for giving defaults on this map.
+PROTOTYPES = {
+    (0, 0): {
+	"prototype_parent": "xyz_room",
+	"key": "A nice glade",
+        "desc": "Sun shines through the branches above.}
+    (0, 0, 'e'): {
+	"prototype_parent": "xyz_exit",
+	"desc": "A quiet path through the foilage"
+    }
+    ('*', '*'): {
+	"prototype_parent": "xyz_room",
+	"key": "In a bright forest",
+	"desc": "There is green all around."
+    },
+    ('*', '*', '*'): {
+	"prototype_parent": "xyz_exit",
+	"desc": "The path leads further into the forest."
+}
+
+# collect all info for this one map
+XYMAP_DATA = {
+    "zcoord": "mymap"  # important!
+    "map": MAPSTR,
+    "legend": LEGEND,
+    "prototypes": PROTOTYPES,
+    "options": {}
+}
+
+# this can be skipped if there is only one map in module
+XYMAP_DATA_LIST = [
+    XYMAP_DATA
+]
+
+```
+
+The above map would be added to the grid with
+
+    $ evennia xyzgrid add world.mymap
+
+In the following sections we'll discuss each component in turn.
+
+### The Zcoord
+
+Each XYMap on the grid has a Z-coordinate which usually can be treated just as the
+name of the map. This is a string that must be unique across the entire grid.
+It is added as the key 'zcoord' to `XYMAP_DATA`.
+
+Actual 3D movement is usually impractical in a text-based game, so all movements
+and pathfinding etc happens within each XYMap (up/down is 'faked' within the XY
+plane). Even for the most hardcore of sci-fi space game, moving on a 2D plane
+usually makes it much easier for players than to attempt to have them visualize
+actual 3D movements.
+
+If you really wanted an actual 3D coordinate system, you could theoretically
+make all maps the same size and name them `0`, `1`, `2` etc. But even then, you
+could not freely move up/down between every point (a special Transitional Node
+is required as outlined below). Also pathfinding will only work per-XYMap.
+
+Most users will want to just treat each map as a location, and name the
+"Z-coordinate" things like `Dungeon of Doom`, `The ice queen's palace` or `City
+of Blackhaven`.
+
+### Map String
+
+The creation of a new map starts with a _Map string_. This allows you to 'draw'
+your map, describing and how rooms are positioned in an X,Y coordinate system.
+It is added to `XYMAP_DATA` with the key 'map'.
+
+```
+MAPSTR = r"""
+
++ 0 1 2
+
+2 #-#-#
+     /
+1 #-#
+  |  \
+0 #---#
+
++ 0 1 2
 
 """
 
 ```
-Above, only the two `+`-characters in the upper-left and bottom-left are
-required to mark the start of grid area - the numbered axes are optional but
-recommended for readability! Note that the coordinate system has (0, 0) in the
-bottom left - this means that +Y movement is 'upwards' in the string as
-expected.
 
-### Map Legend
+On the coordinate axes, only the two `+` are significant - the numbers are
+_optional_, so this is equivalent:
 
-The map legend is a mapping of one-character symbols to Python classes
-representing _Nodes_ (usually equivalent to in-game rooms) or _Links_ (which
-usually start as an Exit, but the length of the link only describes the
-target-destination and has no in-game representation otherwise). These 'map
-components' are Python classes that can be inherited and modified as needed.
+```
+MAPSTR = r"""
 
-The default legend support nearly 20 different symbols, including:
++
 
-- Nodes (rooms) are always on XY coordinates (not between) and
-- 8 two-way cardinal directions (n, ne etc)
-- up/down - this is a 'fake' up-down using XY coordinates for ease of
-  visualization (the exit is just called 'up' or 'down', unless you display the
-  actual coordinate to the user they'll never know the difference).
-- One-way links in 4 cardinal directions (not because it's hard to add more,
-  but because there are no obvious ASCII characters for the diaginal movements ...)
-- Multi-step links are by default considered as one step in-game.
-- 'Invisible' symbols that are used to block or act as deterrent for the
-  pathfinder to use certain routes (like a hidden entrance you should be
-  auto-pathing through).
-- 'Points of interest' are nodes or links where the auto-stepper will always
-  stop, even if it can see what's behind. This is great for places where you
-  expect to have a door or a guard (which are not represented on the map).
-- Teleporter-links, for jumping from one edge of the map to the other without
-  having to draw an actual link across. Good for maps that 'wrap around'.
-- Transitional links between maps/locations/Z-positions. Note that pathfinding
-  will _not_ work across map transitions.
+  #-#-#
+     /
+  #-#
+  | \
+  #---#
 
-### Map
++
 
-All `Map strings` are combined with their `Map Legends` to be parsed into a `Map`
-object. The `Map` object has the relations between all nodes stored in a very
-efficient matrix for quick lookup. This allows for:
+"""
+```
+> Even though it's optional, it's highly recommended that you add numbers to
+> your axes - if only for your own sanity.
 
-- Shortest-path finding. The shortest-path from one coordinate to another
-  is calculated using an optimized implementation of the
+The coordinate area starts _two spaces to the right_ and _two spaces
+below/above_ the mandatory `+` signs (which marks the corners of the map area).
+Origo `(0,0)` is in the bottom left (so X-coordinate increases to the right and
+Y-coordinate increases towards the top). There is no limit to how high/wide the
+map can be, but splitting a large world into multiple maps can make it easier
+to organize.
+
+Position is important on the grid. Full coordinates are placed on every _second_
+space along all axes. Between these 'full' coordinates are `.5` coordinates.
+Note that there are _no_ `.5` coordinates spawned in-game; they are only used
+in the map string to have space to describe how rooms/nodes link to one another.
+
+    + 0 1 2 3 4 5
+
+    4           E
+       B
+    3
+
+    2         D
+
+    1    C
+
+    0 A
+
+    + 0 1 2 3 4 5
+
+- `A` is at origo, `(0, 0)` (a 'full' coordinate)
+- `B` is at `(0.5, 3.5)`
+- `C` is at `(1.5, 1)`
+- `D` is at `(4, 2)` (a 'full' coordinate).
+- `E` is the top-right corner of the map, at `(5, 4)` (a 'full' coordinate)
+
+The map string consists of two main classes of entities - _nodes_ and _links_.
+- A _node_ usually represents a _room_ in-game (but not always). Nodes must
+  _always_ be placed on a 'full' coordinate.
+- A _link_ describes a connection between two nodes. In-game, links are usuallyj
+  represented by _exits_. A link can be placed
+  anywhere in the coordinate space (both on full and 0.5 coordinates). Multiple
+  links are often _chained_ together, but the chain must always end in nodes
+  on both sides.
+
+> Even though a link-chain may consist of several steps, like `#-----#`,
+> in-game it will still only represent one 'step' (e.g. you go 'east' only once
+> to move from leftmost to the rightmost node/room).
+
+
+### Map legend
+
+There can be many different types of _nodes_ and _links_.  Whereas the map
+string describes where they are located. The _Map Legend_ connects each symbol
+on the map to Python code.
+
+The legend is a `dict` added as the key 'legend' to the `XYMAP_DATA` dict. It is
+optional, and any symbol not explicitly given in your legend will fall back to
+its value in the default legend found in
+`evennia.contrib.xyzgrid.xymap_legend`).
+
+- [MapNode](api:evennia.contrib.xyzgrid.xymap_legend#MapNode) is the base
+  class for all nodes.
+- [MapLink](api:evennia.contrib.xyzgrid.xymap_legend#MapLink) is the base
+  class for all links.
+
+As the _Map String_ is parsed, each found symbol is looked up in the legend and
+initialized into the corresponding MapNode/Link instance.
+
+#### Important node/link properties
+
+These are relevant if you want to customize the map. The contrib already comes
+with a full set of map elements that use these properties in various ways
+(described in the next section).
+
+Some useful properties of the
+[MapNode](api:evennia.contrib.xyzgrid.xymap_legend#MapNode)
+class (see class doc for hook methods):
+
+- `symbol` (str) - The character to parse from the map into this node. By default this
+  is `'#'` and _must_ be a single character (with the exception of `\\` that must
+  be escaped to be used). Whatever this value defaults to, it is replaced at
+  run-time by the symbol used in the legend-dict.
+- `display_symbol` (str or `None`) - This is what is used to visualize this node
+  in-game. This symbol must still only have a visual size of 1, but you could e.g.
+  use some fancy unicode character (be aware of encodings to different clients
+  though) or, commonly, add color tags around it. The `.get_display_symbol`
+  of this class can be customized to generate this dynamically; by default it
+  just returns `.display_symbol`. If set to `None` (default), the `symbol` is
+  used.
+- `interrupt_path` (bool): If this is set, the shortest-path algorithm will
+  include this node normally, but the auto-stepper will stop when reaching it,
+  even if not having reached its target yet. This is useful for marking 'points of
+  interest' along a route, or places where you are not expected to be able to
+  continue without some
+  further in-game action not covered by the map (such as a guard or locked gate
+  etc).
+- `prototype` (dict) - The default `prototype` dict to use for reproducing this
+  map component on the game grid. This is used if not overridden specifically
+  for this coordinate in the "prototype" dict of `XYMAP_DATA`.. If this is not
+  given, nothing will be spawned for this coordinate (a 'virtual' node can be
+  useful for various reasons, mostly map-transitions).
+
+Some useful properties of the
+[MapLink](api:evennia.contrib.xyzgrid.xymap_legend#MapLink)
+class (see class doc for hook methods):
+
+- `symbol` (str) - The character to parse from the map into this node. This must
+  be a single character, with the exception of `\\`. This will be replaced
+  at run-time by the symbol used in the legend-dict.
+- `display_symbol` (str or None)  - This is what is used to visualize this node
+  later. This symbol must still only have a visual size of 1, but you could e.g.
+  use some fancy unicode character (be aware of encodings to different clients
+  though) or, commonly, add color tags around it. For further customization, the
+  `.get_display_symbol` can be used.
+- `default_weight` (int) - Each link direction covered by this link can have its
+  separate weight (used for pathfinding). This is used if none specific weight
+  is specified in a particular link direction.  This value must be >= 1, and can
+  be higher than 1 if a link should be less favored.
+- `directions` (dict) - this specifies which from which link edge to which other
+  link-edge this link is connected; A link connecting the link's sw edge to its
+  easted edge would be written as `{'sw': 'e'}` and read 'connects from southwest
+  to east' This ONLY takes cardinal directions (not up/down). Note that if you
+  want the link to go both ways, also the inverse (east to southwest) must be
+  added.
+- `weights (dict)` This maps a link's start direction to a weight. So for the
+  `{'sw': 'e'}` link, a weight would be given as `{'sw': 2}`. If not given, a
+  link will use the `default_weight`.
+- `average_long_link_weights` (bool): This applies to the *first* link out of a
+  node only.  When tracing links to another node, multiple links could be
+  involved, each with a weight.  So for a link chain with default weights, `#---#`
+  would give a total weight of 3. With this setting (default), the weight will
+  be (1+1+1) / 3 = 1.  That is, for evenly weighted links, the length of the
+  link-chain doesn't matter (this is usually what makes most sense).
+- `direction_aliases` (dict): When displaying a direction during pathfinding,
+  one may want to display a different 'direction' than the cardinal on-map one.
+  For example 'up' may be visualized on the map as a 'n' movement, but the found
+  path over this link should show as 'u'. In that case, the alias would be
+  `{'n': 'u'}`.
+- `multilink` (bool): If set, this link accepts links from all directions. It
+  will usually use a custom `.get_direction` method to determine what these are
+  based on surrounding topology. This setting is necessary to avoid infinite
+  loops when such multilinks are next to each other.
+- `interrupt_path` (bool): If set, a shortest-path solution will include this
+  link as normal, but auto-stepper will stop short of actually moving past this
+  link.
+- `prototype` (dict) - The default `prototype` dict to use for reproducing this
+  map component on the game grid. This is only relevant for the *first* link out
+  of a Node (the continuation of the link is only used to determine its
+  destination). This can be overridden on a per-direction basis.
+- `spawn_aliases` (dict): A mapping `{direction: (key, alias, alias, ...),}`to
+  use when spawning actual exits from this link. If not given, a sane set of
+  defaults (`n=(north, n)` etc) will be used. This is required if you use any
+  custom directions outside of the cardinal directions + up/down. The exit's key
+  (useful for auto-walk) is usually retrieved by calling
+  `node.get_exit_spawn_name(direction)`
+
+Below is an example that changes the map's nodes to show up as red
+(maybe for a lava map?):
+
+```
+from evennia.contrib.xyzgrid import xymap_legend
+
+class RedMapNode(xymap_legend.MapNode):
+    display_symbol = "|r#|n"
+
+
+LEGEND = {
+   '#': RedMapNode
+}
+
+```
+
+#### Default Legend
+
+
+Below is the default map legend. The `symbol` is what should be put in the Map
+string. It must always be a single character. The `display-symbol` is what is
+actually visualized when displaying the map to players in-game. This could have
+colors etc. All classes are found in `evennia.contrib.xyzgrid.xymap_legend` and
+their names are included to make it easy to know what to override.
+
+```eval_rst
+=============  ==============  ====  ===================  =========================================
+symbol         display-symbol  type  class                description
+=============  ==============  ====  ===================  =========================================
+#              #               node  `BasicMapNode`       A basic node/room.
+T                              node  `MapTransitionNode`  Transition-target for links between maps
+                                                          (see below)
+I (letter I)   #               node  `InterruptMapNode`   Point of interest, auto-step will always
+                                                          stop here (see below).
+\|             \|              link  `NSMapLink`          North-South two-way
+\-             \-              link  `EWMapLink`          East-West two-way
+/              /               link  `NESWMapLink`        NorthEast-SouthWest two-way
+\\             \\              link  `SENWMapLink`        NorthWest two-way
+u              u               link  `UpMapLink`          Up, one or two-way (see below)
+d              d               link  `DownMapLink`        Down, one or two-way (see below)
+x              x               link  `CrossMapLink`       SW-NE and SE-NW two-way
+\+             \+              link  `PlusMapLink`        Crossing N-S and E-W two-way
+v              v               link  `NSOneWayMapLink`    North-South one-way
+^              ^               link  `SNOneWayMapLink`    South-North one-way
+<              <               link  `EWOneWayMapLink`    East-West one-way
+>              >               link  `WEOneWayMapLink`    West-East one-way
+o              o               link  `RouterMapLink`      Routerlink, used for making link 'knees'
+                                                          and non-orthogonal crosses (see below)
+b              (varies)        link  `BlockedMapLink`     Block pathfinder from using this link.
+                                                          Will appear as logically placed normal
+                                                          link (see below).
+i              (varies)        link  `InterruptMapLink`   Interrupt-link; auto-step will never
+                                                          cross this link (must move manually, see
+                                                          below)
+t                              link  `TeleporterMapLink`  Inter-map teleporter; will teleport to
+                                                          same-symbol teleporter on the same map.
+                                                          (see below)
+=============  ==============  ====  ===================  =========================================
+
+```
+
+
+
+#### Map Nodes
+
+The basic map node (`#`) usually represents a 'room' in the game world. Links
+can connect to the node from any of the 8 cardinal directions, but since nodes
+must _only_ exist on full coordinates, they can never appear directly next to
+each other.
+
+    \|/
+    -#-
+    /|\
+
+    ##     invalid!
+
+All links or link-chains _must_ end in nodes on both sides.
+
+
+    #-#-----#
+
+    #-#-----   invalid!
+
+#### One-way links
+
+`>`,`<`, `v`, `^` are used to indicate one-way links. These indicators should
+either be _first_ or _last_ in a link chain (think of them as arrows):
+
+    #----->#
+    #>-----#
+
+These two are equivalent, but the first one is arguably easier to read. It is also
+faster to parse since the parser on the rightmost node immediately sees that the
+link in that direction is impassable from that direction.
+
+> Note that there are no one-way equivalents to the `\` and `/` directions. This
+> is not because it can't be done but because there are no obvious ASCII
+> characters to represent diagonal arrows. If you want them, it's easy enough to
+> subclass the existing one-way map-legend to add one-way versions of diagonal
+> movement as well.
+
+#### Up- and Down-links
+
+Links like `u` and `d` don't have a clear indicator which directions they
+connect (unlike e.g. `|` and `-`).
+
+So placing them (and many similar types of map elements) requires that the
+directions are visually clear. For example, multiple links cannot connect to the
+up-down links (it'd be unclear which leads where) and if adjacent to a node, the
+link will prioritize connecting to the node. Here are some examples:
+
+        #
+        u     - moving up in BOTH directions will bring you to the other node (two-way)
+        #
+
+        #
+        | - one-way up from the lower node to the upper
+        u
+        #
+
+        #
+        d     - one-way up, one-way down again (expected up/down behavior)
+        u
+        #
+
+        #u#
+        u    - invalid since top-left node has two 'up' directions to go to
+        #
+
+        #     |
+        u# or u-   - invalid since the direction of u is unclear
+        #     |
+
+
+#### Interrupt-nodes
+
+An interrupt-node (`I`, `InterruptMapNode`) is a node that acts like any other
+node except it is considered a 'point of interest' and the auto-walk of the
+`goto` command will always stop auto-stepping at this location.
+
+	#-#-I-#-#
+
+So if auto-walking from left to right, the auto-walk will correctly map a path
+to the end room, but will always stop at the `I` node. If the user _starts_ from
+the `I` room, they will move away from it without interruption (so you can
+manually run the `goto` again to resume the auto-step).
+
+The use of this room is to anticipate blocks not covered by the map. For example
+there could be a guard standing in this room that will arrest you unless you
+show them the right paperwork - trying to auto-walk past them would be bad!
+
+By default, this node looks just like a normal `#` to the player.
+
+#### Interrupt-links
+
+The interrupt-link (`i`, `InterruptMapLink`) is equivalent to the
+`InterruptMapNode` except it applies to a link. While the pathfinder will
+correctly trace a path to the other side, the auto-stepper will never cross an
+interrupting link - you have to do so 'manually'. Similarly to up/down links,
+the InterruptMapLink must be placed so that its direction is un-ambiguous (with
+a priority of linking to nearby nodes).
+
+	#-#-#i#-#
+
+When pathfinding from left to right, the pathfinder will find the end room just
+fine, but when auto-stepping, it will always stop at the node just to the left
+of the `i` link. Rerunning `goto` will not matter.
+
+This is useful for automatically handle in-game blocks not part of the map.
+An example would be a locked door - rather than having the auto-stepper trying
+to walk accross the door exit (and failing), it should stop and let the user
+cross the threshold manually before they can continue.
+
+Same as for interrupt-nodes, the interrupt-link looks like the expected link to the user
+(so in the above example, it would show as `-`).
+
+#### Blocked links
+
+Blockers (`b`, `BlockedMapLink`) indicates a route that the pathfinder should not use. The
+pathfinder will treat it as impassable even though it will be spawned as a
+normal exit in-game.
+
+
+	#-#-#b#-#
+
+There is no way to auto-step from left to right because the pathfinder will
+treat the `b` (block) as if there was no link there (technically it sets the
+link's `weight` to a very high number). The player will need to auto-walk to the
+room just to the left of the block, manually step over the block and then
+continue from there.
+
+This is useful both for actual blocks (maybe the room is full of rubble?) and in
+order to avoid players auto-walking into hidden areas or finding the way out of
+a labyrinth etc. Just hide the labyrinth's exit behind a block and `goto exit`
+will not work (admittedly one may want to turn off pathfinding altogether on
+such maps).
+
+
+#### Router-links
+
+Routers (`o`, `RouterMapLink`) allow for connecting nodes with links at an
+angle, by creating a 'knee'.
+
+	#----o
+	|     \
+	#-#-#  o
+	       |
+	     #-o
+
+Above, you can move east between from the top-left room and the bottommost
+room. Remember that the length of links does not matter, so in-game this will
+only be one step (one exit `east` in each of the two rooms).
+
+Routers can link connect multiple connections as long as there as as many
+'ingoing' as there are 'outgoing' links. If in doubt, the system will assume a
+link will continue to the outgoing link on the opposite side of the router.
+
+          /
+        -o    - this is ok, there can only be one path, w-ne
+
+         |
+        -o-   - equivalent to '+': one n-s and one w-e link crossing
+         |
+
+        \|/
+        -o-   - all links are passing straight through
+        /|\
+
+        -o-   - w-e link pass straight through, other link is sw-s
+        /|
+
+        -o    - invalid; impossible to know which input goes to which output
+        /|
+
+
+#### Teleporter Links
+
+Teleporters (`TeleportMapLink`) always come in pairs using the same map symbol
+(`'t'` by default).  When moving into one link, movement continues out the
+matching teleport link. The pair must both be on the same XYMap and both sides
+must connect/chain to a node (like all links). Only a single link (or node) may
+connect to the teleport link.
+
+Pathfinding will also work correctly across the teleport.
+
+	#-t     t-#
+
+Moving east from the leftmost node will have you appear at the rightmost node
+and vice versa (think of the two `t` as thinking they are in the same location).
+
+Teleportation movement is always two-way, but you can use one-way links to
+create the effect of a one-way teleport:
+
+	#-t    t>#
+
+In this example you can move east across the teleport, but not west since the
+teleporter-link is hidden behind a one-way exit.
+
+	#-t#     (invalid!)
+
+The above is invalid since only one link/node may connect to the teleport at a
+time.
+
+You can have multiple teleports on the same map, by assigning each pair a
+different (unused) unique symbol in your map legend:
+
+
+```python
+# in your map definition module
+
+from evennia.contrib.xyzgrid import xymap_legend
+
+MAPSTR = r"""
+
++ 0 1 2 3 4
+
+2 t q #   q
+  | v/ \  |
+1 #-#-p #-#
+  |       |
+0 #-t p>#-#
+
++ 0 1 2 3 4
+
+"""
+
+LEGEND = {
+    't': xymap_legend.TeleporterMapLink,
+    'p': xymap_legend.TeleporterMapLink,
+    'q': xymap_legend.TeleportermapLink,
+}
+
+
+```
+
+#### Map-Transition Nodes
+
+The map transition (`MapTransitionNode`) teleports between XYMaps (a
+Z-coordinate transition, if you will), like walking from the "Dungeon" map to
+the "Castle" map. Unlike other nodes, the MapTransitionNode is never spawned
+into an actual room (it has no prototype). It just holds an XYZ
+coordinate pointing to somewhere on the other map. The link leading _to_ the
+node will use those coordinates to make an exit pointing there. Only one single
+link may lead to this type of node.
+
+Unlike for `TeleporterMapLink`, there need _not_ be a matching
+`MapTransitionNode` on the other map - the transition can choose to send the
+player to _any_ valid coordinate on the other map.
+
+Each MapTransitionNode has a property `target_map_xyz` that holds the XYZ
+coordinate the player should end up in when going towards this node. This
+must be customized in a child class for every transition.
+
+If there are more than one transition, separate transition classes should be
+added, with different map-legend symbols:
+
+
+```python
+# in your map definition module (let's say this is mapB)
+
+from evennia.contrib.xyzgrid import xymap_legend
+
+MAPSTR = r"""
+
++ 0 1 2
+
+2   #-C
+    |
+1 #-#-#
+     \
+0 A-#-#
+
++ 0 1 2
+
+
+"""
+
+class TransitionToMapA(xymap_legend.MapTransitionNode):
+    """Transition to MapA"""
+    target_map_xyz = (1, 4, "mapA")
+
+class TransitionToMapC(xymap_legend.MapTransitionNode):
+    """Transition to MapB"""
+    target_map_xyz = (12, 14, "mapC")
+
+LEGEND = {
+    'A': TransitionToMapA
+    'C': TransitionToMapC
+
+}
+
+```
+
+Moving west from `(1,0)` will bring you to `(1,4)` of MapA, and moving east from
+`(1,2)` will bring you to `(12,14)` on MapC (assuming those maps exist).
+
+A map transition is always one-way, and can lead to the coordinates of _any_
+existing node on the other map:
+
+	map1        map2
+
+	#-T         #-#---#-#-#-#
+
+A player moving east towards `T` could for example end up at the 4th `#` from
+the left on map2 if so desired (even though it doesn't make sense visually).
+There is no way to get back to map1 from there.
+
+To create the effect of a two-way transition, one can set up a mirrored
+transition-node on the other map:
+
+	citymap    dungeonmap
+
+	#-T        T-#
+
+
+The transition-node of each map above has `target_map_xyz` pointing to the
+coordinate of the `#` node of the other map (_not_ to the other `T`, that is not
+spawned and would lead to the exit finding no destination!). The result is that
+one can go east into the dungeon and then immediately go back west to the city
+across the map boundary.
+
+### Prototypes
+
+[Prototypes](../Components/Prototypes) are dicts that describe how to _spawn_ a new instance
+of an object. Each of the _nodes_ and _links_ above have a default prototype
+that allows the `evennia xyzgrid spawn` command to convert them to
+a [XYZRoom](api:evennia.contrib.xyzgrid.xyzroom#XYZRoom)
+or an [XYZExit](api:evennia.contrib.xyzgrid.xyzroom#XYZExit) respectively.
+
+The default prototypes are found in `evennia.contrib.xyzgrid.prototypes` (added
+during installation of this contrib), with `prototype_key`s `"xyz_room"` and
+`"xyz_exit"` - use these as `prototype_parent` to add your own custom prototypes.
+
+The `"prototypes"` key of the XYMap-data dict allows you to customize which
+prototype is used for each coordinate in your XYMap. The coordinate is given as
+`(X, Y)` for nodes/rooms and `(X, Y, direction)` for links/exits, where the
+direction is one of "n", "ne", "e", "se", "s", "sw", "w", "nw", "u" or "d". For
+exits, it's recommended to _not_ set a `key` since this is generated
+automatically by the grid spawner to be as expected ("north" with alias "n", for
+example).
+
+A special coordinate is `*`. This acts as a wild card for that coordinate and
+allows you to add 'default' prototypes to be used for rooms.
+
+
+```python
+
+MAPSTR = r"""
+
++ 0 1
+
+1 #-#
+   \
+0 #-#
+
++ 0 1
+
+
+"""
+
+
+PROTOTYPES = {
+    (0,0): {
+	"prototype_parent": "xyz_room",
+	"key": "End of a the tunnel",
+	"desc": "This is is the end of the dark tunnel. It smells of sewage."
+    },
+    (0,0, 'e') : {
+	"prototype_parent": "xyz_exit",
+	"desc": "The tunnel continues into darkness to the east"
+    },
+    (1,1): {
+	"prototype_parent": "xyz_room",
+	"key": "Other end of the tunnel",
+	"desc": The other end of the dark tunnel. It smells better here."
+    }
+    # defaults
+    ('*', '*'): {
+    	"prototype_parent": "xyz_room",
+	"key": "A dark tunnel",
+	"desc": "It is dark here."
+    },
+    ('*', '*', '*'): {
+	"prototype_parent": "xyz_exit",
+	"desc": "The tunnel stretches into darkness."
+    }
+}
+
+XYMAP_DATA = {
+    # ...
+    "prototypes": PROTOTYPES
+    # ...
+}
+
+```
+
+When spawning the above map, the room at the bottom-left and top-right of the
+map will get custom descriptions and names, while the others will have default
+values. One exit (the east exit out of the room in the bottom-left will have a
+custom description.
+
+> If you are used to using prototypes, you may notice that we didn't add a
+> `prototype_key` for the above prototypes. This is normally required for every
+> prototype. This is for convenience - if
+> you don't add a `prototype_key`, the grid will automatically generate one for
+> you - a hash based on the current XYZ (+ direction) of the node/link to spawn.
+
+If you find yourself changing your prototypes after already spawning the
+grid/map, you can rerun `evennia xyzgrid spawn` again; The changes will be
+picked up and applied to the existing objects.
+
+#### Extending the base prototypes
+
+The default prototypes are found in `evennia.contrib.xyzgrid.prototypes` and
+should be included as `prototype_parents` for prototypes on the map. Would it
+not be nice to be able to change these and have the change apply to all of the
+grid? You can, by adding the following to your `mygame/server/conf/settings.py`:
+
+    XYZROOM_PARENT_PROTOTYPE_OVERRIDE = {"typeclass": "myxyzroom.MyXYZRoom"}
+    XYZEXIT_PARENT_PROTOTYPE_OVERRIDE = {...}
+
+Only add what you want to change - these dicts will _extend_ the default parent
+prototypes rather than replace them. As long as you define your map's prototypes
+to use a `prototype_parent` of `"xyz_room"` and/or `"xyz_exit"`, your changes
+will now be applied. You may need to respawn your grid and reload the server
+after a change like this.
+
+### Options
+
+The last element of the `XYMAP_DATA` dict is the `"options"`, for example
+
+```
+XYMAP_DATA = {
+    # ...
+    "options": {
+	"map_visual_range": 2
+    }
+}
+
+```
+
+The `options` dict is passed as `**kwargs` to `XYZRoom.return_appearance`
+when visualizing the map in-game. It allows for making different maps display
+differently from one another (note that while these options are convenient one
+could of course also override `return_appearance` entirely by inheriting from
+`XYZRoom` and then pointing to it in your prototypes).
+
+The default visualization is this:
+
+```
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                                     #---#
+                                    /
+                                   @-
+-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dungeon Entrance
+To the east, a narrow opening leads into darkness.
+Exits: northeast and east
+
+```
+
+- `map_display` (bool): This turns off the display entirely for this map.
+- `map_character_symbol` (str): The symbol used to show 'you' on the map. It can
+  have colors but should only take up one character space. By default this is a
+  green `@`.
+- `map_visual_range` (int): This how far away from your current location you can
+  see.
+- `map_mode` (str): This is either "node" or "scan" and affects how the visual
+  range is calculated.
+  In "node" mode, the range shows how many _nodes_ away from that you can see. In "scan"
+  mode you can instead see that many _on-screen characters_ away from your character.
+  To visualize, assume this is the full map (where '@' is the character location):
+
+      #----------------#
+      |                |
+      |                |
+      # @------------#-#
+      |                |
+      #----------------#
+
+  This is what the player will see in 'nodes' mode with `map_visual_range=2`:
+
+      @------------#-#
+
+  ... and in 'scan' mode:
+
+      |
+      |
+      # @--
+      |
+      #----
+
+  The 'nodes' mode has the advantage of showing only connected links and is
+  great for navigation but depending on the map it can include nodes quite
+  visually far away from you. The 'scan' mode can accidentally reveal unconnected
+  parts of the map (see example above), but limiting the range can be used as a
+  way to hide information.
+
+  This is what the player will see in 'nodes' mode with `map_visual_range=1`:
+
+      @------------#
+
+  ... and in 'scan' mode:
+
+      @-
+
+  One could for example use 'nodes' for outdoor/town maps and 'scan' for
+  exploring dungeons.
+
+- `map_align` (str): One of 'r', 'c' or 'l'. This shifts the map relative to
+  the room text. By default it's centered.
+- `map_target_path_style`: How to visualize the path to a target. This is a
+  string that takes the `{display_symbol}` formatting tag. This will be replaced
+  with the `display_symbol` of each map element in the path. By default this is
+  `"|y{display_symbol}|n"`, that is, the path is colored yellow.
+- `map_fill_all` (bool): If the map area should fill the entire client width
+  (default) or change to always only be as wide as the room description. Note
+  that in the latter case, the map can end up 'dancing around' in the client window
+  if descriptions vary a lot in width.
+- `map_separator_char` (str): The char to use for the separator-lines between the map
+  and the room description. Defaults to `"|x~|n"` - wavy, dark-grey lines.
+
+
+Changing the options of an already spawned map does not require re-spawning the
+map, but you _do_ need to reload the server!
+
+### About the Pathfinder
+
+The new `goto` command exemplifies the use of the _Pathfinder_. This
+is an algorithm that calculates the shortest route between nodes (rooms) on an
+XY-map of arbitrary size and complexity. It allows players to quickly move to
+a location if they know that location's name. Here are some details about
+
+- The pathfinder parses the nodes and links to build a matrix of distances
+  of moving from each node to _all_ other nodes on one XYMap. The path
+  is solved using the
   [Dijkstra algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm).
-  While large solutions can be slow (up to 20 seconds for a 10 000 node map
-  with 8 cardinal links between every room), the solution is cached to disk -
-  meaning that as long as the map-string does not change, subsequent
-  path-finding operations are all very fast (<0.1s, usually much faster).
-  Once retrieving the route, the player can easily be auto-stepped along it.
-- Visual-range - useful for displaying the map to the user as they move. The
-  system can either show everything within a certain grid-distance, or a
-  certain number of connected nodes away from the character's position.
-- Visualize-paths. The system can highlight the path to a target on the grid.
-  Useful for showing where the pathfinder is moving you.
-- The Map parser can be customized so as to give different weight to longer
-  links - by default a 3-step long link has the same 'weight' for the
-  pathfinder as two nodes next to each other. This could be combined with
-  some measure of it taking longer to traverse such exits.
+- The pathfinder's matrices can take a long time to build for very large maps.
+  Therefore they are are cached as pickled binary files in
+  `mygame/server/.cache/` and only rebuilt if the map changes. They are safe to
+  delete (you can also use `evennia xyzgrid initpath` to force-create/rebuild the cache files).
+- Once cached, the pathfinder is fast (Finding a 500-step shortest-path over
+  20 000 nodes/rooms takes below 0.1s).
+- It's important to remember that the pathfinder only works within _one_ XYMap.
+  It will not find paths across map transitions. If this is a concern, one can consider
+  making all regions of the game as one XYMap. This probably works fine, but makes it
+  harder to add/remove new maps to/from the grid.
+- The pathfinder will actually sum up the 'weight' of each link to determine which is
+  the 'cheapest' (shortest) route. By default every link except blocking links have
+  a cost of 1 (so cost is equal to the number of steps to move between nodes).
+  Individual links can however change this to a higher/lower weight (must be >=1).
+  A higher weight means the pathfinder will be less likely to use that route
+  compared to others (this can also be vidually confusing for the user, so use with care).
+- The pathfinder will _average_ the weight of long link-chains. Since all links
+  default to having the same weight (=1), this means that
+  `#-#` has the same movement cost as `#----#` even though it is visually 'shorter'.
+  This behavior can be changed per-link by using links with
+`average_long_link_weights = False`.
 
 
-### MultiMap
+##  XYZGrid
 
-Multiple `Maps` (or 'Z coordinates') are combined together in the `MultiMap`
-handler.  The MultiMap knows all maps in the game because it must be possible to
-transition from one to the other by giving the name/Z-coordinate to jump to.
+The `XYZGrid` is a [Global Script](../Components/Scripts) that holds all `XYMap` objects on
+the grid. There should be only one XYZGrid created at any time.
 
-It's worth pointing out that neither `Maps`, nor `MultiMap` has any direct
-link to the game at this point - these are all just abstract _representations_
-of the game world stored in memory.
+To access the grid in-code, there are several ways:
+
+- You can search for the grid like any other Script. It's named "XYZGrid".
+
+	grid = evennia.search_script("XYZGrid")[0]
+
+  (`search_script` always returns a list)
+- You can get it with `evennia.contrib.xyzgrid.xyzgrid.get_xyzgrid`
+
+	from evennia.contrib.xyzgrid.xyzgrid import get_xyzgrid
+	grid = get_xyzgrid()
+
+  This will *always* return a grid, creating an empty grid if one didn't
+  previously exist. So this is also the recommended way of creating a fresh grid
+  in-code.
+- You can get it from an existing XYZRoom/Exit by accessing their `.xyzgrid`
+  property
+
+	grid = self.caller.location.xyzgrid  # if currently in grid room
+
+Most tools on the grid class have to do with loading/adding and deleting maps,
+something you are expected to use the `evennia xyzgrid` commands for. But there
+are also several methods that are generally useful:
+
+- `.get_room(xyz)` - Get a room at a specific coordinate `(X, Y, Z)`. This will
+  only work if the map has been actually spawned first. For example
+  `.get_room((0,4,"the dark castle))`. Use `'*'` as a wild card, so
+  `.get_room(('*','*',"the dark castle))` will get you all rooms spawned on the dark
+ castle map.
+- `.get_exit(xyz, name)` - get a particular exit, e.g.
+  `.get_exit((0,4,"the dark castle", "north")`. You can also use `'*'` as
+  wildcards.
+
+One can also access particular parsed `XYMap` objects on the `XYZGrid` directly:
+
+- `.grid` - this is the actual (cached) store of all XYMaps, as `{zcoord: XYMap, ...}`
+- `.get_map(zcoord)` - get a specific XYMap.
+- `.all_maps()` - get a list of all XYMaps.
+
+Unless you want to heavily change how the map works (or learn what it does), you
+will probably never need to modify the `XYZMap` object itself. You may want to
+know how to call find the pathfinder though:
+
+- `xymap.get_shortest_path(start_xy, end_xy)`
+- `xymap.get_visual_range(xy, dist=2, **kwargs)`
+
+See the [XYMap](api:evennia.contrib.xyzgrid.xymap#XYMap) documentation for
+details.
 
 
-### Rooms and Exits
+## XYZRoom and XYZExit
 
-The component (_Nodes_ and _Links_ both) of each `Map` can have a `prototype`
-dict associated with it. This is the default used when converting this node/link
-into something actually visible in-game. It is also possible to override
-the default on a per-XY coordinate level.
+These are new custom [Typeclasses](../Components/Typeclasses) located in
+`evennia.contrib.xyzgrid.xyzroom`. They extend the base `DefaultRoom` and
+`DefaultExit` to be aware of their `X`, `Y` and `Z` coordinates.
 
-- For _Nodes_, the `evennia.contrib.xyzgrid.room.XYZRoom` typeclass (or a child
-  thereof) should be used. This sets up storage of the XYZ-coordinates correctly
-  (using `Tags`).
-- For _Links_, one uses the `evennia.contrib.xyzgrid.room.XYZExit` typeclass
-  (or a child thereof). This also sets up the proper coordinates, both for the
-  location they are in and for the exit's destination.
+```warning::
 
+    You should usually **not** create XYZRooms/Exits manually. They are intended
+    to be created/deleted based on the layout of the grid. So to add a new room, add
+    a new node to your map. To delete it, you remove it. Then rerun `evennia xyzgrid
+    spawn`. This may lead to manually created rooms being deleted or confusing the
+    system.
 
-### The Grid
+    If you **still** want to create such rooms manually (don't say we didn't warn you!),
+    you should do it with their `XYZRoom.create()` and `XYZExit.create()` methods.
+    This makes sure the XYZ they use are unique.
 
-The combination of `MultiMaps` and `prototypes` are used to create the `Grid`, a
-series of coordinate-bound rooms/exits actually present in the game world. Each
-node of this grid has a unique `(X, Y, Z)` position (no duplicates).
+```
 
-Once the prototypes have been used to create the grid, it must be kept in-sync
-with any changes in map-strings `Map` structures - otherwise pathfinding and
-visual-range displays will not work (or at least be confusingly inaccurate). So
-changes should _only_ be done on the Map-string outside of the game, _not_ by
-digging new XYZRooms manually!
+Useful (extra) properties on `XYZRoom`, `XYZExit`:
 
-The contrib provides a sync mechanism. This compares the stored `Map` with
-the current topology and rebuilds/removes any nodes/rooms/links/exits that
-has changed. Since this process can be slow, you need to run this manually when
-you know you've made a change.
+- `xyz` The `(X, Y, Z)` coordinate of the entity, for example `(23, 1, "greenforest")`
+- `xyzmap` The `XYMap` this belongs to.
+- `get_display_name(looker)` - this has been modified to show the coordinates of
+  the entity as well as the `#dbref` if you have Builder or higher privileges.
+- `return_appearance(looker, **kwargs)` - this has been extensively modified for
+  `XYZRoom`, to display the map. The `options` given in `XYMAP_DATA` will appear
+  as `**kwargs` to this method and if you override this you can customize the
+  map display in depth.
 
-Remember that syncing is only necesssary for topological changes! That is,
-changes visible in the map string. Fixing the `desc` of a room or adding a new
-enemy does not require any re-sync. Also, things not visible on the
-map (like a secret entrance) should not be available to the pathfinder anyway.
+To use your own overridden version of `XYZRoom/Exit`, you need to override
+the prototype used to spawn rooms on the grid. You can modify the base prototype
+parents in settings (see the [Extending the base prototypes](#extending-the-base-prototypes)
+section above).
 
-You can dig non-XYZRoom objects and link them to `XYZRooms` with no issues -
-they will work like normal in-game. But such rooms (and exits leading to/from
-them) are _not_ considered part of the grid for the purposes of pathfinding etc.
-Exactly how to organize this depends on your game.
+## Working with the grid
 
+The work flow of working with the grid is usually as follows:
 
+1. Prepare a module with a _Map String_, _Map Legend_, _Prototypes_ and
+   _Options_ packaged into a dict `XYMAP_DATA`. Include multiple maps per module
+   by adding several `XYMAP_DATA` to a variable `XYMAP_DATA_LIST` instead.
+2. If your map contains `TransitionMapNodes`, the target map must either also be
+   added or already exist in the grid. If not, you should skip that node for
+   now (otherwise you'll face errors when spawning because the exit-destination
+   does not exist).
+2. Run `evennia xyzgrid add <module>` to register the maps with the grid. If no
+   grid existed, it will be created by this. Fix any errors reported by the
+   parser.
+3. Inspect the parsed map(s) with `evennia xyzgrid show <zcoord>` and make sure
+   they look okay.
+4. Run `evennia xyzgrid spawn` to spawn/update maps into actual `XYZRoom`s and
+   `XYZExit`s.
+5. If you want you can now tweak your grid manually by usual building commands.
+   Anything you do _not_ specify in your grid prototypes you can
+   modify locally in your game - as long as the whole room/exit is not deleted,
+   those will be untouched by `evennia xyzgrid spawn`.  You can also dig/open
+   exits to other rooms 'embedded' in your grid. These exits must _not_ be named
+   one of the grid directions (north, northeast, etc, nor up/down) or the grid
+   will delete it next `evennia xyzgrid spawn` runs (since it's not on the map).
+6. If you want to add new grid-rooms/exits you should _always_ do so by
+   modifying the _Map String_ and then rerunning `evennia xyzgrid spawn` to
+   apply the changes.
diff --git a/docs/source/toc.md b/docs/source/toc.md
index 00050cc0c7..8ed4fb7346 100644
--- a/docs/source/toc.md
+++ b/docs/source/toc.md
@@ -1,5 +1,5 @@
 # Toc
-- [API root](api/evennia-api.rst)
+
 - [Coding/Coding Introduction](Coding/Coding-Introduction)
 - [Coding/Coding Overview](Coding/Coding-Overview)
 - [Coding/Continuous Integration](Coding/Continuous-Integration)
@@ -82,6 +82,7 @@
 - [Contribs/Dialogues in events](Contribs/Dialogues-in-events)
 - [Contribs/Dynamic In Game Map](Contribs/Dynamic-In-Game-Map)
 - [Contribs/Static In Game Map](Contribs/Static-In-Game-Map)
+- [Contribs/XYZGrid](Contribs/XYZGrid)
 - [./Contributing](./Contributing)
 - [./Contributing Docs](./Contributing-Docs)
 - [./Evennia API](./Evennia-API)
diff --git a/evennia/contrib/xyzgrid/README.md b/evennia/contrib/xyzgrid/README.md
index 1f5e8de75f..f3ccc5cbdc 100644
--- a/evennia/contrib/xyzgrid/README.md
+++ b/evennia/contrib/xyzgrid/README.md
@@ -16,7 +16,7 @@ your current visual-range and a lot of related features.
 The rooms of the grid are entirely controlled from outside the game, using
 python modules with strings and dicts defining the map(s) of the game. It's
 possible to combine grid- with non-grid rooms, and you can decorate
-grid rooms as much as you like in-game, but you cannot build new grid
+grid rooms as much as you like in-game, but you cannot spawn new grid
 rooms without editing the map files outside of the game.
 
 The full docs are found as
@@ -33,7 +33,7 @@ in the docs.
 
         EXTRA_LAUNCHER_COMMANDS['xyzgrid'] = 'evennia.contrib.launchcmd.xyzcommand'
 
-3. Run the new `evennia xyzgrid help` for instructions on how to build the grid.
+3. Run the new `evennia xyzgrid help` for instructions on how to spawn the grid.
 
 ## Example usage
 
@@ -41,14 +41,14 @@ After installation, do the following (from your command line, where the
 `evennia` command is available) to install an example grid:
 
     evennia xyzgrid init
-    evennia xyzgrid add evennia.contrib.xyzgrid.map_example
+    evennia xyzgrid add evennia.contrib.xyzgrid.example
     evennia xyzgrid list
     evennia xyzgrid show "the large tree"
     evennia xyzgrid show "the small cave"
-    evennia xyzgrid build
+    evennia xyzgrid spawn
     evennia reload
 
-(remember to reload the server after build operations).
+(remember to reload the server after spawn operations).
 
 Now you can log into the
 server and do `teleport (3,0,the large tree)` to teleport into the map.
diff --git a/evennia/contrib/xyzgrid/map_example.py b/evennia/contrib/xyzgrid/example.py
similarity index 96%
rename from evennia/contrib/xyzgrid/map_example.py
rename to evennia/contrib/xyzgrid/example.py
index 20b3fcce02..5e01268c8e 100644
--- a/evennia/contrib/xyzgrid/map_example.py
+++ b/evennia/contrib/xyzgrid/example.py
@@ -21,15 +21,16 @@ from evennia.contrib.xyzgrid import xymap_legend
 
 # default prototype parent. It's important that
 # the typeclass inherits from the XYZRoom (or XYZExit)
-# the xymap_legend.XYZROOM_PARENT and XYZEXIT_PARENTS can also
-# be used as a shortcut.
+# if adding the evennia.contrib.xyzgrid.prototypes to
+# settings.PROTOTYPE_MODULES, one could just set the
+# prototype_parent to 'xyz_room' and 'xyz_exit' respectively
+# instead.
 
 PARENT = {
     "key": "An empty room",
     "prototype_key": "xyzmap_room_map1",
     "typeclass": "evennia.contrib.xyzgrid.xyzroom.XYZRoom",
     "desc": "An empty room.",
-    "options": {}
 }
 
 
@@ -66,7 +67,7 @@ MAP1 = r"""
 """
 
 
-class TransitionToCave(xymap_legend.MapTransitionMapNode):
+class TransitionToCave(xymap_legend.TransitionMapNode):
     """
     A transition from 'the large tree' to 'the small cave' map. This node is never spawned
     into a room but only acts as a target for finding the exit's destination.
@@ -169,7 +170,7 @@ MAP2 = r"""
 """
 
 # custom map node
-class TransitionToLargeTree(xymap_legend.MapTransitionMapNode):
+class TransitionToLargeTree(xymap_legend.TransitionMapNode):
     """
     A transition from 'the small cave' to 'the large tree' map. This node is never spawned
     into a room by only acts as a target for finding the exit's destination.
diff --git a/evennia/contrib/xyzgrid/launchcmd.py b/evennia/contrib/xyzgrid/launchcmd.py
index f6f4ca9b21..e55e4875f6 100644
--- a/evennia/contrib/xyzgrid/launchcmd.py
+++ b/evennia/contrib/xyzgrid/launchcmd.py
@@ -1,6 +1,6 @@
 """
-Custom Evennia launcher command option for building/rebuilding the grid in a separate process than
-the main server (since this can be slow).
+Custom Evennia launcher command option for maintaining the grid in a separate process than the main
+server (since this can be slow).
 
 To use, add to the settings:
 ::
@@ -22,7 +22,7 @@ from evennia.utils import ansi
 from evennia.contrib.xyzgrid.xyzgrid import get_xyzgrid
 
 _HELP_SHORT = """
-evennia xyzgrid help|list|init|add|build|initpath|delete [<options>]
+evennia xyzgrid help|list|init|add|spawn|initpath|delete [<options>]
 Manages the XYZ grid. Use 'xyzgrid help <option>' for documentation.
 """
 
@@ -34,7 +34,7 @@ help <command>   - get help about each command:
     list            - show list
     init            - initialize grid (only one time)
     add             - add new maps to grid
-    build           - build added maps into actual db-rooms/exits
+    spawn           - spawn added maps into actual db-rooms/exits
     initpath        - (re)creates pathfinder matrices
     delete          - delete part or all of grid
 """
@@ -78,38 +78,38 @@ add <path.to.xymap.module> [<path> <path>,...]
         {"map": mapstring, "zcoord": mapname/zcoord, "legend": dict, "prototypes": dict}
         describing one single XYmap, or
     - a XYMAP_DATA_LIST - a list of multiple dicts on the XYMAP_DATA form. This allows for
-        embedding multiple maps in the same module. See evennia/contrib/xyzgrid/map_example.py
+        embedding multiple maps in the same module. See evennia/contrib/xyzgrid/example.py
         for an example of how this looks.
 
-    Note that adding a map does *not* build it. If maps are linked to one another, you should
-    add all linked maps before running 'build', or you'll get errors when creating transitional
+    Note that adding a map does *not* spawn it. If maps are linked to one another, you should
+    add all linked maps before running 'spawn', or you'll get errors when creating transitional
     exits between maps.
 
 Examples:
 
-    evennia xyzgrid add evennia.contrib.xyzgrid.map_example
+    evennia xyzgrid add evennia.contrib.xyzgrid.example
     evennia xyzgrid add world.mymap1 world.mymap2 world.mymap3
 """
 
-_HELP_BUILD = """
-build
+_HELP_SPAWN = """
+spawn
 
-    Builds/updates the entire database grid based on the added maps. For a new grid, this will
+    spawns/updates the entire database grid based on the added maps. For a new grid, this will
     spawn all new rooms/exits (and may take a good while!). For updating, rooms may be
-    removed/spawned if a map changed since the last build.
+    removed/spawned if a map changed since the last spawn.
 
-build "(X,Y,Z|mapname)"
+spawn "(X,Y,Z|mapname)"
 
-    Builds/updates only a part of the grid. Remember the quotes around the coordinate (this
+    spawns/updates only a part of the grid. Remember the quotes around the coordinate (this
     is mostly because shells don't like them)! Use '*' as a wild card for XY coordinates.
     This should usually only be used if the full grid has already been built once - otherwise
-    inter-map transitions may fail! Z is the name/z-coordinate of the map to build.
+    inter-map transitions may fail! Z is the name/z-coordinate of the map to spawn.
 
 Examples:
 
-    evennia xyzgrid build                  - build all
-    evennia xyzgrid "(*, *, mymap1)"       - build everything of map/zcoord mymap1
-    evennia xyzgrid "(12, 5, mymap1)"      - build only coordinate (12, 5) on map/zcoord mymap1
+    evennia xyzgrid spawn                  - spawn all
+    evennia xyzgrid "(*, *, mymap1)"       - spawn everything of map/zcoord mymap1
+    evennia xyzgrid "(12, 5, mymap1)"      - spawn only coordinate (12, 5) on map/zcoord mymap1
 """
 
 _HELP_INITPATH = """
@@ -118,7 +118,7 @@ initpath
     Recreates the pathfinder matrices for the entire grid. These are used for all shortest-path
     calculations. The result will be cached to disk (in mygame/server/.cache/). If not run, each
     map will run this automatically first time it's used. Running this will always force to
-    rebuild the cache.
+    respawn the cache.
 
 initpath Z|mapname
 
@@ -156,7 +156,7 @@ _TOPICS_MAP = {
     "list": _HELP_LIST,
     "init": _HELP_INIT,
     "add": _HELP_ADD,
-    "build": _HELP_BUILD,
+    "spawn": _HELP_SPAWN,
     "initpath": _HELP_INITPATH,
     "delete": _HELP_DELETE
 }
@@ -216,14 +216,14 @@ def _option_list(*suboptions):
                       "to another map), so the 'missing room(s)' may just be from such nodes.")
             elif nrooms > nnodes:
                 print(f"{nrooms} / {nnodes} rooms are spawned\n"
-                      "Note: Maybe some rooms were removed from map. Run 'build' to re-sync.")
+                      "Note: Maybe some rooms were removed from map. Run 'spawn' to re-sync.")
             else:
                 print(f"{nrooms} / {nnodes} rooms are spawned\n")
 
             if checkwarning:
                 print("Note: This check is not complete; it does not consider changed map "
                       "topology\nlike relocated nodes/rooms and new/removed links/exits - this "
-                      "is calculated only during a build.")
+                      "is calculated only during a spawn.")
             print("\nDisplayed map (as appearing in-game):\n\n" + ansi.parse_ansi(str(xymap)))
             print("\nRaw map string (including axes and invisible nodes/links):\n"
                   + str(xymap.mapstring))
@@ -268,9 +268,9 @@ def _option_add(*suboptions):
     print(f"Added (or readded) {len(xymap_data_list)} XYMaps to grid.")
 
 
-def _option_build(*suboptions):
+def _option_spawn(*suboptions):
     """
-    Build the grid or part of it.
+    spawn the grid or part of it.
 
     """
     grid = get_xyzgrid()
@@ -286,14 +286,14 @@ def _option_build(*suboptions):
         try:
             x, y, z = (part.strip() for part in opts.split(","))
         except ValueError:
-            print("Build coordinate must be given as (X, Y, Z) tuple, where '*' act "
+            print("spawn coordinate must be given as (X, Y, Z) tuple, where '*' act "
                   "wild cards and Z is the mapname/z-coord of the map to load.")
             return
     else:
         x, y, z = '*', '*', '*'
 
     if x == y == z == '*':
-        inp = input("This will (re)build the entire grid. If it was built before, it may spawn \n"
+        inp = input("This will (re)spawn the entire grid. If it was built before, it may spawn \n"
                     "new rooms or delete rooms that no longer matches the grid.\nDo you want to "
                     "continue? [Y]/N? ")
     else:
@@ -303,9 +303,9 @@ def _option_build(*suboptions):
         print("Aborted.")
         return
 
-    print("Starting build ...")
+    print("Starting spawn ...")
     grid.spawn(xyz=(x, y, z))
-    print("... build complete!\nIt's recommended to reload the server to refresh caches if this "
+    print("... spawn complete!\nIt's recommended to reload the server to refresh caches if this "
           "modified an existing grid.")
 
 
diff --git a/evennia/contrib/xyzgrid/prototypes.py b/evennia/contrib/xyzgrid/prototypes.py
index 6ba5d875a9..29398246da 100644
--- a/evennia/contrib/xyzgrid/prototypes.py
+++ b/evennia/contrib/xyzgrid/prototypes.py
@@ -14,19 +14,34 @@ and/or
     {'prototype_parent': 'xyz_exit', ...}
 
 """
+from django.conf import settings
 
-# required by the prototype importer
-PROTOTYPE_LIST = [
-    {
-        'prototype_key': 'xyz_room',
-        'typeclass': 'evennia.contrib.xyzgrid.xyzroom.XYZRoom',
-        'prototype_tags': ("xyzroom", ),
-        'key': "A room",
-        'desc': "An empty room."
-    }, {
-        'prototype_key': 'xyz_exit',
-        'prototype_tags': ("xyzexit", ),
-        'typeclass': 'evennia.contrib.xyzgrid.xyzroom.XYZExit',
-        'desc': "An exit."
-    }
-]
+try:
+    room_override = settings.XYZROOM_PROTOTYPE_OVERRIDE
+except AttributeError:
+    room_override = {}
+
+try:
+    exit_override = settings.XYZEXIT_PROTOTYPE_OVERRIDE
+except AttributeError:
+    exit_override = {}
+
+room_prototype = {
+    'prototype_key': 'xyz_room',
+    'typeclass': 'evennia.contrib.xyzgrid.xyzroom.XYZRoom',
+    'prototype_tags': ("xyzroom", ),
+    'key': "A room",
+    'desc': "An empty room."
+}
+room_prototype.update(room_override)
+
+exit_prototype = {
+    'prototype_key': 'xyz_exit',
+    'typeclass': 'evennia.contrib.xyzgrid.xyzroom.XYZExit',
+    'prototype_tags': ("xyzexit", ),
+    'desc': "An exit."
+}
+exit_prototype.update(exit_override)
+
+# accessed by the prototype importer
+PROTOTYPE_LIST = [room_prototype, exit_prototype]
diff --git a/evennia/contrib/xyzgrid/tests.py b/evennia/contrib/xyzgrid/tests.py
index 327bf3af17..59f1a942ec 100644
--- a/evennia/contrib/xyzgrid/tests.py
+++ b/evennia/contrib/xyzgrid/tests.py
@@ -1182,12 +1182,12 @@ class TestXYZGrid(EvenniaTest):
 
 
 # map transitions
-class Map12aTransition(xymap_legend.MapTransitionMapNode):
+class Map12aTransition(xymap_legend.TransitionMapNode):
     symbol = "T"
     target_map_xyz = (1, 0, "map12b")
 
 
-class Map12bTransition(xymap_legend.MapTransitionMapNode):
+class Map12bTransition(xymap_legend.TransitionMapNode):
     symbol = "T"
     target_map_xyz = (0, 1, "map12a")
 
@@ -1251,7 +1251,7 @@ class TestXYZGridTransition(EvenniaTest):
 
 class TestBuildExampleGrid(EvenniaTest):
     """
-    Test building the map_example (this takes about 30s)
+    Test building the map-example (this takes about 30s)
 
     """
     def setUp(self):
@@ -1271,7 +1271,7 @@ class TestBuildExampleGrid(EvenniaTest):
         Build the map example.
 
         """
-        mapdatas = self.grid.maps_from_module("evennia.contrib.xyzgrid.map_example")
+        mapdatas = self.grid.maps_from_module("evennia.contrib.xyzgrid.example")
         self.assertEqual(len(mapdatas), 2)
 
         self.grid.add_maps(*mapdatas)
diff --git a/evennia/contrib/xyzgrid/xymap.py b/evennia/contrib/xyzgrid/xymap.py
index a82ae96342..8c41420af3 100644
--- a/evennia/contrib/xyzgrid/xymap.py
+++ b/evennia/contrib/xyzgrid/xymap.py
@@ -88,7 +88,7 @@ The nodes and links can be customized by add your own implementation of `MapNode
 the LEGEND dict, mapping them to a particular character symbol. A `MapNode` can only be added
 on an even XY coordinate while `MapLink`s can be added anywhere on the xygrid.
 
-See `./map_example.py` for some empty grid areas to start from.
+See `./example.py` for a full grid example.
 
 ----
 """
@@ -456,11 +456,12 @@ class XYMap:
 
                     xygrid[ix][iy] = XYgrid[iX][iY] = node_index_map[node_index] = \
                         mapnode_or_link_class(x=ix, y=iy, Z=self.Z,
-                                              node_index=node_index, xymap=self)
+                                              node_index=node_index, symbol=char, xymap=self)
 
                 else:
                     # we have a link at this xygrid position (this is ok everywhere)
-                    xygrid[ix][iy] = mapnode_or_link_class(x=ix, y=iy, Z=self.Z, xymap=self)
+                    xygrid[ix][iy] = mapnode_or_link_class(x=ix, y=iy, Z=self.Z, symbol=char,
+                                                           xymap=self)
 
                 # store the symbol mapping for transition lookups
                 symbol_map[char].append(xygrid[ix][iy])
diff --git a/evennia/contrib/xyzgrid/xymap_legend.py b/evennia/contrib/xyzgrid/xymap_legend.py
index aaa31607a1..a065a58db8 100644
--- a/evennia/contrib/xyzgrid/xymap_legend.py
+++ b/evennia/contrib/xyzgrid/xymap_legend.py
@@ -45,14 +45,13 @@ class MapNode:
     - `display_symbol` (str or `None`) - This is what is used to visualize this node later. This
       symbol must still only have a visual size of 1, but you could e.g. use some fancy unicode
       character (be aware of encodings to different clients though) or, commonly, add color
-      tags around it. For further customization, the `.get_display_symbol` method receives
-      the full grid and can return a dynamically determined display symbol. If set to `None`,
-      the `symbol` is used.
+      tags around it. For further customization, the `.get_display_symbol` method
+      can return a dynamically determined display symbol. If set to `None`, the `symbol` is used.
     - `interrupt_path` (bool): If this is set, the shortest-path algorithm will include this
-      node as normally, but stop when reaching it, even if not having reached its target yet. This
-      is useful for marking 'points of interest' along a route, or places where you are not
-      expected to be able to continue without some further in-game action not covered by the map
-      (such as a guard or locked gate etc).
+      node as normally, but the auto-stepper will stop when reaching it, even if not having reached
+      its target yet. This is useful for marking 'points of interest' along a route, or places where
+      you are not expected to be able to continue without some further in-game action not covered by
+      the map (such as a guard or locked gate etc).
     - `prototype` (dict) - The default `prototype` dict to use for reproducing this map component
       on the game grid. This is used if not overridden specifically for this coordinate. If this
       is not given, nothing will be spawned for this coordinate (a 'virtual' node can be useful
@@ -88,7 +87,7 @@ class MapNode:
         'u': ('up', 'u'),
     }
 
-    def __init__(self, x, y, Z, node_index=0, xymap=None):
+    def __init__(self, x, y, Z, node_index=0, symbol=None, xymap=None):
         """
         Initialize the mapnode.
 
@@ -99,6 +98,8 @@ class MapNode:
             node_index (int): This identifies this node with a running
                 index number required for pathfinding. This is used
                 internally and should not be set manually.
+            symbol (str, optional): Set during parsing - allows to override
+                the symbol based on what's set in the legend.
             xymap (XYMap, optional): The map object this sits on.
 
         """
@@ -115,6 +116,8 @@ class MapNode:
         self.Z = Z
 
         self.node_index = node_index
+        if symbol is not None:
+            self.symbol = symbol
 
         # this indicates linkage in 8 cardinal directions on the string-map,
         # n,ne,e,se,s,sw,w,nw and link that to a node (always)
@@ -501,8 +504,8 @@ class MapLink:
       symbol must still only have a visual size of 1, but you could e.g. use some fancy unicode
       character (be aware of encodings to different clients though) or, commonly, add color
       tags around it. For further customization, the `.get_display_symbol` can be used.
-    - `default_weight` (int) - Each link direction covered by this link can have its seprate weight,
-      this is used if none is specified in a particular direction. This value must be >= 1,
+    - `default_weight` (int) - Each link direction covered by this link can have its separate
+      weight, this is used if none is specified in a particular direction. This value must be >= 1,
       and can be higher than 1 if a link should be less favored.
     - `directions` (dict) - this specifies which link edge to which other link-edge this link
       is connected; A link connecting the link's sw edge to its easted edge would be written
@@ -577,7 +580,7 @@ class MapLink:
     # will be used.
     spawn_aliases = {}
 
-    def __init__(self, x, y, Z, xymap=None):
+    def __init__(self, x, y, Z, symbol=None, xymap=None):
         """
         Initialize the link.
 
@@ -585,6 +588,8 @@ class MapLink:
             x (int): The xygrid x coordinate
             y (int): The xygrid y coordinate.
             X (int or str): The name/Z-coord of this map we are on.
+            symbol (str, optional): Set during parsing, allows to override
+                the default symbol with the one set in the legend.
             xymap (XYMap, optional): The map object this sits on.
 
         """
@@ -597,6 +602,9 @@ class MapLink:
         self.Y = y / 2
         self.Z = Z
 
+        if symbol is not None:
+            self.symbol = symbol
+
     def __str__(self):
         return f"<LinkNode '{self.symbol}' XY=({self.X:g},{self.Y:g})>"
 
@@ -1117,7 +1125,7 @@ class InterruptMapNode(MapNode):
     interrupt_path = True
     prototype = "xyz_room"
 
-class MapTransitionMapNode(TransitionMapNode):
+class MapTransitionNode(TransitionMapNode):
     """Transition-target node to other map. This is not actually spawned in-game."""
     symbol = "T"
     display_symbol = " "
@@ -1256,7 +1264,7 @@ class TeleporterMapLink(SmartTeleporterMapLink):
 LEGEND = {
     # nodes
     "#": BasicMapNode,
-    "T": MapTransitionMapNode,
+    "T": MapTransitionNode,
     "I": InterruptMapNode,
     # links
     "|": NSMapLink,
diff --git a/evennia/contrib/xyzgrid/xyzroom.py b/evennia/contrib/xyzgrid/xyzroom.py
index c5c0cba0e6..712d05f89d 100644
--- a/evennia/contrib/xyzgrid/xyzroom.py
+++ b/evennia/contrib/xyzgrid/xyzroom.py
@@ -241,6 +241,9 @@ class XYZRoom(DefaultRoom):
         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.
 
     """
 
@@ -255,6 +258,7 @@ class XYZRoom(DefaultRoom):
     map_align = 'c'
     map_target_path_style = "|y{display_symbol}|n"
     map_fill_all = True
+    map_separator_char = "|x~|n"
 
     def __str__(self):
         return repr(self)
@@ -431,6 +435,9 @@ class XYZRoom(DefaultRoom):
                 xymap.options.get("map_target_path_style", self.map_target_path_style))
             map_area_client = kwargs.get(
                 "map_fill_all", xymap.options.get("map_fill_all", self.map_fill_all))
+            map_separator_char = kwargs.get(
+                "map_separator_char",
+                xymap.options.get("map_separator_char", self.map_separator_char))
 
             client_width, _ = looker.sessions.get()[0].get_client_size()
 
@@ -465,8 +472,8 @@ class XYZRoom(DefaultRoom):
                 max_size=(display_width, None),
                 indent=map_indent
             )
-            sep = "~" * sep_width
-            map_display = f"|x{sep}|n\n{map_display}\n|x{sep}"
+            sep = map_separator_char * sep_width
+            map_display = f"{sep}|n\n{map_display}\n{sep}"
 
             # echo directly to make easier to separate in client
             looker.msg(text=(map_display, {"type": "xymap"}), options=None)