Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 21:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Clean up contrib docs, autogeneration

Browse source
This commit is contained in:
Griatch 2022-01-08 14:40:58 +01:00
parent b922cf9b3c
commit e96bbb4b86
94 changed files with 4126 additions and 2536 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/pylib/contrib_readmes2docs.py
View file

@ -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 = """
----
<small>This document page is auto-generated from the sources. Manual changes
<small>This document page is auto-generated. Manual changes
will be overwritten.</small>
"""
@ -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)

158
docs/source/Concepts/Change-Messages-Per-Receiver.md
View file

@ -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.
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.

2
docs/source/Concepts/Soft-Code.md
View file

@ -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.

8
docs/source/Contribs/Contrib-AWSStorage.md
View file

@ -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,

16
docs/source/Contribs/Contrib-Auditing.md
View file

@ -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.

18
docs/source/Contribs/Contrib-Barter.md
View file

@ -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

8
docs/source/Contribs/Contrib-Batchprocessor.md
View file

@ -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:

4
docs/source/Contribs/Contrib-Bodyfunctions.md
View file

@ -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)

14
docs/source/Contribs/Contrib-Building-Menu.md
View file

@ -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

11
docs/source/Contribs/Contrib-Clothing.md
View file

@ -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

5
docs/source/Contribs/Contrib-Color-Markups.md
View file

@ -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

15
docs/source/Contribs/Contrib-Cooldowns.md
View file

@ -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

282
docs/source/Contribs/Contrib-Crafting.md
View file

@ -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 <recipe> [from <ingredient>,...] [using <tool>, ...]
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 <recipe> [from <ingredient>,...] [using <tool>, ...]
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.
----

9
docs/source/Contribs/Contrib-Custom-Gametime.md
View file

@ -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

8
docs/source/Contribs/Contrib-Dice.md
View file

@ -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:

7
docs/source/Contribs/Contrib-Email-Login.md
View file

@ -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

12
docs/source/Contribs/Contrib-Evscaperoom.md
View file

@ -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!

9
docs/source/Contribs/Contrib-Extended-Room.md
View file

@ -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:

18
docs/source/Contribs/Contrib-Fieldfill.md
View file

@ -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)

2
docs/source/Contribs/Contrib-Gendersub.md
View file

@ -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

8
docs/source/Contribs/Contrib-Health-Bar.md
View file

@ -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

32
docs/source/Contribs/Dialogues-in-events.md → docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md
View file

@ -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).
events).

32
docs/source/Contribs/A-voice-operated-elevator-using-events.md → docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Elevator.md
View file

@ -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)

37
docs/source/Contribs/Contrib-Ingame-Python.md
View file

@ -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 |
+~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

12
docs/source/Contribs/Contrib-Mail.md
View file

@ -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

4
docs/source/Contribs/Contrib-Mapbuilder.md
View file

@ -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:

8
docs/source/Contribs/Contrib-Menu-Login.md
View file

@ -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

4
docs/source/Contribs/Contrib-Mirror.md
View file

@ -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

13
docs/source/Contribs/Contrib-Multidescer.md
View file

@ -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

32
docs/source/Contribs/Contrib-Mux-Comms-Cmds.md
View file

@ -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

482
docs/source/Contribs/Contrib-Overview.md
View file

@ -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
```
----
<small>This document page is auto-generated from the sources. Manual changes
<small>This document page is auto-generated. Manual changes
will be overwritten.</small>

15
docs/source/Contribs/Contrib-Puzzles.md
View file

@ -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')

14
docs/source/Contribs/Contrib-RPSystem.md
View file

@ -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

12
docs/source/Contribs/Contrib-Random-String-Generator.md
View file

@ -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

6
docs/source/Contribs/Contrib-Red-Button.md
View file

@ -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

12
docs/source/Contribs/Contrib-Simpledoor.md
View file

@ -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:

8
docs/source/Contribs/Contrib-Slow-Exit.md
View file

@ -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:

6
docs/source/Contribs/Contrib-Talking-Npc.md
View file

@ -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

6
docs/source/Contribs/Contrib-Traits.md
View file

@ -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

16
docs/source/Contribs/Contrib-Tree-Select.md
View file

@ -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

2
docs/source/Contribs/Contrib-Turnbattle.md
View file

@ -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

9
docs/source/Contribs/Contrib-Tutorial-World.md
View file

@ -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.

10
docs/source/Contribs/Contrib-Unixcommand.md
View file

@ -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

6
docs/source/Contribs/Contrib-Wilderness.md
View file

@ -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

1336
docs/source/Contribs/Contrib-XYZGrid.md
View file

File diff suppressed because it is too large Load diff

222
docs/source/Contribs/Crafting.md
View file

@ -1,222 +0,0 @@
# Crafting system contrib
_Contrib by Griatch 2020_
```{versionadded} 1.0
```
This contrib implements a full Crafting system that can be expanded and modified to fit your game.
- See the [evennia/contrib/crafting/crafting.py API](evennia.contrib.crafting.crafting) for installation
instructrions.
- See the [sword example](evennia.contrib.crafting.example_recipes) for an example of how to design
a crafting tree for crafting a sword from base elements.
From in-game it uses the new `craft` command:
```bash
> craft bread from flour, eggs, salt, water, yeast using oven, roller
> craft bandage from cloth using scissors
```
The syntax is `craft <recipe> [from <ingredient>,...][ using <tool>,...]`.
The above example uses the `bread` *recipe* and requires `flour`, `eggs`, `salt`, `water` and `yeast` objects
to be in your inventory. These will be consumed as part of crafting (baking) the bread.
The `oven` and `roller` are "tools" that can be either in your inventory or in your current location (you are not carrying an oven
around with you after all). Tools are *not* consumed in the crafting. If the added ingredients/tools matches
the requirements of the recipe, a new `bread` object will appear in the crafter's inventory.
If you wanted, you could also picture recipes without any consumables:
```
> craft fireball using wand, spellbook
```
With a little creativity, the 'recipe' concept could be adopted to all sorts of things, like puzzles or
magic systems.
In code, you can craft using the `evennia.contrib.crafting.crafting.craft` function:
```python
from evennia.contrib.crafting.crafting import craft
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.
## Adding new recipes
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.
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.
```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.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.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`.

1325
docs/source/Contribs/XYZGrid.md
View file

File diff suppressed because it is too large Load diff

90
docs/source/Contributing-Docs.md
View file

@ -12,10 +12,10 @@ in `evennia/docs/source/` and make a PR for it!
The documentation source files are `*.md` (Markdown) files found in `evennia/docs/source/`.
Markdown files are simple text files that can be edited with a normal text editor. They can also
contain raw HTML directives (but that is very rarely needed). They use
the [Markdown][commonmark] syntax with [MyST extensions][MyST].
the [Markdown][commonmark] syntax with [MyST extensions][MyST].
```{important}
You do _not_ need to be able to test/build the docs locally to contribute a documentation PR.
You do _not_ need to be able to test/build the docs locally to contribute a documentation PR.
We'll resolve any issues when we merge and build documentation. If you still want to build
the docs for yourself, instructions are [at the end of this document](#building-the-docs-locally).
```
@ -126,15 +126,15 @@ The link syntax is `[linktext](url_or_ref)` - this gives a clickable link [linkt
### Internal links
Most links will be to other pages of the documentation or to Evennia's API docs. Each document
heading can be referenced. The reference always starts with `#`. The heading-name is always
given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with
Most links will be to other pages of the documentation or to Evennia's API docs. Each document
heading can be referenced. The reference always starts with `#`. The heading-name is always
given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with
a single dash `-`.
As an example, let's assume the following is the contents of a file `Menu-stuff.md`:
```
# Menu items
# Menu items
Some text...
@ -143,28 +143,28 @@ Some text...
Some more text...
```
- From _inside the same file_ you can refer to each heading as
- From _inside the same file_ you can refer to each heading as
[menus](#menu-items)
[example](#a-yesno-example)
- From _another file_, you reference them as as
- From _another file_, you reference them as as
[menus](Menu-Stuff.md#menu-items)
[example](Menu-Stuff.md#a-yesno-example)
> It's fine to not include the `.md` file ending in the reference. The Evennia doc-build process
> It's fine to not include the `.md` file ending in the reference. The Evennia doc-build process
> will correct for this (and also insert any needed relative paths in the reference).
### API links
### API links
The documentation contains auto-generated documentation for all of Evennia's source code. You
can direct the reader to the sources by just giving the python-path to the location of the
The documentation contains auto-generated documentation for all of Evennia's source code. You
can direct the reader to the sources by just giving the python-path to the location of the
resource under the `evennia/` repository:
[DefaultObject](evennia.objects.objects.DefaultObject)
[DefaultObject](evennia.objects.objects.DefaultObject) <- like this!
[DefaultObject](evennia.objects.objects.DefaultObject) <- like this!
Note that you can't refer to files in the `mygame` folder this way. The game folder is generated
dynamically and is not part of the api docs. Refer to the parent classes in `evennia` where possible.
@ -180,12 +180,12 @@ These are links to resources outside of the documentation. We also provide some
- `[linkname](github:develop/evennia/objects.objects.py` - this points to code in the `develop` branch.
- `[make an issue](github:issue)` - this is a shortcut to the Evennia github issue-creation page.
> Note that if you want to refer to code, it's usually better to [link to the API](#api-links) as
> Note that if you want to refer to code, it's usually better to [link to the API](#api-links) as
> described above.
### Urls/References in one place
Urls can get long and if you are using the same url/reference in many places it can get a
Urls can get long and if you are using the same url/reference in many places it can get a
little cluttered. So you can also put the url as a 'footnote' at the end of your document.
You can then refer to it by putting your reference within square brackets `[ ]`. Here's an example:
@ -202,25 +202,25 @@ This is a [clickable link][mylink]. This is [another link][1].
This makes the main text a little shorter.
## Tables
## Tables
A table is done like this:
A table is done like this:
````
````
| heading1 | heading2 | heading3 |
| --- | --- | --- |
| --- | --- | --- |
| value1 | value2 | value3 |
| | value 4 | |
| value 5 | value 6 | |
````
| heading1 | heading2 | heading3 |
| --- | --- | --- |
| --- | --- | --- |
| value1 | value2 | value3 |
| | value 4 | |
| value 5 | value 6 | |
As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up) as long as you
As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up) as long as you
include the heading separators and make sure to add the correct number of `|` on every line.
@ -252,7 +252,7 @@ Everything within these backticks will be verbatim.
### Code blocks
A special 'verbatim' case is code examples - we want them to get code-highlighting for readability.
A special 'verbatim' case is code examples - we want them to get code-highlighting for readability.
This is done by using the triple-backticks and specify which language we use:
````
@ -281,22 +281,22 @@ class CmdEcho(Command):
For examples of using the Python command-line, use `python` language and `>>>` prompt.
````
```python
```python
>>> print("Hello World")
Hello World
```
````
```python
```python
>>> print("Hello World")
Hello World
```
When showing an in-game command, use the `shell` language type and `>` as the prompt.
When showing an in-game command, use the `shell` language type and `>` as the prompt.
Indent returns from the game.
````
```shell
````
```shell
> look at flower
Red Flower(#34)
A flower with red petals.
@ -310,19 +310,19 @@ Indent returns from the game.
```
For actual shell prompts you can either use `bash` language type or just indent the line.
Use `$` for the prompt when wanting to show what is an input and what is an output, otherwise
For actual shell prompts you can either use `bash` language type or just indent the line.
Use `$` for the prompt when wanting to show what is an input and what is an output, otherwise
skip it - it can be confusing to users not that familiar with the command line.
````
```bash
````
```bash
$ ls
evennia/ mygame/
```
evennia start --log
````
```bash
```bash
$ ls
evennia/ mygame/
```
@ -330,13 +330,13 @@ evennia/ mygame/
evennia start --log
## MyST directives
## MyST directives
Markdown is easy to read and use. But while it does most of what we need, there are some things it's
not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is
on the form
not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is
on the form
````
````
```{directive} any_options_here
content
@ -347,7 +347,7 @@ content
#### Note
This kind of note may pop more than doing a `> Note: ...`.
This kind of note may pop more than doing a `> Note: ...`.
````
```{note}
@ -436,7 +436,7 @@ for example to remind the reader of some concept relevant to the text.
- There can be bullet lists
- in here.
Separate sections with
Separate sections with
an empty line.
```
@ -447,12 +447,12 @@ an empty line.
- There can be bullet lists
- in here.
Separate sections with
Separate sections with
an empty line.
```
Hint: If wanting to make sure to have the next header appear on a row of its own (rather than
Hint: If wanting to make sure to have the next header appear on a row of its own (rather than
squeezed to the left of the sidebar), one can embed a plain HTML string in the markdown like so:
```html
@ -464,7 +464,7 @@ squeezed to the left of the sidebar), one can embed a plain HTML string in the m
### A more flexible code block
The regular Markdown Python codeblock is usually enough but for more direct control over the style, one
can also use the `{code-block}` directive that takes a set of additional `:options:`:
can also use the `{code-block}` directive that takes a set of additional `:options:`:
````
```{code-block} python
@ -536,7 +536,7 @@ same as Markdown.
The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting,
including header levels down to 4th level (`#### SubSubSubHeader`). After the module documentation it's
a good idea to end with four dashes `----`. This will create a visible line between the documentation and the
class/function docs to follow. See for example [the Traits docs](evennia.contrib.traits).
class/function docs to follow. See for example [the Traits docs](evennia.contrib.rpg.traits).
All non-private classes, methods and functions must have a Google-style docstring, as per the
[Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted
@ -545,8 +545,8 @@ into pretty api docs.
## Technical
Evennia leverages [Sphinx][sphinx] with the [MyST][MyST] extension, which allows us
to write our docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github)
rather than Sphinx' normal ReST syntax. The `MyST` parser allows for some extra syntax to
to write our docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github)
rather than Sphinx' normal ReST syntax. The `MyST` parser allows for some extra syntax to
make us able to express more complex displays than plain Markdown can.
For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon]
@ -729,4 +729,4 @@ available at https://evennia.github.io/evennia/latest/.
[linkdemo]: #Links
[retext]: https://github.com/retext-project/retext
[grip]: https://github.com/joeyespo/grip
[pycharm]: https://www.jetbrains.com/pycharm/
[pycharm]: https://www.jetbrains.com/pycharm/

83
docs/source/Contribs/Dynamic-In-Game-Map.md → docs/source/Howto/Dynamic-In-Game-Map.md
View file

@ -1,10 +1,9 @@
# Dynamic In Game Map
## Introduction
## Introduction
An often desired feature in a MUD is to show an in-game map to help navigation. The [Static in-game
map](./Static-In-Game-Map.md) tutorial solves this by creating a *static* map, meaning the map is pre-
map](../Contribs/Contrib-Mapbuilder.md) tutorial solves this by creating a *static* map, meaning the map is pre-
drawn once and for all - the rooms are then created to match that map. When walking around, parts of
the static map is then cut out and displayed next to the room description.
@ -13,7 +12,7 @@ the relationships we find between already existing rooms.
## The Grid of Rooms
There are at least two requirements needed for this tutorial to work.
There are at least two requirements needed for this tutorial to work.
1. The structure of your mud has to follow a logical layout. Evennia supports the layout of your
world to be 'logically' impossible with rooms looping to themselves or exits leading to the other
@ -54,7 +53,7 @@ We are going to create something that displays like this when you type 'look':
Your current location is defined by `[@]` while the `[.]`s are other rooms that the "worm" has seen
since departing from your location.
## Setting up the Map Display
## Setting up the Map Display
First we must define the components for displaying the map. For the "worm" to know what symbol to
draw on the map we will have it check an Attribute on the room it visits called `sector_type`. For
@ -66,9 +65,9 @@ in `mygame/world/map.py.`
```python
# in mygame/world/map.py
# the symbol is identified with a key "sector_type" on the
# Room. Keys None and "you" must always exist.
SYMBOLS = { None : ' . ', # for rooms without sector_type Attribute
# the symbol is identified with a key "sector_type" on the
# Room. Keys None and "you" must always exist.
SYMBOLS = { None : ' . ', # for rooms without sector_type Attribute
'you' : '[@]',
'SECT_INSIDE': '[.]' }
```
@ -122,7 +121,7 @@ class Map(object):
return board
def check_grid(self):
# this method simply checks the grid to make sure
# this method simply checks the grid to make sure
# that both max_l and max_w are odd numbers.
return True if self.max_length % 2 != 0 or self.max_width % 2 != 0\
else False
@ -141,7 +140,7 @@ def draw_room_on_map(room, max_distance):
return
for exit in room.exits:
if self.has_drawn(exit.destination):
if self.has_drawn(exit.destination):
# skip drawing if we already visited the destination
continue
else:
@ -163,14 +162,14 @@ go `4` spaces in either direction:
```
[.][.][.][.][@][.][.][.][.]
4 3 2 1 0 1 2 3 4
4 3 2 1 0 1 2 3 4
```
The max_distance can be set dynamically based on the size of the display area. As your width/length
The `max_distance` can be set dynamically based on the size of the display area. As your width/length
changes it becomes a simple algebraic linear relationship which is simply `max_distance =
(min(max_width, max_length) -1) / 2`.
## Building the Mapper
## Building the Mapper
Now we can start to fill our Map object with some methods. We are still missing a few methods that
are very important:
@ -184,8 +183,8 @@ n
self.curX/Y. .accordingly
* `self.start_loc_on_grid(self)` - the very first initial draw on the grid representing your
location in the middle of the grid
* 'self.show_map` - after everything is done convert the map into a readable string`
* `self.draw_room_on_map(self, room, max_distance)` - the main method that ties it all together.`
* `self.show_map` - after everything is done convert the map into a readable string
* `self.draw_room_on_map(self, room, max_distance)` - the main method that ties it all together.
Now that we know which methods we need, let's refine our initial `__init__(self)` to pass some
@ -209,7 +208,7 @@ class Map(object):
# we have to store the grid into a variable
self.grid = self.create_grid()
# we use the algebraic relationship
self.draw_room_on_map(caller.location,
self.draw_room_on_map(caller.location,
((min(max_width, max_length) -1 ) / 2)
```
@ -234,7 +233,7 @@ def draw_room_on_map(self, room, max_distance):
# we only map in the cardinal directions. Mapping up/down would be
# an interesting learning project for someone who wanted to try it.
continue
if self.has_drawn(exit.destination):
if self.has_drawn(exit.destination):
# we've been to the destination already, skip ahead.
continue
@ -245,7 +244,7 @@ def draw_room_on_map(self, room, max_distance):
The first thing the "worm" does is to draw your current location in `self.draw`. Lets define that...
```python
#in mygame/word/map.py, in the Map class
#in mygame/word/map.py, in the Map class
def draw(self, room):
# draw initial ch location on map first!
@ -272,7 +271,7 @@ def start_loc_on_grid(self):
x = self.median(self.max_width)
y = self.median(self.max_length)
# x and y are floats by default, can't index lists with float types
x, y = int(x), int(y)
x, y = int(x), int(y)
self.grid[x][y] = SYMBOLS['you']
self.curX, self.curY = x, y # updating worms current location
@ -295,12 +294,12 @@ position of the worm; we do this in `self.update_pos()` below.
```python
def update_pos(self, room, exit_name):
# this ensures the coordinates stays up to date
# this ensures the coordinates stays up to date
# to where the worm is currently at.
self.curX, self.curY = \
self.worm_has_mapped[room][0], self.worm_has_mapped[room][1]
# now we have to actually move the pointer
# now we have to actually move the pointer
# variables depending on which 'exit' it found
if exit_name == 'east':
self.curY += 1
@ -343,14 +342,14 @@ from evennia import DefaultRoom
from world.map import Map
class Room(DefaultRoom):
def return_appearance(self, looker):
# [...]
string = f"{Map(looker).show_map()}\n"
# Add all the normal stuff like room description,
# contents, exits etc.
# Add all the normal stuff like room description,
# contents, exits etc.
string += "\n" + super().return_appearance(looker)
return string
return string
```
Obviously this method of generating maps doesn't take into account of any doors or exits that are
@ -369,16 +368,16 @@ to actually call it. Remember that to see different symbols for a location you a
`sector_type` Attribute on the room to one of the keys in the `SYMBOLS` dictionary. So in this
example, to make a room be mapped as `[.]` you would set the room's `sector_type` to
`"SECT_INSIDE"`. Try it out with `@set here/sector_type = "SECT_INSIDE"`. If you wanted all new
rooms to have a given sector symbol, you could change the default in the `SYMBOLS´ dictionary below,
rooms to have a given sector symbol, you could change the default in the `SYMBOLS` dictionary below,
or you could add the Attribute in the Room's `at_object_creation` method.
```python
#mygame/world/map.py
# mygame/world/map.py
# These are keys set with the Attribute sector_type on the room.
# The keys None and "you" must always exist.
SYMBOLS = { None : ' . ', # for rooms without a sector_type attr
'you' : '[@]',
'you' : '[@]',
'SECT_INSIDE': '[.]' }
class Map(object):
@ -394,16 +393,16 @@ class Map(object):
if self.check_grid():
# we actually have to store the grid into a variable
self.grid = self.create_grid()
self.draw_room_on_map(caller.location,
self.draw_room_on_map(caller.location,
((min(max_width, max_length) -1 ) / 2))
def update_pos(self, room, exit_name):
# this ensures the pointer variables always
# this ensures the pointer variables always
# stays up to date to where the worm is currently at.
self.curX, self.curY = \
self.worm_has_mapped[room][0], self.worm_has_mapped[room][1]
# now we have to actually move the pointer
# now we have to actually move the pointer
# variables depending on which 'exit' it found
if exit_name == 'east':
self.curY += 1
@ -419,19 +418,19 @@ class Map(object):
if max_distance == 0:
return
for exit in room.exits:
if exit.name not in ("north", "east", "west", "south"):
# we only map in the cardinal directions. Mapping up/down would be
# an interesting learning project for someone who wanted to try it.
continue
if self.has_drawn(exit.destination):
if self.has_drawn(exit.destination):
# we've been to the destination already, skip ahead.
continue
self.update_pos(room, exit.name.lower())
self.draw_room_on_map(exit.destination, max_distance - 1)
def draw(self, room):
# draw initial caller location on map first!
if room == self.caller.location:
@ -441,30 +440,30 @@ class Map(object):
# map all other rooms
self.worm_has_mapped[room] = [self.curX, self.curY]
# this will use the sector_type Attribute or None if not set.
self.grid[self.curX][self.curY] = SYMBOLS[room.db.sector_type]
self.grid[self.curX][self.curY] = SYMBOLS[room.db.sector_type]
def median(self, num):
lst = sorted(range(0, num))
n = len(lst)
m = n -1
return (lst[n//2] + lst[m//2]) / 2.0
def start_loc_on_grid(self):
x = self.median(self.max_width)
y = self.median(self.max_length)
# x and y are floats by default, can't index lists with float types
x, y = int(x), int(y)
x, y = int(x), int(y)
self.grid[x][y] = SYMBOLS['you']
self.curX, self.curY = x, y # updating worms current location
def has_drawn(self, room):
return True if room in self.worm_has_mapped.keys() else False
def create_grid(self):
# This method simply creates an empty grid
# This method simply creates an empty grid
# with the specified variables from __init__(self):
board = []
for row in range(self.max_width):
@ -474,7 +473,7 @@ class Map(object):
return board
def check_grid(self):
# this method simply checks the grid to make sure
# this method simply checks the grid to make sure
# both max_l and max_w are odd numbers
return True if self.max_length % 2 != 0 or \
self.max_width % 2 != 0 else False
@ -492,4 +491,4 @@ class Map(object):
The Dynamic map could be expanded with further capabilities. For example, it could mark exits or
allow NE, SE etc directions as well. It could have colors for different terrain types. One could
also look into up/down directions and figure out how to display that in a good way.
also look into up/down directions and figure out how to display that in a good way.

2
docs/source/Howto/Starting/Part1/Building-Quickstart.md
View file

@ -207,7 +207,7 @@ to use for creating the object. There you go - one red button.
The RedButton is an example object intended to show off a few of Evennia's features. You will find
that the [Typeclass](../../../Components/Typeclasses.md) and [Commands](../../../Components/Commands.md) controlling it are
inside [evennia/contrib/tutorial_examples](../../../api/evennia.contrib.tutorial_examples.md)
inside [evennia/contrib/tutorials/red_button](evennia.contrib.tutorials.red_button)
If you wait for a while (make sure you dropped it!) the button will blink invitingly.

148
docs/source/Howto/Starting/Part2/Planning-Some-Useful-Contribs.md
View file

@ -1,11 +1,11 @@
# Planning the use of some useful contribs
Evennia is deliberately bare-bones out of the box. The idea is that you should be as unrestricted as possible
in designing your game. This is why you can easily replace the few defaults we have and why we don't try to
prescribe any major game systems on you.
in designing your game. This is why you can easily replace the few defaults we have and why we don't try to
prescribe any major game systems on you.
That said, Evennia _does_ offer some more game-opinionated _optional_ stuff. These are referred to as _Contribs_
and is an ever-growing treasure trove of code snippets, concepts and even full systems you can pick and choose
and is an ever-growing treasure trove of code snippets, concepts and even full systems you can pick and choose
from to use, tweak or take inspiration from when you make your game.
The [Contrib overview](../../../Contribs/Contrib-Overview.md) page gives the full list of the current roster of contributions. On
@ -17,70 +17,62 @@ This is the things we know we need:
- A barter system
- Character generation
- Some concept of wearing armor
- Some concept of wearing armor
- The ability to roll dice
- Rooms with awareness of day, night and season
- Roleplaying with short-descs, poses and emotes
- Quests
- Quests
- Combat (with players and against monsters)
## Barter contrib
## Barter contrib
[source](../../../api/evennia.contrib.barter.md)
[source](../../../api/evennia.contrib.game_systems.barter.md)
Reviewing this contrib suggests that it allows for safe trading between two parties. The basic principle
is that the parties puts up the stuff they want to sell and the system will guarantee that these systems are
exactly what is being offered. Both sides can modify their offers (bartering) until both mark themselves happy
with the deal. Only then the deal is sealed and the objects are exchanged automatically. Interestingly, this
works just fine for money too - just put coin objects on one side of the transaction.
with the deal. Only then the deal is sealed and the objects are exchanged automatically. Interestingly, this
works just fine for money too - just put coin objects on one side of the transaction.
Sue > trade Tom: Hi, I have a necklace to sell; wanna trade for a healing potion?
Tom > trade Sue: Hm, I could use a necklace ...
<both accepted trade. Start trade>
Sue > offer necklace: This necklace is really worth it.
<both accepted trade. Start trade>
Sue > offer necklace: This necklace is really worth it.
Tom > evaluate necklace:
<Tom sees necklace stats>
Tom > offer ration: I don't have a healing potion, but I'll trade you an iron ration!
Sue > Hey, this is a nice necklace, I need more than a ration for it...
Tom > offer ration, 10gold: Ok, a ration and 10 gold as well.
Sue > accept: Ok, that sounds fair!
Sue > accept: Ok, that sounds fair!
Tom > accept: Good! Nice doing business with you.
<goods change hands automatically. Trade ends>
<goods change hands automatically. Trade ends>
Arguably, in a small game you are just fine to just talk to people and use `give` to do the exchange. The
Arguably, in a small game you are just fine to just talk to people and use `give` to do the exchange. The
barter system guarantees trading safety if you don't trust your counterpart to try to give you the wrong thing or
to run away with your money.
to run away with your money.
We will use the barter contrib as an optional feature for player-player bartering. More importantly we can
add it for NPC shopkeepers and expand it with a little AI, which allows them to potentially trade in other
We will use the barter contrib as an optional feature for player-player bartering. More importantly we can
add it for NPC shopkeepers and expand it with a little AI, which allows them to potentially trade in other
things than boring gold coin.
## Character generation contrib
[source](../../../api/evennia.contrib.chargen.md)
This contrib is an example module for creating characters. Since we will be using `MULTISESSION_MODE=3` we will
get a selection screen like this automatically. We also plan to use a proper menu to build our character, so
we will _not_ be using this contrib.
## Clothing contrib
[source](../../../api/evennia.contrib.clothing.md)
[source](../../../api/evennia.contrib.game_systems.clothing.md)
This contrib provides a full system primarily aimed at wearing clothes, but it could also work for armor. You wear
an object in a particular location and this will then be reflected in your character's description. You can
also add roleplaying flavor:
an object in a particular location and this will then be reflected in your character's description. You can
also add roleplaying flavor:
> wear helmet slightly askew on her head
look self
Username is wearing a helmet slightly askew on her head.
By default there are no 'body locations' in this contrib, we will need to expand on it a little to make it useful
for things like armor. It's a good contrib to build from though, so that's what we'll do.
for things like armor. It's a good contrib to build from though, so that's what we'll do.
## Dice contrib
## Dice contrib
[source](../../../api/evennia.contrib.dice.md)
[source](../../../api/evennia.contrib.rpg.dice.md)
The dice contrib presents a general dice roller to use in game.
@ -92,51 +84,51 @@ The dice contrib presents a general dice roller to use in game.
Roll(s): 7. Total result is 7. This is a failure (by 5)
> roll/hidden 1d20 > 12
Roll(s): 18. Total result is 17. This is a success (by 6). (not echoed)
The contrib also has a python function for producing these results in-code. However, while
we will emulate rolls for our rule system, we'll do this as simply as possible with Python's `random`
module.
So while this contrib is fun to have around for GMs or for players who want to get a random result
The contrib also has a python function for producing these results in-code. However, while
we will emulate rolls for our rule system, we'll do this as simply as possible with Python's `random`
module.
So while this contrib is fun to have around for GMs or for players who want to get a random result
or play a game, we will not need it for the core of our game.
## Extended room contrib
## Extended room contrib
[source](../../../api/evennia.contrib.extended_room.md)
[source](../../../api/evennia.contrib.grid.extended_room.md)
This is a custom Room typeclass that changes its description based on time of day and season.
For example, at night, in wintertime you could show the room as being dark and frost-covered while in daylight
at summer it could describe a flowering meadow. The description can also contain special markers, so
`<morning> ... </morning>` would include text only visible at morning.
at summer it could describe a flowering meadow. The description can also contain special markers, so
`<morning> ... </morning>` would include text only visible at morning.
The extended room also supports _details_, which are things to "look at" in the room without there having
to be a separate database object created for it. For example, a player in a church may do `look window` and
get a description of the windows without there needing to be an actual `window` object in the room.
Adding all those extra descriptions can be a lot of work, so they are optional; if not given the room works
like a normal room.
like a normal room.
The contrib is simple to add and provides a lot of optional flexibility, so we'll add it to our
game, why not!
The contrib is simple to add and provides a lot of optional flexibility, so we'll add it to our
game, why not!
## RP-System contrib
[source](../../../api/evennia.contrib.rpsystem.md)
[source](../../../api/evennia.contrib.rpg.rpsystem.md)
This contrib adds a full roleplaying subsystem to your game. It gives every character a "short-description"
(sdesc) that is what people will see when first meeting them. Let's say Tom has an sdesc "A tall man" and
Sue has the sdesc "A muscular, blonde woman"
Tom > look
Tom > look
Tom: <room desc> ... You see: A muscular, blonde woman
Tom > emote /me smiles to /muscular.
Tom: Tom smiles to A muscular, blonde woman.
Sue: A tall man smiles to Sue.
Sue: A tall man smiles to Sue.
Tom > emote Leaning forward, /me says, "Well hello, what's yer name?"
Tom: Leaning forward, Tom says, "Well hello..."
Sue: Leaning forward, A tall man says, "Well hello, what's yer name?"
Sue > emote /me grins. "I'm Angelica", she says.
Sue > emote /me grins. "I'm Angelica", she says.
Sue: Sue grins. "I'm Angelica", she says.
Tom: A muscular, blonde woman grins. "I'm Angelica", she says.
Tom > recog muscular Angelica
@ -145,42 +137,42 @@ Sue has the sdesc "A muscular, blonde woman"
Sue: A tall man nods to Sue: "I have a message for you ..."
Above, Sue introduces herself as "Angelica" and Tom uses this info to `recoc` her as "Angelica" hereafter. He
could have `recoc`-ed her with whatever name he liked - it's only for his own benefit. There is no separate
`say`, the spoken words are embedded in the emotes in quotes `"..."`.
could have `recoc`-ed her with whatever name he liked - it's only for his own benefit. There is no separate
`say`, the spoken words are embedded in the emotes in quotes `"..."`.
The RPSystem module also includes options for `poses`, which help to establish your position in the room
when others look at you.
when others look at you.
Tom > pose stands by the bar, looking bored.
Sue > look
Sue: <room desc> ... A tall man stands by the bar, looking bored.
You can also wear a mask to hide your identity; your sdesc will then be changed to the sdesc of the mask,
like `a person with a mask`.
The RPSystem gives a lot of roleplaying power out of the box, so we will add it. There is also a separate
[rplanguage](../../../api/evennia.contrib.rplanguage.md) module that integrates with the spoken words in your emotes and garbles them if you don't understand
You can also wear a mask to hide your identity; your sdesc will then be changed to the sdesc of the mask,
like `a person with a mask`.
The RPSystem gives a lot of roleplaying power out of the box, so we will add it. There is also a separate
[rplanguage](../../../api/evennia.contrib.rpg.rpsystem.md) module that integrates with the spoken words in your emotes and garbles them if you don't understand
the language spoken. In order to restrict the scope we will not include languages for the tutorial game.
## Talking NPC contrib
[source](../../../api/evennia.contrib.talking_npc.md)
[source](../../../api/evennia.contrib.tutorials.talking_npc.md)
This exemplifies an NPC with a menu-driven dialogue tree. We will not use this contrib explicitly, but it's
good as inspiration for how we'll do quest-givers later.
This exemplifies an NPC with a menu-driven dialogue tree. We will not use this contrib explicitly, but it's
good as inspiration for how we'll do quest-givers later.
## Traits contrib
[source](../../../api/evennia.contrib.traits.md)
[source](../../../api/evennia.contrib.rpg.traits.md)
An issue with dealing with roleplaying attributes like strength, dexterity, or skills like hunting, sword etc
is how to keep track of the values in the moment. Your strength may temporarily be buffed by a strength-potion.
is how to keep track of the values in the moment. Your strength may temporarily be buffed by a strength-potion.
Your swordmanship may be worse because you are encumbered. And when you drink your health potion you must make
sure that those +20 health does not bring your health higher than its maximum. All this adds complexity.
The _Traits_ contrib consists of several types of objects to help track and manage values like this. When
installed, the traits are accessed on a new handler `.traits`, for example
The _Traits_ contrib consists of several types of objects to help track and manage values like this. When
installed, the traits are accessed on a new handler `.traits`, for example
> py self.traits.hp.value
100
@ -190,9 +182,9 @@ installed, the traits are accessed on a new handler `.traits`, for example
> py self.traits.hp.reset() # drink a potion
> py self.traits.hp.value
100
A Trait is persistent (it uses an Attribute under the hood) and tracks changes, min/max and other things
automatically. They can also be added together in various mathematical operations.
A Trait is persistent (it uses an Attribute under the hood) and tracks changes, min/max and other things
automatically. They can also be added together in various mathematical operations.
The contrib introduces three main Trait-classes
@ -200,14 +192,14 @@ The contrib introduces three main Trait-classes
- _Counters_ is a value that never moves outside a given range, even with modifiers. For example a skill
that can at most get a maximum amount of buff. Counters can also easily be _timed_ so that they decrease
or increase with a certain rate per second. This could be good for a time-limited curse for example.
- _Gauge_ is like a fuel-gauge; it starts at a max value and then empties gradually. This is perfect for
- _Gauge_ is like a fuel-gauge; it starts at a max value and then empties gradually. This is perfect for
things like health, stamina and the like. Gauges can also change with a rate, which works well for the
effects of slow poisons and healing both.
```
> py self.traits.hp.value
100
> py self.traits.hp.rate = -1 # poisoned!
> py self.traits.hp.rate = -1 # poisoned!
> py self.traits.hp.ratetarget = 50 # stop at 50 hp
# Wait 30s
> py self.traits.hp.value
@ -217,36 +209,36 @@ effects of slow poisons and healing both.
50 # stopped at 50
> py self.traits.hp.rate = 0 # no more poison
> py self.traits.hp.rate = 5 # healing magic!
# wait 5s
# wait 5s
> pyself.traits.hp.value
75
```
Traits will be very practical to use for our character sheets.
Traits will be very practical to use for our character sheets.
## Turnbattle contrib
[source](../../../api/evennia.contrib.turnbattle.md)
[source](../../../api/evennia.contrib.game_systems.turnbattle.md)
This contrib consists of several implementations of a turn-based combat system, divivided into complexity:
- basic - initiative and turn order, attacks against defense values, damage.
- equip - considers weapons and armor, wielding and weapon accuracy.
- items - adds usable items with conditions and status effects
- magic - adds spellcasting system using MP.
- magic - adds spellcasting system using MP.
- range - adds abstract positioning and 1D movement to differentiate between melee and ranged attacks.
The turnbattle system is comprehensive, but it's meant as a base to start from rather than offer
The turnbattle system is comprehensive, but it's meant as a base to start from rather than offer
a complete system. It's also not built with _Traits_ in mind, so we will need to adjust it for that.
## Conclusions
With some contribs selected, we have pieces to build from and don't have to write everything from scratch.
We will need Quests and will likely need to do a bunch of work on Combat to adapt the combat contrib
We will need Quests and will likely need to do a bunch of work on Combat to adapt the combat contrib
to our needs.
We will now move into actually starting to implement our tutorial game
in the next part of this tutorial series. When doing this for yourself, remember to refer
back to your planning and adjust it as you learn what works and what does not.
We will now move into actually starting to implement our tutorial game
in the next part of this tutorial series. When doing this for yourself, remember to refer
back to your planning and adjust it as you learn what works and what does not.

6
docs/source/Contribs/Static-In-Game-Map.md → docs/source/Howto/Static-In-Game-Map.md
View file

@ -84,7 +84,7 @@ In this section we will try to create an actual "map" object that an account can
at.
Evennia offers a range of [default commands](../Components/Default-Commands.md) for
[creating objects and rooms in-game](../Howto/Starting/Part1/Building-Quickstart.md). While readily accessible, these commands are made to do very
[creating objects and rooms in-game](Starting/Part1/Building-Quickstart.md). While readily accessible, these commands are made to do very
specific, restricted things and will thus not offer as much flexibility to experiment (for an
advanced exception see [the FuncParser](../Components/FuncParser.md)). Additionally, entering long
descriptions and properties over and over in the game client can become tedious; especially when
@ -412,5 +412,5 @@ easily new game defining features can be added to Evennia.
You can easily build from this tutorial by expanding the map and creating more rooms to explore. Why
not add more features to your game by trying other tutorials: [Add weather to your world](Weather-
Tutorial), [fill your world with NPC's](../Howto/Tutorial-Aggressive-NPCs.md) or
[implement a combat system](../Howto/Starting/Part3/Turn-based-Combat-System.md).
Tutorial), [fill your world with NPC's](./Tutorial-Aggressive-NPCs.md) or
[implement a combat system](Starting/Part3/Turn-based-Combat-System.md).

10
docs/source/toc.md
View file

@ -75,7 +75,6 @@ Concepts/TextTags
Concepts/Using-MUX-as-a-Standard
Concepts/Web-Features
Concepts/Zones
Contribs/A-voice-operated-elevator-using-events
Contribs/Arxcode-installing-help
Contribs/Building-menus
Contribs/Contrib-AWSStorage
@ -97,6 +96,8 @@ Contribs/Contrib-Fieldfill
Contribs/Contrib-Gendersub
Contribs/Contrib-Health-Bar
Contribs/Contrib-Ingame-Python
Contribs/Contrib-Ingame-Python-Tutorial-Dialogue
Contribs/Contrib-Ingame-Python-Tutorial-Elevator
Contribs/Contrib-Mail
Contribs/Contrib-Mapbuilder
Contribs/Contrib-Menu-Login
@ -118,11 +119,6 @@ Contribs/Contrib-Tutorial-World
Contribs/Contrib-Unixcommand
Contribs/Contrib-Wilderness
Contribs/Contrib-XYZGrid
Contribs/Crafting
Contribs/Dialogues-in-events
Contribs/Dynamic-In-Game-Map
Contribs/Static-In-Game-Map
Contribs/XYZGrid
Contributing
Contributing-Docs
Evennia-API
@ -137,6 +133,7 @@ Howto/Command-Duration
Howto/Command-Prompt
Howto/Coordinates
Howto/Default-Exit-Errors
Howto/Dynamic-In-Game-Map
Howto/Evennia-for-Diku-Users
Howto/Evennia-for-MUSH-Users
Howto/Evennia-for-roleplaying-sessions
@ -174,6 +171,7 @@ Howto/Starting/Part4/Starting-Part4
Howto/Starting/Part5/Add-a-simple-new-web-page
Howto/Starting/Part5/Starting-Part5
Howto/Starting/Part5/Web-Tutorial
Howto/Static-In-Game-Map
Howto/Tutorial-Aggressive-NPCs
Howto/Tutorial-NPCs-listening
Howto/Tutorial-Tweeting-Game-Stats

8
evennia/contrib/base_systems/awsstorage/README.md
View file

@ -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,

14
evennia/contrib/base_systems/building_menu/README.md
View file

@ -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

5
evennia/contrib/base_systems/color_markups/README.md
View file

@ -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

9
evennia/contrib/base_systems/custom_gametime/README.md
View file

@ -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

7
evennia/contrib/base_systems/email_login/README.md
View file

@ -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

37
evennia/contrib/base_systems/ingame_python/README.md
View file

@ -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](Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md), where
NPCs react to things said.
- [A voice operated elevator](Contribs/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 |
+~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

8
evennia/contrib/base_systems/menu_login/README.md
View file

@ -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

32
evennia/contrib/base_systems/mux_comms_cmds/README.md
View file

@ -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

10
evennia/contrib/base_systems/unixcommand/README.md
View file

@ -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

12
evennia/contrib/full_systems/evscaperoom/README.md
View file

@ -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!

18
evennia/contrib/game_systems/barter/README.md
View file

@ -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

11
evennia/contrib/game_systems/clothing/README.md
View file

@ -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

15
evennia/contrib/game_systems/cooldowns/README.md
View file

@ -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

282
evennia/contrib/game_systems/crafting/README.md
View file

@ -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 <recipe> [from <ingredient>,...] [using <tool>, ...]
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 <recipe> [from <ingredient>,...] [using <tool>, ...]
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,34 +102,199 @@ 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.

4
evennia/contrib/game_systems/crafting/__init__.py
View file

@ -3,5 +3,7 @@ Crafting - Griatch 2020
"""
from .crafting import craft # noqa
from .crafting import CraftingRecipe # noqa
from .crafting import CraftingValidationError # noqa
from .crafting import CraftingRecipeBase # noqa
from .crafting import CraftingError, CraftingValidationError # noqa

2
evennia/contrib/game_systems/gendersub/README.md
View file

@ -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

12
evennia/contrib/game_systems/mail/README.md
View file

@ -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

13
evennia/contrib/game_systems/multidescer/README.md
View file

@ -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

15
evennia/contrib/game_systems/puzzles/README.md
View file

@ -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')

2
evennia/contrib/game_systems/turnbattle/README.md
View file

@ -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

9
evennia/contrib/grid/extended_room/README.md
View file

@ -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:

4
evennia/contrib/grid/mapbuilder/README.md
View file

@ -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:

12
evennia/contrib/grid/simpledoor/README.md
View file

@ -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:

8
evennia/contrib/grid/slow_exit/README.md
View file

@ -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:

6
evennia/contrib/grid/wilderness/README.md
View file

@ -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

1336
evennia/contrib/grid/xyzgrid/README.md
View file

File diff suppressed because it is too large Load diff

8
evennia/contrib/rpg/dice/README.md
View file

@ -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:

8
evennia/contrib/rpg/health_bar/README.md
View file

@ -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

14
evennia/contrib/rpg/rpsystem/README.md
View file

@ -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

6
evennia/contrib/rpg/traits/README.md
View file

@ -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

8
evennia/contrib/tutorials/batchprocessor/README.md
View file

@ -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:

4
evennia/contrib/tutorials/bodyfunctions/README.md
View file

@ -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)

4
evennia/contrib/tutorials/mirror/README.md
View file

@ -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

6
evennia/contrib/tutorials/red_button/README.md
View file

@ -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

6
evennia/contrib/tutorials/talking_npc/README.md
View file

@ -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

9
evennia/contrib/tutorials/tutorial_world/README.md
View file

@ -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.

16
evennia/contrib/utils/auditing/README.md
View file

@ -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.

18
evennia/contrib/utils/fieldfill/README.md
View file

@ -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)

12
evennia/contrib/utils/random_string_generator/README.md
View file

@ -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

16
evennia/contrib/utils/tree_select/README.md
View file

@ -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

2
evennia/utils/gametime.py
View file

@ -242,7 +242,7 @@ def schedule(
to store in Attributes on the generated scheduling Script.
Returns:
script (Script): The created Script handling the sceduling.
Script: The created Script handling the scheduling.
Examples:
::