Add XYZgrid contrib api files, prepare for merge

docs/source/Contribs/Contrib-Overview.md

@@ -1,33 +1,33 @@
 # Contrib modules
 
-Contribs are found in [evennia/contrib/](api:evennia.contrib) and are optional game-specific code-snippets 
-or even full systems you can use for your game. They are contributed by the Evennia community and 
-released under the same license as Evennia itself. Each contrib has its own installation instructions. 
+Contribs are found in [evennia/contrib/](api:evennia.contrib) and are optional game-specific code-snippets
+or even full systems you can use for your game. They are contributed by the Evennia community and
+released under the same license as Evennia itself. Each contrib has its own installation instructions.
 Bugs are reported to the Evennia [issue tracker](github:issue) as usual.
 
-## Character-related 
+## Character-related
 
 Contribs related to characters and character displays.
 
-### CharGen 
+### CharGen
 
 *Griatch 2011*
 
 A simple Character creator for OOC mode. Meant as a starting point for a more fleshed-out system.
 
-### Clothing 
+### Clothing
 
 *FlutterSprite 2017*
 
 A layered clothing system with slots for different types of garments auto-showing in description.
 
-### Health Bar 
+### Health Bar
 
 *Tim Ashley Jenkins 2017*
 
 Tool to create colorful bars/meters.
 
-### Multidescer 
+### Multidescer
 
 *Griatch 2016*
 
@@ -39,13 +39,22 @@ Advanced descriptions combined from many separate description components, inspir
 
 Contribs modifying locations, movement or helping to creating rooms.
 
-### Extended Room 
+### XYZGrid
+
+*Griatch 2021*
+
+Adds an XYZgrid to Evennia, with map-display and pathfinding. Created via map
+strings and maintained outside of the game via Evennia launch commands.
+
+- [XYZGrid documentation](./XYZGrid)
+
+### Extended Room
 
 *Griatch 2012*
 
 An expanded Room typeclass with multiple descriptions for time and season as well as details.
 
-### Map Builder 
+### Map Builder
 
 *CloudKeeper 2016*
 
@@ -53,19 +62,19 @@ Build a game area based on a 2D "graphical" unicode map. Supports asymmetric exi
 
 - [Static in-game map](./Static-In-Game-Map)
 
-### Simple Door 
+### Simple Door
 
 *Griatch 2014*
 
 Example of an exit that can be opened and closed from both sides.
 
-###  Slow exit 
+###  Slow exit
 
 *Griatch 2014*
 
 Custom Exit class that takes different time to pass depending on if you are walking/running etc.
 
-### Wilderness 
+### Wilderness
 
 *titeuf87 2017*
 
@@ -79,7 +88,7 @@ Make infinitely large wilderness areas with dynamically created locations.
 
 Contribs supporting roleplay and in-game roleplaying actions.
 
-### Barter system 
+### Barter system
 
 *Griatch 2012*
 
@@ -95,25 +104,25 @@ A full, extendable crafting system.
 - [Crafting API documentation](api:evennia.contrib.crafting.crafting)
 - [Example of a sword crafting tree](api:evennia.contrib.crafting.example_recipes)
 
-### Dice 
+### Dice
 
 *Griatch 2012*
 
 A fully featured dice rolling system.
 
-### Mail 
+### Mail
 
 *grungies1138 2016*
 
 An in-game mail system for communication.
 
-### Puzzles 
+### Puzzles
 
 *Hendher 2019*
 
 Combine objects to create new items, adventure-game style
 
-### RP System 
+### RP System
 
 *Griatch 2015*
 
@@ -125,7 +134,7 @@ Full director-style emoting system replacing names with sdescs/recogs. Supports
 
 Dynamic obfuscation of emotes when speaking unfamiliar languages. Also obfuscates whispers.
 
-### Turnbattle 
+### Turnbattle
 
 *FlutterSprite 2017*
 
@@ -142,7 +151,7 @@ and includes optional expansions for equipment and combat movement, magic and ra
 
 An `@edit` command for modifying objects using a generated menu. Customizable for different games.
 
-### Field Fill 
+### Field Fill
 
 *FlutterSprite 2018*
 
@@ -159,18 +168,18 @@ Allow Builders to add Python-scripted events to their objects (OBS-not for untru
 
 ### Menu-builder
 
-A tool for building using an in-game menu instead of the normal build commands. Meant to 
+A tool for building using an in-game menu instead of the normal build commands. Meant to
 be expanded for the needs of your game.
 
 - [Building Menus](./Building-menus)
 
-### Security/Auditing 
+### Security/Auditing
 
 *Johhny 2018*
 
 Log server input/output for debug/security.
 
-### Tree Select 
+### Tree Select
 
 *FlutterSprite 2017*
 
@@ -183,13 +192,13 @@ multi-line string.
 
 Contribs meant to be used as part of other code, or as replacements for default settings.
 
-### Color-markups 
+### Color-markups
 
 *Griatch, 2017*
 
 Alternative in-game color markups.
 
-### Custom gametime 
+### Custom gametime
 
 *Griatch, vlgeoff 2017*
 
@@ -203,19 +212,19 @@ Implements Evennia's gametime module but for custom game world-specific calendar
 
 A variant of the standard login system that requires an email to login rather then just name+password.
 
-#### Menu login 
+#### Menu login
 
 *Griatch 2011, 2019, Vincent-lg 2016*
 
 A login system using menus asking for name/password rather than giving them as one command.
 
-### Random String Generator 
+### Random String Generator
 
 *Vincent Le Goff 2017*
 
 Simple pseudo-random generator of strings with rules, avoiding repetitions.
 
-### UnixCommand 
+### UnixCommand
 
 *Vincent Le Geoff 2017*
 
@@ -227,19 +236,19 @@ Add commands with UNIX-style syntax.
 
 Contribs not meant to be used as-is, but just as examples to learn from.
 
-### GenderSub 
+### GenderSub
 
 *Griatch 2015*
 
 Simple example (only) of storing gender on a character and access it in an emote with a custom marker.
 
-### Talking NPC 
+### Talking NPC
 
 *Griatch 2011*
 
 A talking NPC object that offers a menu-driven conversation tree.
 
-### Tutorial examples 
+### Tutorial examples
 
 *Griatch 2011, 2015*
 
@@ -259,12 +268,12 @@ The Evennia single-player sole quest. Made to be analyzed to learn.
 
 Full game-dir replacement systems.
 
-### Ainneve 
+### Ainneve
 
 *Evennia community 2015-?*
 
-This is a community attempt to make an Evennia 'example game' using good practices. It is also a good 
-place to jump in if you want to help in another project rather than run it alone. Development of this 
+This is a community attempt to make an Evennia 'example game' using good practices. It is also a good
+place to jump in if you want to help in another project rather than run it alone. Development of this
 has stalled a bit so we are looking for enthusiastic people to lead the charge.
 
 - [evennia/ainneve repository](https://github.com/evennia/ainneve)
@@ -274,26 +283,26 @@ has stalled a bit so we are looking for enthusiastic people to lead the charge.
 
 *Tehom 2019*
 
-Open source code release of the popular Evennia-based [Arx, after the reckoning](https://play.arxgame.org/). 
-This is a fantasy game with a focus on roleplay and code-supported political intrigue. This code-release 
+Open source code release of the popular Evennia-based [Arx, after the reckoning](https://play.arxgame.org/).
+This is a fantasy game with a focus on roleplay and code-supported political intrigue. This code-release
 is maintained by Tehom in its own repository so bug reports should be directed there.
 
 - [Arxcode repository on github](https://github.com/Arx-Game/arxcode)
 - [Arxcode issue tracker](https://github.com/Arx-Game/arxcode/issues)
-- [Arxcode installation help](./Arxcode-installing-help) - this may not always be fully up-to-date with 
+- [Arxcode installation help](./Arxcode-installing-help) - this may not always be fully up-to-date with
   latest Evennia. Report your findings!
-  
-### Evscaperoom 
+
+### Evscaperoom
 
 *Griatch 2019*
 
-A full engine for making multiplayer 'escape-rooms' completely in code. 
-This is based on the 2019 MUD Game jam winner *Evscaperoom*. 
+A full engine for making multiplayer 'escape-rooms' completely in code.
+This is based on the 2019 MUD Game jam winner *Evscaperoom*.
 
 - [contrib/evscaperoom](api:evennia.contrib.evscaperoom) - game engine to make your own escape rooms.
-- [https://demo.evennia.com](https://demo.evennia.com) - a full installation of the original game can 
+- [https://demo.evennia.com](https://demo.evennia.com) - a full installation of the original game can
   be played by entering the *evscaperoom* exit in the first Limbo room.
-- https://github.com/Griatch/evscaperoom - the original game's source code (warning for spoilers if you 
+- https://github.com/Griatch/evscaperoom - the original game's source code (warning for spoilers if you
   want to solve the puzzles and mystery yourself).
 
 
@@ -303,7 +312,7 @@ This is based on the 2019 MUD Game jam winner *Evscaperoom*.
     :hidden:
 
     ./Crafting
-    ../api/evennia.contrib.crafting.crafting 
+    ../api/evennia.contrib.crafting.crafting
     ../api/evennia.contrib.crafting.example_recipes
     ./A-voice-operated-elevator-using-events
     ./Dialogues-in-events

docs/source/Contribs/XYZGrid.md

@@ -1,4 +1,4 @@
-# XYZGrid contribution
+# XYZGrid contrib
 
 ```versionadded:: 1.0
 ```
@@ -7,8 +7,10 @@ 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).
+range). Grid-management is done outside of the game using a new evennia-launcher
+option.
 
+<script id="asciicast-Zz36JuVAiPF0fSUR09Ii7lcxc" src="https://asciinema.org/a/Zz36JuVAiPF0fSUR09Ii7lcxc.js" async></script>
 
 ```
 #-#-#-#   #
@@ -36,8 +38,6 @@ Exits: northeast and east
 
 ```
 
-
-
 ## Installation
 
 1. Import and add the `evennia.contrib.commands.XYZGridCmdSet` to the
@@ -406,10 +406,10 @@ 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.
+- [MapNode](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapNode)
+  is the base class for all nodes.
+- [MapLink](api:evennia.contrib.xyzgrid.xymap_legend#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.
@@ -421,7 +421,7 @@ 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)
+[MapNode](api:evennia.contrib.xyzgrid.xymap_legend#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
@@ -449,7 +449,7 @@ class (see class doc for hook methods):
   useful for various reasons, mostly map-transitions).
 
 Some useful properties of the
-[MapLink](api:evennia.contrib.xyzgrid.xymap_legend#MapLink)
+[MapLink](api:evennia.contrib.xyzgrid.xymap_legend#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
@@ -1207,11 +1207,50 @@ Useful (extra) properties on `XYZRoom`, `XYZExit`:
   `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.
+- `xyz_destination` (only for `XYZExits`) - this gives the xyz-coordinate of
+  the exit's destination.
 
-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).
+The coordinates are stored as [Tags](../Components/Tags) where both rooms and exits tag
+categories `room_x_coordinate`, `room_y_coordinate` and `room_z_coordinate`
+while exits use the same in addition to tags for their destination, with tag
+categories `exit_dest_x_coordinate`, `exit_dest_y_coordinate` and
+`exit_dest_z_coordinate`.
+
+The make it easier to query the database by coordinates, each typeclass offers
+custom manager methods. The filter methods allow for `'*'` as a wildcard.
+
+```python
+
+# find a list of all rooms in map foo
+rooms = XYZRoom.objects.filter_xyz(('*', '*', 'foo'))
+
+# find list of all rooms with name "Tunnel" on map foo
+rooms = XYZRoom.objects.filter_xyz(('*', '*', 'foo'), db_key="Tunnel")
+
+# find all rooms in the first column of map footer
+rooms = XYZRoom.objects.filter_xyz((0, '*', 'foo'))
+
+# find exactly one room at given coordinate (no wildcards allowed)
+room = XYZRoom.objects.get_xyz((13, 2, foo))
+
+# find all exits in a given room
+exits = XYZExit.objects.filter_xyz((10, 4, foo))
+
+# find all exits pointing to a specific destination (from all maps)
+exits = XYZExit.objects.filter_xyz_exit(xyz_destination=(13,5,'bar'))
+
+# find exits from a room to anywhere on another map
+exits = XYZExit.objects.filter_xyz_exit(xyz=(1, 5, 'foo'), xyz_destination=('*', '*', 'bar'))
+
+# find exactly one exit to specific destination (no wildcards allowed)
+exit = XYZExit.objects.get_xyz_exit(xyz=(0, 12, 'foo'), xyz_destination=(5, 2, 'foo'))
+
+```
+
+You can customize the XYZRoom/Exit by having the grid spawn your own subclasses
+of them. To do this you need to override the prototype used to spawn rooms on
+the grid. Easiest is to modify the base prototype-parents in settings (see the
+[Extending the base prototypes](#extending-the-base-prototypes) section above).
 
 ## Working with the grid
 

docs/source/api/evennia.contrib.rst

@@ -52,3 +52,4 @@ evennia.contrib
    evennia.contrib.turnbattle
    evennia.contrib.tutorial_examples
    evennia.contrib.tutorial_world
+   evennia.contrib.xyzgrid

docs/source/api/evennia.contrib.xyzgrid.commands.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.commands 
+=======================================
+
+.. automodule:: evennia.contrib.xyzgrid.commands
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.example.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.example 
+======================================
+
+.. automodule:: evennia.contrib.xyzgrid.example
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.launchcmd.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.launchcmd 
+========================================
+
+.. automodule:: evennia.contrib.xyzgrid.launchcmd
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.prototypes.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.prototypes 
+=========================================
+
+.. automodule:: evennia.contrib.xyzgrid.prototypes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.rst

@@ -0,0 +1,23 @@
+evennia.contrib.xyzgrid 
+===============================
+
+.. automodule:: evennia.contrib.xyzgrid
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+.. toctree::
+   :maxdepth: 6
+
+   evennia.contrib.xyzgrid.commands
+   evennia.contrib.xyzgrid.example
+   evennia.contrib.xyzgrid.launchcmd
+   evennia.contrib.xyzgrid.prototypes
+   evennia.contrib.xyzgrid.tests
+   evennia.contrib.xyzgrid.utils
+   evennia.contrib.xyzgrid.xymap
+   evennia.contrib.xyzgrid.xymap_legend
+   evennia.contrib.xyzgrid.xyzgrid
+   evennia.contrib.xyzgrid.xyzroom

docs/source/api/evennia.contrib.xyzgrid.tests.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.tests 
+====================================
+
+.. automodule:: evennia.contrib.xyzgrid.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.utils.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.utils 
+====================================
+
+.. automodule:: evennia.contrib.xyzgrid.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.xymap.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.xymap 
+====================================
+
+.. automodule:: evennia.contrib.xyzgrid.xymap
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.xymap_legend.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.xymap\_legend 
+============================================
+
+.. automodule:: evennia.contrib.xyzgrid.xymap_legend
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.xyzgrid.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.xyzgrid 
+======================================
+
+.. automodule:: evennia.contrib.xyzgrid.xyzgrid
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.xyzgrid.xyzroom.rst

@@ -0,0 +1,7 @@
+evennia.contrib.xyzgrid.xyzroom 
+======================================
+
+.. automodule:: evennia.contrib.xyzgrid.xyzroom
+   :members:
+   :undoc-members:
+   :show-inheritance:

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)