Expand command-add tutorial. Fix typos. Resolve #3277

CHANGELOG.md

@@ -7,6 +7,8 @@
   instead of 'Custom' (InspectorCaracal)
 - [Fix][pull3274]: Traceback when creating objects with initial nattributes
   (InspectorCaracal)
+- Docs: Typo fixes and starting earlier with explaining how to add to the
+  default cmdsets.
 
 [pull3267]: https://github.com/evennia/evennia/pull/3267
 [pull3270]: https://github.com/evennia/evennia/pull/3270

docs/source/Coding/Changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Main branch
+
+- [Fix][pull3267]: Missing recache step in ObjectSessionHandler (InspectorCaracal)
+- [Fix][pull3270]: Evennia is its own MSSP family now, so we should return that
+  instead of 'Custom' (InspectorCaracal)
+- [Fix][pull3274]: Traceback when creating objects with initial nattributes
+  (InspectorCaracal)
+- Docs: Typo fixes and starting earlier with explaining how to add to the
+  default cmdsets.
+
+[pull3267]: https://github.com/evennia/evennia/pull/3267
+[pull3270]: https://github.com/evennia/evennia/pull/3270
+[pull3274]: https://github.com/evennia/evennia/pull/3274
+
 ## Evennia 2.3.0
 
 Sept 3, 2023

docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md

@@ -66,6 +66,7 @@ Next we need to put this in a CmdSet. It will be a one-command CmdSet for now! C
 
 
 ```python
+# in mygame/commands/mycommands.py
 
 from commands.command import Command
 from evennia import CmdSet
@@ -137,6 +138,7 @@ These are all properties you can access with `.` on the Command instance, such a
 The reason our command doesn't do anything yet is because it's missing a `func` method. This is what Evennia looks for to figure out what a Command actually does. Modify your `CmdEcho` class:
 
 ```python
+# in mygame/commands/mycommands.py
 # ...
 
 class CmdEcho(Command):
@@ -175,14 +177,10 @@ Try to pass an argument:
     > echo Woo Tang!
     Echo: ' Woo Tang!'
 
-Note that there is an extra space before `Woo!`. That is because self.args contains _everything_ after the command name, including spaces. Evennia will happily understand if you skip that space too:
-
-    > echoWoo Tang!
-    Echo: 'Woo Tang!'
-
-There are ways to force Evennia to _require_ an initial space, but right now we want to just ignore it since it looks a bit weird for our echo example. Tweak the code:
+Note that there is an extra space before `Woo`. That is because self.args contains _everything_ after the command name, including spaces. Let's remove that extra space with a small tweak:
 
 ```python
+# in mygame/commands/mycommands.py
 # ...
 
 class CmdEcho(Command):
@@ -221,13 +219,64 @@ enough to make `echo` a _persistent_ change though:
 
     > py self.cmdset.add("commands.mycommands.MyCmdSet", persistent=True)
 
-Now you can `reload` as much as you want and your code changes will be available directly without
-needing to re-add the MyCmdSet again. To remove the cmdset again, you'd do
+Now you can `reload` as much as you want and your code changes will be available directly without needing to re-add the MyCmdSet again. 
+
+We will add this cmdset in another way, so remove it manually: 
 
     > py self.cmdset.remove("commands.mycommands.MyCmdSet")
 
-But for now, keep it around, we'll expand it with some more examples.
+## Add the echo command to the default cmdset 
 
+Above we added the `echo` command to ourselves. It will _only_ be available to us and noone else in the game. But all commands in Evennia are part of command-sets, including the normal `look` and `py` commands we have been using all the while. You can easily extend the default command set with your `echo` command - this way _everyone_ in the game will have access to it! 
+
+In `mygame/commands/` you'll find an existing module named `default_cmdsets.py` Open it and you'll find four empty cmdset-classes: 
+
+- `CharacterCmdSet` - this sits on all Characters (this is the one we usually want to modify)
+- `AccountCmdSet` - this sits on all Accounts (shared between Characters, like `logout` etc)
+- `UnloggedCmdSet` - commands available _before_ you login, like the commands for creating your password and connecting to the game.
+- `SessionCmdSet` - commands unique to your Session (your particular client connection). This is unused by default.
+
+Tweak this file as follows:
+
+```python
+# in mygame/commands/default_cmdsets.py 
+
+# ,.. 
+
+from .mycommands import CmdEcho    # <-------  
+
+class CharacterCmdSet(default_cmds.CharacterCmdSet):
+    """
+    The `CharacterCmdSet` contains general in-game commands like `look`,
+    `get`, etc available on in-game Character objects. It is merged with
+    the `AccountCmdSet` when an Account puppets a Character.
+    """
+ 
+    key = "DefaultCharacter"
+ 
+    def at_cmdset_creation(self):
+        """
+        Populates the cmdset
+        """
+        super().at_cmdset_creation()
+        #
+        # any commands you add below will overload the default ones.
+        #
+        self.add(command.CmdEcho)    # <-----------
+
+# ... 
+```
+
+```{sidebar} super() and overriding defaults
+The `super()` Python keyword means that the _parent_ is called. In this case, the parent adds all default commands to this cmdset.  
+
+Coincidentally, this is also how you replace default commands in Evennia!jj To replace e.g. the command `get`, you just give your replacement command the `key` 'get' and add it here - since it's added after `super()`, it will replace the default version of `get`.
+```
+This works the same way as when you added `CmdEcho` to your `MyCmdSet`. The only difference cmdsets are automatically added to all Characters/Accounts etc so you don't have to do so manually. We must also make sure to import the `CmdEcho` from your `mycommands` module in order for this module to know about it. The period `.` in  `from .mycommands import ...` means that we are telling Python that `mycommands.py` sits in the same directory as this current module. 
+
+Just `reload` the server and your `echo` command will be available again. There is no limit to how many cmdsets a given Command can be a part of. 
+
+To remove, you just comment out or delete the `self.add()` line. Keep it like this for now though - we'll expand on it below. 
 ### Figuring out who to hit
 
 Let's try something a little more exciting than just echo. Let's make a `hit` command, for punching someone in the face! This is how we want it to work:

docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Objects.md

@@ -247,10 +247,10 @@ class EvAdventureWeapon(EvAdventureObject):
     inventory_use_slot = AttributeProperty(WieldLocation.WEAPON_HAND, autocreate=False)
     quality = AttributeProperty(3, autocreate=False)
     
-    attack_type = AttibuteProperty(Ability.STR, autocreate=False)
-    defend_type = AttibuteProperty(Ability.ARMOR, autocreate=False)
+    attack_type = AttributeProperty(Ability.STR, autocreate=False)
+    defend_type = AttributeProperty(Ability.ARMOR, autocreate=False)
     
-    damage_roll = AttibuteProperty("1d6", autocreate=False)
+    damage_roll = AttributeProperty("1d6", autocreate=False)
 
 
 def at_pre_use(self, user, target=None, *args, **kwargs):
@@ -386,10 +386,10 @@ class EvAdventureRuneStone(EvAdventureWeapon, EvAdventureConsumable):
     inventory_use_slot = WieldLocation.TWO_HANDS  # always two hands for magic
     quality = AttributeProperty(3, autocreate=False)
 
-    attack_type = AttibuteProperty(Ability.INT, autocreate=False)
-    defend_type = AttibuteProperty(Ability.DEX, autocreate=False)
+    attack_type = AttributeProperty(Ability.INT, autocreate=False)
+    defend_type = AttributeProperty(Ability.DEX, autocreate=False)
     
-    damage_roll = AttibuteProperty("1d8", autocreate=False)
+    damage_roll = AttributeProperty("1d8", autocreate=False)
 
     def at_post_use(self, user, *args, **kwargs):
         """Called after usage/spell was cast""" 

docs/source/api/evennia.contrib.tutorials.evadventure.tests.md

@@ -13,6 +13,7 @@ evennia.contrib.tutorials.evadventure.tests
    :maxdepth: 6
 
    evennia.contrib.tutorials.evadventure.tests.mixins
+   evennia.contrib.tutorials.evadventure.tests.test_ai
    evennia.contrib.tutorials.evadventure.tests.test_characters
    evennia.contrib.tutorials.evadventure.tests.test_chargen
    evennia.contrib.tutorials.evadventure.tests.test_combat