From 22067c32dc76cef8a423c261d77ea9c1752cc309 Mon Sep 17 00:00:00 2001 From: Griatch Date: Mon, 1 Apr 2024 14:50:43 +0200 Subject: [PATCH] Fix the adding-command tutorial with correct example --- docs/source/Coding/Changelog.md | 12 +++ .../Beginner-Tutorial-Adding-Commands.md | 98 ++++++++----------- 2 files changed, 55 insertions(+), 55 deletions(-) diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index 980dcc8c8a..a40a4871a0 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -9,6 +9,11 @@ category after it was created (chiizujin) - [Feature][pull3467]: Add `alias/delete` switch for removing object aliases from in-game with default command (chiizujin) +- [Feature][issue3450]: The default `page` command now tags its `Msg` objects + with tag 'page' (category 'comms') and also checks the `Msg`' 'read' lock. + made backwards compatible for old pages (Griatch) +- Feature: Clean up the default Command variable list shown when a command has + no `func()` defined (Griatch) - [Fix][pull3446]: Use plural ('no apples') instead of singular ('no apple') in `get_numbered_name` for better grammatical form (InspectorCaracal) - [Fix][pull3453]: Object aliases not showing in search multi-match @@ -26,6 +31,10 @@ way (chiizujin) - [Fix][pull3464]: EvEditor range:range specification didn't return correct range (chiizujin) +- [Fix][issue3462]: EvEditor :UU and :DD etc commands were not properly + differentiating from their lower-case alternatives (Griatch) +- [Fix][issue3460]: The `menu_login` contrib regression caused it to error out + when creating a new character (Griatch) - Doc: Added Beginner Tutorial lessons for AI, Quests and Procedural dungeon (Griatch) - Doc fixes (Griatch, InspectorCaracal) @@ -41,6 +50,9 @@ [pull3463]: https://github.com/evennia/evennia/pull/3463 [pull3464]: https://github.com/evennia/evennia/pull/3464 [pull3467]: https://github.com/evennia/evennia/pull/3467 +[issue3450]: https://github.com/evennia/evennia/issues/3450 +[issue3462]: https://github.com/evennia/evennia/issues/3462 +[issue3460]: https://github.com/evennia/evennia/issues/3460 ## Evennia 4.0.0 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 5d9d3f6e2c..fba93441f7 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 @@ -91,47 +91,34 @@ The `me.cmdset` is the store of all cmdsets stored on us. By giving the path to Now try > echo - Command echo has no defined `func()` - showing on-command variables: - ... - ... + Command "echo" has no defined `func()`. Available properties ... + ...(lots of stuff)... -`echo` works! You should be getting a long list of outputs. The reason for this is that your `echo` function is not really "doing" anything yet and the default function is then to show all useful resources available to you when you use your Command. Let's look at some of those listed: +`echo` works! You should be getting a long list of outputs. Your `echo` function is not really "doing" anything yet and the default function is then to show all useful resources available to you when you use your Command. Let's look at some of those listed: - Command echo has no defined `func()` - showing on-command variables: - obj (): YourName - lockhandler (): cmd:all() - caller (): YourName - cmdname (): echo - raw_cmdname (): echo - cmdstring (): echo - args (): - cmdset (): @mail, about, access, accounts, addcom, alias, allcom, ban, batchcode, batchcommands, boot, cboot, ccreate, - cdesc, cdestroy, cemit, channels, charcreate, chardelete, checklockstring, clientwidth, clock, cmdbare, cmdsets, color, copy, cpattr, create, cwho, delcom, - desc, destroy, dig, dolphin, drop, echo, emit, examine, find, force, get, give, grapevine2chan, help, home, ic, inventory, irc2chan, ircstatus, link, lock, - look, menutest, mudinfo, mvattr, name, nick, objects, ooc, open, option, page, password, perm, pose, public, py, quell, quit, reload, reset, rss2chan, say, - script, scripts, server, service, sessions, set, setdesc, sethelp, sethome, shutdown, spawn, style, tag, tel, test2010, test2028, testrename, testtable, - tickers, time, tunnel, typeclass, unban, unlink, up, up, userpassword, wall, whisper, who, wipe - session (): Griatch(#1)@1:2:7:.:0:.:0:.:1 - account (): Griatch(account 1) - raw_string (): echo - - -------------------------------------------------- - echo - Command variables from evennia: - -------------------------------------------------- - name of cmd (self.key): echo - cmd aliases (self.aliases): [] - cmd locks (self.locks): cmd:all(); - help category (self.help_category): General - object calling (self.caller): Griatch - object storing cmdset (self.obj): Griatch - command string given (self.cmdstring): echo - current cmdset (self.cmdset): ChannelCmdSet +``` +Command "echo" has no defined `func()` method. Available properties on this command are: + self.key (): "echo" + self.cmdname (): "echo" + self.raw_cmdname (): "echo" + self.raw_string (): "echo +" + self.aliases (): [] + self.args (): "" + self.caller (): YourName + self.obj (): YourName + self.session (): YourName(#1)@1:2:7:.:0:.:0:.:1 + self.locks (): "cmd:all();" + self.help_category (): "general" + self.cmdset (... a long list of commands ...) +``` These are all properties you can access with `.` on the Command instance, such as `.key`, `.args` and so on. Evennia makes these available to you and they will be different every time a command is run. The most important ones we will make use of now are: - `caller` - this is 'you', the person calling the command. - - `args` - this is all arguments to the command. Now it's empty, but if you tried `echo foo bar` you'd find that this would be `" foo bar"`. + - `args` - this is all arguments to the command. Now it's empty, but if you tried `echo foo bar` you'd find that this would be `" foo bar"` (including the extra space between `echo` and `foo` that you may want to strip away). - `obj` - this is object on which this Command (and CmdSet) "sits". So you, in this case. + - `raw_string` is not commonly used, but it's the completely unmodified input from the user. It even includes the line break used to send to the command to the server (that's why the end-quotes appear on the next line). 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: @@ -297,6 +284,8 @@ And Bob would see Still in `mygame/commands/mycommands.py`, add a new class, between `CmdEcho` and `MyCmdSet`. ```{code-block} python +:linenos: +:emphasize-lines: 5,6,13,16,19,20,21,23 # in mygame/commands/mycommands.py # ... @@ -321,18 +310,17 @@ class CmdHit(Command): return self.caller.msg(f"You hit {target.key} with full force!") target.msg(f"You got hit by {self.caller.key} with full force!") -# ... +# ... ``` A lot of things to dissect here: -- **Line 3**: The normal `class` header. We inherit from `Command` which we imported at the top of this file. -- **Lines 4-10**: The docstring and help-entry for the command. You could expand on this as much as you wanted. -- **Line 11**: We want to write `hit` to use this command. -- **Line 14**: We strip the whitespace from the argument like before. Since we don't want to have to do `self.args.strip()` over and over, we store the stripped version in a _local variable_ `args`. Note that we don't modify `self.args` by doing this, `self.args` will still have the whitespace and is not the same as `args` in this example. +- **Line 5**: The normal `class` header. We inherit from `Command` which we imported at the top of this file. +- **Lines 6-12**: The docstring and help-entry for the command. You could expand on this as much as you wanted. +- **Line 13**: We want to write `hit` to use this command. +- **Line 16**: We strip the whitespace from the argument like before. Since we don't want to have to do `self.args.strip()` over and over, we store the stripped version in a _local variable_ `args`. Note that we don't modify `self.args` by doing this, `self.args` will still have the whitespace and is not the same as `args` in this example. ```{sidebar} if-statements - The full form of the if statement is if condition: @@ -343,9 +331,9 @@ The full form of the if statement is ... There can be any number of `elifs` to mark when different branches of the code should run. If `else` is provided, it will run if none of the other conditions were truthy. - ``` -- **Line 15** has our first _conditional_, an `if` statement. This is written on the form `if :` and only if that condition is 'truthy' will the indented code block under the `if` statement run. To learn what is truthy in Python it's usually easier to learn what is "falsy": + +- **Line 17** has our first _conditional_, an `if` statement. This is written on the form `if :` and only if that condition is 'truthy' will the indented code block under the `if` statement run. To learn what is truthy in Python it's usually easier to learn what is "falsy": - `False` - this is a reserved boolean word in Python. The opposite is `True`. - `None` - another reserved word. This represents nothing, a null-result or value. - `0` or `0.0` @@ -353,12 +341,20 @@ There can be any number of `elifs` to mark when different branches of the code s - Empty _iterables_ we haven't used yet, like empty lists `[]`, empty tuples `()` and empty dicts `{}`. - Everything else is "truthy". -- **Line 16**'s condition is `not args`. The `not` _inverses_ the result, so if `args` is the empty string (falsy), the whole conditional becomes truthy. Let's continue in the code: + The conditional on **Line 16**'s condition is `not args`. The `not` _inverses_ the result, so if `args` is the empty string (falsy), the whole conditional becomes truthy. Let's continue in the code: +```{sidebar} Errors in your code + +With longer code snippets to try, it gets more and more likely you'll +make an error and get a `traceback` when you reload. This will either appear +directly in-game or in your log (view it with `evennia -l` in a terminal). + +Don't panic - tracebacks are your friends! They are to be read bottom-up and usually describe exactly where your problem is. Refer to [The Python introduction lesson](./Beginner-Tutorial-Python-basic-introduction.md) for more hints. If you get stuck, reach out to the Evennia community for help. +``` - **Lines 16-17**: This code will only run if the `if` statement is truthy, in this case if `args` is the empty string. -- **Line 17**: `return` is a reserved Python word that exits `func` immediately. -- **Line 18**: We use `self.caller.search` to look for the target in the current location. -- **Lines 19-20**: A feature of `.search` is that it will already inform `self.caller` if it couldn't find the target. In that case, `target` will be `None` and we should just directly `return`. -- **Lines 21-22**: At this point we have a suitable target and can send our punching strings to each. +- **Line 19**: `return` is a reserved Python word that exits `func` immediately. +- **Line 20**: We use `self.caller.search` to look for the target in the current location. +- **Lines 21-22**: A feature of `.search` is that it will already inform `self.caller` if it couldn't find the target. In that case, `target` will be `None` and we should just directly `return`. +- **Lines 23-24**: At this point we have a suitable target and can send our punching strings to each. Finally we must also add this to a CmdSet. Let's add it to `MyCmdSet`. @@ -374,14 +370,6 @@ class MyCmdSet(CmdSet): ``` -```{sidebar} Errors in your code - -With longer code snippets to try, it gets more and more likely you'll -make an error and get a `traceback` when you reload. This will either appear -directly in-game or in your log (view it with `evennia -l` in a terminal). -Don't panic; tracebacks are your friends - they are to be read bottom-up and usually describe exactly where your problem is. Refer to [The Python introduction lesson](./Beginner-Tutorial-Python-basic-introduction.md) for more hints. If you get stuck, reach out to the Evennia community for help. -``` - Note that since we did `py self.cmdset.remove("commands.mycommands.MyCmdSet")` earlier, this cmdset is no longer available on our Character. Instead we will add these commands directly to our default cmdset. ```python