<spanid="evennia-contrib-grid-xyzgrid-xymap"></span><h1>evennia.contrib.grid.xyzgrid.xymap<aclass="headerlink"href="#module-evennia.contrib.grid.xyzgrid.xymap"title="Permalink to this headline">¶</a></h1>
<sectionid="xymap">
<h2>XYMap<aclass="headerlink"href="#xymap"title="Permalink to this headline">¶</a></h2>
<p>The <strong>XYMap</strong> class represents one XY-grid of interconnected map-legend components. It’s built from an
ASCII representation, where unique characters represents each type of component. The Map parses the
map into an internal graph that can be efficiently used for pathfinding the shortest route between
any two nodes (rooms).</p>
<p>Each room (MapNode) can have exits (links) in 8 cardinal directions (north, northwest etc) as well
as up and down. These are indicated in code as ‘n’, ‘ne’, ‘e’, ‘se’, ‘s’, ‘sw’, ‘w’,
‘nw’, ‘u’ and ‘d’.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in module passed to 'Map' class</span>
<p>The two <strong>+</strong> signs in the upper/lower left corners are required and marks the edge of the map area.
The origo of the grid is always two steps right and two up from the bottom test marker and the grid
extends to two lines below the top-left marker. Anything outside the grid is ignored, so numbering
the coordinate axes is optional but recommended for readability.</p>
<p>The XY positions represent coordinates positions in the game world. When existing, they are usually
represented by Rooms in-game. The links between nodes would normally represent Exits, but the length
of links on the map have no in-game equivalence except that traversing a multi-step link will place
you in a location with an XY coordinate different from what you’d expect by a single step (most
games don’t relay the XY position to the player anyway).</p>
<p>In the map string, every XY coordinate must have exactly one spare space/line between them - this is
used for node linkings. This finer grid which has 2x resolution of the <strong>XYgrid</strong> is only used by the
mapper and is referred to as the <strong>xygrid</strong> (small xy) internally. Note that an XY position can also
be held by a link (for example a passthrough).</p>
<p>The nodes and links can be customized by add your own implementation of <strong>MapNode</strong> or <strong>MapLink</strong> to
the LEGEND dict, mapping them to a particular character symbol. A <strong>MapNode</strong> can only be added
on an even XY coordinate while <ahref="#id1"><spanclass="problematic"id="id2">**</span></a>MapLink**s can be added anywhere on the xygrid.</p>
<p>See <strong>./example.py</strong> for a full grid example.</p>
<hrclass="docutils"/>
<dlclass="py class">
<dtid="evennia.contrib.grid.xyzgrid.xymap.XYMap">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.contrib.grid.xyzgrid.xymap.</code><codeclass="sig-name descname">XYMap</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">map_module_or_dict</span></em>, <emclass="sig-param"><spanclass="n">Z</span><spanclass="o">=</span><spanclass="default_value">'map'</span></em>, <emclass="sig-param"><spanclass="n">xyzgrid</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">mapcorner_symbol</code><emclass="property"> = '+'</em><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.mapcorner_symbol"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">max_pathfinding_length</code><emclass="property"> = 500</em><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.max_pathfinding_length"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">empty_symbol</code><emclass="property"> = ' '</em><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.empty_symbol"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">legend_key_exceptions</code><emclass="property"> = '\\'</em><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.legend_key_exceptions"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">map_module_or_dict</span></em>, <emclass="sig-param"><spanclass="n">Z</span><spanclass="o">=</span><spanclass="default_value">'map'</span></em>, <emclass="sig-param"><spanclass="n">xyzgrid</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Initialize the map parser by feeding it the map.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>map_module_or_dict</strong> (<em>str</em><em>, </em><em>module</em><em> or </em><em>dict</em>) – Path or module pointing to a map. If a dict,
this should be a dict with a MAP_DATA key ‘map’ and optionally a ‘legend’
dicts to specify the map structure.</p></li>
<li><p><strong>Z</strong> (<em>int</em><em> or </em><em>str</em><em>, </em><em>optional</em>) – Name or Z-coord for for this map. Needed if the game uses
more than one map. If not given, it can also be embedded in the
<strong>map_module_or_dict</strong>. Used when referencing this map during map transitions,
baking of pathfinding matrices etc.</p></li>
<li><p><strong>xyzgrid</strong> (<em>xyzgrid.XYZgrid</em>) – A top-level grid this map is a part of.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>Interally, the map deals with two sets of coordinate systems:
- grid-coordinates x,y are the character positions in the map string.
- world-coordinates X,Y are the in-world coordinates of nodes/rooms.</p>
<blockquote>
<div><p>There are fewer of these since they ignore the ‘link’ spaces between
the nodes in the grid, s</p>
<blockquote>
<div><p>X = x // 2
Y = y // 2</p>
</div></blockquote>
</div></blockquote>
<ulclass="simple">
<li><p>The Z-coordinate, if given, is only used when transitioning between maps
<codeclass="sig-name descname">log</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">msg</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.log"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.log"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">reload</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">map_module_or_dict</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.reload"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.reload"title="Permalink to this definition">¶</a></dt>
<dd><p>(Re)Load a map.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>map_module_or_dict</strong> (<em>str</em><em>, </em><em>module</em><em> or </em><em>dict</em><em>, </em><em>optional</em>) – See description for the variable
in the class’<strong>__init__</strong> function. If given, replace the already loaded
map with a new one. If not given, the existing one given on class creation
will be reloaded.</p></li>
<li><p><strong>parse</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, auto-run <strong>.parse()</strong> on the newly loaded data.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>This will both (re)load the data and parse it into a new map structure, replacing any
<codeclass="sig-name descname">parse</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.parse"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.parse"title="Permalink to this definition">¶</a></dt>
<dd><p>Parses the numerical grid from the string. The first pass means parsing out
all nodes. The linking-together of nodes is not happening until the second pass
(the reason for this is that maps can also link to other maps, so all maps need
to have gone through their first parsing-passes before they can be linked together).</p>
<p>See the class docstring for details of how the grid should be defined.</p>
<pclass="rubric">Notes</p>
<p>In this parsing, the ‘xygrid’ is the full range of chraracters read from
the string. The <strong>XYgrid</strong> is used to denote the game-world coordinates
<codeclass="sig-name descname">calculate_path_matrix</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">force</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.calculate_path_matrix"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.calculate_path_matrix"title="Permalink to this definition">¶</a></dt>
<dd><p>Solve the pathfinding problem using Dijkstra’s algorithm. This will try to
load the solution from disk if possible.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>force</strong> (<em>bool</em><em>, </em><em>optional</em>) – If the cache should always be rebuilt.</p>
<codeclass="sig-name descname">spawn_nodes</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">xy</span><spanclass="o">=</span><spanclass="default_value">'*', '*'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.spawn_nodes"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.spawn_nodes"title="Permalink to this definition">¶</a></dt>
<dd><p>Convert the nodes of this XYMap into actual in-world rooms by spawning their
related prototypes in the correct coordinate positions. This must be done <em>first</em>
before spawning links (with <strong>spawn_links</strong> because exits require the target destination
to exist. It’s also possible to only spawn a subset of the map</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>xy</strong> (<em>tuple</em><em>, </em><em>optional</em>) – An (X,Y) coordinate of node(s). <strong>‘*’</strong> acts as a wildcard.</p>
<codeclass="sig-name descname">spawn_links</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">xy</span><spanclass="o">=</span><spanclass="default_value">'*', '*'</span></em>, <emclass="sig-param"><spanclass="n">nodes</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">directions</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.spawn_links"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.spawn_links"title="Permalink to this definition">¶</a></dt>
<dd><p>Convert links of this XYMap into actual in-game exits by spawning their related
prototypes. It’s possible to only spawn a specic exit by specifying the node and</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>xy</strong> (<em>tuple</em><em>, </em><em>optional</em>) – An (X,Y) coordinate of node(s). <strong>‘*’</strong> acts as a wildcard.</p></li>
<li><p><strong>nodes</strong> (<em>list</em><em>, </em><em>optional</em>) – If given, only consider links out of these nodes. This also
affects <strong>xy</strong>, so that if there are no nodes of given coords in <strong>nodes</strong>, no
links will be spawned at all.</p></li>
<li><p><strong>directions</strong> (<em>list</em><em>, </em><em>optional</em>) – A list of cardinal directions (‘n’, ‘ne’ etc). If given,
sync only the exit in the given directions (<strong>xy</strong> limits which links out of which
nodes should be considered). If unset, there are no limits to directions.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Examples</p>
<ulclass="simple">
<li><dlclass="simple">
<dt><strong>xy=(1, 3 )</strong>, <strong>direction=’ne’</strong> - sync only the north-eastern exit</dt><dd><p>out of the (1, 3) node.</p>
<codeclass="sig-name descname">get_node_from_coord</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">xy</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.get_node_from_coord"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.get_node_from_coord"title="Permalink to this definition">¶</a></dt>
<dd><p>Get a MapNode from a coordinate.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>xy</strong> (<em>tuple</em>) – X,Y coordinate on XYgrid.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>MapNode</em>–</p>
<dlclass="simple">
<dt>The node found at the given coordinates. Returns</dt><dd><p><strong>None</strong> if there is no mapnode at the given coordinate.</p>
</dd>
</dl>
</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="evennia.contrib.grid.xyzgrid.utils.html#evennia.contrib.grid.xyzgrid.utils.MapError"title="evennia.contrib.grid.xyzgrid.utils.MapError"><strong>MapError</strong></a>– If trying to specify an iX,iY outside
<codeclass="sig-name descname">get_components_with_symbol</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">symbol</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.get_components_with_symbol"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.get_components_with_symbol"title="Permalink to this definition">¶</a></dt>
<dd><p>Find all map components (nodes, links) with a given symbol in this map.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>symbol</strong> (<em>char</em>) – A single character-symbol to search for.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>list</em>– A list of MapNodes and/or MapLinks found with the matching symbol.</p>
<codeclass="sig-name descname">get_shortest_path</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">start_xy</span></em>, <emclass="sig-param"><spanclass="n">end_xy</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/grid/xyzgrid/xymap.html#XYMap.get_shortest_path"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.grid.xyzgrid.xymap.XYMap.get_shortest_path"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the shortest route between two points on the grid.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>start_xy</strong> (<em>tuple</em>) – A starting (X,Y) coordinate on the XYgrid (in-game coordinate) for
where we start from.</p></li>
<li><p><strong>end_xy</strong> (<em>tuple</em><em> or </em><aclass="reference internal"href="evennia.contrib.grid.xyzgrid.xymap_legend.html#evennia.contrib.grid.xyzgrid.xymap_legend.MapNode"title="evennia.contrib.grid.xyzgrid.xymap_legend.MapNode"><em>MapNode</em></a>) – The end (X,Y) coordinate on the XYgrid (in-game coordinate)
we want to find the shortest route to.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>tuple</em>– Two lists, first containing the list of directions as strings (n, ne etc) and
the second is a mixed list of MapNodes and all MapLinks in a sequence describing
the full path including the start- and end-node.</p>
