From e96bbb4b8652d5ce7c1142769a18c36604eb9b40 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sat, 8 Jan 2022 14:40:58 +0100 Subject: [PATCH] Clean up contrib docs, autogeneration --- docs/pylib/contrib_readmes2docs.py | 20 +- .../Concepts/Change-Messages-Per-Receiver.md | 158 +- docs/source/Concepts/Soft-Code.md | 2 +- docs/source/Contribs/Contrib-AWSStorage.md | 8 +- docs/source/Contribs/Contrib-Auditing.md | 16 +- docs/source/Contribs/Contrib-Barter.md | 18 +- .../source/Contribs/Contrib-Batchprocessor.md | 8 +- docs/source/Contribs/Contrib-Bodyfunctions.md | 4 +- docs/source/Contribs/Contrib-Building-Menu.md | 14 +- docs/source/Contribs/Contrib-Clothing.md | 11 +- docs/source/Contribs/Contrib-Color-Markups.md | 5 +- docs/source/Contribs/Contrib-Cooldowns.md | 15 +- docs/source/Contribs/Contrib-Crafting.md | 282 +++- .../Contribs/Contrib-Custom-Gametime.md | 9 +- docs/source/Contribs/Contrib-Dice.md | 8 +- docs/source/Contribs/Contrib-Email-Login.md | 7 +- docs/source/Contribs/Contrib-Evscaperoom.md | 12 +- docs/source/Contribs/Contrib-Extended-Room.md | 9 +- docs/source/Contribs/Contrib-Fieldfill.md | 18 +- docs/source/Contribs/Contrib-Gendersub.md | 2 +- docs/source/Contribs/Contrib-Health-Bar.md | 8 +- ...ontrib-Ingame-Python-Tutorial-Dialogue.md} | 32 +- ...ontrib-Ingame-Python-Tutorial-Elevator.md} | 32 +- docs/source/Contribs/Contrib-Ingame-Python.md | 37 +- docs/source/Contribs/Contrib-Mail.md | 12 +- docs/source/Contribs/Contrib-Mapbuilder.md | 4 +- docs/source/Contribs/Contrib-Menu-Login.md | 8 +- docs/source/Contribs/Contrib-Mirror.md | 4 +- docs/source/Contribs/Contrib-Multidescer.md | 13 +- .../source/Contribs/Contrib-Mux-Comms-Cmds.md | 32 +- docs/source/Contribs/Contrib-Overview.md | 482 +++--- docs/source/Contribs/Contrib-Puzzles.md | 15 +- docs/source/Contribs/Contrib-RPSystem.md | 14 +- .../Contrib-Random-String-Generator.md | 12 +- docs/source/Contribs/Contrib-Red-Button.md | 6 +- docs/source/Contribs/Contrib-Simpledoor.md | 12 +- docs/source/Contribs/Contrib-Slow-Exit.md | 8 +- docs/source/Contribs/Contrib-Talking-Npc.md | 6 +- docs/source/Contribs/Contrib-Traits.md | 6 +- docs/source/Contribs/Contrib-Tree-Select.md | 16 +- docs/source/Contribs/Contrib-Turnbattle.md | 2 +- .../source/Contribs/Contrib-Tutorial-World.md | 9 +- docs/source/Contribs/Contrib-Unixcommand.md | 10 +- docs/source/Contribs/Contrib-Wilderness.md | 6 +- docs/source/Contribs/Contrib-XYZGrid.md | 1336 ++++++++++++++++- docs/source/Contribs/Crafting.md | 222 --- docs/source/Contribs/XYZGrid.md | 1325 ---------------- docs/source/Contributing-Docs.md | 90 +- .../Dynamic-In-Game-Map.md | 83 +- .../Starting/Part1/Building-Quickstart.md | 2 +- .../Part2/Planning-Some-Useful-Contribs.md | 148 +- .../{Contribs => Howto}/Static-In-Game-Map.md | 6 +- docs/source/toc.md | 10 +- .../contrib/base_systems/awsstorage/README.md | 8 +- .../base_systems/building_menu/README.md | 14 +- .../base_systems/color_markups/README.md | 5 +- .../base_systems/custom_gametime/README.md | 9 +- .../base_systems/email_login/README.md | 7 +- .../base_systems/ingame_python/README.md | 37 +- .../contrib/base_systems/menu_login/README.md | 8 +- .../base_systems/mux_comms_cmds/README.md | 32 +- .../base_systems/unixcommand/README.md | 10 +- .../full_systems/evscaperoom/README.md | 12 +- evennia/contrib/game_systems/barter/README.md | 18 +- .../contrib/game_systems/clothing/README.md | 11 +- .../contrib/game_systems/cooldowns/README.md | 15 +- .../contrib/game_systems/crafting/README.md | 282 +++- .../contrib/game_systems/crafting/__init__.py | 4 +- .../contrib/game_systems/gendersub/README.md | 2 +- evennia/contrib/game_systems/mail/README.md | 12 +- .../game_systems/multidescer/README.md | 13 +- .../contrib/game_systems/puzzles/README.md | 15 +- .../contrib/game_systems/turnbattle/README.md | 2 +- evennia/contrib/grid/extended_room/README.md | 9 +- evennia/contrib/grid/mapbuilder/README.md | 4 +- evennia/contrib/grid/simpledoor/README.md | 12 +- evennia/contrib/grid/slow_exit/README.md | 8 +- evennia/contrib/grid/wilderness/README.md | 6 +- evennia/contrib/grid/xyzgrid/README.md | 1336 ++++++++++++++++- evennia/contrib/rpg/dice/README.md | 8 +- evennia/contrib/rpg/health_bar/README.md | 8 +- evennia/contrib/rpg/rpsystem/README.md | 14 +- evennia/contrib/rpg/traits/README.md | 6 +- .../tutorials/batchprocessor/README.md | 8 +- .../contrib/tutorials/bodyfunctions/README.md | 4 +- evennia/contrib/tutorials/mirror/README.md | 4 +- .../contrib/tutorials/red_button/README.md | 6 +- .../contrib/tutorials/talking_npc/README.md | 6 +- .../tutorials/tutorial_world/README.md | 9 +- evennia/contrib/utils/auditing/README.md | 16 +- evennia/contrib/utils/fieldfill/README.md | 18 +- .../utils/random_string_generator/README.md | 12 +- evennia/contrib/utils/tree_select/README.md | 16 +- evennia/utils/gametime.py | 2 +- 94 files changed, 4126 insertions(+), 2536 deletions(-) rename docs/source/Contribs/{Dialogues-in-events.md => Contrib-Ingame-Python-Tutorial-Dialogue.md} (91%) rename docs/source/Contribs/{A-voice-operated-elevator-using-events.md => Contrib-Ingame-Python-Tutorial-Elevator.md} (93%) delete mode 100644 docs/source/Contribs/Crafting.md delete mode 100644 docs/source/Contribs/XYZGrid.md rename docs/source/{Contribs => Howto}/Dynamic-In-Game-Map.md (91%) rename docs/source/{Contribs => Howto}/Static-In-Game-Map.md (98%) diff --git a/docs/pylib/contrib_readmes2docs.py b/docs/pylib/contrib_readmes2docs.py index a37a4b52ff..9c83c8f3b9 100644 --- a/docs/pylib/contrib_readmes2docs.py +++ b/docs/pylib/contrib_readmes2docs.py @@ -72,19 +72,18 @@ Each contrib contains installation instructions for how to integrate it with your other code. If you want to tweak the code of a contrib, just copy its entire folder to your game directory and modify/use it from there. -If you want to contribute yourself, see [here](Contributing)! - > Hint: Additional (potentially un-maintained) code snippets from the community can be found in our discussion forum's [Community Contribs & Snippets](https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets) category. +If you want to contribute yourself, see [here](Contributing)! """ TOCTREE = """ ```{{toctree}} -:depth: 2 {listing} +``` """ @@ -101,11 +100,11 @@ _{category_desc}_ BLURB = """ ### Contrib: `{name}` -{credits} +_{credits}_ {blurb} -[Read the documentation]({filename}) +[Read the documentation](./{filename}) - [Browse the Code](api:{code_location}) """ @@ -121,7 +120,7 @@ INDEX_FOOTER = """ ---- -This document page is auto-generated from the sources. Manual changes +This document page is auto-generated. Manual changes will be overwritten. """ @@ -141,6 +140,8 @@ def readmes2docs(directory=_SOURCE_DIR): # paths are e.g. evennia/contrib/utils/auditing/README.md _, category, name, _ = file_path.rsplit(sep, 3) + pypath = f"evennia.contrib.{category}.{name}" + filename = "Contrib-" + "-".join( _FILENAME_MAP.get( part, part.capitalize() if part[0].islower() else part) @@ -162,7 +163,7 @@ def readmes2docs(directory=_SOURCE_DIR): with open(outfile, 'w') as fil: fil.write(data) - categories[category].append((name, credits, blurb, filename)) + categories[category].append((name, credits, blurb, filename, pypath)) ncount += 1 # build the index with blurbs @@ -179,6 +180,7 @@ def readmes2docs(directory=_SOURCE_DIR): credits=tup[1], blurb=tup[2], filename=tup[3], + code_location=tup[4] ) ) filenames.append(f"Contribs{sep}{tup[3]}") @@ -190,15 +192,13 @@ def readmes2docs(directory=_SOURCE_DIR): ) ) lines.append(TOCTREE.format( - listing="\n".join(filenames)) + listing="\n ".join(filenames)) ) lines.append(INDEX_FOOTER) text = "\n".join(lines) - - with open(_OUT_INDEX_FILE, 'w') as fil: fil.write(text) diff --git a/docs/source/Concepts/Change-Messages-Per-Receiver.md b/docs/source/Concepts/Change-Messages-Per-Receiver.md index ca452f9f52..b1468f4ac2 100644 --- a/docs/source/Concepts/Change-Messages-Per-Receiver.md +++ b/docs/source/Concepts/Change-Messages-Per-Receiver.md @@ -1,71 +1,71 @@ # Sending different messages depending on viewpoint and receiver -Sending messages to everyong in a location is handled by the -[msg_contents](evennia.objects.objects.DefaultObject.msg_contents) method on +Sending messages to everyong in a location is handled by the +[msg_contents](evennia.objects.objects.DefaultObject.msg_contents) method on all [Objects](../Components/Objects.md). It's most commonly called on rooms. -```python +```python room.msg_contents("Anna walks into the room.") ``` -You can also embed references in the string: +You can also embed references in the string: -```python +```python -room.msg_contents("{anna} walks into the room.", - from_obj=caller, +room.msg_contents("{anna} walks into the room.", + from_obj=caller, mapping={'anna': anna_object}) ``` Use `exclude=object_or_list_of_object` to skip sending the message one or more targets. -The advantage of this is that `anna_object.get_display_name(looker)` will be called -for every onlooker; this allows the `{anna}` stanza to be different depending on who +The advantage of this is that `anna_object.get_display_name(looker)` will be called +for every onlooker; this allows the `{anna}` stanza to be different depending on who sees the strings. How this is to work depends on the _stance_ of your game. -The stance indicates how your game echoes its messages to the player. Knowing how you want to +The stance indicates how your game echoes its messages to the player. Knowing how you want to handle the stance is important for a text game. There are two main stances that are usually considered, -_Actor stance_ and _Director stance_. +_Actor stance_ and _Director stance_. -| Stance | You see | Others in the same location see | +| Stance | You see | Others in the same location see | | --- | --- | --- | -| Actor stance | You pick up the stone | Anna picks up the stone | -|Director stance | Anna picks up the stone | Anna picks up the stone | +| Actor stance | You pick up the stone | Anna picks up the stone | +|Director stance | Anna picks up the stone | Anna picks up the stone | -It's not unheard of to mix the two stances - with commands from the game being told -in Actor stance while Director stance is used for complex emoting and roleplaying. One should +It's not unheard of to mix the two stances - with commands from the game being told +in Actor stance while Director stance is used for complex emoting and roleplaying. One should usually try to be consistent however. -## Director Stance +## Director Stance -While not so common as Actor stance, director stance has the advantage of simplicity, particularly -in roleplaying MUDs where longer roleplaying emotes are used. It is also a pretty simple stance to +While not so common as Actor stance, director stance has the advantage of simplicity, particularly +in roleplaying MUDs where longer roleplaying emotes are used. It is also a pretty simple stance to implement technically since everyone sees the same text, regardless of viewpoint. -Here's an example of a flavorful text to show the room: +Here's an example of a flavorful text to show the room: Tom picks up the gun, whistling to himself. Everyone will see this string, both Tom and others. Here's how to send it to everyone in the room. -```python +```python text = "Tom picks up the gun, whistling to himself." room.msg_contents(text) ``` One may want to expand on it by making the name `Tom` be seen differently by different people, -but the English grammar of the sentence does not change. Not only is this pretty easy to do -technically, it's also easy to write for the player. +but the English grammar of the sentence does not change. Not only is this pretty easy to do +technically, it's also easy to write for the player. -## Actor Stance +## Actor Stance -This means that the game addresses "you" when it does things. In actor stance, whenever you perform +This means that the game addresses "you" when it does things. In actor stance, whenever you perform an action, you should get a different message than those _observing_ you doing that action. Tom picks up the gun, whistling to himself. -This is what _others_ should see. The player themselves should see this: +This is what _others_ should see. The player themselves should see this: You pick up the gun, whistling to yourself. @@ -74,24 +74,24 @@ Not only do you need to map "Tom" to "You" above, there are also grammatical dif developer making simple "You/Tom pick/picks up the stone" messages, you could in principle hand-craft the strings from every view point, but there's a better way. -The `msg_contents` method helps by parsing the ingoing string with a -[FuncParser functions](../Components/FuncParser.md) with some very specific `$inline-functions`. The inline funcs -basically provides you with a mini-language for building _one_ string that will change -appropriately depending on who sees it. +The `msg_contents` method helps by parsing the ingoing string with a +[FuncParser functions](../Components/FuncParser.md) with some very specific `$inline-functions`. The inline funcs +basically provides you with a mini-language for building _one_ string that will change +appropriately depending on who sees it. -```python +```python text = "$You() $conj(pick) up the gun, whistling to $pron(yourself)." room.msg_contents(text, from_obj=caller, mapping={"gun": gun_object}) ``` -These are the inline-functions available: +These are the inline-functions available: - `$You()/$you()` - this is a reference to 'you' in the text. It will be replaced with "You/you" for the one sending the text and with the return from `caller.get_display_name(looker)` for everyone else. -- `$conj(verb)` - this will conjugate the given verb depending on who sees the string (like `pick` - to `picks`). Enter the root form of the verb. -- `$pron(pronoun[,options])` - A pronoun is a word you want to use instead of a proper noun, like +- `$conj(verb)` - this will conjugate the given verb depending on who sees the string (like `pick` + to `picks`). Enter the root form of the verb. +- `$pron(pronoun[,options])` - A pronoun is a word you want to use instead of a proper noun, like _him_, _herself_, _its_, _me_, _I_, _their_ and so on. The `options` is a space- or comma-separated set of options to help the system map your pronoun from 1st/2nd person to 3rd person and vice versa. See next section. @@ -99,11 +99,11 @@ These are the inline-functions available: ### More on $pron() The `$pron()` inline func maps between 1st/2nd person (I/you) to 3rd person (he/she etc). In short, -it translates between this table ... +it translates between this table ... | | Subject Pronoun | Object Pronoun | Possessive Adjective | Possessive Pronoun | Reflexive Pronoun | | --- | --- | --- | --- | --- | --- | -| **1st person** | I | me | my | mine | myself | +| **1st person** | I | me | my | mine | myself | | **1st person plural** | we | us | our | ours | ourselves | | **2nd person** | you | you | your | yours | yourself | | **2nd person plural** | you | you | your | yours | yourselves | @@ -117,52 +117,52 @@ it translates between this table ... | **3rd person neutral** | it | it | its | theirs* | itself | | **3rd person plural** | they | them | their | theirs | themselves | -> *) The neutral 3rd person possessive pronoun is not actually used in English. We set it to "theirs" +> *) The neutral 3rd person possessive pronoun is not actually used in English. We set it to "theirs" > just to have something to show should someone accidentally ask for a neutral possessive pronoun. -Some mappings are easy. For example, if you write `$pron(yourselves)` then the 3rd-person -form is always `themselves`. But because English grammar is the way it is, not all mappings -are 1:1. For example, if you write +Some mappings are easy. For example, if you write `$pron(yourselves)` then the 3rd-person +form is always `themselves`. But because English grammar is the way it is, not all mappings +are 1:1. For example, if you write `$pron(you)`, Evennia will not know which 3rd-persion equivalent this should map to - you need to -provide more info to help out. This can either be provided as a second space-separated option +provide more info to help out. This can either be provided as a second space-separated option to `$pron` or the system will try to figure it out on its own. - `pronoun_type` - this is one of the columns in the table and can be set as a `$pron` option. - `subject pronoun` (aliases `subject` or `sp`) - - `object pronoun` (aliases `object` or `op`) + - `object pronoun` (aliases `object` or `op`) - `possessive adjective` (aliases `adjective` or `pa`) - - `possessive pronoun` (aliases `pronoun` or `pp`). + - `possessive pronoun` (aliases `pronoun` or `pp`). - (There is no need to specify reflexive pronouns since they - are all uniquely mapped 1:1). Speciying the pronoun-type is mainly needed when using `you`, + (There is no need to specify reflexive pronouns since they + are all uniquely mapped 1:1). Speciying the pronoun-type is mainly needed when using `you`, since the same 'you' is used to represent all sorts of things in English grammar. If not specified and the mapping is not clear, a 'subject pronoun' (he/she/it/they) is assumed. -- `gender` - set in `$pron` option as - +- `gender` - set in `$pron` option as + - `male`, or `m` - - `female'` or `f` - - `neutral`, or `n` - - `plural`, or `p` (yes plural is considered a 'gender' for this purpose). - - If not set as an option the system will - look for a callable or property `.gender` on the current `from_obj`. A callable will be called - with no arguments and is expected to return a string 'male/female/neutral/plural'. If none - is found, a neutral gender is assumed. -- `viewpoint`- set in `$pron` option as - - - `1st person` (aliases `1st` or `1`) + - `female'` or `f` + - `neutral`, or `n` + - `plural`, or `p` (yes plural is considered a 'gender' for this purpose). + + If not set as an option the system will + look for a callable or property `.gender` on the current `from_obj`. A callable will be called + with no arguments and is expected to return a string 'male/female/neutral/plural'. If none + is found, a neutral gender is assumed. +- `viewpoint`- set in `$pron` option as + + - `1st person` (aliases `1st` or `1`) - `2nd person` (aliases `2nd` or `2`) - This is only needed if you want to have 1st person perspective - if - not, 2nd person is assumed wherever the viewpoint is unclear. + This is only needed if you want to have 1st person perspective - if + not, 2nd person is assumed wherever the viewpoint is unclear. -`$pron()` examples: +`$pron()` examples: | Input | you see | others see | note | | --- | --- | ---| --- | -| `$pron(I, male)` | I | he | | -| `$pron(I, f)` | I | she | | +| `$pron(I, male)` | I | he | | +| `$pron(I, f)` | I | she | | | `$pron(my)` | my | its | figures out it's an possessive adjective, assumes neutral | | `$pron(you)` | you | it | assumes neutral subject pronoun | | `$pron(you, f)` | you | she | female specified, assumes subject pronoun | @@ -170,7 +170,7 @@ to `$pron` or the system will try to figure it out on its own. | `$pron(you,op p)` | you | them | | | `$pron(you, f op)` | you | her | specified female and objective pronoun| | `$pron(yourself)` | yourself | itself | | -| `$pron(its)` | your | its | | +| `$pron(its)` | your | its | | | `$Pron(its)` | Your | Its | Using $Pron always capitalizes | | `$pron(her)` | you | her | 3rd person -> 2nd person | | `$pron(her, 1)` | I | her | 3rd person -> 1st person | @@ -185,36 +185,36 @@ The [$pron inlinefunc api is found here](evennia.utils.funcparser.funcparser_cal # Referencing other objects -There is one more inlinefunc understood by `msg_contents`. This can be used natively to spruce up +There is one more inlinefunc understood by `msg_contents`. This can be used natively to spruce up your strings (for both director- and actor stance): - `$Obj(name)/$obj(name)` references another entity, which must be supplied in the `mapping` keyword argument to `msg_contents`. The object's `.get_display_name(looker)` will be - called and inserted instead. This is essentially the same as using the `{anna}` marker we used - in the first example at the top of this page, but using `$Obj/$obj` allows you to easily + called and inserted instead. This is essentially the same as using the `{anna}` marker we used + in the first example at the top of this page, but using `$Obj/$obj` allows you to easily control capitalization. -This is used like so: +This is used like so: -```python +```python # director stance text = "Tom picks up the $obj(gun), whistling to himself" -# actor stance +# actor stance text = "$You() $conj(pick) up the $obj(gun), whistling to $pron(yourself)" room.msg_contents(text, from_obj=caller, mapping={"gun": gun_object}) ``` -Depending on your game, Tom may now see himself picking up `A rusty old gun`, whereas an onlooker -with a high gun smith skill may instead see him picking up `A rare-make Smith & Wesson model 686 +Depending on your game, Tom may now see himself picking up `A rusty old gun`, whereas an onlooker +with a high gun smith skill may instead see him picking up `A rare-make Smith & Wesson model 686 in poor condition" ...` -# Recog systems and roleplaying +# Recog systems and roleplaying -The `$funcparser` inline functions are very powerful for the game developer, but they may +The `$funcparser` inline functions are very powerful for the game developer, but they may be a bit too much to write for the regular player. -The [rpsystem contrib](evennia.contribs.rpsystem) implements a full dynamic emote/pose and recognition -system with short-descriptions and disguises. It uses director stance with a custom markup -language, like `/me` `/gun` and `/tall man` to refer to players and objects in the location. It can be -worth checking out for inspiration. \ No newline at end of file +The [rpsystem contrib](evennia.contrib.rpg.rpsystem) implements a full dynamic emote/pose and recognition +system with short-descriptions and disguises. It uses director stance with a custom markup +language, like `/me` `/gun` and `/tall man` to refer to players and objects in the location. It can be +worth checking out for inspiration. diff --git a/docs/source/Concepts/Soft-Code.md b/docs/source/Concepts/Soft-Code.md index cb78a93da2..9a37571b31 100644 --- a/docs/source/Concepts/Soft-Code.md +++ b/docs/source/Concepts/Soft-Code.md @@ -90,5 +90,5 @@ Adding advanced and flexible building commands to your game is easy and will pro satisfy most creative builders. However, if you really, *really* want to offer online coding, there is of course nothing stopping you from adding that to Evennia, no matter our recommendations. You could even re-implement MUX' softcode in Python should you be very ambitious. The -[in-game-python](../Contribs/Dialogues-in-events.md) is an optional +[in-game-python](../Contribs/Contrib-Ingame-Python.md) is an optional pseudo-softcode plugin aimed at developers wanting to script their game from inside it. diff --git a/docs/source/Contribs/Contrib-AWSStorage.md b/docs/source/Contribs/Contrib-AWSStorage.md index c07e92ea6b..c6ea74ba63 100644 --- a/docs/source/Contribs/Contrib-AWSStorage.md +++ b/docs/source/Contribs/Contrib-AWSStorage.md @@ -1,12 +1,10 @@ # AWSstorage system -Contrib by The Right Honourable Reverend (trhr) 2020 - -## What is this for? +Contrib by The Right Honourable Reverend (trhr), 2020 This plugin migrates the Web-based portion of Evennia, namely images, -javascript, and other items located inside staticfiles into Amazon AWS (S3) for -hosting. +javascript, and other items located inside staticfiles into Amazon AWS (S3) +cloud hosting. Great for those serving media with the game. Files hosted on S3 are "in the cloud," and while your personal server may be sufficient for serving multimedia to a minimal number of users, diff --git a/docs/source/Contribs/Contrib-Auditing.md b/docs/source/Contribs/Contrib-Auditing.md index 60c2a59cc6..565414408f 100644 --- a/docs/source/Contribs/Contrib-Auditing.md +++ b/docs/source/Contribs/Contrib-Auditing.md @@ -1,15 +1,15 @@ # Input/Output Auditing -Contrib - Johnny 2017 +Contribution by Johnny, 2017 -This is a tap that optionally intercepts all data sent to/from clients and the -server and passes it to a callback of your choosing. +Utility that taps and intercepts all data sent to/from clients and the +server and passes it to a callback of your choosing. This is intended for +quality assurance, post-incident investigations and debugging. -It is intended for quality assurance, post-incident investigations and debugging -but obviously can be abused. All data is recorded in cleartext. Please -be ethical, and if you are unwilling to properly deal with the implications of -recording user passwords or private communications, please do not enable -this module. +Note that this should be used with care since it can obviously be abused. All +data is recorded in cleartext. Please be ethical, and if you are unwilling to +properly deal with the implications of recording user passwords or private +communications, please do not enable this module. Some checks have been implemented to protect the privacy of users. diff --git a/docs/source/Contribs/Contrib-Barter.md b/docs/source/Contribs/Contrib-Barter.md index 5e60cc9be1..20e0875f6d 100644 --- a/docs/source/Contribs/Contrib-Barter.md +++ b/docs/source/Contribs/Contrib-Barter.md @@ -1,18 +1,14 @@ # Barter system -Evennia contribution - Griatch 2012 +Contribution by Griatch, 2012 This implements a full barter system - a way for players to safely -trade items between each other using code rather than simple free-form -talking. The advantage of this is increased buy/sell safety but it -also streamlines the process and makes it faster when doing many -transactions (since goods are automatically exchanged once both -agree). - -This system is primarily intended for a barter economy, but can easily -be used in a monetary economy as well -- just let the "goods" on one -side be coin objects (this is more flexible than a simple "buy" -command since you can mix coins and goods in your trade). +trade items between each other in code rather than simple `give/get` +commands. This increases both safety (at no time will one player have +both goods and payment in-hand) and speed, since agreed goods will +be moved automatically). By just replacing one side with coin objects, +(or a mix of coins and goods), this also works fine for regular money +transactions. ## Installation diff --git a/docs/source/Contribs/Contrib-Batchprocessor.md b/docs/source/Contribs/Contrib-Batchprocessor.md index a3510385eb..476425314b 100644 --- a/docs/source/Contribs/Contrib-Batchprocessor.md +++ b/docs/source/Contribs/Contrib-Batchprocessor.md @@ -1,10 +1,10 @@ # Batch processor examples -Contibution - Griatch 2012 +Contibution by Griatch, 2012 -The batch processor is used for generating in-game content from one or more -static files. Files can be stored with version control and then 'applied' -to the game to create content. +Simple examples for the batch-processor. The batch processor is used for generating +in-game content from one or more static files. Files can be stored with version +control and then 'applied' to the game to create content. There are two batch processor types: diff --git a/docs/source/Contribs/Contrib-Bodyfunctions.md b/docs/source/Contribs/Contrib-Bodyfunctions.md index ffe39eac44..3273a356d5 100644 --- a/docs/source/Contribs/Contrib-Bodyfunctions.md +++ b/docs/source/Contribs/Contrib-Bodyfunctions.md @@ -1,9 +1,9 @@ # Script example -Griatch - 2012 +Contribution by Griatch, 2012 Example script for testing. This adds a simple timer that has your -character make observations and notices at irregular intervals. +character make small verbal observations at irregular intervals. To test, use (in game) diff --git a/docs/source/Contribs/Contrib-Building-Menu.md b/docs/source/Contribs/Contrib-Building-Menu.md index a8a92c73ab..e5c8d062aa 100644 --- a/docs/source/Contribs/Contrib-Building-Menu.md +++ b/docs/source/Contribs/Contrib-Building-Menu.md @@ -1,15 +1,13 @@ # Building menu -Module containing the building menu system. - -Evennia contributor: vincent-lg 2018 +Contrib by vincent-lg, 2018 Building menus are in-game menus, not unlike `EvMenu` though using a -different approach. Building menus have been specifically designed to edit -information as a builder. Creating a building menu in a command allows -builders quick-editing of a given object, like a room. If you follow the -steps below to add the contrib, you will have access to an `@edit` command -that will edit any default object offering to change its key and description. +different approach. Building menus have been specifically designed to edit +information as a builder. Creating a building menu in a command allows +builders quick-editing of a given object, like a room. If you follow the +steps to add the contrib, you will have access to an `edit` command +that will edit any default object, offering to change its key and description. ## Install diff --git a/docs/source/Contribs/Contrib-Clothing.md b/docs/source/Contribs/Contrib-Clothing.md index 95109e5361..21addd6ecb 100644 --- a/docs/source/Contribs/Contrib-Clothing.md +++ b/docs/source/Contribs/Contrib-Clothing.md @@ -1,9 +1,9 @@ # Clothing -Evennia contribution - Tim Ashley Jenkins 2017 +Contribution by Tim Ashley Jenkins, 2017 -Provides a typeclass and commands for wearable clothing, -which is appended to a character's description when worn. +Provides a typeclass and commands for wearable clothing. These +look of these clothes are appended to the character's description when worn. Clothing items, when worn, are added to the character's description in a list. For example, if wearing the following clothing items: @@ -13,6 +13,11 @@ in a list. For example, if wearing the following clothing items: one nice hat a very pretty dress +Would result in this added description: + + Tim is wearing one nice hat, a thin and delicate necklace, + a very pretty dress and a pair of regular ol' shoes. + ## Installation To install, import this module and have your default character diff --git a/docs/source/Contribs/Contrib-Color-Markups.md b/docs/source/Contribs/Contrib-Color-Markups.md index 71226f9277..be5a983e05 100644 --- a/docs/source/Contribs/Contrib-Color-Markups.md +++ b/docs/source/Contribs/Contrib-Color-Markups.md @@ -1,9 +1,10 @@ # Color markups -Contribution, Griatch 2017 +Contrib by Griatch, 2017 Additional color markup styles for Evennia (extending or replacing the default -`|r`, `|234` etc). +`|r`, `|234`). Adds support for MUSH-style (`%cr`, `%c123`) and/or legacy-Evennia +(`{r`, `{123`). ## Installation diff --git a/docs/source/Contribs/Contrib-Cooldowns.md b/docs/source/Contribs/Contrib-Cooldowns.md index 5272053de2..794af0b009 100644 --- a/docs/source/Contribs/Contrib-Cooldowns.md +++ b/docs/source/Contribs/Contrib-Cooldowns.md @@ -1,13 +1,12 @@ -# Cooldown contrib module. +# Cooldowns -Evennia contrib - owllex, 2021 +Contribution by owllex, 2021 -This contrib provides a simple cooldown handler that can be attached to any -typeclassed Object or Account. A cooldown is a lightweight persistent -asynchronous timer that you can query to see if it is ready. - -Cooldowns are good for modelling rate-limited actions, like how often a -character can perform a given command. +Cooldowns are used modelling rate-limited actions, like how often a +character can perform a given action; until a certain time has passed their +command can not be used again. This contrib provides a simple cooldown +handler that can be attached to any typeclass. A cooldown is a lightweight persistent +asynchronous timer that you can query to see if a certain time has yet passed. Cooldowns are completely asynchronous and must be queried to know their state. They do not fire callbacks, so are not a good fit for use cases diff --git a/docs/source/Contribs/Contrib-Crafting.md b/docs/source/Contribs/Contrib-Crafting.md index a03b8ea7bf..95e9dadcb4 100644 --- a/docs/source/Contribs/Contrib-Crafting.md +++ b/docs/source/Contribs/Contrib-Crafting.md @@ -1,25 +1,46 @@ # Crafting system -Contrib - Griatch 2020 +Contribution by Griatch 2020 -This implements a full crafting system. The principle is that of a 'recipe': +This implements a full crafting system. The principle is that of a 'recipe', +where you combine items (tagged as ingredients) create something new. The recipe can also +require certain (non-consumed) tools. An example would be to use the 'bread recipe' to +combine 'flour', 'water' and 'yeast' with an 'oven' to bake a 'loaf of bread'. - ingredient1 + ingredient2 + ... + tool1 + tool2 + ... + craft_recipe -> objectA, objectB, ... +The recipe process can be understood like this: + + ingredient(s) + tool(s) + recipe -> object(s) Here, 'ingredients' are consumed by the crafting process, whereas 'tools' are -necessary for the process by will not be destroyed by it. +necessary for the process but will not be destroyed by it. -An example would be to use the tools 'bowl' and 'oven' to use the ingredients -'flour', 'salt', 'yeast' and 'water' to create 'bread' using the 'bread recipe'. +The included `craft` command works like this: -A recipe does not have to use tools, like 'snow' + 'snowball-recipe' becomes -'snowball'. Conversely one could also imagine using tools without consumables, -like using 'spell book' and 'wand' to produce 'fireball' by having the recipe -check some magic skill on the character. + craft [from ,...] [using , ...] -The system is generic enough to be used also for adventure-like puzzles, like -combining 'stick', 'string' and 'hook' to get a 'makeshift fishing rod' that -you can use with 'storm drain' (treated as a tool) to get 'key' ... +## Examples + +Using the `craft` command: + + craft toy car from plank, wooden wheels, nails using saw, hammer + +A recipe does not have to use tools or even multiple ingredients: + + snow + snowball_recipe -> snowball + +Conversely one could also imagine using tools without consumables, like + + spell_book + wand + fireball_recipe -> fireball + +The system is generic enough to be used also for adventure-like puzzles (but +one would need to change the command and determine the recipe on based on what +is being combined instead): + + stick + string + hook -> makeshift_fishing_rod + makeshift_fishing_rod + storm_drain -> key + +See the [sword example](evennia.contrib.game_systems.crafting.example_recipes) for an example +of how to design a recipe tree for crafting a sword from base elements. ## Intallation and Usage @@ -29,18 +50,30 @@ available to you: craft [from ,...] [using , ...] -For example +In code, you can craft using the +`evennia.contrib.game_systems.crafting.craft` function: - craft toy car from plank, wooden wheels, nails using saw, hammer +```python +from evennia.contrib.game_systems.crafting import craft -To use crafting you need recipes. Add a new variable to `mygame/server/conf/settings.py`: +result = craft(caller, "recipename", *inputs) + +``` +Here, `caller` is the one doing the crafting and `*inputs` is any combination of +consumables and/or tool Objects. The system will identify which is which by the +[Tags](../Components/Tags.md) on them (see below) The `result` is always a list. + +To use crafting you need recipes. Add a new variable to +`mygame/server/conf/settings.py`: CRAFT_RECIPE_MODULES = ['world.recipes'] -All top-level classes in these modules (whose name does not start with `_`) -will be parsed by Evennia as recipes to make available to the crafting system. -Using the above example, create `mygame/world/recipes.py` and add your recipies -in there: +All top-level classes in these modules (whose name does not start with `_`) will +be parsed by Evennia as recipes to make available to the crafting system. Using +the above example, create `mygame/world/recipes.py` and add your recipies in +there: + +A quick example (read on for more details): ```python @@ -69,37 +102,202 @@ class RecipeBread(CraftingRecipe): def pre_craft(self, **kwargs): # validates inputs etc. Raise `CraftingValidationError` if fails - def craft(self, **kwargs): - # performs the craft - but it can still fail (check skills etc here) + def do_craft(self, **kwargs): + # performs the craft - report errors directly to user and return None (if + # failed) and the created object(s) if successful. - def craft(self, result, **kwargs): - # any post-crafting effects. Always called, even if crafting failed (be + def post_craft(self, result, **kwargs): + # any post-crafting effects. Always called, even if do_craft failed (the # result would be None then) ``` -## Technical +## Adding new recipes -The Recipe is a class that specifies the consumables, tools and output along -with various methods (that you can override) to do the the validation of inputs -and perform the crafting itself. +A *recipe* is a class inheriting from +`evennia.contrib.crafting.crafting.CraftingRecipe`. This class implements the +most common form of crafting - that using in-game objects. Each recipe is a +separate class which gets initialized with the consumables/tools you provide. -By default the input is a list of object-tags (using the "crafting_material" -and "crafting_tool" tag-categories respectively). Providing a set of objects -matching these tags are required for the crafting to be done. The use of tags -means that multiple different objects could all work for the same recipe, as -long as they have the right tag. This can be very useful for allowing players -to experiment and explore alternative ways to create things! +For the `craft` command to find your custom recipes, you need to tell Evennia +where they are. Add a new line to your `mygame/server/conf/settings.py` file, +with a list to any new modules with recipe classes. -The output is given by a set of prototype-dicts. If the input is correct and -other checks are passed (such as crafting skill, for example), these prototypes -will be used to generate the new object(s) being crafted. +```python +CRAFT_RECIPE_MODULES = ["world.myrecipes"] +``` + +(You need to reload after adding this). All global-level classes in these +modules (whose names don't start with underscore) are considered by the system +as viable recipes. + +Here we assume you created `mygame/world/myrecipes.py` to match the above +example setting: + +```python +# in mygame/world/myrecipes.py + +from evennia.contrib.crafting.crafting import CraftingRecipe + +class WoodenPuppetRecipe(CraftingRecipe): + """A puppet"""" + name = "wooden puppet" # name to refer to this recipe as + tool_tags = ["knife"] + consumable_tags = ["wood"] + output_prototypes = [ + {"key": "A carved wooden doll", + "typeclass": "typeclasses.objects.decorations.Toys", + "desc": "A small carved doll"} + ] + +``` + +This specifies which tags to look for in the inputs. It defines a +[Prototype](../Components/Prototypes.md) for the recipe to use to spawn the +result on the fly (a recipe could spawn more than one result if needed). +Instead of specifying the full prototype-dict, you could also just provide a +list of `prototype_key`s to existing prototypes you have. + +After reloading the server, this recipe would now be available to use. To try it +we should create materials and tools to insert into the recipe. + + +The recipe analyzes inputs, looking for [Tags](../Components/Tags.md) with +specific tag-categories. The tag-category used can be set per-recipe using the +(`.consumable_tag_category` and `.tool_tag_category` respectively). The defaults +are `crafting_material` and `crafting_tool`. For +the puppet we need one object with the `wood` tag and another with the `knife` +tag: + +```python +from evennia import create_object + +knife = create_object(key="Hobby knife", tags=[("knife", "crafting_tool")]) +wood = create_object(key="Piece of wood", tags[("wood", "crafting_material")]) +``` + +Note that the objects can have any name, all that matters is the +tag/tag-category. This means if a "bayonet" also had the "knife" crafting tag, +it could also be used to carve a puppet. This is also potentially interesting +for use in puzzles and to allow users to experiment and find alternatives to +know ingredients. + +By the way, there is also a simple shortcut for doing this: + +``` +tools, consumables = WoodenPuppetRecipe.seed() +``` + +The `seed` class-method will create simple dummy objects that fulfills the +recipe's requirements. This is great for testing. + +Assuming these objects were put in our inventory, we could now craft using the +in-game command: + +```bash +> craft wooden puppet from wood using hobby knife +``` +In code we would do + +```python +from evennia.contrub.crafting.crafting import craft +puppet = craft(crafter, "wooden puppet", knife, wood) + +``` +In the call to `craft`, the order of `knife` and `wood` doesn't matter - the +recipe will sort out which is which based on their tags. + +## Deeper customization of recipes + +For customizing recipes further, it helps to understand how to use the +recipe-class directly: + +```python +class MyRecipe(CraftingRecipe): + # ... + +tools, consumables = MyRecipe.seed() +recipe = MyRecipe(crafter, *(tools + consumables)) +result = recipe.craft() + +``` +This is useful for testing and allows you to use the class directly without +adding it to a module in `settings.CRAFTING_RECIPE_MODULES`. + +Even without modifying more than the class properties, there are a lot of +options to set on the `CraftingRecipe` class. Easiest is to refer to the +[CraftingRecipe api +documentation](evennia.contrib.game_systems.crafting.crafting.CraftingRecipe). For example, +you can customize the validation-error messages, decide if the ingredients have +to be exactly right, if a failure still consumes the ingredients or not, and +much more. + +For even more control you can override hooks in your own class: + +- `pre_craft` - this should handle input validation and store its data in `.validated_consumables` and + `validated_tools` respectively. On error, this reports the error to the crafter and raises the + `CraftingValidationError`. +- `craft` - this will only be called if `pre_craft` finished without an exception. This should + return the result of the crafting, by spawnging the prototypes. Or the empty list if crafting + fails for some reason. This is the place to add skill-checks or random chance if you need it + for your game. +- `post_craft` - this receives the result from `craft` and handles error messages and also deletes + any consumables as needed. It may also modify the result before returning it. +- `msg` - this is a wrapper for `self.crafter.msg` and should be used to send messages to the + crafter. Centralizing this means you can also easily modify the sending style in one place later. + +The class constructor (and the `craft` access function) takes optional `**kwargs`. These are passed +into each crafting hook. These are unused by default but could be used to customize things per-call. + +### Skilled crafters + +What the crafting system does not have out of the box is a 'skill' system - the +notion of being able to fail the craft if you are not skilled enough. Just how +skills work is game-dependent, so to add this you need to make your own recipe +parent class and have your recipes inherit from this. + + +```python +from random import randint +from evennia.contrib.crafting.crafting import CraftingRecipe + +class SkillRecipe(CraftingRecipe): + """A recipe that considers skill""" + + difficulty = 20 + + def craft(self, **kwargs): + """The input is ok. Determine if crafting succeeds""" + + # this is set at initialization + crafter = self.crafte + + # let's assume the skill is stored directly on the crafter + # - the skill is 0..100. + crafting_skill = crafter.db.skill_crafting + # roll for success: + if randint(1, 100) <= (crafting_skill - self.difficulty): + # all is good, craft away + return super().craft() + else: + self.msg("You are not good enough to craft this. Better luck next time!") + return [] +``` +In this example we introduce a `.difficulty` for the recipe and makes a 'dice roll' to see +if we succed. We would of course make this a lot more immersive and detailed in a full game. In +principle you could customize each recipe just the way you want it, but you could also inherit from +a central parent like this to cut down on work. + +The [sword recipe example module](evennia.contrib.game_systems.crafting.example_recipes) also shows an example +of a random skill-check being implemented in a parent and then inherited for multiple use. + +## Even more customization + +If you want to build something even more custom (maybe using different input types of validation logic) +you could also look at the `CraftingRecipe` parent class `CraftingRecipeBase`. +It implements just the minimum needed to be a recipe and for big changes you may be better off starting +from this rather than the more opinionated `CraftingRecipe`. -Each recipe is a stand-alone entity which allows for very advanced -customization for every recipe - for example one could have a recipe that -checks other properties of the inputs (like quality, color etc) and have that -affect the result. Your recipes could also (and likely would) tie into your -game's skill system to determine the success or outcome of the crafting. ---- diff --git a/docs/source/Contribs/Contrib-Custom-Gametime.md b/docs/source/Contribs/Contrib-Custom-Gametime.md index 1d1f008182..f927c67f6e 100644 --- a/docs/source/Contribs/Contrib-Custom-Gametime.md +++ b/docs/source/Contribs/Contrib-Custom-Gametime.md @@ -1,10 +1,11 @@ # Custom gameime -Contrib - Griatch 2017, vlgeoff 2017 +Contrib by vlgeoff, 2017 - based on Griatch's core original -This reimplements the `evennia.utils.gametime` module but supporting a custom -calendar for your game world. It allows for scheduling events to happen at given -in-game times, taking this custom calendar into account. +This reimplements the `evennia.utils.gametime` module but with a _custom_ +calendar (unusual number of days per week/month/year etc) for your game world. +Like the original, it allows for scheduling events to happen at given +in-game times, but now taking this custom calendar into account. ## Installation diff --git a/docs/source/Contribs/Contrib-Dice.md b/docs/source/Contribs/Contrib-Dice.md index e5b99e2e72..14f232b2f6 100644 --- a/docs/source/Contribs/Contrib-Dice.md +++ b/docs/source/Contribs/Contrib-Dice.md @@ -1,8 +1,12 @@ # Dice -Rolls dice for roleplaying, in-game gambling or GM:ing +Contribution by Griatch, 2012 + +A dice roller for any number and side of dice. Adds in-game dice rolling +(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target) +and functions for rolling dice in code. Command also supports hidden or secret +rolls for use by a human game master. -Evennia contribution - Griatch 2012 # Installation: diff --git a/docs/source/Contribs/Contrib-Email-Login.md b/docs/source/Contribs/Contrib-Email-Login.md index 4de1b66218..512531c868 100644 --- a/docs/source/Contribs/Contrib-Email-Login.md +++ b/docs/source/Contribs/Contrib-Email-Login.md @@ -1,9 +1,10 @@ # Email-based login system -Evennia contrib - Griatch 2012 +Contrib by Griatch, 2012 -This is a variant of the login system that requires an email-address -instead of a username to login. +This is a variant of the login system that asks for an email-address +instead of a username to login. Note that it does not verify the email, +it just uses it as the identifier rather than a username. This used to be the default Evennia login before replacing it with a more standard username + password system (having to supply an email diff --git a/docs/source/Contribs/Contrib-Evscaperoom.md b/docs/source/Contribs/Contrib-Evscaperoom.md index b675d3f5df..c0170f440f 100644 --- a/docs/source/Contribs/Contrib-Evscaperoom.md +++ b/docs/source/Contribs/Contrib-Evscaperoom.md @@ -1,16 +1,18 @@ # EvscapeRoom -Evennia contrib - Griatch 2019 +Contribution by Griatch, 2019 -This 'Evennia escaperoom game engine' was created for the MUD Coders Guild game -Jam, April 14-May 15 2019. The theme for the jam was "One Room". This contains the -utilities and base classes and an empty example room. +A full engine for creating multiplayer escape-rooms in Evennia. Allows players to +spawn and join puzzle rooms that track their state independently. Any number of players +can join to solve a room together. This is the engine created for 'EvscapeRoom', which won +the MUD Coders Guild "One Room" Game Jam in April-May, 2019. The contrib has no game +content but contains the utilities and base classes and an empty example room. The original code for the contest is found at https://github.com/Griatch/evscaperoom but the version on the public Evennia demo is more updated, so if you really want the latest bug fixes etc you should rather look at https://github.com/evennia/evdemo/tree/master/evdemo/evscaperoom -instead. A copy of the full game can also be played on the Evennia demo server +instead. A copy of the full game can also be played on the Evennia demo server at https://demo.evennia.com - just connect to the server and write `evscaperoom` in the first room to start! diff --git a/docs/source/Contribs/Contrib-Extended-Room.md b/docs/source/Contribs/Contrib-Extended-Room.md index b125b8abec..41ba4ac92b 100644 --- a/docs/source/Contribs/Contrib-Extended-Room.md +++ b/docs/source/Contribs/Contrib-Extended-Room.md @@ -1,10 +1,11 @@ # Extended Room -Evennia Contribution - Griatch 2012, vincent-lg 2019 +Contribution - Griatch 2012, vincent-lg 2019 -This is an extended Room typeclass for Evennia. It is supported -by an extended `Look` command and an extended `desc` command, also -in this module. +This extends the normal `Room` typeclass to allow its description to change +with time-of-day and/or season. It also adds 'details' for the player to look at +in the room (without having to create a new in-game object for each). The room is +supported by new `look` and `desc` commands. ## Installation/testing: diff --git a/docs/source/Contribs/Contrib-Fieldfill.md b/docs/source/Contribs/Contrib-Fieldfill.md index 4a0cf99c59..eeb9977a12 100644 --- a/docs/source/Contribs/Contrib-Fieldfill.md +++ b/docs/source/Contribs/Contrib-Fieldfill.md @@ -1,14 +1,16 @@ # Easy fillable form -Contrib - Tim Ashley Jenkins 2018 +Contribution by Tim Ashley Jenkins, 2018 -This module contains a function that calls an easily customizable EvMenu - this -menu presents the player with a fillable form, with fields that can be filled -out in any order. Each field's value can be verified, with the function -allowing easy checks for text and integer input, minimum and maximum values / -character lengths, or can even be verified by a custom function. Once the form -is submitted, the form's data is submitted as a dictionary to any callable of -your choice. +This module contains a function that generates an `EvMenu` for you - this +menu presents the player with a form of fields that can be filled +out in any order (e.g. for character generation or building). Each field's value can +be verified, with the function allowing easy checks for text and integer input, +minimum and maximum values / character lengths, or can even be verified by a custom +function. Once the form is submitted, the form's data is submitted as a dictionary +to any callable of your choice. + +## Usage The function that initializes the fillable form menu is fairly simple, and includes the caller, the template for the form, and the callback(caller, result) diff --git a/docs/source/Contribs/Contrib-Gendersub.md b/docs/source/Contribs/Contrib-Gendersub.md index 8cde5eb57c..8300260416 100644 --- a/docs/source/Contribs/Contrib-Gendersub.md +++ b/docs/source/Contribs/Contrib-Gendersub.md @@ -1,6 +1,6 @@ # Gendersub -Contrib - Griatch 2015 +Contribution by Griatch 2015 This is a simple gender-aware Character class for allowing users to insert custom markers in their text to indicate gender-aware diff --git a/docs/source/Contribs/Contrib-Health-Bar.md b/docs/source/Contribs/Contrib-Health-Bar.md index e9e000dc86..51f1418491 100644 --- a/docs/source/Contribs/Contrib-Health-Bar.md +++ b/docs/source/Contribs/Contrib-Health-Bar.md @@ -1,11 +1,11 @@ # Health Bar -Contrib - Tim Ashley Jenkins 2017 +Contribution by Tim Ashley Jenkins, 2017 The function provided in this module lets you easily display visual -bars or meters - "health bar" is merely the most obvious use for this, -though these bars are highly customizable and can be used for any sort -of appropriate data besides player health. +bars or meters as a colorful bar instead of just a number. A "health bar" +is merely the most obvious use for this, but the bar is highly customizable +and can be used for any sort of appropriate data besides player health. Today's players may be more used to seeing statistics like health, stamina, magic, and etc. displayed as bars rather than bare numerical diff --git a/docs/source/Contribs/Dialogues-in-events.md b/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md similarity index 91% rename from docs/source/Contribs/Dialogues-in-events.md rename to docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md index 4549a84d2f..aa4c456591 100644 --- a/docs/source/Contribs/Dialogues-in-events.md +++ b/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md @@ -1,23 +1,19 @@ # Dialogues in events - -- Next tutorial: [adding a voice-operated elevator with events](A-voice-operated-elevator-using- -events). - -This tutorial will walk you through the steps to create several dialogues with characters, using the -[in-game Python -system](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md). -This tutorial assumes the in-game Python system is installed in your game. If it isn't, you can -follow the installation steps given in [the documentation on in-game -Python](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md), and -come back on this tutorial once the system is installed. **You do not need to read** the entire -documentation, it's a good reference, but not the easiest way to learn about it. Hence these +This tutorial will walk you through the steps to create several dialogues with +characters, using the Ingame-Python system. This tutorial assumes the in-game +Python system is installed in your game. If it isn't, you can follow the +installation steps given in [The main In-game Python +docs](./Contrib-Ingame-Python.md) and come back on this tutorial once the +system is installed. **You do not need to read** the entire documentation, it's +a good reference, but not the easiest way to learn about it. Hence these tutorials. -The in-game Python system allows to run code on individual objects in some situations. You don't -have to modify the source code to add these features, past the installation. The entire system -makes it easy to add specific features to some objects, but not all. This is why it can be very -useful to create a dialogue system taking advantage of the in-game Python system. +The in-game Python system allows to run code on individual objects in some +situations. You don't have to modify the source code to add these features, +past the installation. The entire system makes it easy to add specific features +to some objects, but not all. This is why it can be very useful to create a +dialogue system taking advantage of the in-game Python system. > What will we try to do? @@ -115,7 +111,7 @@ This command has opened an editor where we can type our Python code. ``` ----------Line Editor [Callback say of a merchant]-------------------------------- -01| +01| ----------[l:01 w:000 c:0000]------------(:h for help)---------------------------- ``` @@ -246,4 +242,4 @@ could share the same events as well. It is possible to do but requires modifica code. - Next tutorial: [adding a voice-operated elevator with events](A-voice-operated-elevator-using- -events). \ No newline at end of file +events). diff --git a/docs/source/Contribs/A-voice-operated-elevator-using-events.md b/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Elevator.md similarity index 93% rename from docs/source/Contribs/A-voice-operated-elevator-using-events.md rename to docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Elevator.md index b5e45a8cda..04e179bffa 100644 --- a/docs/source/Contribs/A-voice-operated-elevator-using-events.md +++ b/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Elevator.md @@ -1,15 +1,8 @@ # A voice operated elevator using events - -- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events.md) - This tutorial will walk you through the steps to create a voice-operated elevator, using the [in- -game Python -system](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md). -This tutorial assumes the in-game Python system is installed in your game. If it isn't, you can -follow the installation steps given in [the documentation on in-game -Python](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md), and -come back on this tutorial once the system is installed. **You do not need to read** the entire +game Python system](./Contrib-Ingame-Python.md). This tutorial assumes the in-game Python +system is installed per the instructions in that doc. **You do not need to read** the entire documentation, it's a good reference, but not the easiest way to learn about it. Hence these tutorials. @@ -97,7 +90,8 @@ things to decorate it a bit. But what we want now is to be able to say "1", "2" or "3" and have the elevator move in that direction. -If you have read [the previous tutorial about adding dialogues in events](./Dialogues-in-events.md), you +If you have read +[the other in-game Python tutorial about adding dialogues in events](./Contrib-Ingame-Python-Tutorial-Dialogue.md), you may remember what we need to do. If not, here's a summary: we need to run some code when somebody speaks in the room. So we need to create a callback (the callback will contain our lines of code). We just need to know on which event this should be set. You can enter `call here` to see the @@ -132,7 +126,7 @@ Variables you can use in this event: message: the text having been spoken by the character. ----------Line Editor [Callback say of Inside of an elevator]--------------------- -01| +01| ----------[l:01 w:000 c:0000]------------(:h for help)---------------------------- ``` @@ -244,7 +238,7 @@ This is a great opportunity to learn about chained events. Chained events are v pauses. Contrary to the events we have seen so far, chained events aren't called automatically. They must be called by you, and can be called after some time. -- Chained events always have the name "chain_X". Usually, X is a number, but you can give the +- Chained events always have the name `"chain_X"`. Usually, X is a number, but you can give the chained event a more explicit name. - In our original callback, we will call our chained events in, say, 15 seconds. - We'll also have to make sure the elevator isn't already moving. @@ -254,7 +248,7 @@ event in our elevator, that will only contain the code necessary to open the doo call/add here = chain_1 -The callback is added to the "chain_1" event, an event that will not be automatically called by the +The callback is added to the `"chain_1"` event, an event that will not be automatically called by the system when something happens. Inside this event, you can paste the code to open the doors at the new floor. You can notice a few differences: @@ -273,7 +267,7 @@ Now let's edit our callback in the "say" event. We'll have to change it a bit: - The callback will have to check the elevator isn't already moving. - It must change the exits when the elevator move. -- It has to call the "chain_1" event we have defined. It should call it 15 seconds later. +- It has to call the `"chain_1"` event we have defined. It should call it 15 seconds later. Let's see the code in our callback. @@ -415,8 +409,8 @@ constraints on persistent attributes. A callback will not be stored in this way This variable will not be available in your chained event. - **Q:** when you say I can call my chained events something else than "chain_1", "chain_2" and such, what is the naming convention? -- **A:** chained events have names beginning by "chain_". This is useful for you and for the -system. But after the underscore, you can give a more useful name, like "chain_open_doors" in our +- **A:** chained events have names beginning by `"chain_"`. This is useful for you and for the +system. But after the underscore, you can give a more useful name, like `"chain_open_doors"` in our case. - **Q:** do I have to pause several seconds to call a chained event? - **A:** no, you can call it right away. Just leave the third parameter of `call_event` out (it @@ -424,13 +418,11 @@ will default to 0, meaning the chained event will be called right away). This w task. - **Q:** can I have chained events calling themselves? - **A:** you can. There's no limitation. Just be careful, a callback that calls itself, -particularly without delay, might be a good recipe for an infinite loop. However, in some cases, it +particularly without delay, might be a good recipe for an infinite loop. However, in some cases, it is useful to have chained events calling themselves, to do the same repeated action every X seconds for instance. - **Q:** what if I need several elevators, do I need to copy/paste these callbacks each time? - **A:** not advisable. There are definitely better ways to handle this situation. One of them is to consider adding the code in the source itself. Another possibility is to call chained events -with the expected behavior, which makes porting code very easy. This side of chained events will be +with the expected behavior, which makes porting code very easy. This side of chained events will be shown in the next tutorial. - -- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events.md) \ No newline at end of file diff --git a/docs/source/Contribs/Contrib-Ingame-Python.md b/docs/source/Contribs/Contrib-Ingame-Python.md index 5cb3872922..2880b78055 100644 --- a/docs/source/Contribs/Contrib-Ingame-Python.md +++ b/docs/source/Contribs/Contrib-Ingame-Python.md @@ -1,15 +1,15 @@ # Evennia in-game Python system -Vincent Le Goff 2017 +Contrib by Vincent Le Goff 2017 -This contrib adds the system of in-game Python in Evennia, allowing immortals -(or other trusted builders) to dynamically add features to individual objects. -Using custom Python set in-game, every immortal or privileged users could have a -specific room, exit, character, object or something else behave differently from -its "cousins". For these familiar with the use of softcode in MU`*`, like SMAUG -MudProgs, the ability to add arbitrary behavior to individual objects is a step -toward freedom. Keep in mind, however, the warning below, and read it carefully -before the rest of the documentation. +This contrib adds the ability to script with Python in-game. It allows trusted +staff/builders to dynamically add features and triggers to individual objects +without needing to do it in external Python modules. Using custom Python in-game, +specific rooms, exits, characters, objects etc can be made to behave differently from +its "cousins". This is similar to how softcode works for MU or MudProgs for DIKU. +Keep in mind, however, that allowing Python in-game comes with _severe_ +security concerns (you must trust your builders deeply), so read the warnings in +this module carefully before continuing. ## A WARNING REGARDING SECURITY @@ -22,6 +22,17 @@ will have to keep in mind these points before deciding to install it: 2. You can do all of this in Python outside the game. The in-game Python system is not to replace all your game feature. +## Extra tutorials + +These tutorials cover examples of using ingame python. Once you have the system +installed (see below) they may be an easier way to learn than reading the full +documentation from beginning to end. + +- [Dialogue events](./Contrib-Ingame-Python-Tutorial-Dialogue.md), where + NPCs react to things said. +- [A voice operated elevator](./Contrib-Ingame-Python-Tutorial-Elevator.md) +using ingame-python events. + ## Basic structure and vocabulary - At the basis of the in-game Python system are **events**. An **event** @@ -73,7 +84,9 @@ default. You need to do it manually, following these steps: This is the quick summary. Scroll down for more detailed help on each step. 1. Launch the main script (important!): - ```py evennia.create_script("evennia.contrib.base_systems.ingame_python.scripts.EventHandler")``` + + py evennia.create_script("evennia.contrib.base_systems.ingame_python.scripts.EventHandler") + 2. Set the permissions (optional): - `EVENTS_WITH_VALIDATION`: a group that can edit callbacks, but will need approval (default to `None`). @@ -176,7 +189,7 @@ the `EVENTS_WITH_VALIDATION` setting will be able to call the command (with diff ### Adding the `call` command You also have to add the `@call` command to your Character CmdSet. This command allows your users -to add, edit and delete callbacks in-game. In your `commands/default_cmdsets, it might look like +to add, edit and delete callbacks in-game. In your `commands/default_cmdsets`, it might look like this: ```python @@ -277,7 +290,7 @@ We'll see callbacks with parameters later. For the time being, let's try to pre from going through the "north" exit of this room: ``` -@call north +call north +------------------+---------+-----------------------------------------------+ | Event name | Number | Description | +~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ diff --git a/docs/source/Contribs/Contrib-Mail.md b/docs/source/Contribs/Contrib-Mail.md index 027844ba84..e8e493c93a 100644 --- a/docs/source/Contribs/Contrib-Mail.md +++ b/docs/source/Contribs/Contrib-Mail.md @@ -1,13 +1,15 @@ # In-Game Mail system -Evennia Contribution - grungies1138 2016 +Contribution by grungies1138 2016 -A simple Brandymail style mail system that uses the Msg class from Evennia -Core. It has two Commands, both of which can be used on their own: +A simple Brandymail style mail system that uses the `Msg` class from Evennia +Core. It has two Commands for either sending mails between Accounts (out of game) +or between Characters (in-game). The two types of mails can be used together or +on their own. - - CmdMail - this should sit on the Account cmdset and makes the `mail` command + - `CmdMail` - this should sit on the Account cmdset and makes the `mail` command available both IC and OOC. Mails will always go to Accounts (other players). - - CmdMailCharacter - this should sit on the Character cmdset and makes the `mail` + - `CmdMailCharacter` - this should sit on the Character cmdset and makes the `mail` command ONLY available when puppeting a character. Mails will be sent to other Characters only and will not be available when OOC. - If adding *both* commands to their respective cmdsets, you'll get two separate diff --git a/docs/source/Contribs/Contrib-Mapbuilder.md b/docs/source/Contribs/Contrib-Mapbuilder.md index bbbc73def7..b1cda773f4 100644 --- a/docs/source/Contribs/Contrib-Mapbuilder.md +++ b/docs/source/Contribs/Contrib-Mapbuilder.md @@ -1,8 +1,8 @@ # Map Builder -Contribution - Cloud_Keeper 2016 +Contribution by Cloud_Keeper 2016 -Build a map from a 2D ASCII map. +Build a game map from the drawing of a 2D ASCII map. This is a command which takes two inputs: diff --git a/docs/source/Contribs/Contrib-Menu-Login.md b/docs/source/Contribs/Contrib-Menu-Login.md index 846fef07a2..9c47216b6d 100644 --- a/docs/source/Contribs/Contrib-Menu-Login.md +++ b/docs/source/Contribs/Contrib-Menu-Login.md @@ -1,10 +1,10 @@ # Menu-based login system -Contribution - Vincent-lg 2016, Griatch 2019 (rework for modern EvMenu) +Contribution by Vincent-lg 2016. Reworked for modern EvMenu by Griatch, 2019. -This changes the Evennia login to ask for the account name and password in -sequence instead of requiring you to enter both at once. It uses EvMenu under -the hood. +This changes the Evennia login to ask for the account name and password as a series +of questions instead of requiring you to enter both at once. It uses Evennia's +menu system `EvMenu` under the hood. ## Installation diff --git a/docs/source/Contribs/Contrib-Mirror.md b/docs/source/Contribs/Contrib-Mirror.md index 87f872f2ea..52a0bd7ab8 100644 --- a/docs/source/Contribs/Contrib-Mirror.md +++ b/docs/source/Contribs/Contrib-Mirror.md @@ -1,8 +1,8 @@ # TutorialMirror -A simple mirror object to experiment with. +Contribution by Griatch, 2017 -A simple mirror object that +A simple mirror object to experiment with. It will respond to being looked at. - echoes back the description of the object looking at it - echoes back whatever is being sent to its .msg - to the diff --git a/docs/source/Contribs/Contrib-Multidescer.md b/docs/source/Contribs/Contrib-Multidescer.md index 842ac0ab41..462cb7c6ac 100644 --- a/docs/source/Contribs/Contrib-Multidescer.md +++ b/docs/source/Contribs/Contrib-Multidescer.md @@ -1,15 +1,16 @@ # Evennia Multidescer -Contrib - Griatch 2016 +Contribution by Griatch 2016 A "multidescer" is a concept from the MUSH world. It allows for creating, managing and switching between multiple character -descriptions. This multidescer will not require any changes to the -Character class, rather it will use the `multidescs` Attribute (a -list) and create it if it does not exist. +descriptions and is a way for quickly managing your look (such as when +changing clothes) in more free-form roleplaying systems. This will also +work well together with the `rpsystem` contrib. -This contrib also works well together with the rpsystem contrib (which -also adds the short descriptions and the `sdesc` command). +This multidescer will not +require any changes to the Character class, rather it will use the `multidescs` +Attribute (a list) and create it if it does not exist. ## Installation diff --git a/docs/source/Contribs/Contrib-Mux-Comms-Cmds.md b/docs/source/Contribs/Contrib-Mux-Comms-Cmds.md index 7ab4a10d5d..691f0701f1 100644 --- a/docs/source/Contribs/Contrib-Mux-Comms-Cmds.md +++ b/docs/source/Contribs/Contrib-Mux-Comms-Cmds.md @@ -1,22 +1,24 @@ # Legacy Comms-commands -Contribution - Griatch 2021 +Contribution by Griatch 2021 -In Evennia 1.0, the old Channel commands (originally inspired by MUX) were -replaced by the single `channel` command that performs all these function. -That command is still required to talk on channels. This contrib (extracted -from Evennia 0.9.5) reuses the channel-management of the base Channel command -but breaks out its functionality into separate Commands with MUX-familiar names. +In Evennia 1.0+, the old Channel commands (originally inspired by MUX) were +replaced by the single `channel` command that performs all these functions. +This contrib (extracted from Evennia 0.9.5) breaks out the functionality into +separate Commands more familiar to MU* users. This is just for show though, the +main `channel` command is still called under the hood. -- `allcom` - `channel/all` and `channel` -- `addcom` - `channel/alias`, `channel/sub` and `channel/unmute` -- `delcom` - `channel/unalias`, `alias/unsub` and `channel/mute` -- `cboot` - `channel/boot` (`channel/ban` and `/unban` not supported) -- `cwho` - `channel/who` -- `ccreate` - `channel/create` -- `cdestroy` - `channel/destroy` -- `clock` - `channel/lock` -- `cdesc` - `channel/desc` +| Contrib syntax | Default `channel` syntax | +| -------------- | --------------------------------------------------------- | +| `allcom` | `channel/all` and `channel` | +| `addcom` | `channel/alias`, `channel/sub` and `channel/unmute` | +| `delcom` | `channel/unalias`, `alias/unsub` and `channel/mute` | +| `cboot` | `channel/boot` (`channel/ban` and `/unban` not supported) | +| `cwho` | `channel/who` | +| `ccreate` | `channel/create` | +| `cdestroy` | `channel/destroy` | +| `clock` | `channel/lock` | +| `cdesc` | `channel/desc` | ## Installation diff --git a/docs/source/Contribs/Contrib-Overview.md b/docs/source/Contribs/Contrib-Overview.md index 92a4de663e..da12d1854f 100644 --- a/docs/source/Contribs/Contrib-Overview.md +++ b/docs/source/Contribs/Contrib-Overview.md @@ -13,11 +13,10 @@ Each contrib contains installation instructions for how to integrate it with your other code. If you want to tweak the code of a contrib, just copy its entire folder to your game directory and modify/use it from there. -If you want to contribute yourself, see [here](../Contributing.md)! - > Hint: Additional (potentially un-maintained) code snippets from the community can be found in our discussion forum's [Community Contribs & Snippets](https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets) category. +If you want to contribute yourself, see [here](../Contributing.md)! ## base_systems @@ -29,113 +28,123 @@ login systems, new command syntaxes, and build helpers._ ### Contrib: `awsstorage` -Contrib by The Right Honourable Reverend (trhr) 2020 +_Contrib by The Right Honourable Reverend (trhr), 2020_ -## What is this for? +This plugin migrates the Web-based portion of Evennia, namely images, +javascript, and other items located inside staticfiles into Amazon AWS (S3) +cloud hosting. Great for those serving media with the game. -[Read the documentation](./Contrib-AWSStorage.md) +[Read the documentation](./Contrib-AWSStorage.md) - [Browse the Code](evennia.contrib.base_systems.awsstorage) ### Contrib: `building_menu` -Module containing the building menu system. +_Contrib by vincent-lg, 2018_ -Evennia contributor: vincent-lg 2018 +Building menus are in-game menus, not unlike `EvMenu` though using a +different approach. Building menus have been specifically designed to edit +information as a builder. Creating a building menu in a command allows +builders quick-editing of a given object, like a room. If you follow the +steps to add the contrib, you will have access to an `edit` command +that will edit any default object, offering to change its key and description. -[Read the documentation](./Contrib-Building-Menu.md) +[Read the documentation](./Contrib-Building-Menu.md) - [Browse the Code](evennia.contrib.base_systems.building_menu) ### Contrib: `color_markups` -Contribution, Griatch 2017 +_Contrib by Griatch, 2017_ Additional color markup styles for Evennia (extending or replacing the default -`|r`, `|234` etc). +`|r`, `|234`). Adds support for MUSH-style (`%cr`, `%c123`) and/or legacy-Evennia +(`{r`, `{123`). -[Read the documentation](./Contrib-Color-Markups.md) +[Read the documentation](./Contrib-Color-Markups.md) - [Browse the Code](evennia.contrib.base_systems.color_markups) ### Contrib: `custom_gametime` -Contrib - Griatch 2017, vlgeoff 2017 +_Contrib by vlgeoff, 2017 - based on Griatch's core original_ -This reimplements the `evennia.utils.gametime` module but supporting a custom -calendar for your game world. It allows for scheduling events to happen at given -in-game times, taking this custom calendar into account. +This reimplements the `evennia.utils.gametime` module but with a _custom_ +calendar (unusual number of days per week/month/year etc) for your game world. +Like the original, it allows for scheduling events to happen at given +in-game times, but now taking this custom calendar into account. -[Read the documentation](./Contrib-Custom-Gametime.md) +[Read the documentation](./Contrib-Custom-Gametime.md) - [Browse the Code](evennia.contrib.base_systems.custom_gametime) ### Contrib: `email_login` -Evennia contrib - Griatch 2012 +_Contrib by Griatch, 2012_ -This is a variant of the login system that requires an email-address -instead of a username to login. +This is a variant of the login system that asks for an email-address +instead of a username to login. Note that it does not verify the email, +it just uses it as the identifier rather than a username. -[Read the documentation](./Contrib-Email-Login.md) +[Read the documentation](./Contrib-Email-Login.md) - [Browse the Code](evennia.contrib.base_systems.email_login) ### Contrib: `ingame_python` -Vincent Le Goff 2017 +_Contrib by Vincent Le Goff 2017_ -This contrib adds the system of in-game Python in Evennia, allowing immortals -(or other trusted builders) to dynamically add features to individual objects. -Using custom Python set in-game, every immortal or privileged users could have a -specific room, exit, character, object or something else behave differently from -its "cousins". For these familiar with the use of softcode in MU`*`, like SMAUG -MudProgs, the ability to add arbitrary behavior to individual objects is a step -toward freedom. Keep in mind, however, the warning below, and read it carefully -before the rest of the documentation. +This contrib adds the ability to script with Python in-game. It allows trusted +staff/builders to dynamically add features and triggers to individual objects +without needing to do it in external Python modules. Using custom Python in-game, +specific rooms, exits, characters, objects etc can be made to behave differently from +its "cousins". This is similar to how softcode works for MU or MudProgs for DIKU. +Keep in mind, however, that allowing Python in-game comes with _severe_ +security concerns (you must trust your builders deeply), so read the warnings in +this module carefully before continuing. -[Read the documentation](./Contrib-Ingame-Python.md) +[Read the documentation](./Contrib-Ingame-Python.md) - [Browse the Code](evennia.contrib.base_systems.ingame_python) ### Contrib: `menu_login` -Contribution - Vincent-lg 2016, Griatch 2019 (rework for modern EvMenu) +_Contribution by Vincent-lg 2016. Reworked for modern EvMenu by Griatch, 2019._ -This changes the Evennia login to ask for the account name and password in -sequence instead of requiring you to enter both at once. It uses EvMenu under -the hood. +This changes the Evennia login to ask for the account name and password as a series +of questions instead of requiring you to enter both at once. It uses Evennia's +menu system `EvMenu` under the hood. -[Read the documentation](./Contrib-Menu-Login.md) +[Read the documentation](./Contrib-Menu-Login.md) - [Browse the Code](evennia.contrib.base_systems.menu_login) ### Contrib: `mux_comms_cmds` -Contribution - Griatch 2021 +_Contribution by Griatch 2021_ -In Evennia 1.0, the old Channel commands (originally inspired by MUX) were -replaced by the single `channel` command that performs all these function. -That command is still required to talk on channels. This contrib (extracted -from Evennia 0.9.5) reuses the channel-management of the base Channel command -but breaks out its functionality into separate Commands with MUX-familiar names. +In Evennia 1.0+, the old Channel commands (originally inspired by MUX) were +replaced by the single `channel` command that performs all these functions. +This contrib (extracted from Evennia 0.9.5) breaks out the functionality into +separate Commands more familiar to MU* users. This is just for show though, the +main `channel` command is still called under the hood. -[Read the documentation](./Contrib-Mux-Comms-Cmds.md) +[Read the documentation](./Contrib-Mux-Comms-Cmds.md) - [Browse the Code](evennia.contrib.base_systems.mux_comms_cmds) ### Contrib: `unixcommand` -Evennia contribution, Vincent Le Geoff 2017 +_Contribution by Vincent Le Geoff (vlgeoff), 2017_ -This module contains a command class that allows for unix-style command syntax -in-game, using --options, positional arguments and stuff like -n 10 etc -similarly to a unix command. It might not the best syntax for the average player +This module contains a command class with an alternate syntax parser implementing +Unix-style command syntax in-game. This means `--options`, positional arguments +and stuff like `-n 10`. It might not the best syntax for the average player but can be really useful for builders when they need to have a single command do -many things with many options. It uses the ArgumentParser from Python's standard +many things with many options. It uses the `ArgumentParser` from Python's standard library under the hood. -[Read the documentation](./Contrib-Unixcommand.md) +[Read the documentation](./Contrib-Unixcommand.md) - [Browse the Code](evennia.contrib.base_systems.unixcommand) @@ -150,13 +159,15 @@ to start creating content without no further additions (unless you want to)._ ### Contrib: `evscaperoom` -Evennia contrib - Griatch 2019 +_Contribution by Griatch, 2019_ -This 'Evennia escaperoom game engine' was created for the MUD Coders Guild game -Jam, April 14-May 15 2019. The theme for the jam was "One Room". This contains the -utilities and base classes and an empty example room. +A full engine for creating multiplayer escape-rooms in Evennia. Allows players to +spawn and join puzzle rooms that track their state independently. Any number of players +can join to solve a room together. This is the engine created for 'EvscapeRoom', which won +the MUD Coders Guild "One Room" Game Jam in April-May, 2019. The contrib has no game +content but contains the utilities and base classes and an empty example room. -[Read the documentation](./Contrib-Evscaperoom.md) +[Read the documentation](./Contrib-Evscaperoom.md) - [Browse the Code](evennia.contrib.full_systems.evscaperoom) @@ -173,104 +184,115 @@ roleplaying-specific systems, those are found in the `rpg` folder._ ### Contrib: `barter` -Evennia contribution - Griatch 2012 +_Contribution by Griatch, 2012_ This implements a full barter system - a way for players to safely -trade items between each other using code rather than simple free-form -talking. The advantage of this is increased buy/sell safety but it -also streamlines the process and makes it faster when doing many -transactions (since goods are automatically exchanged once both -agree). +trade items between each other in code rather than simple `give/get` +commands. This increases both safety (at no time will one player have +both goods and payment in-hand) and speed, since agreed goods will +be moved automatically). By just replacing one side with coin objects, +(or a mix of coins and goods), this also works fine for regular money +transactions. -[Read the documentation](./Contrib-Barter.md) +[Read the documentation](./Contrib-Barter.md) - [Browse the Code](evennia.contrib.game_systems.barter) ### Contrib: `clothing` -Evennia contribution - Tim Ashley Jenkins 2017 +_Contribution by Tim Ashley Jenkins, 2017_ -Provides a typeclass and commands for wearable clothing, -which is appended to a character's description when worn. +Provides a typeclass and commands for wearable clothing. These +look of these clothes are appended to the character's description when worn. -[Read the documentation](./Contrib-Clothing.md) +[Read the documentation](./Contrib-Clothing.md) - [Browse the Code](evennia.contrib.game_systems.clothing) ### Contrib: `cooldowns` -Evennia contrib - owllex, 2021 +_Contribution by owllex, 2021_ -This contrib provides a simple cooldown handler that can be attached to any -typeclassed Object or Account. A cooldown is a lightweight persistent -asynchronous timer that you can query to see if it is ready. +Cooldowns are used modelling rate-limited actions, like how often a +character can perform a given action; until a certain time has passed their +command can not be used again. This contrib provides a simple cooldown +handler that can be attached to any typeclass. A cooldown is a lightweight persistent +asynchronous timer that you can query to see if a certain time has yet passed. -[Read the documentation](./Contrib-Cooldowns.md) +[Read the documentation](./Contrib-Cooldowns.md) - [Browse the Code](evennia.contrib.game_systems.cooldowns) ### Contrib: `crafting` -Contrib - Griatch 2020 +_Contribution by Griatch 2020_ -This implements a full crafting system. The principle is that of a 'recipe': +This implements a full crafting system. The principle is that of a 'recipe', +where you combine items (tagged as ingredients) create something new. The recipe can also +require certain (non-consumed) tools. An example would be to use the 'bread recipe' to +combine 'flour', 'water' and 'yeast' with an 'oven' to bake a 'loaf of bread'. -[Read the documentation](./Contrib-Crafting.md) +[Read the documentation](./Contrib-Crafting.md) - [Browse the Code](evennia.contrib.game_systems.crafting) ### Contrib: `gendersub` -Contrib - Griatch 2015 +_Contribution by Griatch 2015_ This is a simple gender-aware Character class for allowing users to insert custom markers in their text to indicate gender-aware messaging. It relies on a modified msg() and is meant as an inspiration and starting point to how to do stuff like this. -[Read the documentation](./Contrib-Gendersub.md) +[Read the documentation](./Contrib-Gendersub.md) - [Browse the Code](evennia.contrib.game_systems.gendersub) ### Contrib: `mail` -Evennia Contribution - grungies1138 2016 +_Contribution by grungies1138 2016_ -A simple Brandymail style mail system that uses the Msg class from Evennia -Core. It has two Commands, both of which can be used on their own: +A simple Brandymail style mail system that uses the `Msg` class from Evennia +Core. It has two Commands for either sending mails between Accounts (out of game) +or between Characters (in-game). The two types of mails can be used together or +on their own. -[Read the documentation](./Contrib-Mail.md) +[Read the documentation](./Contrib-Mail.md) - [Browse the Code](evennia.contrib.game_systems.mail) ### Contrib: `multidescer` -Contrib - Griatch 2016 +_Contribution by Griatch 2016_ A "multidescer" is a concept from the MUSH world. It allows for creating, managing and switching between multiple character -descriptions. This multidescer will not require any changes to the -Character class, rather it will use the `multidescs` Attribute (a -list) and create it if it does not exist. +descriptions and is a way for quickly managing your look (such as when +changing clothes) in more free-form roleplaying systems. This will also +work well together with the `rpsystem` contrib. -[Read the documentation](./Contrib-Multidescer.md) +[Read the documentation](./Contrib-Multidescer.md) - [Browse the Code](evennia.contrib.game_systems.multidescer) ### Contrib: `puzzles` -Evennia contribution - Henddher 2018 +_Contribution by Henddher 2018_ -Provides a typeclass and commands for objects that can be combined (i.e. 'use'd) -to produce new objects. +Intended for adventure-game style combination puzzles, such as combining fruits +and a blender to create a smoothie. Provides a typeclass and commands for objects +that can be combined (i.e. used together). Unlike the `crafting` contrib, each +puzzle is built from unique objects rather than using tags and a builder can create +the puzzle entirely from in-game. -[Read the documentation](./Contrib-Puzzles.md) +[Read the documentation](./Contrib-Puzzles.md) - [Browse the Code](evennia.contrib.game_systems.puzzles) ### Contrib: `turnbattle` -Contrib - Tim Ashley Jenkins 2017 +_Contribution by Tim Ashley Jenkins, 2017_ This is a framework for a simple turn-based combat system, similar to those used in D&D-style tabletop role playing games. It allows @@ -280,7 +302,7 @@ has a limited time to decide their action for that turn (30 seconds by default), and combat progresses through the turn order, looping through the participants until the fight ends. -[Read the documentation](./Contrib-Turnbattle.md) +[Read the documentation](./Contrib-Turnbattle.md) - [Browse the Code](evennia.contrib.game_systems.turnbattle) @@ -295,80 +317,77 @@ contribs related to rooms, exits and map building._ ### Contrib: `extended_room` -Evennia Contribution - Griatch 2012, vincent-lg 2019 +_Contribution - Griatch 2012, vincent-lg 2019_ -This is an extended Room typeclass for Evennia. It is supported -by an extended `Look` command and an extended `desc` command, also -in this module. +This extends the normal `Room` typeclass to allow its description to change +with time-of-day and/or season. It also adds 'details' for the player to look at +in the room (without having to create a new in-game object for each). The room is +supported by new `look` and `desc` commands. -[Read the documentation](./Contrib-Extended-Room.md) +[Read the documentation](./Contrib-Extended-Room.md) - [Browse the Code](evennia.contrib.grid.extended_room) ### Contrib: `mapbuilder` -Contribution - Cloud_Keeper 2016 +_Contribution by Cloud_Keeper 2016_ -Build a map from a 2D ASCII map. +Build a game map from the drawing of a 2D ASCII map. -[Read the documentation](./Contrib-Mapbuilder.md) +[Read the documentation](./Contrib-Mapbuilder.md) - [Browse the Code](evennia.contrib.grid.mapbuilder) ### Contrib: `simpledoor` -Contribution - Griatch 2016 +_Contribution by Griatch, 2016_ A simple two-way exit that represents a door that can be opened and -closed. Can easily be expanded from to make it lockable, destroyable -etc. Note that the simpledoor is based on Evennia locks, so it will -not work for a superuser (which bypasses all locks) - the superuser -will always appear to be able to close/open the door over and over -without the locks stopping you. To use the door, use `@quell` or a -non-superuser account. +closed from both sides. Can easily be expanded to make it lockable, +destroyable etc. -[Read the documentation](./Contrib-Simpledoor.md) +[Read the documentation](./Contrib-Simpledoor.md) - [Browse the Code](evennia.contrib.grid.simpledoor) ### Contrib: `slow_exit` -Contribution - Griatch 2014 +_Contribution by Griatch 2014_ -This is an example of an Exit-type that delays its traversal. This simulates -slow movement, common in many different types of games. The contrib also -contains two commands, `CmdSetSpeed` and CmdStop for changing the movement speed +An example of an Exit-type that delays its traversal. This simulates +slow movement, common in many games. The contrib also +contains two commands, `setspeed` and `stop` for changing the movement speed and abort an ongoing traversal, respectively. -[Read the documentation](./Contrib-Slow-Exit.md) +[Read the documentation](./Contrib-Slow-Exit.md) - [Browse the Code](evennia.contrib.grid.slow_exit) ### Contrib: `wilderness` -Evennia contrib - titeuf87 2017 +_Contribution by titeuf87, 2017_ This contrib provides a wilderness map without actually creating a large number -of rooms - as you move, your room is instead updated with different -descriptions. This means you can make huge areas with little database use as +of rooms - as you move, you instead end up back in the same room but its description +changes. This means you can make huge areas with little database use as long as the rooms are relatively similar (name/desc changing). -[Read the documentation](./Contrib-Wilderness.md) +[Read the documentation](./Contrib-Wilderness.md) - [Browse the Code](evennia.contrib.grid.wilderness) ### Contrib: `xyzgrid` -Full grid coordinate- pathfinding and visualization system -Evennia Contrib by Griatch 2021 +_Contribution by Griatch 2021_ -The default Evennia's rooms are non-euclidian - they can connect -to each other with any types of exits without necessarily having a clear -position relative to each other. This gives maximum flexibility, but many games -want to use cardinal movements (north, east etc) and also features like finding -the shortest-path between two points. +Places Evennia's game world on an xy (z being different maps) coordinate grid. +Grid is created and maintained externally by drawing and parsing 2D ASCII maps, +including teleports, map transitions and special markers to aid pathfinding. +Supports very fast shortest-route pathfinding on each map. Also includes a +fast view function for seeing only a limited number of steps away from your +current location (useful for displaying the grid as an in-game, updating map). -[Read the documentation](./Contrib-XYZGrid.md) +[Read the documentation](./Contrib-XYZGrid.md) - [Browse the Code](evennia.contrib.grid.xyzgrid) @@ -383,48 +402,59 @@ and rule implementation like character traits, dice rolling and emoting._ ### Contrib: `dice` -Rolls dice for roleplaying, in-game gambling or GM:ing +_Contribution by Griatch, 2012_ -Evennia contribution - Griatch 2012 +A dice roller for any number and side of dice. Adds in-game dice rolling +(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target) +and functions for rolling dice in code. Command also supports hidden or secret +rolls for use by a human game master. -[Read the documentation](./Contrib-Dice.md) +[Read the documentation](./Contrib-Dice.md) - [Browse the Code](evennia.contrib.rpg.dice) ### Contrib: `health_bar` -Contrib - Tim Ashley Jenkins 2017 +_Contribution by Tim Ashley Jenkins, 2017_ The function provided in this module lets you easily display visual -bars or meters - "health bar" is merely the most obvious use for this, -though these bars are highly customizable and can be used for any sort -of appropriate data besides player health. +bars or meters as a colorful bar instead of just a number. A "health bar" +is merely the most obvious use for this, but the bar is highly customizable +and can be used for any sort of appropriate data besides player health. -[Read the documentation](./Contrib-Health-Bar.md) +[Read the documentation](./Contrib-Health-Bar.md) - [Browse the Code](evennia.contrib.rpg.health_bar) ### Contrib: `rpsystem` -Roleplaying emotes/sdescs - Griatch, 2015 -Language/whisper emotes - Griatch, 2015 +_Contribution by Griatch, 2015_ -## Roleplaying emotes +A full roleplaying emote system. Short-descriptions and recognition (only +know people by their looks until you assign a name to them). Room poses. Masks/disguises +(hide your description). Speak directly in emote, with optional language obscuration +(words get garbled if you don't know the language, you can also have different languages +with different 'sounding' garbling). Whispers can be partly overheard from a distance. A +very powerful in-emote reference system, for referencing and differentiate targets +(including objects). -[Read the documentation](./Contrib-RPSystem.md) +[Read the documentation](./Contrib-RPSystem.md) - [Browse the Code](evennia.contrib.rpg.rpsystem) ### Contrib: `traits` -Whitenoise 2014, Ainneve contributors, -Griatch 2020 +_Contribution by Griatch 2020, based on code by Whitenoise and Ainneve contribs, 2014_ A `Trait` represents a modifiable property on (usually) a Character. They can be used to represent everything from attributes (str, agi etc) to skills -(hunting 10, swords 14 etc) and dynamically changing things like HP, XP etc. +(hunting 10, swords 14 etc) and dynamically changing things like HP, XP etc. +Traits differ from normal Attributes in that they track their changes and limit +themselves to particular value-ranges. One can add/subtract from them easily and +they can even change dynamically at a particular rate (like you being poisoned or +healed). -[Read the documentation](./Contrib-Traits.md) +[Read the documentation](./Contrib-Traits.md) - [Browse the Code](evennia.contrib.rpg.traits) @@ -440,71 +470,72 @@ tutorials are found here. Also the home of the Tutorial World demo adventure._ ### Contrib: `batchprocessor` -Contibution - Griatch 2012 +_Contibution by Griatch, 2012_ -The batch processor is used for generating in-game content from one or more -static files. Files can be stored with version control and then 'applied' -to the game to create content. +Simple examples for the batch-processor. The batch processor is used for generating +in-game content from one or more static files. Files can be stored with version +control and then 'applied' to the game to create content. -[Read the documentation](./Contrib-Batchprocessor.md) +[Read the documentation](./Contrib-Batchprocessor.md) - [Browse the Code](evennia.contrib.tutorials.batchprocessor) ### Contrib: `bodyfunctions` -Griatch - 2012 +_Contribution by Griatch, 2012_ Example script for testing. This adds a simple timer that has your -character make observations and notices at irregular intervals. +character make small verbal observations at irregular intervals. -[Read the documentation](./Contrib-Bodyfunctions.md) +[Read the documentation](./Contrib-Bodyfunctions.md) - [Browse the Code](evennia.contrib.tutorials.bodyfunctions) ### Contrib: `mirror` -A simple mirror object to experiment with. +_Contribution by Griatch, 2017_ -A simple mirror object that +A simple mirror object to experiment with. It will respond to being looked at. -[Read the documentation](./Contrib-Mirror.md) +[Read the documentation](./Contrib-Mirror.md) - [Browse the Code](evennia.contrib.tutorials.mirror) ### Contrib: `red_button` -Griatch - 2011 +_Contribution by Griatch, 2011_ -This is a more advanced example object with its own functionality (commands) -on it. +A red button that you can press to have an effect. This is a more advanced example +object with its own functionality and state tracking. -[Read the documentation](./Contrib-Red-Button.md) +[Read the documentation](./Contrib-Red-Button.md) - [Browse the Code](evennia.contrib.tutorials.red_button) ### Contrib: `talking_npc` -Contribution - Griatch 2011, grungies1138, 2016 +_Contribution by Griatch 2011. Updated by grungies1138, 2016_ -This is a static NPC object capable of holding a simple menu-driven -conversation. It's just meant as an example. +This is an example of a static NPC object capable of holding a simple menu-driven +conversation. Suitable for example as a quest giver or merchant. -[Read the documentation](./Contrib-Talking-Npc.md) +[Read the documentation](./Contrib-Talking-Npc.md) - [Browse the Code](evennia.contrib.tutorials.talking_npc) ### Contrib: `tutorial_world` -Griatch 2011, 2015 +_Contribution by Griatch 2011, 2015_ -This is a stand-alone tutorial area for an unmodified Evennia install. +A stand-alone tutorial area for an unmodified Evennia install. Think of it as a sort of single-player adventure rather than a full-fledged multi-player game world. The various rooms and objects -herein are designed to show off features of the engine, not to be a +are designed to show off features of Evennia, not to be a very challenging (nor long) gaming experience. As such it's of course -only skimming the surface of what is possible. +only skimming the surface of what is possible. Taking this apart +is a great way to start learning the system. -[Read the documentation](./Contrib-Tutorial-World.md) +[Read the documentation](./Contrib-Tutorial-World.md) - [Browse the Code](evennia.contrib.tutorials.tutorial_world) @@ -519,54 +550,53 @@ and more._ ### Contrib: `auditing` -Contrib - Johnny 2017 +_Contribution by Johnny, 2017_ -This is a tap that optionally intercepts all data sent to/from clients and the -server and passes it to a callback of your choosing. +Utility that taps and intercepts all data sent to/from clients and the +server and passes it to a callback of your choosing. This is intended for +quality assurance, post-incident investigations and debugging. -[Read the documentation](./Contrib-Auditing.md) +[Read the documentation](./Contrib-Auditing.md) - [Browse the Code](evennia.contrib.utils.auditing) ### Contrib: `fieldfill` -Contrib - Tim Ashley Jenkins 2018 +_Contribution by Tim Ashley Jenkins, 2018_ -This module contains a function that calls an easily customizable EvMenu - this -menu presents the player with a fillable form, with fields that can be filled -out in any order. Each field's value can be verified, with the function -allowing easy checks for text and integer input, minimum and maximum values / -character lengths, or can even be verified by a custom function. Once the form -is submitted, the form's data is submitted as a dictionary to any callable of -your choice. +This module contains a function that generates an `EvMenu` for you - this +menu presents the player with a form of fields that can be filled +out in any order (e.g. for character generation or building). Each field's value can +be verified, with the function allowing easy checks for text and integer input, +minimum and maximum values / character lengths, or can even be verified by a custom +function. Once the form is submitted, the form's data is submitted as a dictionary +to any callable of your choice. -[Read the documentation](./Contrib-Fieldfill.md) +[Read the documentation](./Contrib-Fieldfill.md) - [Browse the Code](evennia.contrib.utils.fieldfill) ### Contrib: `random_string_generator` -Contribution - Vincent Le Goff 2017 +_Contribution by Vincent Le Goff (vlgeoff), 2017_ -This contrib can be used to generate pseudo-random strings of information +This utility can be used to generate pseudo-random strings of information with specific criteria. You could, for instance, use it to generate -phone numbers, license plate numbers, validation codes, non-sensivite -passwords and so on. The strings generated by the generator will be -stored and won't be available again in order to avoid repetition. -Here's a very simple example: +phone numbers, license plate numbers, validation codes, in-game security +passwords and so on. The strings generated will be stored and won't be repeated. -[Read the documentation](./Contrib-Random-String-Generator.md) +[Read the documentation](./Contrib-Random-String-Generator.md) - [Browse the Code](evennia.contrib.utils.random_string_generator) ### Contrib: `tree_select` -Contrib - Tim Ashley Jenkins 2017 +_Contribution by Tim Ashley Jenkins, 2017_ -This module allows you to create and initialize an entire branching EvMenu -instance with nothing but a multi-line string passed to one function. +This utility allows you to create and initialize an entire branching EvMenu +instance from a multi-line string passed to one function. -[Read the documentation](./Contrib-Tree-Select.md) +[Read the documentation](./Contrib-Tree-Select.md) - [Browse the Code](evennia.contrib.utils.tree_select) @@ -574,52 +604,52 @@ instance with nothing but a multi-line string passed to one function. ```{toctree} -:depth: 2 Contribs/Contrib-AWSStorage.md -Contribs/Contrib-Building-Menu.md -Contribs/Contrib-Color-Markups.md -Contribs/Contrib-Custom-Gametime.md -Contribs/Contrib-Email-Login.md -Contribs/Contrib-Ingame-Python.md -Contribs/Contrib-Menu-Login.md -Contribs/Contrib-Mux-Comms-Cmds.md -Contribs/Contrib-Unixcommand.md -Contribs/Contrib-Evscaperoom.md -Contribs/Contrib-Barter.md -Contribs/Contrib-Clothing.md -Contribs/Contrib-Cooldowns.md -Contribs/Contrib-Crafting.md -Contribs/Contrib-Gendersub.md -Contribs/Contrib-Mail.md -Contribs/Contrib-Multidescer.md -Contribs/Contrib-Puzzles.md -Contribs/Contrib-Turnbattle.md -Contribs/Contrib-Extended-Room.md -Contribs/Contrib-Mapbuilder.md -Contribs/Contrib-Simpledoor.md -Contribs/Contrib-Slow-Exit.md -Contribs/Contrib-Wilderness.md -Contribs/Contrib-XYZGrid.md -Contribs/Contrib-Dice.md -Contribs/Contrib-Health-Bar.md -Contribs/Contrib-RPSystem.md -Contribs/Contrib-Traits.md -Contribs/Contrib-Batchprocessor.md -Contribs/Contrib-Bodyfunctions.md -Contribs/Contrib-Mirror.md -Contribs/Contrib-Red-Button.md -Contribs/Contrib-Talking-Npc.md -Contribs/Contrib-Tutorial-World.md -Contribs/Contrib-Auditing.md -Contribs/Contrib-Fieldfill.md -Contribs/Contrib-Random-String-Generator.md -Contribs/Contrib-Tree-Select.md + Contribs/Contrib-Building-Menu.md + Contribs/Contrib-Color-Markups.md + Contribs/Contrib-Custom-Gametime.md + Contribs/Contrib-Email-Login.md + Contribs/Contrib-Ingame-Python.md + Contribs/Contrib-Menu-Login.md + Contribs/Contrib-Mux-Comms-Cmds.md + Contribs/Contrib-Unixcommand.md + Contribs/Contrib-Evscaperoom.md + Contribs/Contrib-Barter.md + Contribs/Contrib-Clothing.md + Contribs/Contrib-Cooldowns.md + Contribs/Contrib-Crafting.md + Contribs/Contrib-Gendersub.md + Contribs/Contrib-Mail.md + Contribs/Contrib-Multidescer.md + Contribs/Contrib-Puzzles.md + Contribs/Contrib-Turnbattle.md + Contribs/Contrib-Extended-Room.md + Contribs/Contrib-Mapbuilder.md + Contribs/Contrib-Simpledoor.md + Contribs/Contrib-Slow-Exit.md + Contribs/Contrib-Wilderness.md + Contribs/Contrib-XYZGrid.md + Contribs/Contrib-Dice.md + Contribs/Contrib-Health-Bar.md + Contribs/Contrib-RPSystem.md + Contribs/Contrib-Traits.md + Contribs/Contrib-Batchprocessor.md + Contribs/Contrib-Bodyfunctions.md + Contribs/Contrib-Mirror.md + Contribs/Contrib-Red-Button.md + Contribs/Contrib-Talking-Npc.md + Contribs/Contrib-Tutorial-World.md + Contribs/Contrib-Auditing.md + Contribs/Contrib-Fieldfill.md + Contribs/Contrib-Random-String-Generator.md + Contribs/Contrib-Tree-Select.md +``` ---- -This document page is auto-generated from the sources. Manual changes +This document page is auto-generated. Manual changes will be overwritten. diff --git a/docs/source/Contribs/Contrib-Puzzles.md b/docs/source/Contribs/Contrib-Puzzles.md index ee37c819b8..6d9b331760 100644 --- a/docs/source/Contribs/Contrib-Puzzles.md +++ b/docs/source/Contribs/Contrib-Puzzles.md @@ -1,18 +1,21 @@ # Puzzles System -Evennia contribution - Henddher 2018 +Contribution by Henddher 2018 -Provides a typeclass and commands for objects that can be combined (i.e. 'use'd) -to produce new objects. +Intended for adventure-game style combination puzzles, such as combining fruits +and a blender to create a smoothie. Provides a typeclass and commands for objects +that can be combined (i.e. used together). Unlike the `crafting` contrib, each +puzzle is built from unique objects rather than using tags and a builder can create +the puzzle entirely from in-game. -A Puzzle is a recipe of what objects (aka parts) must be combined by a player so +A `Puzzle` is a recipe of what objects (aka parts) must be combined by a player so a new set of objects (aka results) are automatically created. ## Installation -Add the PuzzleSystemCmdSet to all players (e.g. in their Character typeclass). +Add the `PuzzleSystemCmdSet` to all players (e.g. in their Character typeclass). -Alternatively: +Alternatively (for quick testing): py self.cmdset.add('evennia.contrib.game_systems.puzzles.PuzzleSystemCmdSet') diff --git a/docs/source/Contribs/Contrib-RPSystem.md b/docs/source/Contribs/Contrib-RPSystem.md index 9abee81e02..4ed4eeb644 100644 --- a/docs/source/Contribs/Contrib-RPSystem.md +++ b/docs/source/Contribs/Contrib-RPSystem.md @@ -1,7 +1,17 @@ # Roleplaying base system for Evennia -Roleplaying emotes/sdescs - Griatch, 2015 -Language/whisper emotes - Griatch, 2015 +Contribution by Griatch, 2015 + +A full roleplaying emote system. Short-descriptions and recognition (only +know people by their looks until you assign a name to them). Room poses. Masks/disguises +(hide your description). Speak directly in emote, with optional language obscuration +(words get garbled if you don't know the language, you can also have different languages +with different 'sounding' garbling). Whispers can be partly overheard from a distance. A +very powerful in-emote reference system, for referencing and differentiate targets +(including objects). + +The system contains of two main modules - the roleplaying emote system and the language +obscuration module. ## Roleplaying emotes diff --git a/docs/source/Contribs/Contrib-Random-String-Generator.md b/docs/source/Contribs/Contrib-Random-String-Generator.md index 936f0f9fbc..a7e4c2af9c 100644 --- a/docs/source/Contribs/Contrib-Random-String-Generator.md +++ b/docs/source/Contribs/Contrib-Random-String-Generator.md @@ -1,12 +1,14 @@ # Pseudo-random generator and registry -Contribution - Vincent Le Goff 2017 +Contribution by Vincent Le Goff (vlgeoff), 2017 -This contrib can be used to generate pseudo-random strings of information +This utility can be used to generate pseudo-random strings of information with specific criteria. You could, for instance, use it to generate -phone numbers, license plate numbers, validation codes, non-sensivite -passwords and so on. The strings generated by the generator will be -stored and won't be available again in order to avoid repetition. +phone numbers, license plate numbers, validation codes, in-game security +passwords and so on. The strings generated will be stored and won't be repeated. + +## Usage Example + Here's a very simple example: ```python diff --git a/docs/source/Contribs/Contrib-Red-Button.md b/docs/source/Contribs/Contrib-Red-Button.md index 70c1a771a6..b3c30e955e 100644 --- a/docs/source/Contribs/Contrib-Red-Button.md +++ b/docs/source/Contribs/Contrib-Red-Button.md @@ -1,9 +1,9 @@ # Red Button example -Griatch - 2011 +Contribution by Griatch, 2011 -This is a more advanced example object with its own functionality (commands) -on it. +A red button that you can press to have an effect. This is a more advanced example +object with its own functionality and state tracking. Create the button with diff --git a/docs/source/Contribs/Contrib-Simpledoor.md b/docs/source/Contribs/Contrib-Simpledoor.md index ea464fa613..219de31c93 100644 --- a/docs/source/Contribs/Contrib-Simpledoor.md +++ b/docs/source/Contribs/Contrib-Simpledoor.md @@ -1,13 +1,15 @@ # SimpleDoor -Contribution - Griatch 2016 +Contribution by Griatch, 2016 A simple two-way exit that represents a door that can be opened and -closed. Can easily be expanded from to make it lockable, destroyable -etc. Note that the simpledoor is based on Evennia locks, so it will -not work for a superuser (which bypasses all locks) - the superuser +closed from both sides. Can easily be expanded to make it lockable, +destroyable etc. + +Note that the simpledoor is based on Evennia locks, so it will +not work for a superuser (which bypasses all locks). The superuser will always appear to be able to close/open the door over and over -without the locks stopping you. To use the door, use `@quell` or a +without the locks stopping you. To use the door, use `quell` or a non-superuser account. ## Installation: diff --git a/docs/source/Contribs/Contrib-Slow-Exit.md b/docs/source/Contribs/Contrib-Slow-Exit.md index 57ea4cac03..401c7be1bf 100644 --- a/docs/source/Contribs/Contrib-Slow-Exit.md +++ b/docs/source/Contribs/Contrib-Slow-Exit.md @@ -1,10 +1,10 @@ # Slow Exit -Contribution - Griatch 2014 +Contribution by Griatch 2014 -This is an example of an Exit-type that delays its traversal. This simulates -slow movement, common in many different types of games. The contrib also -contains two commands, `CmdSetSpeed` and CmdStop for changing the movement speed +An example of an Exit-type that delays its traversal. This simulates +slow movement, common in many games. The contrib also +contains two commands, `setspeed` and `stop` for changing the movement speed and abort an ongoing traversal, respectively. ## Installation: diff --git a/docs/source/Contribs/Contrib-Talking-Npc.md b/docs/source/Contribs/Contrib-Talking-Npc.md index 0d43feaa10..3836a6bf11 100644 --- a/docs/source/Contribs/Contrib-Talking-Npc.md +++ b/docs/source/Contribs/Contrib-Talking-Npc.md @@ -1,9 +1,9 @@ # Talkative NPC example -Contribution - Griatch 2011, grungies1138, 2016 +Contribution by Griatch 2011. Updated by grungies1138, 2016 -This is a static NPC object capable of holding a simple menu-driven -conversation. It's just meant as an example. +This is an example of a static NPC object capable of holding a simple menu-driven +conversation. Suitable for example as a quest giver or merchant. ## Installation diff --git a/docs/source/Contribs/Contrib-Traits.md b/docs/source/Contribs/Contrib-Traits.md index a49d4f8679..be56c8ab76 100644 --- a/docs/source/Contribs/Contrib-Traits.md +++ b/docs/source/Contribs/Contrib-Traits.md @@ -1,12 +1,10 @@ # Traits -Whitenoise 2014, Ainneve contributors, -Griatch 2020 +Contribution by Griatch 2020, based on code by Whitenoise and Ainneve contribs, 2014 A `Trait` represents a modifiable property on (usually) a Character. They can be used to represent everything from attributes (str, agi etc) to skills -(hunting 10, swords 14 etc) and dynamically changing things like HP, XP etc. - +(hunting 10, swords 14 etc) and dynamically changing things like HP, XP etc. Traits differ from normal Attributes in that they track their changes and limit themselves to particular value-ranges. One can add/subtract from them easily and they can even change dynamically at a particular rate (like you being poisoned or diff --git a/docs/source/Contribs/Contrib-Tree-Select.md b/docs/source/Contribs/Contrib-Tree-Select.md index a8445d9e50..e0e9698ba8 100644 --- a/docs/source/Contribs/Contrib-Tree-Select.md +++ b/docs/source/Contribs/Contrib-Tree-Select.md @@ -1,14 +1,16 @@ # Easy menu selection tree -Contrib - Tim Ashley Jenkins 2017 +Contribution by Tim Ashley Jenkins, 2017 -This module allows you to create and initialize an entire branching EvMenu -instance with nothing but a multi-line string passed to one function. +This utility allows you to create and initialize an entire branching EvMenu +instance from a multi-line string passed to one function. -EvMenu is incredibly powerful and flexible, but using it for simple menus -can often be fairly cumbersome - a simple menu that can branch into five -categories would require six nodes, each with options represented as a list -of dictionaries. +> Note: Since the time this contrib was created, EvMenu itself got its own templating +> language that has more features and is not compatible with the style used in +> this contrib. Both can still be used in parallel. + +`EvMenu` is incredibly powerful and flexible but it can be a little overwhelming +and offers a lot of power that may not be needed for a simple multiple-choice menu. This module provides a function, `init_tree_selection`, which acts as a frontend for EvMenu, dynamically sourcing the options from a multi-line string you diff --git a/docs/source/Contribs/Contrib-Turnbattle.md b/docs/source/Contribs/Contrib-Turnbattle.md index d1b7b20bb4..a35d96a0a3 100644 --- a/docs/source/Contribs/Contrib-Turnbattle.md +++ b/docs/source/Contribs/Contrib-Turnbattle.md @@ -1,6 +1,6 @@ # Turn based battle system framework -Contrib - Tim Ashley Jenkins 2017 +Contribution by Tim Ashley Jenkins, 2017 This is a framework for a simple turn-based combat system, similar to those used in D&D-style tabletop role playing games. It allows diff --git a/docs/source/Contribs/Contrib-Tutorial-World.md b/docs/source/Contribs/Contrib-Tutorial-World.md index 72d37fd601..dee6e663b3 100644 --- a/docs/source/Contribs/Contrib-Tutorial-World.md +++ b/docs/source/Contribs/Contrib-Tutorial-World.md @@ -1,13 +1,14 @@ # Evennia Tutorial World -Griatch 2011, 2015 +Contribution by Griatch 2011, 2015 -This is a stand-alone tutorial area for an unmodified Evennia install. +A stand-alone tutorial area for an unmodified Evennia install. Think of it as a sort of single-player adventure rather than a full-fledged multi-player game world. The various rooms and objects -herein are designed to show off features of the engine, not to be a +are designed to show off features of Evennia, not to be a very challenging (nor long) gaming experience. As such it's of course -only skimming the surface of what is possible. +only skimming the surface of what is possible. Taking this apart +is a great way to start learning the system. The tutorial world also includes a game tutor menu example, exemplifying Evmenu. diff --git a/docs/source/Contribs/Contrib-Unixcommand.md b/docs/source/Contribs/Contrib-Unixcommand.md index d9958e1c80..d63ba3241d 100644 --- a/docs/source/Contribs/Contrib-Unixcommand.md +++ b/docs/source/Contribs/Contrib-Unixcommand.md @@ -1,12 +1,12 @@ # Unix-like Command style parent -Evennia contribution, Vincent Le Geoff 2017 +Contribution by Vincent Le Geoff (vlgeoff), 2017 -This module contains a command class that allows for unix-style command syntax -in-game, using --options, positional arguments and stuff like -n 10 etc -similarly to a unix command. It might not the best syntax for the average player +This module contains a command class with an alternate syntax parser implementing +Unix-style command syntax in-game. This means `--options`, positional arguments +and stuff like `-n 10`. It might not the best syntax for the average player but can be really useful for builders when they need to have a single command do -many things with many options. It uses the ArgumentParser from Python's standard +many things with many options. It uses the `ArgumentParser` from Python's standard library under the hood. ## Installation diff --git a/docs/source/Contribs/Contrib-Wilderness.md b/docs/source/Contribs/Contrib-Wilderness.md index 96fce8e37b..bac22e1f6e 100644 --- a/docs/source/Contribs/Contrib-Wilderness.md +++ b/docs/source/Contribs/Contrib-Wilderness.md @@ -1,10 +1,10 @@ # Wilderness system -Evennia contrib - titeuf87 2017 +Contribution by titeuf87, 2017 This contrib provides a wilderness map without actually creating a large number -of rooms - as you move, your room is instead updated with different -descriptions. This means you can make huge areas with little database use as +of rooms - as you move, you instead end up back in the same room but its description +changes. This means you can make huge areas with little database use as long as the rooms are relatively similar (name/desc changing). ## Installation diff --git a/docs/source/Contribs/Contrib-XYZGrid.md b/docs/source/Contribs/Contrib-XYZGrid.md index 77f6e854ab..ab87a7fdaf 100644 --- a/docs/source/Contribs/Contrib-XYZGrid.md +++ b/docs/source/Contribs/Contrib-XYZGrid.md @@ -1,7 +1,1334 @@ # XYZgrid -Full grid coordinate- pathfinding and visualization system -Evennia Contrib by Griatch 2021 +Contribution by Griatch 2021 + +Places Evennia's game world on an xy (z being different maps) coordinate grid. +Grid is created and maintained externally by drawing and parsing 2D ASCII maps, +including teleports, map transitions and special markers to aid pathfinding. +Supports very fast shortest-route pathfinding on each map. Also includes a +fast view function for seeing only a limited number of steps away from your +current location (useful for displaying the grid as an in-game, updating map). + +Grid-management is done outside of the game using a new evennia-launcher +option. + +## Examples + + + +``` +#-#-#-# # +| / d +#-# | # + \ u |\ +o---#-----#---+-#-# +| ^ |/ +| | # +v | \ +#-#-#-#-#-# #---# + |x|x| / + #-#-# #- +``` + +``` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + #---# + / + @- +-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Dungeon Entrance +To the east, a narrow opening leads into darkness. +Exits: northeast and east + +``` + +## Installation + +1. XYZGrid requires the `scipy` library. Easiest is to just install the + optional/contrib requirements in `evennia/requirements_extra.txt` by + doing + + (cd to evennia/ folder) + pip install -r requirements_extra.txt + (then go back to your mygame/ folder) + + This will install all optional requirements of Evennia. +2. Import and add the `evennia.contrib.commands.XYZGridCmdSet` to the + `CharacterCmdset` cmdset in `mygame/commands.default_cmds.py`. Reload + the server. This makes the `map`, `goto/path` and the modified `teleport` and + `open` commands available in-game. +3. Edit `mygame/server/conf/settings.py` and add + + EXTRA_LAUNCHER_COMMANDS['xyzgrid'] = 'evennia.contrib.launchcmd.xyzcommand' + + and + + PROTOTYPE_MODULES += [’evennia.contrib.grid.xyzgrid.prototypes’] + + This will add the new ability to enter `evennia xyzgrid