Add XYZgrid contrib api files, prepare for merge

CHANGELOG.md

@@ -72,6 +72,8 @@ Up requirements to Django 3.2+
 - Make `help` index output clickable for webclient/clients with MXP (PR by davewiththenicehat)
 - Custom `evennia` launcher commands (e.g. `evennia mycmd foo bar`). Add new commands as callables
   accepting `*args`, as `settings.EXTRA_LAUNCHER_COMMANDS = {'mycmd': 'path.to.callable', ...}`.
+- New `XYZGrid` contrib, adding x,y,z grid coordinates with in-game map and
+  pathfinding. Controlled outside of the game via custom evennia launcher command.
 
 ### Evennia 0.9.5 (2019-2020)
 

docs/source/Contribs/Contrib-Overview.md

@@ -39,6 +39,15 @@ Advanced descriptions combined from many separate description components, inspir
 
 Contribs modifying locations, movement or helping to creating rooms.
 
+### 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*

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
+- [MapNode](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapNode)
-  class for all nodes.
+  is the base class for all nodes.
-- [MapLink](api:evennia.contrib.xyzgrid.xymap_legend#MapLink) is the base
+- [MapLink](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapLink)
-  class for all links.
+  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 coordinates are stored as [Tags](../Components/Tags) where both rooms and exits tag
-the prototype used to spawn rooms on the grid. You can modify the base prototype
+categories `room_x_coordinate`, `room_y_coordinate` and `room_z_coordinate`
-parents in settings (see the [Extending the base prototypes](#extending-the-base-prototypes)
+while exits use the same in addition to tags for their destination, with tag
-section above).
+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)

evennia/contrib/xyzgrid/launchcmd.py

@@ -22,8 +22,8 @@ from evennia.utils import ansi
 from evennia.contrib.xyzgrid.xyzgrid import get_xyzgrid
 
 _HELP_SHORT = """
-evennia xyzgrid help|list|init|add|spawn|initpath|delete [<options>]
+evennia xyzgrid help | list | init | add | spawn | initpath | delete [<options>]
-Manages the XYZ grid. Use 'xyzgrid help <option>' for documentation.
+ Manages the XYZ grid. Use 'xyzgrid help <option>' for documentation.
 """
 
 _HELP_HELP = """
@@ -198,7 +198,7 @@ def _option_list(*suboptions):
             print(ansi.parse_ansi(str(xymap)))
         return
 
-    for zcoord in suboptions:
+    zcoord = " ".join(suboptions)
     xymap = xyzgrid.get_map(zcoord)
     if not xymap:
         print(f"No XYMap with Z='{zcoord}' was found on grid.")
@@ -401,8 +401,8 @@ def xyzcommand(*args):
         _option_init(*suboptions)
     elif option == 'add':
         _option_add(*suboptions)
-    elif option == 'build':
+    elif option == 'spawn':
-        _option_build(*suboptions)
+        _option_spawn(*suboptions)
     elif option == 'initpath':
         _option_initpath(*suboptions)
     elif option == 'delete':

evennia/contrib/xyzgrid/xymap_legend.py

@@ -1,10 +1,12 @@
 """
-# Map legend comhponents
+# Map legend components
 
 Each map-legend component is either a 'mapnode' - something that represents and actual in-game
 location (usually a room) or a 'maplink' - something connecting nodes together. The start of a link
 usually shows as an Exit, but the length of the link has no in-game equivalent.
 
+----
+
 """
 
 try:

evennia/contrib/xyzgrid/xyzgrid.py

@@ -105,12 +105,6 @@ class XYZGrid(DefaultScript):
         kwargs['db_key'] = name
         return XYZExit.objects.filter_xyz_exit(xyz=xyz, **kwargs)
 
-    def build_diff(zcoord):
-        """
-        Find out which rooms are built/not built and if some should be deleted. This
-
-        """
-
     def maps_from_module(self, module_path):
         """
         Load map data from module. The loader will look for a dict XYMAP_DATA or a list of

evennia/contrib/xyzgrid/xyzroom.py

@@ -81,8 +81,8 @@ class XYZManager(ObjectManager):
             XYRoom: A single room instance found at the combination of x, y and z given.
 
         Raises:
-            DoesNotExist: If no matching query was found.
+            XYZRoom.DoesNotExist: If no matching query was found.
-            MultipleObjectsReturned: If more than one match was found (which should not
+            XYZRoom.MultipleObjectsReturned: If more than one match was found (which should not
                 possible with a unique combination of x,y,z).
 
         """
@@ -189,8 +189,8 @@ class XYZExitManager(XYZManager):
             XYZExit: A single exit instance found at the combination of x, y and xgiven.
 
         Raises:
-            DoesNotExist: If no matching query was found.
+            XYZExit.DoesNotExist: If no matching query was found.
-            MultipleObjectsReturned: If more than one match was found (which should not
+            XYZExit.MultipleObjectsReturned: If more than one match was found (which should not
                 be possible with a unique combination of x,y,x).
 
         Notes:

evennia/server/serversession.py

@@ -206,6 +206,7 @@ class ServerSession(_BASE_SESSION_CLASS):
 
         """
         flags = self.protocol_flags
+        print("session flags:", flags)
         width = flags.get("SCREENWIDTH", {}).get(0, settings.CLIENT_DEFAULT_WIDTH)
         height = flags.get("SCREENHEIGHT", {}).get(0, settings.CLIENT_DEFAULT_HEIGHT)
         return width, height