Fix issue in sittable-object tutorial

docs/source/Coding/Changelog.md

@@ -2,10 +2,19 @@
 
 ## Main
 
+- Feature: Add `fly/dive` commands to `XYZGrid` contrib to showcase treating its
+  Z-axis as a full 3D grid. Also fixed minor bug in `XYZGrid` contrib when using
+  a Z axis named using an integer rather than a string.
+- Bug fix: `$an()` inlinefunc didn't understand to use 'an' words starting with a
+  capital vowel
+- Bug fix: Another case of the 'duplicate Discord bot connections' bug
+
+## Evennia 1.1.1
+
 - Bug fix: Better handler malformed alias-regex given to nickhandler. A
   regex-relevant character in a channel alias could cause server to not restart.
-- Add `attr` keyword to `create_channel`. This allows setting attributes on
-  channels at creation, also from `DEFAULT_CHANNELS` definitions.
+- Feature: Add `attr` keyword to `create_channel`. This allows setting
+  attributes on channels at creation, also from `DEFAULT_CHANNELS` definitions.
 
 ## Evennia 1.1.0
 Jan 7, 2023

docs/source/Contribs/Contrib-XYZGrid.md

@@ -310,24 +310,102 @@ 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.
+Each XYMap on the grid has a Z-coordinate which usually can be treated just as
+the name of the map. The Z-coordinate can be either a string or an integer, and must
+be unique across the entire grid. It is added as the key 'zcoord' to `XYMAP_DATA`.
 
 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`.
+of Blackhaven`. But you could also name it -1, 0, 1, 2, 3 if you wanted.
+
+Pathfinding happens only within each XYMap (up/down is normally 'faked' by moving
+sideways to a new area of the XY plane).
+
+#### A true 3D map
+
+Even for the most hardcore of sci-fi space game, consider sticking to 2D
+movement. It's hard enough for players to visualize a 3D volume with graphics.
+In text it's even harder.
+
+That said, if you want to set up a true X, Y, Z 3D coordinate system (where
+you can move up/down from every point), you can do that too.
+
+This contrib provides an example command `commands.CmdFlyAndDive` that provides the player
+with the ability to use `fly` and `dive` to move straight up/down between Z
+coordinates. Just add it (or its cmdset `commands.XYZGridFlyDiveCmdSet`) to your
+Character cmdset and reload to try it out.
+
+For the fly/dive to work you need to build your grid as a 'stack' of XY-grid maps
+and name them by their Z-coordinate as an integer. The fly/dive actions will
+only work if there is actually a matching room directly above/below.
+
+> Note that since pathfinding only works within each XYmap, the player will not
+> be able to include fly/dive in their autowalking - this is always a manual
+> action.
+
+As an example, let's assume coordinate `(1, 1, -3)`
+is the bottom of a deep well leading up to the surface (at level 0)
+
+```
+LEVEL_MINUS_3 = r"""
++ 0 1
+
+1   #
+    |
+0 #-#
+
++ 0 1
+"""
+
+LEVEL_MINUS_2 = r"""
++ 0 1
+
+1   #
+
+0
+
++ 0 1
+"""
+
+LEVEL_MINUS_1 = r"""
++ 0 1
+
+1   #
+
+0
+
++ 0 1
+"""
+
+LEVEL_0 = r"""
++ 0 1
+
+1 #-#
+  |x|
+0 #-#
+
++ 0 1
+"""
+
+XYMAP_DATA_LIST = [
+    {"zcoord": -3, "map": LEVEL_MINUS_3},
+    {"zcoord": -2, "map": LEVEL_MINUS_2},
+    {"zcoord": -1, "map": LEVEL_MINUS_1},
+    {"zcoord": 0, "map": LEVEL_0},
+]
+```
+
+In this example, if we arrive to the bottom of the well at `(1, 1, -3)` we
+`fly` straight up three levels until we arrive at `(1, 1, 0)`, at the corner
+of some sort of open field.
+
+We can dive down from `(1, 1, 0)`. In the default implementation you must `dive` 3 times
+to get to the bottom. If you wanted you could tweak the command so you
+automatically fall to the bottom and take damage etc.
+
+We can't fly/dive up/down from any other XY positions because there are no open rooms at the
+adjacent Z coordinates.
+
 
 ### Map String
 

docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Making-A-Sittable-Object.md

@@ -447,7 +447,7 @@ class CmdStand(Command):
      Stand up.
      """
      key = "stand"
-     lock = "cmd:sitsonthis()"
+     locks = "cmd:sitsonthis()"
 
      def func(self):
          self.obj.do_stand(self.caller)
@@ -471,7 +471,7 @@ def sitsonthis(accessing_obj, accessed_obj, *args, **kwargs):
     """
     True if accessing_obj is sitting on/in the accessed_obj.
     """
-    return accessed_obj.db.sitting == accessing_obj
+    return accessed_obj.obj.db.sitting == accessing_obj
 
 # ...
 ```
@@ -486,7 +486,7 @@ Evennia provides a large number of default lockfuncs, such as checking permissio
 ```
 
 - `accessing_obj` is the one trying to access the lock. So us, in this case.
-- `accessed_obj` is the entity we are trying to gain a particular type of access to. So the chair.
+- `accessed_obj` is the entity we are trying to gain a particular type of access to. Since we define the lock on the `CmdStand` class, this is _the command instance_. We are however not interested in that, but the object the command is assigned to (the chair). The object is available on the Command as `.obj`. So here, `accessed_obj.obj` is the chair. 
 - `args` is a tuple holding any arguments passed to the lockfunc. Since we use `sitsondthis()` this will be empty (and if we add anything, it will be ignored).
 - `kwargs` is a tuple of keyword arguments passed to the lockfuncs. This will be empty as well in our example.
 
@@ -519,7 +519,7 @@ The make the following changes:
 
 This disables the on-object command solution so we can try an alternative. Make sure to `reload` so the changes are known to Evennia.
 
-In this variation we will put the `sit` and `stand` commands on the `Character` instead of on the chair. This makes some things easier, but makes the Commands themselves more complex because they will not know which chair to sit on. We can't just do `sit` anymore. This is how it will work.
+In this variation we will put the `sit` and `stand` commands on the `Character` instead of on the chair. This makes some things easier, but makes the Commands themselves more complex because they will not know which chair to sit on. We can't just do `sit` anymore. This is how it will work:
 
     > sit <chair>
     You sit on chair.