From 8e10db5dca8686f12ca80a16dbb6803157633c78 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sat, 23 Sep 2023 22:23:38 +0200 Subject: [PATCH] Expand command-add tutorial. Fix typos. Resolve #3277 --- CHANGELOG.md | 2 + docs/source/Coding/Changelog.md | 14 ++++ .../Beginner-Tutorial-Adding-Commands.md | 67 ++++++++++++++++--- .../Part3/Beginner-Tutorial-Objects.md | 12 ++-- ...nia.contrib.tutorials.evadventure.tests.md | 1 + 5 files changed, 81 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5f2b1c717..84a8afba69 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index b1871540d5..84a8afba69 100644 --- a/docs/source/Coding/Changelog.md +++ b/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 diff --git a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md index 3b1c562534..8a166c32af 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md +++ b/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: diff --git a/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Objects.md b/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Objects.md index 55090dc0c4..a1ffb51526 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Objects.md +++ b/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""" diff --git a/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md b/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md index 78fb3c7812..3c4466534e 100644 --- a/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md +++ b/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