Annikka/evennia
1
0
Fork 0
Code Issues Pull requests 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 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. 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 > 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. 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 = """
```{{toctree}} ```{{toctree}}
:depth: 2
{listing} {listing}
```
""" """
@ -101,11 +100,11 @@ _{category_desc}_
BLURB = """ BLURB = """
### Contrib: `{name}` ### Contrib: `{name}`
{credits} _{credits}_
{blurb} {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> will be overwritten.</small>
""" """
@ -141,6 +140,8 @@ def readmes2docs(directory=_SOURCE_DIR):
# paths are e.g. evennia/contrib/utils/auditing/README.md # paths are e.g. evennia/contrib/utils/auditing/README.md
_, category, name, _ = file_path.rsplit(sep, 3) _, category, name, _ = file_path.rsplit(sep, 3)
pypath = f"evennia.contrib.{category}.{name}"
filename = "Contrib-" + "-".join( filename = "Contrib-" + "-".join(
_FILENAME_MAP.get( _FILENAME_MAP.get(
part, part.capitalize() if part[0].islower() else part) part, part.capitalize() if part[0].islower() else part)
@ -162,7 +163,7 @@ def readmes2docs(directory=_SOURCE_DIR):
with open(outfile, 'w') as fil: with open(outfile, 'w') as fil:
fil.write(data) fil.write(data)
categories[category].append((name, credits, blurb, filename)) categories[category].append((name, credits, blurb, filename, pypath))
ncount += 1 ncount += 1
# build the index with blurbs # build the index with blurbs
@ -179,6 +180,7 @@ def readmes2docs(directory=_SOURCE_DIR):
credits=tup[1], credits=tup[1],
blurb=tup[2], blurb=tup[2],
filename=tup[3], filename=tup[3],
code_location=tup[4]
) )
) )
filenames.append(f"Contribs{sep}{tup[3]}") filenames.append(f"Contribs{sep}{tup[3]}")
@ -190,15 +192,13 @@ def readmes2docs(directory=_SOURCE_DIR):
) )
) )
lines.append(TOCTREE.format( lines.append(TOCTREE.format(
listing="\n".join(filenames)) listing="\n ".join(filenames))
) )
lines.append(INDEX_FOOTER) lines.append(INDEX_FOOTER)
text = "\n".join(lines) text = "\n".join(lines)
with open(_OUT_INDEX_FILE, 'w') as fil: with open(_OUT_INDEX_FILE, 'w') as fil:
fil.write(text) 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 different messages depending on viewpoint and receiver
Sending messages to everyong in a location is handled by the Sending messages to everyong in a location is handled by the
[msg_contents](evennia.objects.objects.DefaultObject.msg_contents) method on [msg_contents](evennia.objects.objects.DefaultObject.msg_contents) method on
all [Objects](../Components/Objects.md). It's most commonly called on rooms. all [Objects](../Components/Objects.md). It's most commonly called on rooms.
```python ```python
room.msg_contents("Anna walks into the room.") 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.", room.msg_contents("{anna} walks into the room.",
from_obj=caller, from_obj=caller,
mapping={'anna': anna_object}) mapping={'anna': anna_object})
``` ```
Use `exclude=object_or_list_of_object` to skip sending the message one or more targets. 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 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 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. 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, 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 | | Actor stance | You pick up the stone | Anna picks up the stone |
|Director stance | Anna picks 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 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 in Actor stance while Director stance is used for complex emoting and roleplaying. One should
usually try to be consistent however. 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 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 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. 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. 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 Everyone will see this string, both Tom and others. Here's how to send it to everyone in
the room. the room.
```python ```python
text = "Tom picks up the gun, whistling to himself." text = "Tom picks up the gun, whistling to himself."
room.msg_contents(text) room.msg_contents(text)
``` ```
One may want to expand on it by making the name `Tom` be seen differently by different people, 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 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. 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. an action, you should get a different message than those _observing_ you doing that action.
Tom picks up the gun, whistling to himself. 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. 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 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 strings from every view point, but there's a better way.
The `msg_contents` method helps by parsing the ingoing string with a 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 [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 basically provides you with a mini-language for building _one_ string that will change
appropriately depending on who sees it. appropriately depending on who sees it.
```python ```python
text = "$You() $conj(pick) up the gun, whistling to $pron(yourself)." text = "$You() $conj(pick) up the gun, whistling to $pron(yourself)."
room.msg_contents(text, from_obj=caller, mapping={"gun": gun_object}) 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 - `$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. 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` - `$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. 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 - `$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 _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. set of options to help the system map your pronoun from 1st/2nd person to 3rd person and vice versa.
See next section. See next section.
@ -99,11 +99,11 @@ These are the inline-functions available:
### More on $pron() ### More on $pron()
The `$pron()` inline func maps between 1st/2nd person (I/you) to 3rd person (he/she etc). In short, 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 | | | 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 | | **1st person plural** | we | us | our | ours | ourselves |
| **2nd person** | you | you | your | yours | yourself | | **2nd person** | you | you | your | yours | yourself |
| **2nd person plural** | you | you | your | yours | yourselves | | **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 neutral** | it | it | its | theirs* | itself |
| **3rd person plural** | they | them | their | theirs | themselves | | **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. > 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 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 form is always `themselves`. But because English grammar is the way it is, not all mappings
are 1:1. For example, if you write 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 `$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. 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. - `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`) - `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 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 (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`, 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. 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. 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` - `male`, or `m`
- `female'` or `f` - `female'` or `f`
- `neutral`, or `n` - `neutral`, or `n`
- `plural`, or `p` (yes plural is considered a 'gender' for this purpose). - `plural`, or `p` (yes plural is considered a 'gender' for this purpose).
If not set as an option the system will 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 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 with no arguments and is expected to return a string 'male/female/neutral/plural'. If none
is found, a neutral gender is assumed. is found, a neutral gender is assumed.
- `viewpoint`- set in `$pron` option as - `viewpoint`- set in `$pron` option as
- `1st person` (aliases `1st` or `1`) - `1st person` (aliases `1st` or `1`)
- `2nd person` (aliases `2nd` or `2`) - `2nd person` (aliases `2nd` or `2`)
This is only needed if you want to have 1st person perspective - if This is only needed if you want to have 1st person perspective - if
not, 2nd person is assumed wherever the viewpoint is unclear. not, 2nd person is assumed wherever the viewpoint is unclear.
`$pron()` examples: `$pron()` examples:
| Input | you see | others see | note | | Input | you see | others see | note |
| --- | --- | ---| --- | | --- | --- | ---| --- |
| `$pron(I, male)` | I | he | | | `$pron(I, male)` | I | he | |
| `$pron(I, f)` | I | she | | | `$pron(I, f)` | I | she | |
| `$pron(my)` | my | its | figures out it's an possessive adjective, assumes neutral | | `$pron(my)` | my | its | figures out it's an possessive adjective, assumes neutral |
| `$pron(you)` | you | it | assumes neutral subject pronoun | | `$pron(you)` | you | it | assumes neutral subject pronoun |
| `$pron(you, f)` | you | she | female specified, assumes 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,op p)` | you | them | |
| `$pron(you, f op)` | you | her | specified female and objective pronoun| | `$pron(you, f op)` | you | her | specified female and objective pronoun|
| `$pron(yourself)` | yourself | itself | | | `$pron(yourself)` | yourself | itself | |
| `$pron(its)` | your | its | | | `$pron(its)` | your | its | |
| `$Pron(its)` | Your | Its | Using $Pron always capitalizes | | `$Pron(its)` | Your | Its | Using $Pron always capitalizes |
| `$pron(her)` | you | her | 3rd person -> 2nd person | | `$pron(her)` | you | her | 3rd person -> 2nd person |
| `$pron(her, 1)` | I | her | 3rd person -> 1st 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 # 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): your strings (for both director- and actor stance):
- `$Obj(name)/$obj(name)` references another entity, which must be supplied - `$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 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 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 in the first example at the top of this page, but using `$Obj/$obj` allows you to easily
control capitalization. control capitalization.
This is used like so: This is used like so:
```python ```python
# director stance # director stance
text = "Tom picks up the $obj(gun), whistling to himself" 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)" text = "$You() $conj(pick) up the $obj(gun), whistling to $pron(yourself)"
room.msg_contents(text, from_obj=caller, mapping={"gun": gun_object}) 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 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 with a high gun smith skill may instead see him picking up `A rare-make Smith & Wesson model 686
in poor condition" ...` 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. 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 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 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 language, like `/me` `/gun` and `/tall man` to refer to players and objects in the location. It can be
worth checking out for inspiration. 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 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 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 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. 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 # AWSstorage system
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, This plugin migrates the Web-based portion of Evennia, namely images,
javascript, and other items located inside staticfiles into Amazon AWS (S3) for javascript, and other items located inside staticfiles into Amazon AWS (S3)
hosting. cloud hosting. Great for those serving media with the game.
Files hosted on S3 are "in the cloud," and while your personal 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, 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 # 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 Utility that taps and intercepts all data sent to/from clients and the
server and passes it to a callback of your choosing. 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 Note that this should be used with care since it can obviously be abused. All
but obviously can be abused. All data is recorded in cleartext. Please data is recorded in cleartext. Please be ethical, and if you are unwilling to
be ethical, and if you are unwilling to properly deal with the implications of properly deal with the implications of recording user passwords or private
recording user passwords or private communications, please do not enable communications, please do not enable this module.
this module.
Some checks have been implemented to protect the privacy of users. 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 # Barter system
Evennia contribution - Griatch 2012 Contribution by Griatch, 2012
This implements a full barter system - a way for players to safely This implements a full barter system - a way for players to safely
trade items between each other using code rather than simple free-form trade items between each other in code rather than simple `give/get`
talking. The advantage of this is increased buy/sell safety but it commands. This increases both safety (at no time will one player have
also streamlines the process and makes it faster when doing many both goods and payment in-hand) and speed, since agreed goods will
transactions (since goods are automatically exchanged once both be moved automatically). By just replacing one side with coin objects,
agree). (or a mix of coins and goods), this also works fine for regular money
transactions.
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).
## Installation ## Installation

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

@ -1,10 +1,10 @@
# Batch processor examples # Batch processor examples
Contibution - Griatch 2012 Contibution by Griatch, 2012
The batch processor is used for generating in-game content from one or more Simple examples for the batch-processor. The batch processor is used for generating
static files. Files can be stored with version control and then 'applied' in-game content from one or more static files. Files can be stored with version
to the game to create content. control and then 'applied' to the game to create content.
There are two batch processor types: There are two batch processor types:

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

@ -1,9 +1,9 @@
# Script example # Script example
Griatch - 2012 Contribution by Griatch, 2012
Example script for testing. This adds a simple timer that has your 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) To test, use (in game)

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

@ -1,15 +1,13 @@
# Building menu # 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 Building menus are in-game menus, not unlike `EvMenu` though using a
different approach. Building menus have been specifically designed to edit different approach. Building menus have been specifically designed to edit
information as a builder. Creating a building menu in a command allows 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 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 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. that will edit any default object, offering to change its key and description.
## Install ## Install

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

@ -1,9 +1,9 @@
# Clothing # Clothing
Evennia contribution - Tim Ashley Jenkins 2017 Contribution by Tim Ashley Jenkins, 2017
Provides a typeclass and commands for wearable clothing, Provides a typeclass and commands for wearable clothing. These
which is appended to a character's description when worn. look of these clothes are appended to the character's description when worn.
Clothing items, when worn, are added to the character's description Clothing items, when worn, are added to the character's description
in a list. For example, if wearing the following clothing items: 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 one nice hat
a very pretty dress 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 ## Installation
To install, import this module and have your default character 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 # Color markups
Contribution, Griatch 2017 Contrib by Griatch, 2017
Additional color markup styles for Evennia (extending or replacing the default 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 ## 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 Cooldowns are used modelling rate-limited actions, like how often a
typeclassed Object or Account. A cooldown is a lightweight persistent character can perform a given action; until a certain time has passed their
asynchronous timer that you can query to see if it is ready. 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
Cooldowns are good for modelling rate-limited actions, like how often a asynchronous timer that you can query to see if a certain time has yet passed.
character can perform a given command.
Cooldowns are completely asynchronous and must be queried to know their 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 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 # 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 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 The included `craft` command works like this:
'flour', 'salt', 'yeast' and 'water' to create 'bread' using the 'bread recipe'.
A recipe does not have to use tools, like 'snow' + 'snowball-recipe' becomes craft <recipe> [from <ingredient>,...] [using <tool>, ...]
'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.
The system is generic enough to be used also for adventure-like puzzles, like ## Examples
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' ... 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 ## Intallation and Usage
@ -29,18 +50,30 @@ available to you:
craft <recipe> [from <ingredient>,...] [using <tool>, ...] 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'] CRAFT_RECIPE_MODULES = ['world.recipes']
All top-level classes in these modules (whose name does not start with `_`) All top-level classes in these modules (whose name does not start with `_`) will
will be parsed by Evennia as recipes to make available to the crafting system. be parsed by Evennia as recipes to make available to the crafting system. Using
Using the above example, create `mygame/world/recipes.py` and add your recipies the above example, create `mygame/world/recipes.py` and add your recipies in
in there: there:
A quick example (read on for more details):
```python ```python
@ -69,37 +102,202 @@ class RecipeBread(CraftingRecipe):
def pre_craft(self, **kwargs): def pre_craft(self, **kwargs):
# validates inputs etc. Raise `CraftingValidationError` if fails # validates inputs etc. Raise `CraftingValidationError` if fails
def craft(self, **kwargs): def do_craft(self, **kwargs):
# performs the craft - but it can still fail (check skills etc here) # 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): def post_craft(self, result, **kwargs):
# any post-crafting effects. Always called, even if crafting failed (be # any post-crafting effects. Always called, even if do_craft failed (the
# result would be None then) # result would be None then)
``` ```
## Technical ## Adding new recipes
The Recipe is a class that specifies the consumables, tools and output along A *recipe* is a class inheriting from
with various methods (that you can override) to do the the validation of inputs `evennia.contrib.crafting.crafting.CraftingRecipe`. This class implements the
and perform the crafting itself. 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" For the `craft` command to find your custom recipes, you need to tell Evennia
and "crafting_tool" tag-categories respectively). Providing a set of objects where they are. Add a new line to your `mygame/server/conf/settings.py` file,
matching these tags are required for the crafting to be done. The use of tags with a list to any new modules with recipe classes.
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!
The output is given by a set of prototype-dicts. If the input is correct and ```python
other checks are passed (such as crafting skill, for example), these prototypes CRAFT_RECIPE_MODULES = ["world.myrecipes"]
will be used to generate the new object(s) being crafted. ```
(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 # 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 This reimplements the `evennia.utils.gametime` module but with a _custom_
calendar for your game world. It allows for scheduling events to happen at given calendar (unusual number of days per week/month/year etc) for your game world.
in-game times, taking this custom calendar into account. Like the original, it allows for scheduling events to happen at given
in-game times, but now taking this custom calendar into account.
## Installation ## Installation

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

@ -1,8 +1,12 @@
# Dice # 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: # Installation:

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

@ -1,9 +1,10 @@
# Email-based login system # 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 This is a variant of the login system that asks for an email-address
instead of a username to login. 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 This used to be the default Evennia login before replacing it with a
more standard username + password system (having to supply an email more standard username + password system (having to supply an email

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

@ -1,16 +1,18 @@
# EvscapeRoom # EvscapeRoom
Evennia contrib - Griatch 2019 Contribution by Griatch, 2019
This 'Evennia escaperoom game engine' was created for the MUD Coders Guild game A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
Jam, April 14-May 15 2019. The theme for the jam was "One Room". This contains the spawn and join puzzle rooms that track their state independently. Any number of players
utilities and base classes and an empty example room. 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 The original code for the contest is found at
https://github.com/Griatch/evscaperoom but the version on the public Evennia 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 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 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` at https://demo.evennia.com - just connect to the server and write `evscaperoom`
in the first room to start! in the first room to start!

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

@ -1,10 +1,11 @@
# Extended Room # 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 This extends the normal `Room` typeclass to allow its description to change
by an extended `Look` command and an extended `desc` command, also with time-of-day and/or season. It also adds 'details' for the player to look at
in this module. 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: ## Installation/testing:

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

@ -1,14 +1,16 @@
# Easy fillable form # 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 This module contains a function that generates an `EvMenu` for you - this
menu presents the player with a fillable form, with fields that can be filled menu presents the player with a form of fields that can be filled
out in any order. Each field's value can be verified, with the function out in any order (e.g. for character generation or building). Each field's value can
allowing easy checks for text and integer input, minimum and maximum values / be verified, with the function allowing easy checks for text and integer input,
character lengths, or can even be verified by a custom function. Once the form minimum and maximum values / character lengths, or can even be verified by a custom
is submitted, the form's data is submitted as a dictionary to any callable of function. Once the form is submitted, the form's data is submitted as a dictionary
your choice. to any callable of your choice.
## Usage
The function that initializes the fillable form menu is fairly simple, and 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) 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 # Gendersub
Contrib - Griatch 2015 Contribution by Griatch 2015
This is a simple gender-aware Character class for allowing users to This is a simple gender-aware Character class for allowing users to
insert custom markers in their text to indicate gender-aware 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 # Health Bar
Contrib - Tim Ashley Jenkins 2017 Contribution by Tim Ashley Jenkins, 2017
The function provided in this module lets you easily display visual The function provided in this module lets you easily display visual
bars or meters - "health bar" is merely the most obvious use for this, bars or meters as a colorful bar instead of just a number. A "health bar"
though these bars are highly customizable and can be used for any sort is merely the most obvious use for this, but the bar is highly customizable
of appropriate data besides player health. 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, Today's players may be more used to seeing statistics like health,
stamina, magic, and etc. displayed as bars rather than bare numerical 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 # Dialogues in events
This tutorial will walk you through the steps to create several dialogues with
- Next tutorial: [adding a voice-operated elevator with events](A-voice-operated-elevator-using- characters, using the Ingame-Python system. This tutorial assumes the in-game
events). Python system is installed in your game. If it isn't, you can follow the
installation steps given in [The main In-game Python
This tutorial will walk you through the steps to create several dialogues with characters, using the docs](./Contrib-Ingame-Python.md) and come back on this tutorial once the
[in-game Python system is installed. **You do not need to read** the entire documentation, it's
system](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md). a good reference, but not the easiest way to learn about it. Hence these
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
tutorials. tutorials.
The in-game Python system allows to run code on individual objects in some situations. You don't The in-game Python system allows to run code on individual objects in some
have to modify the source code to add these features, past the installation. The entire system situations. You don't have to modify the source code to add these features,
makes it easy to add specific features to some objects, but not all. This is why it can be very past the installation. The entire system makes it easy to add specific features
useful to create a dialogue system taking advantage of the in-game Python system. 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? > 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]-------------------------------- ----------Line Editor [Callback say of a merchant]--------------------------------
01| 01|
----------[l:01 w:000 c:0000]------------(:h for help)---------------------------- ----------[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. code.
- Next tutorial: [adding a voice-operated elevator with events](A-voice-operated-elevator-using- - 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 # 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- This tutorial will walk you through the steps to create a voice-operated elevator, using the [in-
game Python game Python system](./Contrib-Ingame-Python.md). This tutorial assumes the in-game Python
system](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md). system is installed per the instructions in that doc. **You do not need to read** the entire
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 documentation, it's a good reference, but not the easiest way to learn about it. Hence these
tutorials. 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 But what we want now is to be able to say "1", "2" or "3" and have the elevator move in that
direction. 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 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). 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 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. message: the text having been spoken by the character.
----------Line Editor [Callback say of Inside of an elevator]--------------------- ----------Line Editor [Callback say of Inside of an elevator]---------------------
01| 01|
----------[l:01 w:000 c:0000]------------(:h for help)---------------------------- ----------[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. 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. 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. chained event a more explicit name.
- In our original callback, we will call our chained events in, say, 15 seconds. - 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. - 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 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 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: 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. - The callback will have to check the elevator isn't already moving.
- It must change the exits when the elevator move. - 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. 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. 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 - **Q:** when you say I can call my chained events something else than "chain_1", "chain_2" and
such, what is the naming convention? such, what is the naming convention?
- **A:** chained events have names beginning by "chain_". This is useful for you and for the - **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 system. But after the underscore, you can give a more useful name, like `"chain_open_doors"` in our
case. case.
- **Q:** do I have to pause several seconds to call a chained event? - **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 - **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. task.
- **Q:** can I have chained events calling themselves? - **Q:** can I have chained events calling themselves?
- **A:** you can. There's no limitation. Just be careful, a callback that calls itself, - **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 is useful to have chained events calling themselves, to do the same repeated action every X seconds
for instance. for instance.
- **Q:** what if I need several elevators, do I need to copy/paste these callbacks each time? - **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 - **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 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. 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 # 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 This contrib adds the ability to script with Python in-game. It allows trusted
(or other trusted builders) to dynamically add features to individual objects. staff/builders to dynamically add features and triggers to individual objects
Using custom Python set in-game, every immortal or privileged users could have a without needing to do it in external Python modules. Using custom Python in-game,
specific room, exit, character, object or something else behave differently from specific rooms, exits, characters, objects etc can be made to behave differently from
its "cousins". For these familiar with the use of softcode in MU`*`, like SMAUG its "cousins". This is similar to how softcode works for MU or MudProgs for DIKU.
MudProgs, the ability to add arbitrary behavior to individual objects is a step Keep in mind, however, that allowing Python in-game comes with _severe_
toward freedom. Keep in mind, however, the warning below, and read it carefully security concerns (you must trust your builders deeply), so read the warnings in
before the rest of the documentation. this module carefully before continuing.
## A WARNING REGARDING SECURITY ## 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 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. 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 ## Basic structure and vocabulary
- At the basis of the in-game Python system are **events**. An **event** - 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. This is the quick summary. Scroll down for more detailed help on each step.
1. Launch the main script (important!): 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): 2. Set the permissions (optional):
- `EVENTS_WITH_VALIDATION`: a group that can edit callbacks, but will need approval (default to - `EVENTS_WITH_VALIDATION`: a group that can edit callbacks, but will need approval (default to
`None`). `None`).
@ -176,7 +189,7 @@ the `EVENTS_WITH_VALIDATION` setting will be able to call the command (with diff
### Adding the `call` command ### Adding the `call` command
You also have to add the `@call` command to your Character CmdSet. This command allows your users 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: this:
```python ```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: from going through the "north" exit of this room:
``` ```
@call north call north
+------------------+---------+-----------------------------------------------+ +------------------+---------+-----------------------------------------------+
| Event name | Number | Description | | Event name | Number | Description |
+~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ +~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

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

@ -1,13 +1,15 @@
# In-Game Mail system # 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 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: 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). 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 command ONLY available when puppeting a character. Mails will be sent to other
Characters only and will not be available when OOC. Characters only and will not be available when OOC.
- If adding *both* commands to their respective cmdsets, you'll get two separate - 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 # 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: 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 # 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 This changes the Evennia login to ask for the account name and password as a series
sequence instead of requiring you to enter both at once. It uses EvMenu under of questions instead of requiring you to enter both at once. It uses Evennia's
the hood. menu system `EvMenu` under the hood.
## Installation ## Installation

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

@ -1,8 +1,8 @@
# TutorialMirror # 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 the description of the object looking at it
- echoes back whatever is being sent to its .msg - to the - 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 # Evennia Multidescer
Contrib - Griatch 2016 Contribution by Griatch 2016
A "multidescer" is a concept from the MUSH world. It allows for A "multidescer" is a concept from the MUSH world. It allows for
creating, managing and switching between multiple character creating, managing and switching between multiple character
descriptions. This multidescer will not require any changes to the descriptions and is a way for quickly managing your look (such as when
Character class, rather it will use the `multidescs` Attribute (a changing clothes) in more free-form roleplaying systems. This will also
list) and create it if it does not exist. work well together with the `rpsystem` contrib.
This contrib also works well together with the rpsystem contrib (which This multidescer will not
also adds the short descriptions and the `sdesc` command). 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 ## Installation

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

@ -1,22 +1,24 @@
# Legacy Comms-commands # Legacy Comms-commands
Contribution - Griatch 2021 Contribution by Griatch 2021
In Evennia 1.0, the old Channel commands (originally inspired by MUX) were In Evennia 1.0+, the old Channel commands (originally inspired by MUX) were
replaced by the single `channel` command that performs all these function. replaced by the single `channel` command that performs all these functions.
That command is still required to talk on channels. This contrib (extracted This contrib (extracted from Evennia 0.9.5) breaks out the functionality into
from Evennia 0.9.5) reuses the channel-management of the base Channel command separate Commands more familiar to MU* users. This is just for show though, the
but breaks out its functionality into separate Commands with MUX-familiar names. main `channel` command is still called under the hood.
- `allcom` - `channel/all` and `channel` | Contrib syntax | Default `channel` syntax |
- `addcom` - `channel/alias`, `channel/sub` and `channel/unmute` | -------------- | --------------------------------------------------------- |
- `delcom` - `channel/unalias`, `alias/unsub` and `channel/mute` | `allcom` | `channel/all` and `channel` |
- `cboot` - `channel/boot` (`channel/ban` and `/unban` not supported) | `addcom` | `channel/alias`, `channel/sub` and `channel/unmute` |
- `cwho` - `channel/who` | `delcom` | `channel/unalias`, `alias/unsub` and `channel/mute` |
- `ccreate` - `channel/create` | `cboot` | `channel/boot` (`channel/ban` and `/unban` not supported) |
- `cdestroy` - `channel/destroy` | `cwho` | `channel/who` |
- `clock` - `channel/lock` | `ccreate` | `channel/create` |
- `cdesc` - `channel/desc` | `cdestroy` | `channel/destroy` |
| `clock` | `channel/lock` |
| `cdesc` | `channel/desc` |
## Installation ## 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 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. 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 > 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. 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 ## base_systems
@ -29,113 +28,123 @@ login systems, new command syntaxes, and build helpers._
### Contrib: `awsstorage` ### 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` ### 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` ### Contrib: `color_markups`
Contribution, Griatch 2017 _Contrib by Griatch, 2017_
Additional color markup styles for Evennia (extending or replacing the default 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: `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 This reimplements the `evennia.utils.gametime` module but with a _custom_
calendar for your game world. It allows for scheduling events to happen at given calendar (unusual number of days per week/month/year etc) for your game world.
in-game times, taking this custom calendar into account. 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` ### Contrib: `email_login`
Evennia contrib - Griatch 2012 _Contrib by Griatch, 2012_
This is a variant of the login system that requires an email-address This is a variant of the login system that asks for an email-address
instead of a username to login. 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` ### 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 This contrib adds the ability to script with Python in-game. It allows trusted
(or other trusted builders) to dynamically add features to individual objects. staff/builders to dynamically add features and triggers to individual objects
Using custom Python set in-game, every immortal or privileged users could have a without needing to do it in external Python modules. Using custom Python in-game,
specific room, exit, character, object or something else behave differently from specific rooms, exits, characters, objects etc can be made to behave differently from
its "cousins". For these familiar with the use of softcode in MU`*`, like SMAUG its "cousins". This is similar to how softcode works for MU or MudProgs for DIKU.
MudProgs, the ability to add arbitrary behavior to individual objects is a step Keep in mind, however, that allowing Python in-game comes with _severe_
toward freedom. Keep in mind, however, the warning below, and read it carefully security concerns (you must trust your builders deeply), so read the warnings in
before the rest of the documentation. 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` ### 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 This changes the Evennia login to ask for the account name and password as a series
sequence instead of requiring you to enter both at once. It uses EvMenu under of questions instead of requiring you to enter both at once. It uses Evennia's
the hood. 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` ### Contrib: `mux_comms_cmds`
Contribution - Griatch 2021 _Contribution by Griatch 2021_
In Evennia 1.0, the old Channel commands (originally inspired by MUX) were In Evennia 1.0+, the old Channel commands (originally inspired by MUX) were
replaced by the single `channel` command that performs all these function. replaced by the single `channel` command that performs all these functions.
That command is still required to talk on channels. This contrib (extracted This contrib (extracted from Evennia 0.9.5) breaks out the functionality into
from Evennia 0.9.5) reuses the channel-management of the base Channel command separate Commands more familiar to MU* users. This is just for show though, the
but breaks out its functionality into separate Commands with MUX-familiar names. 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` ### 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 This module contains a command class with an alternate syntax parser implementing
in-game, using --options, positional arguments and stuff like -n 10 etc Unix-style command syntax in-game. This means `--options`, positional arguments
similarly to a unix command. It might not the best syntax for the average player 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 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. 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` ### Contrib: `evscaperoom`
Evennia contrib - Griatch 2019 _Contribution by Griatch, 2019_
This 'Evennia escaperoom game engine' was created for the MUD Coders Guild game A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
Jam, April 14-May 15 2019. The theme for the jam was "One Room". This contains the spawn and join puzzle rooms that track their state independently. Any number of players
utilities and base classes and an empty example room. 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` ### Contrib: `barter`
Evennia contribution - Griatch 2012 _Contribution by Griatch, 2012_
This implements a full barter system - a way for players to safely This implements a full barter system - a way for players to safely
trade items between each other using code rather than simple free-form trade items between each other in code rather than simple `give/get`
talking. The advantage of this is increased buy/sell safety but it commands. This increases both safety (at no time will one player have
also streamlines the process and makes it faster when doing many both goods and payment in-hand) and speed, since agreed goods will
transactions (since goods are automatically exchanged once both be moved automatically). By just replacing one side with coin objects,
agree). (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` ### Contrib: `clothing`
Evennia contribution - Tim Ashley Jenkins 2017 _Contribution by Tim Ashley Jenkins, 2017_
Provides a typeclass and commands for wearable clothing, Provides a typeclass and commands for wearable clothing. These
which is appended to a character's description when worn. 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` ### Contrib: `cooldowns`
Evennia contrib - owllex, 2021 _Contribution by owllex, 2021_
This contrib provides a simple cooldown handler that can be attached to any Cooldowns are used modelling rate-limited actions, like how often a
typeclassed Object or Account. A cooldown is a lightweight persistent character can perform a given action; until a certain time has passed their
asynchronous timer that you can query to see if it is ready. 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: `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: `gendersub`
Contrib - Griatch 2015 _Contribution by Griatch 2015_
This is a simple gender-aware Character class for allowing users to This is a simple gender-aware Character class for allowing users to
insert custom markers in their text to indicate gender-aware insert custom markers in their text to indicate gender-aware
messaging. It relies on a modified msg() and is meant as an messaging. It relies on a modified msg() and is meant as an
inspiration and starting point to how to do stuff like this. 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` ### Contrib: `mail`
Evennia Contribution - grungies1138 2016 _Contribution by grungies1138 2016_
A simple Brandymail style mail system that uses the Msg class from Evennia 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: 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: `multidescer`
Contrib - Griatch 2016 _Contribution by Griatch 2016_
A "multidescer" is a concept from the MUSH world. It allows for A "multidescer" is a concept from the MUSH world. It allows for
creating, managing and switching between multiple character creating, managing and switching between multiple character
descriptions. This multidescer will not require any changes to the descriptions and is a way for quickly managing your look (such as when
Character class, rather it will use the `multidescs` Attribute (a changing clothes) in more free-form roleplaying systems. This will also
list) and create it if it does not exist. 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` ### 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) Intended for adventure-game style combination puzzles, such as combining fruits
to produce new objects. 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: `turnbattle`
Contrib - Tim Ashley Jenkins 2017 _Contribution by Tim Ashley Jenkins, 2017_
This is a framework for a simple turn-based combat system, similar 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 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 default), and combat progresses through the turn order, looping through
the participants until the fight ends. 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` ### 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 This extends the normal `Room` typeclass to allow its description to change
by an extended `Look` command and an extended `desc` command, also with time-of-day and/or season. It also adds 'details' for the player to look at
in this module. 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` ### 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` ### Contrib: `simpledoor`
Contribution - Griatch 2016 _Contribution by Griatch, 2016_
A simple two-way exit that represents a door that can be opened and 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 closed from both sides. Can easily be expanded to make it lockable,
etc. Note that the simpledoor is based on Evennia locks, so it will destroyable etc.
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.
[Read the documentation](./Contrib-Simpledoor.md) [Read the documentation](./Contrib-Simpledoor.md) - [Browse the Code](evennia.contrib.grid.simpledoor)
### Contrib: `slow_exit` ### Contrib: `slow_exit`
Contribution - Griatch 2014 _Contribution by Griatch 2014_
This is an example of an Exit-type that delays its traversal. This simulates An example of an Exit-type that delays its traversal. This simulates
slow movement, common in many different types of games. The contrib also slow movement, common in many games. The contrib also
contains two commands, `CmdSetSpeed` and CmdStop for changing the movement speed contains two commands, `setspeed` and `stop` for changing the movement speed
and abort an ongoing traversal, respectively. 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` ### Contrib: `wilderness`
Evennia contrib - titeuf87 2017 _Contribution by titeuf87, 2017_
This contrib provides a wilderness map without actually creating a large number This contrib provides a wilderness map without actually creating a large number
of rooms - as you move, your room is instead updated with different of rooms - as you move, you instead end up back in the same room but its description
descriptions. This means you can make huge areas with little database use as changes. This means you can make huge areas with little database use as
long as the rooms are relatively similar (name/desc changing). 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` ### Contrib: `xyzgrid`
Full grid coordinate- pathfinding and visualization system _Contribution by Griatch 2021_
Evennia Contrib by Griatch 2021
The default Evennia's rooms are non-euclidian - they can connect Places Evennia's game world on an xy (z being different maps) coordinate grid.
to each other with any types of exits without necessarily having a clear Grid is created and maintained externally by drawing and parsing 2D ASCII maps,
position relative to each other. This gives maximum flexibility, but many games including teleports, map transitions and special markers to aid pathfinding.
want to use cardinal movements (north, east etc) and also features like finding Supports very fast shortest-route pathfinding on each map. Also includes a
the shortest-path between two points. 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` ### 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: `health_bar`
Contrib - Tim Ashley Jenkins 2017 _Contribution by Tim Ashley Jenkins, 2017_
The function provided in this module lets you easily display visual The function provided in this module lets you easily display visual
bars or meters - "health bar" is merely the most obvious use for this, bars or meters as a colorful bar instead of just a number. A "health bar"
though these bars are highly customizable and can be used for any sort is merely the most obvious use for this, but the bar is highly customizable
of appropriate data besides player health. 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` ### Contrib: `rpsystem`
Roleplaying emotes/sdescs - Griatch, 2015 _Contribution by Griatch, 2015_
Language/whisper emotes - 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` ### Contrib: `traits`
Whitenoise 2014, Ainneve contributors, _Contribution by Griatch 2020, based on code by Whitenoise and Ainneve contribs, 2014_
Griatch 2020
A `Trait` represents a modifiable property on (usually) a Character. They can A `Trait` represents a modifiable property on (usually) a Character. They can
be used to represent everything from attributes (str, agi etc) to skills 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` ### Contrib: `batchprocessor`
Contibution - Griatch 2012 _Contibution by Griatch, 2012_
The batch processor is used for generating in-game content from one or more Simple examples for the batch-processor. The batch processor is used for generating
static files. Files can be stored with version control and then 'applied' in-game content from one or more static files. Files can be stored with version
to the game to create content. 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` ### Contrib: `bodyfunctions`
Griatch - 2012 _Contribution by Griatch, 2012_
Example script for testing. This adds a simple timer that has your 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` ### 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` ### Contrib: `red_button`
Griatch - 2011 _Contribution by Griatch, 2011_
This is a more advanced example object with its own functionality (commands) A red button that you can press to have an effect. This is a more advanced example
on it. 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` ### 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 This is an example of a static NPC object capable of holding a simple menu-driven
conversation. It's just meant as an example. 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` ### 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 Think of it as a sort of single-player adventure rather than a
full-fledged multi-player game world. The various rooms and objects 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 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: `auditing`
Contrib - Johnny 2017 _Contribution by Johnny, 2017_
This is a tap that optionally intercepts all data sent to/from clients and the Utility that taps and intercepts all data sent to/from clients and the
server and passes it to a callback of your choosing. 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: `fieldfill`
Contrib - Tim Ashley Jenkins 2018 _Contribution by Tim Ashley Jenkins, 2018_
This module contains a function that calls an easily customizable EvMenu - this This module contains a function that generates an `EvMenu` for you - this
menu presents the player with a fillable form, with fields that can be filled menu presents the player with a form of fields that can be filled
out in any order. Each field's value can be verified, with the function out in any order (e.g. for character generation or building). Each field's value can
allowing easy checks for text and integer input, minimum and maximum values / be verified, with the function allowing easy checks for text and integer input,
character lengths, or can even be verified by a custom function. Once the form minimum and maximum values / character lengths, or can even be verified by a custom
is submitted, the form's data is submitted as a dictionary to any callable of function. Once the form is submitted, the form's data is submitted as a dictionary
your choice. 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` ### 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 with specific criteria. You could, for instance, use it to generate
phone numbers, license plate numbers, validation codes, non-sensivite phone numbers, license plate numbers, validation codes, in-game security
passwords and so on. The strings generated by the generator will be passwords and so on. The strings generated will be stored and won't be repeated.
stored and won't be available again in order to avoid repetition.
Here's a very simple example:
[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: `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 This utility allows you to create and initialize an entire branching EvMenu
instance with nothing but a multi-line string passed to one function. 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} ```{toctree}
:depth: 2
Contribs/Contrib-AWSStorage.md Contribs/Contrib-AWSStorage.md
Contribs/Contrib-Building-Menu.md Contribs/Contrib-Building-Menu.md
Contribs/Contrib-Color-Markups.md Contribs/Contrib-Color-Markups.md
Contribs/Contrib-Custom-Gametime.md Contribs/Contrib-Custom-Gametime.md
Contribs/Contrib-Email-Login.md Contribs/Contrib-Email-Login.md
Contribs/Contrib-Ingame-Python.md Contribs/Contrib-Ingame-Python.md
Contribs/Contrib-Menu-Login.md Contribs/Contrib-Menu-Login.md
Contribs/Contrib-Mux-Comms-Cmds.md Contribs/Contrib-Mux-Comms-Cmds.md
Contribs/Contrib-Unixcommand.md Contribs/Contrib-Unixcommand.md
Contribs/Contrib-Evscaperoom.md Contribs/Contrib-Evscaperoom.md
Contribs/Contrib-Barter.md Contribs/Contrib-Barter.md
Contribs/Contrib-Clothing.md Contribs/Contrib-Clothing.md
Contribs/Contrib-Cooldowns.md Contribs/Contrib-Cooldowns.md
Contribs/Contrib-Crafting.md Contribs/Contrib-Crafting.md
Contribs/Contrib-Gendersub.md Contribs/Contrib-Gendersub.md
Contribs/Contrib-Mail.md Contribs/Contrib-Mail.md
Contribs/Contrib-Multidescer.md Contribs/Contrib-Multidescer.md
Contribs/Contrib-Puzzles.md Contribs/Contrib-Puzzles.md
Contribs/Contrib-Turnbattle.md Contribs/Contrib-Turnbattle.md
Contribs/Contrib-Extended-Room.md Contribs/Contrib-Extended-Room.md
Contribs/Contrib-Mapbuilder.md Contribs/Contrib-Mapbuilder.md
Contribs/Contrib-Simpledoor.md Contribs/Contrib-Simpledoor.md
Contribs/Contrib-Slow-Exit.md Contribs/Contrib-Slow-Exit.md
Contribs/Contrib-Wilderness.md Contribs/Contrib-Wilderness.md
Contribs/Contrib-XYZGrid.md Contribs/Contrib-XYZGrid.md
Contribs/Contrib-Dice.md Contribs/Contrib-Dice.md
Contribs/Contrib-Health-Bar.md Contribs/Contrib-Health-Bar.md
Contribs/Contrib-RPSystem.md Contribs/Contrib-RPSystem.md
Contribs/Contrib-Traits.md Contribs/Contrib-Traits.md
Contribs/Contrib-Batchprocessor.md Contribs/Contrib-Batchprocessor.md
Contribs/Contrib-Bodyfunctions.md Contribs/Contrib-Bodyfunctions.md
Contribs/Contrib-Mirror.md Contribs/Contrib-Mirror.md
Contribs/Contrib-Red-Button.md Contribs/Contrib-Red-Button.md
Contribs/Contrib-Talking-Npc.md Contribs/Contrib-Talking-Npc.md
Contribs/Contrib-Tutorial-World.md Contribs/Contrib-Tutorial-World.md
Contribs/Contrib-Auditing.md Contribs/Contrib-Auditing.md
Contribs/Contrib-Fieldfill.md Contribs/Contrib-Fieldfill.md
Contribs/Contrib-Random-String-Generator.md Contribs/Contrib-Random-String-Generator.md
Contribs/Contrib-Tree-Select.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> will be overwritten.</small>

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

@ -1,18 +1,21 @@
# Puzzles System # 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) Intended for adventure-game style combination puzzles, such as combining fruits
to produce new objects. 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. a new set of objects (aka results) are automatically created.
## Installation ## 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') 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 base system for Evennia
Roleplaying emotes/sdescs - Griatch, 2015 Contribution by Griatch, 2015
Language/whisper emotes - 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 ## Roleplaying emotes

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

@ -1,12 +1,14 @@
# Pseudo-random generator and registry # 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 with specific criteria. You could, for instance, use it to generate
phone numbers, license plate numbers, validation codes, non-sensivite phone numbers, license plate numbers, validation codes, in-game security
passwords and so on. The strings generated by the generator will be passwords and so on. The strings generated will be stored and won't be repeated.
stored and won't be available again in order to avoid repetition.
## Usage Example
Here's a very simple example: Here's a very simple example:
```python ```python

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

@ -1,9 +1,9 @@
# Red Button example # Red Button example
Griatch - 2011 Contribution by Griatch, 2011
This is a more advanced example object with its own functionality (commands) A red button that you can press to have an effect. This is a more advanced example
on it. object with its own functionality and state tracking.
Create the button with Create the button with

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

@ -1,13 +1,15 @@
# SimpleDoor # SimpleDoor
Contribution - Griatch 2016 Contribution by Griatch, 2016
A simple two-way exit that represents a door that can be opened and 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 closed from both sides. Can easily be expanded to make it lockable,
etc. Note that the simpledoor is based on Evennia locks, so it will destroyable etc.
not work for a superuser (which bypasses all locks) - the superuser
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 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. non-superuser account.
## Installation: ## Installation:

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

@ -1,10 +1,10 @@
# Slow Exit # Slow Exit
Contribution - Griatch 2014 Contribution by Griatch 2014
This is an example of an Exit-type that delays its traversal. This simulates An example of an Exit-type that delays its traversal. This simulates
slow movement, common in many different types of games. The contrib also slow movement, common in many games. The contrib also
contains two commands, `CmdSetSpeed` and CmdStop for changing the movement speed contains two commands, `setspeed` and `stop` for changing the movement speed
and abort an ongoing traversal, respectively. and abort an ongoing traversal, respectively.
## Installation: ## Installation:

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

@ -1,9 +1,9 @@
# Talkative NPC example # 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 This is an example of a static NPC object capable of holding a simple menu-driven
conversation. It's just meant as an example. conversation. Suitable for example as a quest giver or merchant.
## Installation ## Installation

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

@ -1,12 +1,10 @@
# Traits # Traits
Whitenoise 2014, Ainneve contributors, Contribution by Griatch 2020, based on code by Whitenoise and Ainneve contribs, 2014
Griatch 2020
A `Trait` represents a modifiable property on (usually) a Character. They can A `Trait` represents a modifiable property on (usually) a Character. They can
be used to represent everything from attributes (str, agi etc) to skills 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 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 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 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 # 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 This utility allows you to create and initialize an entire branching EvMenu
instance with nothing but a multi-line string passed to one function. instance from a multi-line string passed to one function.
EvMenu is incredibly powerful and flexible, but using it for simple menus > Note: Since the time this contrib was created, EvMenu itself got its own templating
can often be fairly cumbersome - a simple menu that can branch into five > language that has more features and is not compatible with the style used in
categories would require six nodes, each with options represented as a list > this contrib. Both can still be used in parallel.
of dictionaries.
`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 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 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 # 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 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 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 # 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 Think of it as a sort of single-player adventure rather than a
full-fledged multi-player game world. The various rooms and objects 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 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 The tutorial world also includes a game tutor menu example, exemplifying
Evmenu. Evmenu.

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

@ -1,12 +1,12 @@
# Unix-like Command style parent # 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 This module contains a command class with an alternate syntax parser implementing
in-game, using --options, positional arguments and stuff like -n 10 etc Unix-style command syntax in-game. This means `--options`, positional arguments
similarly to a unix command. It might not the best syntax for the average player 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 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. library under the hood.
## Installation ## Installation

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

@ -1,10 +1,10 @@
# Wilderness system # Wilderness system
Evennia contrib - titeuf87 2017 Contribution by titeuf87, 2017
This contrib provides a wilderness map without actually creating a large number This contrib provides a wilderness map without actually creating a large number
of rooms - as you move, your room is instead updated with different of rooms - as you move, you instead end up back in the same room but its description
descriptions. This means you can make huge areas with little database use as changes. This means you can make huge areas with little database use as
long as the rooms are relatively similar (name/desc changing). long as the rooms are relatively similar (name/desc changing).
## Installation ## 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/`. 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 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 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} ```{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 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). 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 ### Internal links
Most links will be to other pages of the documentation or to Evennia's API docs. Each document 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 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 given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with
a single dash `-`. a single dash `-`.
As an example, let's assume the following is the contents of a file `Menu-stuff.md`: As an example, let's assume the following is the contents of a file `Menu-stuff.md`:
``` ```
# Menu items # Menu items
Some text... Some text...
@ -143,28 +143,28 @@ Some text...
Some more 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) [menus](#menu-items)
[example](#a-yesno-example) [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) [menus](Menu-Stuff.md#menu-items)
[example](Menu-Stuff.md#a-yesno-example) [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). > 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 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 can direct the reader to the sources by just giving the python-path to the location of the
resource under the `evennia/` repository: resource under the `evennia/` repository:
[DefaultObject](evennia.objects.objects.DefaultObject) [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 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. 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. - `[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. - `[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. > described above.
### Urls/References in one place ### 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. 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: 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. 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 | | heading1 | heading2 | heading3 |
| --- | --- | --- | | --- | --- | --- |
| value1 | value2 | value3 | | value1 | value2 | value3 |
| | value 4 | | | | value 4 | |
| value 5 | value 6 | | | value 5 | value 6 | |
```` ````
| heading1 | heading2 | heading3 | | heading1 | heading2 | heading3 |
| --- | --- | --- | | --- | --- | --- |
| value1 | value2 | value3 | | value1 | value2 | value3 |
| | value 4 | | | | value 4 | |
| value 5 | value 6 | | | 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. 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 ### 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: 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. For examples of using the Python command-line, use `python` language and `>>>` prompt.
```` ````
```python ```python
>>> print("Hello World") >>> print("Hello World")
Hello World Hello World
``` ```
```` ````
```python ```python
>>> print("Hello World") >>> print("Hello World")
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. Indent returns from the game.
```` ````
```shell ```shell
> look at flower > look at flower
Red Flower(#34) Red Flower(#34)
A flower with red petals. 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. 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 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. skip it - it can be confusing to users not that familiar with the command line.
```` ````
```bash ```bash
$ ls $ ls
evennia/ mygame/ evennia/ mygame/
``` ```
evennia start --log evennia start --log
```` ````
```bash ```bash
$ ls $ ls
evennia/ mygame/ evennia/ mygame/
``` ```
@ -330,13 +330,13 @@ evennia/ mygame/
evennia start --log 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 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 not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is
on the form on the form
```` ````
```{directive} any_options_here ```{directive} any_options_here
content content
@ -347,7 +347,7 @@ content
#### Note #### Note
This kind of note may pop more than doing a `> Note: ...`. This kind of note may pop more than doing a `> Note: ...`.
```` ````
```{note} ```{note}
@ -436,7 +436,7 @@ for example to remind the reader of some concept relevant to the text.
- There can be bullet lists - There can be bullet lists
- in here. - in here.
Separate sections with Separate sections with
an empty line. an empty line.
``` ```
@ -447,12 +447,12 @@ an empty line.
- There can be bullet lists - There can be bullet lists
- in here. - in here.
Separate sections with Separate sections with
an empty line. 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: squeezed to the left of the sidebar), one can embed a plain HTML string in the markdown like so:
```html ```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 ### A more flexible code block
The regular Markdown Python codeblock is usually enough but for more direct control over the style, one 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 ```{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, 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 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 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 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 [Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted
@ -545,8 +545,8 @@ into pretty api docs.
## Technical ## Technical
Evennia leverages [Sphinx][sphinx] with the [MyST][MyST] extension, which allows us 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) 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 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. 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] 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 [linkdemo]: #Links
[retext]: https://github.com/retext-project/retext [retext]: https://github.com/retext-project/retext
[grip]: https://github.com/joeyespo/grip [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 # 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 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 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. 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 ## 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 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 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 Your current location is defined by `[@]` while the `[.]`s are other rooms that the "worm" has seen
since departing from your location. 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 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 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 ```python
# in mygame/world/map.py # in mygame/world/map.py
# the symbol is identified with a key "sector_type" on the # the symbol is identified with a key "sector_type" on the
# Room. Keys None and "you" must always exist. # Room. Keys None and "you" must always exist.
SYMBOLS = { None : ' . ', # for rooms without sector_type Attribute SYMBOLS = { None : ' . ', # for rooms without sector_type Attribute
'you' : '[@]', 'you' : '[@]',
'SECT_INSIDE': '[.]' } 'SECT_INSIDE': '[.]' }
``` ```
@ -122,7 +121,7 @@ class Map(object):
return board return board
def check_grid(self): 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. # that both max_l and max_w are odd numbers.
return True if self.max_length % 2 != 0 or self.max_width % 2 != 0\ return True if self.max_length % 2 != 0 or self.max_width % 2 != 0\
else False else False
@ -141,7 +140,7 @@ def draw_room_on_map(room, max_distance):
return return
for exit in room.exits: 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 # skip drawing if we already visited the destination
continue continue
else: 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 = changes it becomes a simple algebraic linear relationship which is simply `max_distance =
(min(max_width, max_length) -1) / 2`. (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 Now we can start to fill our Map object with some methods. We are still missing a few methods that
are very important: are very important:
@ -184,8 +183,8 @@ n
self.curX/Y. .accordingly self.curX/Y. .accordingly
* `self.start_loc_on_grid(self)` - the very first initial draw on the grid representing your * `self.start_loc_on_grid(self)` - the very first initial draw on the grid representing your
location in the middle of the grid location in the middle of the grid
* 'self.show_map` - after everything is done convert the map into a readable string` * `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.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 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 # we have to store the grid into a variable
self.grid = self.create_grid() self.grid = self.create_grid()
# we use the algebraic relationship # 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) ((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 # we only map in the cardinal directions. Mapping up/down would be
# an interesting learning project for someone who wanted to try it. # an interesting learning project for someone who wanted to try it.
continue continue
if self.has_drawn(exit.destination): if self.has_drawn(exit.destination):
# we've been to the destination already, skip ahead. # we've been to the destination already, skip ahead.
continue 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... The first thing the "worm" does is to draw your current location in `self.draw`. Lets define that...
```python ```python
#in mygame/word/map.py, in the Map class #in mygame/word/map.py, in the Map class
def draw(self, room): def draw(self, room):
# draw initial ch location on map first! # draw initial ch location on map first!
@ -272,7 +271,7 @@ def start_loc_on_grid(self):
x = self.median(self.max_width) x = self.median(self.max_width)
y = self.median(self.max_length) y = self.median(self.max_length)
# x and y are floats by default, can't index lists with float types # 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.grid[x][y] = SYMBOLS['you']
self.curX, self.curY = x, y # updating worms current location 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 ```python
def update_pos(self, room, exit_name): 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. # to where the worm is currently at.
self.curX, self.curY = \ self.curX, self.curY = \
self.worm_has_mapped[room][0], self.worm_has_mapped[room][1] 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 # variables depending on which 'exit' it found
if exit_name == 'east': if exit_name == 'east':
self.curY += 1 self.curY += 1
@ -343,14 +342,14 @@ from evennia import DefaultRoom
from world.map import Map from world.map import Map
class Room(DefaultRoom): class Room(DefaultRoom):
def return_appearance(self, looker): def return_appearance(self, looker):
# [...] # [...]
string = f"{Map(looker).show_map()}\n" string = f"{Map(looker).show_map()}\n"
# Add all the normal stuff like room description, # Add all the normal stuff like room description,
# contents, exits etc. # contents, exits etc.
string += "\n" + super().return_appearance(looker) 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 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 `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 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 `"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. or you could add the Attribute in the Room's `at_object_creation` method.
```python ```python
#mygame/world/map.py # mygame/world/map.py
# These are keys set with the Attribute sector_type on the room. # These are keys set with the Attribute sector_type on the room.
# The keys None and "you" must always exist. # The keys None and "you" must always exist.
SYMBOLS = { None : ' . ', # for rooms without a sector_type attr SYMBOLS = { None : ' . ', # for rooms without a sector_type attr
'you' : '[@]', 'you' : '[@]',
'SECT_INSIDE': '[.]' } 'SECT_INSIDE': '[.]' }
class Map(object): class Map(object):
@ -394,16 +393,16 @@ class Map(object):
if self.check_grid(): if self.check_grid():
# we actually have to store the grid into a variable # we actually have to store the grid into a variable
self.grid = self.create_grid() 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)) ((min(max_width, max_length) -1 ) / 2))
def update_pos(self, room, exit_name): 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. # stays up to date to where the worm is currently at.
self.curX, self.curY = \ self.curX, self.curY = \
self.worm_has_mapped[room][0], self.worm_has_mapped[room][1] 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 # variables depending on which 'exit' it found
if exit_name == 'east': if exit_name == 'east':
self.curY += 1 self.curY += 1
@ -419,19 +418,19 @@ class Map(object):
if max_distance == 0: if max_distance == 0:
return return
for exit in room.exits: for exit in room.exits:
if exit.name not in ("north", "east", "west", "south"): if exit.name not in ("north", "east", "west", "south"):
# we only map in the cardinal directions. Mapping up/down would be # we only map in the cardinal directions. Mapping up/down would be
# an interesting learning project for someone who wanted to try it. # an interesting learning project for someone who wanted to try it.
continue continue
if self.has_drawn(exit.destination): if self.has_drawn(exit.destination):
# we've been to the destination already, skip ahead. # we've been to the destination already, skip ahead.
continue continue
self.update_pos(room, exit.name.lower()) self.update_pos(room, exit.name.lower())
self.draw_room_on_map(exit.destination, max_distance - 1) self.draw_room_on_map(exit.destination, max_distance - 1)
def draw(self, room): def draw(self, room):
# draw initial caller location on map first! # draw initial caller location on map first!
if room == self.caller.location: if room == self.caller.location:
@ -441,30 +440,30 @@ class Map(object):
# map all other rooms # map all other rooms
self.worm_has_mapped[room] = [self.curX, self.curY] self.worm_has_mapped[room] = [self.curX, self.curY]
# this will use the sector_type Attribute or None if not set. # 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): def median(self, num):
lst = sorted(range(0, num)) lst = sorted(range(0, num))
n = len(lst) n = len(lst)
m = n -1 m = n -1
return (lst[n//2] + lst[m//2]) / 2.0 return (lst[n//2] + lst[m//2]) / 2.0
def start_loc_on_grid(self): def start_loc_on_grid(self):
x = self.median(self.max_width) x = self.median(self.max_width)
y = self.median(self.max_length) y = self.median(self.max_length)
# x and y are floats by default, can't index lists with float types # 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.grid[x][y] = SYMBOLS['you']
self.curX, self.curY = x, y # updating worms current location self.curX, self.curY = x, y # updating worms current location
def has_drawn(self, room): def has_drawn(self, room):
return True if room in self.worm_has_mapped.keys() else False return True if room in self.worm_has_mapped.keys() else False
def create_grid(self): 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): # with the specified variables from __init__(self):
board = [] board = []
for row in range(self.max_width): for row in range(self.max_width):
@ -474,7 +473,7 @@ class Map(object):
return board return board
def check_grid(self): 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 # both max_l and max_w are odd numbers
return True if self.max_length % 2 != 0 or \ return True if self.max_length % 2 != 0 or \
self.max_width % 2 != 0 else False 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 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 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 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 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. 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 # 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 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 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. prescribe any major game systems on you.
That said, Evennia _does_ offer some more game-opinionated _optional_ stuff. These are referred to as _Contribs_ 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. 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 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 - A barter system
- Character generation - Character generation
- Some concept of wearing armor - Some concept of wearing armor
- The ability to roll dice - The ability to roll dice
- Rooms with awareness of day, night and season - Rooms with awareness of day, night and season
- Roleplaying with short-descs, poses and emotes - Roleplaying with short-descs, poses and emotes
- Quests - Quests
- Combat (with players and against monsters) - 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 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 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 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 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. 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? 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 ... Tom > trade Sue: Hm, I could use a necklace ...
<both accepted trade. Start trade> <both accepted trade. Start trade>
Sue > offer necklace: This necklace is really worth it. Sue > offer necklace: This necklace is really worth it.
Tom > evaluate necklace: Tom > evaluate necklace:
<Tom sees necklace stats> <Tom sees necklace stats>
Tom > offer ration: I don't have a healing potion, but I'll trade you an iron ration! 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... 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. 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. 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 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 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 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. 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 ## 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 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 an object in a particular location and this will then be reflected in your character's description. You can
also add roleplaying flavor: also add roleplaying flavor:
> wear helmet slightly askew on her head > wear helmet slightly askew on her head
look self look self
Username is wearing a helmet slightly askew on her head. 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 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. 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(s): 7. Total result is 7. This is a failure (by 5)
> roll/hidden 1d20 > 12 > roll/hidden 1d20 > 12
Roll(s): 18. Total result is 17. This is a success (by 6). (not echoed) 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. 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. 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 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 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. `<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 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 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. 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 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 The contrib is simple to add and provides a lot of optional flexibility, so we'll add it to our
game, why not! game, why not!
## RP-System contrib ## 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" 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 (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" Sue has the sdesc "A muscular, blonde woman"
Tom > look Tom > look
Tom: <room desc> ... You see: A muscular, blonde woman Tom: <room desc> ... You see: A muscular, blonde woman
Tom > emote /me smiles to /muscular. Tom > emote /me smiles to /muscular.
Tom: Tom smiles to A muscular, blonde woman. 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 > emote Leaning forward, /me says, "Well hello, what's yer name?"
Tom: Leaning forward, Tom says, "Well hello..." Tom: Leaning forward, Tom says, "Well hello..."
Sue: Leaning forward, A tall man says, "Well hello, what's yer name?" 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. Sue: Sue grins. "I'm Angelica", she says.
Tom: A muscular, blonde woman grins. "I'm Angelica", she says. Tom: A muscular, blonde woman grins. "I'm Angelica", she says.
Tom > recog muscular Angelica 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 ..." 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 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 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 `"..."`. `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 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. Tom > pose stands by the bar, looking bored.
Sue > look Sue > look
Sue: <room desc> ... A tall man stands by the bar, looking bored. 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 You can also wear a mask to hide your identity; your sdesc will then be changed to the sdesc of the mask,
[rplanguage](../../../api/evennia.contrib.rplanguage.md) module that integrates with the spoken words in your emotes and garbles them if you don't understand 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. the language spoken. In order to restrict the scope we will not include languages for the tutorial game.
## Talking NPC contrib ## 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 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. good as inspiration for how we'll do quest-givers later.
## Traits contrib ## 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 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 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. 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 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 installed, the traits are accessed on a new handler `.traits`, for example
> py self.traits.hp.value > py self.traits.hp.value
100 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.reset() # drink a potion
> py self.traits.hp.value > py self.traits.hp.value
100 100
A Trait is persistent (it uses an Attribute under the hood) and tracks changes, min/max and other things 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. automatically. They can also be added together in various mathematical operations.
The contrib introduces three main Trait-classes 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 - _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 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. 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 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. effects of slow poisons and healing both.
``` ```
> py self.traits.hp.value > py self.traits.hp.value
100 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 > py self.traits.hp.ratetarget = 50 # stop at 50 hp
# Wait 30s # Wait 30s
> py self.traits.hp.value > py self.traits.hp.value
@ -217,36 +209,36 @@ effects of slow poisons and healing both.
50 # stopped at 50 50 # stopped at 50
> py self.traits.hp.rate = 0 # no more poison > py self.traits.hp.rate = 0 # no more poison
> py self.traits.hp.rate = 5 # healing magic! > py self.traits.hp.rate = 5 # healing magic!
# wait 5s # wait 5s
> pyself.traits.hp.value > pyself.traits.hp.value
75 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 ## 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: 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. - basic - initiative and turn order, attacks against defense values, damage.
- equip - considers weapons and armor, wielding and weapon accuracy. - equip - considers weapons and armor, wielding and weapon accuracy.
- items - adds usable items with conditions and status effects - 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. - 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. a complete system. It's also not built with _Traits_ in mind, so we will need to adjust it for that.
## Conclusions ## Conclusions
With some contribs selected, we have pieces to build from and don't have to write everything from scratch. 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. to our needs.
We will now move into actually starting to implement our tutorial game 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 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. 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. at.
Evennia offers a range of [default commands](../Components/Default-Commands.md) for 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 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 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 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 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- 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 Tutorial), [fill your world with NPC's](./Tutorial-Aggressive-NPCs.md) or
[implement a combat system](../Howto/Starting/Part3/Turn-based-Combat-System.md). [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/Using-MUX-as-a-Standard
Concepts/Web-Features Concepts/Web-Features
Concepts/Zones Concepts/Zones
Contribs/A-voice-operated-elevator-using-events
Contribs/Arxcode-installing-help Contribs/Arxcode-installing-help
Contribs/Building-menus Contribs/Building-menus
Contribs/Contrib-AWSStorage Contribs/Contrib-AWSStorage
@ -97,6 +96,8 @@ Contribs/Contrib-Fieldfill
Contribs/Contrib-Gendersub Contribs/Contrib-Gendersub
Contribs/Contrib-Health-Bar Contribs/Contrib-Health-Bar
Contribs/Contrib-Ingame-Python Contribs/Contrib-Ingame-Python
Contribs/Contrib-Ingame-Python-Tutorial-Dialogue
Contribs/Contrib-Ingame-Python-Tutorial-Elevator
Contribs/Contrib-Mail Contribs/Contrib-Mail
Contribs/Contrib-Mapbuilder Contribs/Contrib-Mapbuilder
Contribs/Contrib-Menu-Login Contribs/Contrib-Menu-Login
@ -118,11 +119,6 @@ Contribs/Contrib-Tutorial-World
Contribs/Contrib-Unixcommand Contribs/Contrib-Unixcommand
Contribs/Contrib-Wilderness Contribs/Contrib-Wilderness
Contribs/Contrib-XYZGrid Contribs/Contrib-XYZGrid
Contribs/Crafting
Contribs/Dialogues-in-events
Contribs/Dynamic-In-Game-Map
Contribs/Static-In-Game-Map
Contribs/XYZGrid
Contributing Contributing
Contributing-Docs Contributing-Docs
Evennia-API Evennia-API
@ -137,6 +133,7 @@ Howto/Command-Duration
Howto/Command-Prompt Howto/Command-Prompt
Howto/Coordinates Howto/Coordinates
Howto/Default-Exit-Errors Howto/Default-Exit-Errors
Howto/Dynamic-In-Game-Map
Howto/Evennia-for-Diku-Users Howto/Evennia-for-Diku-Users
Howto/Evennia-for-MUSH-Users Howto/Evennia-for-MUSH-Users
Howto/Evennia-for-roleplaying-sessions 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/Add-a-simple-new-web-page
Howto/Starting/Part5/Starting-Part5 Howto/Starting/Part5/Starting-Part5
Howto/Starting/Part5/Web-Tutorial Howto/Starting/Part5/Web-Tutorial
Howto/Static-In-Game-Map
Howto/Tutorial-Aggressive-NPCs Howto/Tutorial-Aggressive-NPCs
Howto/Tutorial-NPCs-listening Howto/Tutorial-NPCs-listening
Howto/Tutorial-Tweeting-Game-Stats Howto/Tutorial-Tweeting-Game-Stats

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

@ -1,12 +1,10 @@
# AWSstorage system # AWSstorage system
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, This plugin migrates the Web-based portion of Evennia, namely images,
javascript, and other items located inside staticfiles into Amazon AWS (S3) for javascript, and other items located inside staticfiles into Amazon AWS (S3)
hosting. cloud hosting. Great for those serving media with the game.
Files hosted on S3 are "in the cloud," and while your personal 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, 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 # 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 Building menus are in-game menus, not unlike `EvMenu` though using a
different approach. Building menus have been specifically designed to edit different approach. Building menus have been specifically designed to edit
information as a builder. Creating a building menu in a command allows 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 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 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. that will edit any default object, offering to change its key and description.
## Install ## Install

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

@ -1,9 +1,10 @@
# Color markups # Color markups
Contribution, Griatch 2017 Contrib by Griatch, 2017
Additional color markup styles for Evennia (extending or replacing the default 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 ## Installation

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

@ -1,10 +1,11 @@
# Custom gameime # 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 This reimplements the `evennia.utils.gametime` module but with a _custom_
calendar for your game world. It allows for scheduling events to happen at given calendar (unusual number of days per week/month/year etc) for your game world.
in-game times, taking this custom calendar into account. Like the original, it allows for scheduling events to happen at given
in-game times, but now taking this custom calendar into account.
## Installation ## Installation

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

@ -1,9 +1,10 @@
# Email-based login system # 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 This is a variant of the login system that asks for an email-address
instead of a username to login. 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 This used to be the default Evennia login before replacing it with a
more standard username + password system (having to supply an email 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 # 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 This contrib adds the ability to script with Python in-game. It allows trusted
(or other trusted builders) to dynamically add features to individual objects. staff/builders to dynamically add features and triggers to individual objects
Using custom Python set in-game, every immortal or privileged users could have a without needing to do it in external Python modules. Using custom Python in-game,
specific room, exit, character, object or something else behave differently from specific rooms, exits, characters, objects etc can be made to behave differently from
its "cousins". For these familiar with the use of softcode in MU`*`, like SMAUG its "cousins". This is similar to how softcode works for MU or MudProgs for DIKU.
MudProgs, the ability to add arbitrary behavior to individual objects is a step Keep in mind, however, that allowing Python in-game comes with _severe_
toward freedom. Keep in mind, however, the warning below, and read it carefully security concerns (you must trust your builders deeply), so read the warnings in
before the rest of the documentation. this module carefully before continuing.
## A WARNING REGARDING SECURITY ## 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 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. 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 ## Basic structure and vocabulary
- At the basis of the in-game Python system are **events**. An **event** - 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. This is the quick summary. Scroll down for more detailed help on each step.
1. Launch the main script (important!): 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): 2. Set the permissions (optional):
- `EVENTS_WITH_VALIDATION`: a group that can edit callbacks, but will need approval (default to - `EVENTS_WITH_VALIDATION`: a group that can edit callbacks, but will need approval (default to
`None`). `None`).
@ -176,7 +189,7 @@ the `EVENTS_WITH_VALIDATION` setting will be able to call the command (with diff
### Adding the `call` command ### Adding the `call` command
You also have to add the `@call` command to your Character CmdSet. This command allows your users 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: this:
```python ```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: from going through the "north" exit of this room:
``` ```
@call north call north
+------------------+---------+-----------------------------------------------+ +------------------+---------+-----------------------------------------------+
| Event name | Number | Description | | Event name | Number | Description |
+~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ +~~~~~~~~~~~~~~~~~~+~~~~~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

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

@ -1,10 +1,10 @@
# Menu-based login system # 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 This changes the Evennia login to ask for the account name and password as a series
sequence instead of requiring you to enter both at once. It uses EvMenu under of questions instead of requiring you to enter both at once. It uses Evennia's
the hood. menu system `EvMenu` under the hood.
## Installation ## Installation

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

@ -1,22 +1,24 @@
# Legacy Comms-commands # Legacy Comms-commands
Contribution - Griatch 2021 Contribution by Griatch 2021
In Evennia 1.0, the old Channel commands (originally inspired by MUX) were In Evennia 1.0+, the old Channel commands (originally inspired by MUX) were
replaced by the single `channel` command that performs all these function. replaced by the single `channel` command that performs all these functions.
That command is still required to talk on channels. This contrib (extracted This contrib (extracted from Evennia 0.9.5) breaks out the functionality into
from Evennia 0.9.5) reuses the channel-management of the base Channel command separate Commands more familiar to MU* users. This is just for show though, the
but breaks out its functionality into separate Commands with MUX-familiar names. main `channel` command is still called under the hood.
- `allcom` - `channel/all` and `channel` | Contrib syntax | Default `channel` syntax |
- `addcom` - `channel/alias`, `channel/sub` and `channel/unmute` | -------------- | --------------------------------------------------------- |
- `delcom` - `channel/unalias`, `alias/unsub` and `channel/mute` | `allcom` | `channel/all` and `channel` |
- `cboot` - `channel/boot` (`channel/ban` and `/unban` not supported) | `addcom` | `channel/alias`, `channel/sub` and `channel/unmute` |
- `cwho` - `channel/who` | `delcom` | `channel/unalias`, `alias/unsub` and `channel/mute` |
- `ccreate` - `channel/create` | `cboot` | `channel/boot` (`channel/ban` and `/unban` not supported) |
- `cdestroy` - `channel/destroy` | `cwho` | `channel/who` |
- `clock` - `channel/lock` | `ccreate` | `channel/create` |
- `cdesc` - `channel/desc` | `cdestroy` | `channel/destroy` |
| `clock` | `channel/lock` |
| `cdesc` | `channel/desc` |
## Installation ## Installation

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

@ -1,12 +1,12 @@
# Unix-like Command style parent # 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 This module contains a command class with an alternate syntax parser implementing
in-game, using --options, positional arguments and stuff like -n 10 etc Unix-style command syntax in-game. This means `--options`, positional arguments
similarly to a unix command. It might not the best syntax for the average player 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 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. library under the hood.
## Installation ## Installation

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

@ -1,16 +1,18 @@
# EvscapeRoom # EvscapeRoom
Evennia contrib - Griatch 2019 Contribution by Griatch, 2019
This 'Evennia escaperoom game engine' was created for the MUD Coders Guild game A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
Jam, April 14-May 15 2019. The theme for the jam was "One Room". This contains the spawn and join puzzle rooms that track their state independently. Any number of players
utilities and base classes and an empty example room. 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 The original code for the contest is found at
https://github.com/Griatch/evscaperoom but the version on the public Evennia 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 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 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` at https://demo.evennia.com - just connect to the server and write `evscaperoom`
in the first room to start! in the first room to start!

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

@ -1,18 +1,14 @@
# Barter system # Barter system
Evennia contribution - Griatch 2012 Contribution by Griatch, 2012
This implements a full barter system - a way for players to safely This implements a full barter system - a way for players to safely
trade items between each other using code rather than simple free-form trade items between each other in code rather than simple `give/get`
talking. The advantage of this is increased buy/sell safety but it commands. This increases both safety (at no time will one player have
also streamlines the process and makes it faster when doing many both goods and payment in-hand) and speed, since agreed goods will
transactions (since goods are automatically exchanged once both be moved automatically). By just replacing one side with coin objects,
agree). (or a mix of coins and goods), this also works fine for regular money
transactions.
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).
## Installation ## Installation

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

@ -1,9 +1,9 @@
# Clothing # Clothing
Evennia contribution - Tim Ashley Jenkins 2017 Contribution by Tim Ashley Jenkins, 2017
Provides a typeclass and commands for wearable clothing, Provides a typeclass and commands for wearable clothing. These
which is appended to a character's description when worn. look of these clothes are appended to the character's description when worn.
Clothing items, when worn, are added to the character's description Clothing items, when worn, are added to the character's description
in a list. For example, if wearing the following clothing items: 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 one nice hat
a very pretty dress 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 ## Installation
To install, import this module and have your default character 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 Cooldowns are used modelling rate-limited actions, like how often a
typeclassed Object or Account. A cooldown is a lightweight persistent character can perform a given action; until a certain time has passed their
asynchronous timer that you can query to see if it is ready. 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
Cooldowns are good for modelling rate-limited actions, like how often a asynchronous timer that you can query to see if a certain time has yet passed.
character can perform a given command.
Cooldowns are completely asynchronous and must be queried to know their 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 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 # 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 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 The included `craft` command works like this:
'flour', 'salt', 'yeast' and 'water' to create 'bread' using the 'bread recipe'.
A recipe does not have to use tools, like 'snow' + 'snowball-recipe' becomes craft <recipe> [from <ingredient>,...] [using <tool>, ...]
'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.
The system is generic enough to be used also for adventure-like puzzles, like ## Examples
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' ... 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 ## Intallation and Usage
@ -29,18 +50,30 @@ available to you:
craft <recipe> [from <ingredient>,...] [using <tool>, ...] 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'] CRAFT_RECIPE_MODULES = ['world.recipes']
All top-level classes in these modules (whose name does not start with `_`) All top-level classes in these modules (whose name does not start with `_`) will
will be parsed by Evennia as recipes to make available to the crafting system. be parsed by Evennia as recipes to make available to the crafting system. Using
Using the above example, create `mygame/world/recipes.py` and add your recipies the above example, create `mygame/world/recipes.py` and add your recipies in
in there: there:
A quick example (read on for more details):
```python ```python
@ -69,34 +102,199 @@ class RecipeBread(CraftingRecipe):
def pre_craft(self, **kwargs): def pre_craft(self, **kwargs):
# validates inputs etc. Raise `CraftingValidationError` if fails # validates inputs etc. Raise `CraftingValidationError` if fails
def craft(self, **kwargs): def do_craft(self, **kwargs):
# performs the craft - but it can still fail (check skills etc here) # 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): def post_craft(self, result, **kwargs):
# any post-crafting effects. Always called, even if crafting failed (be # any post-crafting effects. Always called, even if do_craft failed (the
# result would be None then) # result would be None then)
``` ```
## Technical ## Adding new recipes
The Recipe is a class that specifies the consumables, tools and output along A *recipe* is a class inheriting from
with various methods (that you can override) to do the the validation of inputs `evennia.contrib.crafting.crafting.CraftingRecipe`. This class implements the
and perform the crafting itself. 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" For the `craft` command to find your custom recipes, you need to tell Evennia
and "crafting_tool" tag-categories respectively). Providing a set of objects where they are. Add a new line to your `mygame/server/conf/settings.py` file,
matching these tags are required for the crafting to be done. The use of tags with a list to any new modules with recipe classes.
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!
The output is given by a set of prototype-dicts. If the input is correct and ```python
other checks are passed (such as crafting skill, for example), these prototypes CRAFT_RECIPE_MODULES = ["world.myrecipes"]
will be used to generate the new object(s) being crafted. ```
(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 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 # Gendersub
Contrib - Griatch 2015 Contribution by Griatch 2015
This is a simple gender-aware Character class for allowing users to This is a simple gender-aware Character class for allowing users to
insert custom markers in their text to indicate gender-aware 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 # 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 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: 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). 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 command ONLY available when puppeting a character. Mails will be sent to other
Characters only and will not be available when OOC. Characters only and will not be available when OOC.
- If adding *both* commands to their respective cmdsets, you'll get two separate - 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 # Evennia Multidescer
Contrib - Griatch 2016 Contribution by Griatch 2016
A "multidescer" is a concept from the MUSH world. It allows for A "multidescer" is a concept from the MUSH world. It allows for
creating, managing and switching between multiple character creating, managing and switching between multiple character
descriptions. This multidescer will not require any changes to the descriptions and is a way for quickly managing your look (such as when
Character class, rather it will use the `multidescs` Attribute (a changing clothes) in more free-form roleplaying systems. This will also
list) and create it if it does not exist. work well together with the `rpsystem` contrib.
This contrib also works well together with the rpsystem contrib (which This multidescer will not
also adds the short descriptions and the `sdesc` command). 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 ## Installation

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

@ -1,18 +1,21 @@
# Puzzles System # 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) Intended for adventure-game style combination puzzles, such as combining fruits
to produce new objects. 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. a new set of objects (aka results) are automatically created.
## Installation ## 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') 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 # 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 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 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 # 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 This extends the normal `Room` typeclass to allow its description to change
by an extended `Look` command and an extended `desc` command, also with time-of-day and/or season. It also adds 'details' for the player to look at
in this module. 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: ## Installation/testing:

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

@ -1,8 +1,8 @@
# Map Builder # 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: This is a command which takes two inputs:

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

@ -1,13 +1,15 @@
# SimpleDoor # SimpleDoor
Contribution - Griatch 2016 Contribution by Griatch, 2016
A simple two-way exit that represents a door that can be opened and 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 closed from both sides. Can easily be expanded to make it lockable,
etc. Note that the simpledoor is based on Evennia locks, so it will destroyable etc.
not work for a superuser (which bypasses all locks) - the superuser
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 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. non-superuser account.
## Installation: ## Installation:

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

@ -1,10 +1,10 @@
# Slow Exit # Slow Exit
Contribution - Griatch 2014 Contribution by Griatch 2014
This is an example of an Exit-type that delays its traversal. This simulates An example of an Exit-type that delays its traversal. This simulates
slow movement, common in many different types of games. The contrib also slow movement, common in many games. The contrib also
contains two commands, `CmdSetSpeed` and CmdStop for changing the movement speed contains two commands, `setspeed` and `stop` for changing the movement speed
and abort an ongoing traversal, respectively. and abort an ongoing traversal, respectively.
## Installation: ## Installation:

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

@ -1,10 +1,10 @@
# Wilderness system # Wilderness system
Evennia contrib - titeuf87 2017 Contribution by titeuf87, 2017
This contrib provides a wilderness map without actually creating a large number This contrib provides a wilderness map without actually creating a large number
of rooms - as you move, your room is instead updated with different of rooms - as you move, you instead end up back in the same room but its description
descriptions. This means you can make huge areas with little database use as changes. This means you can make huge areas with little database use as
long as the rooms are relatively similar (name/desc changing). long as the rooms are relatively similar (name/desc changing).
## Installation ## 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 # 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: # Installation:

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

@ -1,11 +1,11 @@
# Health Bar # Health Bar
Contrib - Tim Ashley Jenkins 2017 Contribution by Tim Ashley Jenkins, 2017
The function provided in this module lets you easily display visual The function provided in this module lets you easily display visual
bars or meters - "health bar" is merely the most obvious use for this, bars or meters as a colorful bar instead of just a number. A "health bar"
though these bars are highly customizable and can be used for any sort is merely the most obvious use for this, but the bar is highly customizable
of appropriate data besides player health. 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, Today's players may be more used to seeing statistics like health,
stamina, magic, and etc. displayed as bars rather than bare numerical 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 base system for Evennia
Roleplaying emotes/sdescs - Griatch, 2015 Contribution by Griatch, 2015
Language/whisper emotes - 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 ## Roleplaying emotes

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

@ -1,12 +1,10 @@
# Traits # Traits
Whitenoise 2014, Ainneve contributors, Contribution by Griatch 2020, based on code by Whitenoise and Ainneve contribs, 2014
Griatch 2020
A `Trait` represents a modifiable property on (usually) a Character. They can A `Trait` represents a modifiable property on (usually) a Character. They can
be used to represent everything from attributes (str, agi etc) to skills 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 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 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 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 # Batch processor examples
Contibution - Griatch 2012 Contibution by Griatch, 2012
The batch processor is used for generating in-game content from one or more Simple examples for the batch-processor. The batch processor is used for generating
static files. Files can be stored with version control and then 'applied' in-game content from one or more static files. Files can be stored with version
to the game to create content. control and then 'applied' to the game to create content.
There are two batch processor types: There are two batch processor types:

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

@ -1,9 +1,9 @@
# Script example # Script example
Griatch - 2012 Contribution by Griatch, 2012
Example script for testing. This adds a simple timer that has your 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) To test, use (in game)

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

@ -1,8 +1,8 @@
# TutorialMirror # 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 the description of the object looking at it
- echoes back whatever is being sent to its .msg - to the - 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 # Red Button example
Griatch - 2011 Contribution by Griatch, 2011
This is a more advanced example object with its own functionality (commands) A red button that you can press to have an effect. This is a more advanced example
on it. object with its own functionality and state tracking.
Create the button with Create the button with

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

@ -1,9 +1,9 @@
# Talkative NPC example # 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 This is an example of a static NPC object capable of holding a simple menu-driven
conversation. It's just meant as an example. conversation. Suitable for example as a quest giver or merchant.
## Installation ## Installation

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

@ -1,13 +1,14 @@
# Evennia Tutorial World # 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 Think of it as a sort of single-player adventure rather than a
full-fledged multi-player game world. The various rooms and objects 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 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 The tutorial world also includes a game tutor menu example, exemplifying
Evmenu. Evmenu.

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

@ -1,15 +1,15 @@
# Input/Output Auditing # 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 Utility that taps and intercepts all data sent to/from clients and the
server and passes it to a callback of your choosing. 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 Note that this should be used with care since it can obviously be abused. All
but obviously can be abused. All data is recorded in cleartext. Please data is recorded in cleartext. Please be ethical, and if you are unwilling to
be ethical, and if you are unwilling to properly deal with the implications of properly deal with the implications of recording user passwords or private
recording user passwords or private communications, please do not enable communications, please do not enable this module.
this module.
Some checks have been implemented to protect the privacy of users. 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 # 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 This module contains a function that generates an `EvMenu` for you - this
menu presents the player with a fillable form, with fields that can be filled menu presents the player with a form of fields that can be filled
out in any order. Each field's value can be verified, with the function out in any order (e.g. for character generation or building). Each field's value can
allowing easy checks for text and integer input, minimum and maximum values / be verified, with the function allowing easy checks for text and integer input,
character lengths, or can even be verified by a custom function. Once the form minimum and maximum values / character lengths, or can even be verified by a custom
is submitted, the form's data is submitted as a dictionary to any callable of function. Once the form is submitted, the form's data is submitted as a dictionary
your choice. to any callable of your choice.
## Usage
The function that initializes the fillable form menu is fairly simple, and 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) 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 # 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 with specific criteria. You could, for instance, use it to generate
phone numbers, license plate numbers, validation codes, non-sensivite phone numbers, license plate numbers, validation codes, in-game security
passwords and so on. The strings generated by the generator will be passwords and so on. The strings generated will be stored and won't be repeated.
stored and won't be available again in order to avoid repetition.
## Usage Example
Here's a very simple example: Here's a very simple example:
```python ```python

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

@ -1,14 +1,16 @@
# Easy menu selection tree # 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 This utility allows you to create and initialize an entire branching EvMenu
instance with nothing but a multi-line string passed to one function. instance from a multi-line string passed to one function.
EvMenu is incredibly powerful and flexible, but using it for simple menus > Note: Since the time this contrib was created, EvMenu itself got its own templating
can often be fairly cumbersome - a simple menu that can branch into five > language that has more features and is not compatible with the style used in
categories would require six nodes, each with options represented as a list > this contrib. Both can still be used in parallel.
of dictionaries.
`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 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 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. to store in Attributes on the generated scheduling Script.
Returns: Returns:
script (Script): The created Script handling the sceduling. Script: The created Script handling the scheduling.
Examples: Examples:
:: ::