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

Make wiki compile fully into static site

Browse source
This commit is contained in:
Griatch 2020-06-07 02:35:06 +02:00
parent 13df0adebf
commit d072950cc5
51 changed files with 343 additions and 511 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/Makefile
View file

@ -83,6 +83,11 @@ clean:
@git clean -f -d docs/
@echo "Cleaned old build dir and leftover files."
# TODO remove once done with migration
copy:
@cd pylib && python copy_from_wiki.py && cd ..
make quick
quick:
make _check-env
make _quick-build $(FILES)

27
docs/pylib/copy_from_wiki.py
View file

@ -16,14 +16,11 @@ We also need to build the toc-tree and should do so automatically for now.
import glob
import re
_RE_MD_LINK = re.compile(r"\[(?P<txt>[\w -]+)\]\((?P<url>.+?)\)", re.I + re.S + re.U)
_RE_MD_LINK = re.compile(r"\[(?P<txt>[\w -\[\]]+?)\]\((?P<url>.+?)\)", re.I + re.S + re.U)
_IGNORE_FILES = (
"_Sidebar.md",
# "Evennia-for-MUSH-Users.md",
# "Installing-on-Android.md",
# "Nicks.md",
# "Spawner-and-Prototypes.md"
"Wiki-Index.md"
)
_WIKI_DIR = "../../../evennia.wiki/"
@ -35,7 +32,8 @@ _FILENAMESLOW = [path.lower() for path in _FILENAMES]
_OUTDIR = "../source/"
_OLD_WIKI_URL = "https://github.com/evennia/evennia/wiki/"
_OLD_WIKI_URL_LEN = len(_OLD_WIKI_URL)
_CODE_PREFIX = "code:"
_CODE_PREFIX = "github:"
_API_PREFIX = "api:"
_CUSTOM_LINK_REMAP = {
"CmdSets": "Command-Sets",
@ -55,12 +53,13 @@ _CUSTOM_LINK_REMAP = {
"Using-Mux-as-a-Standard": "Using-MUX-as-a-Standard",
"Building-quickstart": "Building-Quickstart",
"Adding-Object-Typeclass-tutorial": "Adding-Object-Typeclass-Tutorial",
"EvTable": _API_PREFIX + "evennia.utils#module-evennia.utils.evtable",
}
# absolute links (mainly github links) that should not be converted. This
# should be given without any #anchor.
_ABSOLUTE_LINK_SKIP = (
"https://github.com/evennia/evennia/wiki/feature-request"
# "https://github.com/evennia/evennia/wiki/feature-request",
)
# specific references tokens that should be ignored. Should be given
@ -73,16 +72,11 @@ _REF_SKIP = (
"[EvTable](EvTable)",
"[styled](OptionStyles)",
"[Inputfunc](Inputfunc)",
"[API](evennia)",
"[online documentation wiki](index)",
"[online documentation](index)",
"[Home](index)",
"[Accounts](Account)",
"[Session](Session)",
"[Inputfuncs](Inputfunc)",
# "[Nicks](Nicks)",
# "[Nick](Nicks)",
)
@ -96,7 +90,7 @@ def _sub_link(match):
# if not txt:
# # the 'comment' is not supported by Mkdocs
# return ""
# url = url if url.endswith(".md") or url.startswith("http") else url + ".md"
print(f" [{txt}]({url})")
url = _CUSTOM_LINK_REMAP.get(url, url)
@ -106,6 +100,10 @@ def _sub_link(match):
url += (("#" + anchor[0]) if anchor else "")
return f"[{txt}]({url})"
if url.startswith("evennia"):
print(f" Convert evennia url {url} -> {_CODE_PREFIX + url}")
url = _API_PREFIX + url
if url.startswith(_OLD_WIKI_URL):
# old wiki is an url on the form https://<wikiurl>/wiki/TextTags#header
# we don't refer to the old wiki but use internal mapping.
@ -175,8 +173,6 @@ def create_toctree(files):
def convert_links(files, outdir):
global _CURRENT_TITLE
print(_INFILES)
for inpath in files:
outfile = inpath.rsplit('/', 1)[-1]
@ -201,4 +197,3 @@ if __name__ == "__main__":
create_toctree(_INFILES)
convert_links(_INFILES, _OUTDIR)

3
docs/source/API-refactoring.md
View file

@ -28,6 +28,3 @@ def get(self, key=None, default=None, category=None, return_obj=False,
default_access=True, return_list=False):
```
Many classes have methods requiring lengthy positional argument lists, which are tedious and error-prone to extend and override especially in cases where not all arguments are even required. It would be useful if arguments were reserved for required inputs and anything else relegated to kwargs for easier passthrough on extension.
---

2
docs/source/Accounts.md
View file

@ -83,7 +83,7 @@ Account also has the following custom properties:
- `obj` - an alias for `character`.
- `name` - an alias for `user.username`
- `sessions` - an instance of
[ObjectSessionHandler](code:evennia.objects.objects#objectsessionhandler)
[ObjectSessionHandler](github:evennia.objects.objects#objectsessionhandler)
managing all connected Sessions (physical connections) this object listens to (Note: In older
versions of Evennia, this was a list). The so-called `session-id` (used in many places) is found as
a property `sessid` on each Session instance.

2
docs/source/Administrative-Docs.md
View file

@ -12,7 +12,7 @@ The following pages are aimed at game administrators -- the higher-ups that poss
- [Resetting your database](Updating-Your-Game#resetting-your-database)
- [Making your game available online](Online-Setup)
- [Hosting options](Online-Setup#hosting-options)
- [Securing your server with SSL/Let's Encrypt](https://github.com/evennia/evennia/wiki/Online-Setup#ssl)
- [Securing your server with SSL/Let's Encrypt](Online-Setup#ssl)
- [Listing your game](Evennia-Game-Index) at the online [Evennia game index](http://games.evennia.com)
### Customizing the server

79
docs/source/Apache-Config.md
View file

@ -15,24 +15,21 @@ Note that the Apache instructions below might be outdated. If something is not w
use Evennia with a different server, please let us know. Also, if there is a particular Linux distro
you would like covered, please let us know.
## mod_wsgi Setup
## `mod_wsgi` Setup
### Install mod_wsgi
### Install `mod_wsgi`
#### Fedora/RHEL
Apache HTTP Server and mod_wsgi are available in the standard package repositories for Fedora and RHEL:
```
# dnf install httpd mod_wsgi
or
# yum install httpd mod_wsgi
```
#### Ubuntu/Debian
Apache HTTP Server and mod_wsgi are available in the standard package repositories for Ubuntu and Debian:
```
# apt-get update
# apt-get install apache2 libapache2-mod-wsgi
```
- *Fedora/RHEL* - Apache HTTP Server and `mod_wsgi` are available in the standard package repositories for Fedora and RHEL:
```
$ dnf install httpd mod_wsgi
or
$ yum install httpd mod_wsgi
```
- *Ubuntu/Debian* - Apache HTTP Server and `mod_wsgi` are available in the standard package repositories for Ubuntu and Debian:
```
$ apt-get update
$ apt-get install apache2 libapache2-mod-wsgi
```
### Copy and modify the VHOST
@ -46,15 +43,14 @@ Read the comments and change the paths to point to the appropriate locations wit
You'll then want to reload or restart apache2 after changing the configurations.
#### Fedora/RHEL/Ubuntu
```
# systemctl restart httpd
```
#### Ubuntu/Debian
```
# systemctl restart apache2
```
- *Fedora/RHEL/Ubuntu*
```
$ systemctl restart httpd
```
- *Ubuntu/Debian*
```
$ systemctl restart apache2
```
### Enjoy
@ -96,28 +92,21 @@ Below are steps on running Evennia using a front-end proxy (Apache HTTP), `mod_p
### Install `mod_ssl`
#### Fedora/RHEL
Apache HTTP Server and `mod_ssl` are available in the standard package repositories for Fedora and RHEL:
```
# dnf install httpd mod_ssl
or
# yum install httpd mod_ssl
```
#### Ubuntu/Debian
Apache HTTP Server and `mod_sslj`kl are installed together in the `apache2` package and available in the
- *Fedora/RHEL* - Apache HTTP Server and `mod_ssl` are available in the standard package repositories for Fedora and RHEL:
```
$ dnf install httpd mod_ssl
or
$ yum install httpd mod_ssl
```
- *Ubuntu/Debian* - Apache HTTP Server and `mod_sslj`kl are installed together in the `apache2` package and available in the
standard package repositories for Ubuntu and Debian. `mod_ssl` needs to be enabled after installation:
```
$ apt-get update
$ apt-get install apache2
$ a2enmod ssl
```
# apt-get update
# apt-get install apache2
# a2enmod ssl
```
```
### TLS proxy+websocket configuration

2
docs/source/Bootstrap-Components-and-Utilities.md
View file

@ -60,4 +60,4 @@ Bootstrap provides classes to easily add responsive margin and padding. Most of
```
### Forms
[Forms](https://getbootstrap.com/docs/4.0/components/forms/) are highly customizable with Bootstrap. For a more in-depth look at how to use forms and their styles in your own Evennia site, please read over [the web character gen tutorial.](https://github.com/evennia/evennia/wiki/Web-Character-Generation)
[Forms](https://getbootstrap.com/docs/4.0/components/forms/) are highly customizable with Bootstrap. For a more in-depth look at how to use forms and their styles in your own Evennia site, please read over [the web character gen tutorial.](Web-Character-Generation)

3
docs/source/Building-a-mech-tutorial.md
View file

@ -73,7 +73,7 @@ class CmdShoot(Command):
if not self.args:
# no argument given to command - shoot in the air
message = “BOOM! The mech fires its gun in the air!”
message = "BOOM! The mech fires its gun in the air!"
location.msg_contents(message)
return
@ -86,6 +86,7 @@ class CmdShoot(Command):
class CmdLaunch(Command):
# make your own 'launch'-command here as an exercise!
# (it's very similar to the 'shoot' command above).
```
This is saved as a normal Python module (let’s call it `mechcommands.py`), in a place Evennia looks for such modules (`mygame/commands/`). This command will trigger when the player gives the command “shoot”, “fire,” or even “fire!” with an exclamation mark. The mech can shoot in the air or at a target if you give one. In a real game the gun would probably be given a chance to hit and give damage to the target, but this is enough for now.

16
docs/source/Choosing-An-SQL-Server.md
View file

@ -62,15 +62,17 @@ On the psql command line:
CREATE USER evennia WITH PASSWORD 'somepassword';
CREATE DATABASE evennia;
# Postgres-specific optimizations
# https://docs.djangoproject.com/en/dev/ref/databases/#optimizing-postgresql-s-configuration
-- Postgres-specific optimizations
-- https://docs.djangoproject.com/en/dev/ref/databases/#optimizing-postgresql-s-configuration
ALTER ROLE evennia SET client_encoding TO 'utf8';
ALTER ROLE evennia SET default_transaction_isolation TO 'read committed';
ALTER ROLE evennia SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE evennia TO evennia;
\l # list all databases and permissions
\q # exit
-- Other useful commands:
-- \l (list all databases and permissions)
-- \q (exit)
```
[Here](https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546) is a cheat-sheet for psql commands.
@ -131,10 +133,10 @@ Inside the database client interface:
```sql
CREATE USER 'evennia'@'localhost' IDENTIFIED BY 'somepassword';
CREATE DATABASE evennia;
ALTER DATABASE `evennia` CHARACTER SET utf8; # note that it's `evennia` not 'evennia'!
ALTER DATABASE `evennia` CHARACTER SET utf8; -- note that it's `evennia` with back-ticks, not quotes!
GRANT ALL PRIVILEGES ON evennia.* TO 'evennia'@'localhost';
FLUSH PRIVILEGES;
exit
-- use 'exit' to quit client
```
[Here](https://gist.github.com/hofmannsven/9164408) is a mysql command cheat sheet.
@ -177,4 +179,4 @@ With the database setup you should now be able to start start Evennia normally w
## Others
No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for [MS SQL](http://code.google.com/p/django-mssql/) and possibly a few others. If you try other databases out, consider expanding this page with instructions.
No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for [MS SQL](http://code.google.com/p/django-mssql/) and possibly a few others. If you try other databases out, consider expanding this page with instructions.

16
docs/source/Client-Support-Grid.md
View file

@ -61,19 +61,23 @@ Name | Version | Comments
### Issue: Telnet NOP displays as spurious character.
#### Known Clients
* [BlowTorch][16]([16](Andr))
* [Mukluk][17]([17](Andr))
Known clients:
* [BlowTorch][16](Andr)
* [Mukluk][17](Andr)
Workaround:
#### Workarounds
* Set the command in game to `@option NOPKEEPALIVE=off` for the session, or use the `/save` parameter to disable it for that Evennian account permanently.
* Client-side: Set a gag-type trigger on the NOP character to make it invisible to the client.
### Issue: Won't send blank line on Enter key press.
#### Known Clients
Known clients:
* [Potato][8]
#### Workaround
Workaround:
* Press Control Enter, then Enter key again to send blank line.

22
docs/source/Coding-FAQ.md
View file

@ -5,17 +5,17 @@
## Table of Contents
- [Removing default commands](#removing-default-commands)
- [Preventing character from moving based on a condition](#preventing-character-from-moving-based-on-a-condition)
- [Reference initiating object in an EvMenu command](#reference-initiating-object-in-an-evmenu-command)
- [Adding color to default Evennia Channels](#adding-color-to-default-evennia-channels)
- [Selectively turn off commands in a room](#selectively-turn-off-commands-in-a-room)
- [Select Command based on a condition](#select-command-based-on-a-condition)
- [Automatically updating code when reloading](#automatically-updating-code-when-reloading)
- [Changing all exit messages](#changing-all-exit-messages)
- [Add parsing with the "to" delimiter](#add-parsing-with-the-to-delimiter)
- [Store last used session IP address](#store-last-used-session-ip-address)
- [Use wide characters with EvTable](#non-latin-characters-in-evtable)
- [Removing default commands](Coding-FAQ#removing-default-commands)
- [Preventing character from moving based on a condition](Coding-FAQ#preventing-character-from-moving-based-on-a-condition)
- [Reference initiating object in an EvMenu command](Coding-FAQ#reference-initiating-object-in-an-evmenu-command)
- [Adding color to default Evennia Channels](Coding-FAQ#adding-color-to-default-evennia-channels)
- [Selectively turn off commands in a room](Coding-FAQ#selectively-turn-off-commands-in-a-room)
- [Select Command based on a condition](Coding-FAQ#select-command-based-on-a-condition)
- [Automatically updating code when reloading](Coding-FAQ#automatically-updating-code-when-reloading)
- [Changing all exit messages](Coding-FAQ#changing-all-exit-messages)
- [Add parsing with the "to" delimiter](Coding-FAQ#add-parsing-with-the-to-delimiter)
- [Store last used session IP address](Coding-FAQ#store-last-used-session-ip-address)
- [Use wide characters with EvTable](Coding-FAQ#non-latin-characters-in-evtable)
## Removing default commands
**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](Commands) from the Character [Command Set](Command-Sets)?

8
docs/source/Coding-Utils.md
View file

@ -112,7 +112,7 @@ gametime.reset_gametime()
The setting `TIME_FACTOR` determines how fast/slow in-game time runs compared to the real world. The setting `TIME_GAME_EPOCH` sets the starting game epoch (in seconds). The functions from the `gametime` module all return their times in seconds. You can convert this to whatever units of time you desire for your game. You can use the `@time` command to view the server time info.
You can also *schedule* things to happen at specific in-game times using the [gametime.schedule](https://github.com/evennia/evennia/wiki/evennia.utils.gametime#schedule) function:
You can also *schedule* things to happen at specific in-game times using the [gametime.schedule](github:evennia.utils.gametime#schedule) function:
```python
import evennia
@ -223,14 +223,14 @@ never raise a traceback but instead echo errors through logging. See
[here](Text-Encodings) for more info.
### Ansi Coloring Tools
- [evennia.ansi](../wiki/evennia.utils.ansi)
- [evennia.ansi](api:evennia.utils.ansi)
## Display utilities
### Making ascii tables
The [EvTable](code:evennia.utils.evtable#evtable) class (`evennia/utils/evtable.py`) can be used to create correctly formatted text tables. There is also [EvForm](code:evennia.utils.evform#evform) (`evennia/utils/evform.py`). This reads a fixed-format text template from a file in order to create any level of sophisticated ascii layout. Both evtable and evform have lots of options and inputs so see the header of each module for help.
The [EvTable](github:evennia.utils.evtable#evtable) class (`evennia/utils/evtable.py`) can be used to create correctly formatted text tables. There is also [EvForm](github:evennia.utils.evform#evform) (`evennia/utils/evform.py`). This reads a fixed-format text template from a file in order to create any level of sophisticated ascii layout. Both evtable and evform have lots of options and inputs so see the header of each module for help.
The third-party [PrettyTable](https://code.google.com/p/prettytable/) module is also included in Evennia. PrettyTable is considered deprecated in favor of EvTable since PrettyTable cannot handle ANSI colour. PrettyTable can be found in `evennia/utils/prettytable/`. See its homepage above for instructions.
### Menus
- [evennia.EvMenu](https://github.com/evennia/evennia/wiki/evennia.utils.evmenu#evmenu)
- [evennia.EvMenu](github:evennia.utils.evmenu#evmenu)

8
docs/source/Command-Sets.md
View file

@ -15,7 +15,7 @@ If you want a quick start into defining your first commands and using them with
## Defining Command Sets
A CmdSet is, as most things in Evennia, defined as a Python class inheriting from the correct parent (`evennia.CmdSet`, which is a shortcut to `evennia.commands.cmdset.CmdSet`). The CmdSet class only needs to define one method, called `at_cmdset_creation()`. All other class parameters are optional, but are used for more advanced set manipulation and coding (see the [merge rules](#merge-rules) section).
A CmdSet is, as most things in Evennia, defined as a Python class inheriting from the correct parent (`evennia.CmdSet`, which is a shortcut to `evennia.commands.cmdset.CmdSet`). The CmdSet class only needs to define one method, called `at_cmdset_creation()`. All other class parameters are optional, but are used for more advanced set manipulation and coding (see the [merge rules](Command-Sets#merge-rules) section).
```python
# file mygame/commands/mycmdset.py
@ -94,14 +94,14 @@ There are several extra flags that you can set on CmdSets in order to modify how
- `key` (string) - an identifier for the cmdset. This is optional, but should be unique. It is used for display in lists, but also to identify special merging behaviours using the `key_mergetype` dictionary below.
- `mergetype` (string) - allows for one of the following string values: "*Union*", "*Intersect*", "*Replace*", or "*Remove*".
- `priority` (int) - This defines the merge order of the merge stack - cmdsets will merge in rising order of priority with the highest priority set merging last. During a merger, the commands from the set with the higher priority will have precedence (just what happens depends on the [merge type](#adding-and-merging-command-sets)). If priority is identical, the order in the merge stack determines preference. The priority value must be greater or equal to `-100`. Most in-game sets should usually have priorities between `0` and `100`. Evennia default sets have priorities as follows (these can be changed if you want a different distribution):
- `priority` (int) - This defines the merge order of the merge stack - cmdsets will merge in rising order of priority with the highest priority set merging last. During a merger, the commands from the set with the higher priority will have precedence (just what happens depends on the [merge type](Command-Sets#adding-and-merging-command-sets)). If priority is identical, the order in the merge stack determines preference. The priority value must be greater or equal to `-100`. Most in-game sets should usually have priorities between `0` and `100`. Evennia default sets have priorities as follows (these can be changed if you want a different distribution):
- EmptySet: `-101` (should be lower than all other sets)
- SessionCmdSet: `-20`
- AccountCmdSet: `-10`
- CharacterCmdSet: `0`
- ExitCmdSet: ` 101` (generally should always be available)
- ChannelCmdSet: `101` (should usually always be available) - since exits never accept arguments, there is no collision between exits named the same as a channel even though the commands "collide".
- `key_mergetype` (dict) - a dict of `key:mergetype` pairs. This allows this cmdset to merge differently with certain named cmdsets. If the cmdset to merge with has a `key` matching an entry in `key_mergetype`, it will not be merged according to the setting in `mergetype` but according to the mode in this dict. Please note that this is more complex than it may seem due to the [merge order](#adding-and-merging-command-sets) of command sets. Please review that section before using `key_mergetype`.
- `key_mergetype` (dict) - a dict of `key:mergetype` pairs. This allows this cmdset to merge differently with certain named cmdsets. If the cmdset to merge with has a `key` matching an entry in `key_mergetype`, it will not be merged according to the setting in `mergetype` but according to the mode in this dict. Please note that this is more complex than it may seem due to the [merge order](Command-Sets#adding-and-merging-command-sets) of command sets. Please review that section before using `key_mergetype`.
- `duplicates` (bool/None default `None`) - this determines what happens when merging same-priority cmdsets containing same-key commands together. The`dupicate` option will *only* apply when merging the cmdset with this option onto one other cmdset with the same priority. The resulting cmdset will *not* retain this `duplicate` setting.
- `None` (default): No duplicates are allowed and the cmdset being merged "onto" the old one will take precedence. The result will be unique commands. *However*, the system will assume this value to be `True` for cmdsets on Objects, to avoid dangerous clashes. This is usually the safe bet.
- `False`: Like `None` except the system will not auto-assume any value for cmdsets defined on Objects.
@ -118,7 +118,7 @@ There are several extra flags that you can set on CmdSets in order to modify how
## Command Sets Searched
When a user issues a command, it is matched against the [merged](#adding-and-merging-command-sets) command sets available to the player at the moment. Which those are may change at any time (such as when the player walks into the room with the `Window` object described earlier).
When a user issues a command, it is matched against the [merged](Command-Sets#adding-and-merging-command-sets) command sets available to the player at the moment. Which those are may change at any time (such as when the player walks into the room with the `Window` object described earlier).
The currently valid command sets are collected from the following sources:

6
docs/source/Commands.md
View file

@ -91,9 +91,9 @@ Let's say account *Bob* with a character *BigGuy* enters the command *look at sw
used, but they could be used to implement alternate help-display systems.
- `.client_width()` - Shortcut for getting the client's screen-width. Note that not all clients will
truthfully report this value - that case the `settings.DEFAULT_SCREEN_WIDTH` will be returned.
- `.styled_table(*args, **kwargs)` - This returns an [EvTable]([EvTable](EvTable)) [styled]([styled](OptionStyles)) based on the
- `.styled_table(*args, **kwargs)` - This returns an [EvTable](api:evennia.utils#module-evennia.utils.evtable) styled based on the
session calling this command. The args/kwargs are the same as for EvTable, except styling defaults are set.
- `.styled_header`, `_footer`, `separator` - These will produce [styled]([styled](OptionStyles)) decorations for
- `.styled_header`, `_footer`, `separator` - These will produce styled decorations for
display to the user. They are useful for creating listings and forms with colors adjustable per-user.
### Defining your own command classes
@ -105,7 +105,7 @@ Beyond the properties Evennia always assigns to the command at run-time (listed
- `locks` (string) - a [lock definition](Locks), usually on the form `cmd:<lockfuncs>`. Locks is a rather big topic, so until you learn more about locks, stick to giving the lockstring `"cmd:all()"` to make the command available to everyone (if you don't provide a lock string, this will be assigned for you).
- `help_category` (optional string) - setting this helps to structure the auto-help into categories. If none is set, this will be set to *General*.
- `save_for_next` (optional boolean). This defaults to `False`. If `True`, a copy of this command object (along with any changes you have done to it) will be stored by the system and can be accessed by the next command by retrieving `self.caller.ndb.last_cmd`. The next run command will either clear or replace the storage.
- `arg_regex` (optional raw string): Used to force the parser to limit itself and tell it when the command-name ends and arguments begin (such as requiring this to be a space or a /switch). This is done with a regular expression. [See the arg_regex section](#on-arg_regex) for the details.
- `arg_regex` (optional raw string): Used to force the parser to limit itself and tell it when the command-name ends and arguments begin (such as requiring this to be a space or a /switch). This is done with a regular expression. [See the arg_regex section](Commands#on-arg_regex) for the details.
- `auto_help` (optional boolean). Defaults to `True`. This allows for turning off the [auto-help system](Help-System#command-auto-help-system) on a per-command basis. This could be useful if you either want to write your help entries manually or hide the existence of a command from `help`'s generated list.
- `is_exit` (bool) - this marks the command as being used for an in-game exit. This is, by default, set by all Exit objects and you should not need to set it manually unless you make your own Exit system. It is used for optimization and allows the cmdhandler to easily disregard this command when the cmdset has its `no_exits` flag set.
- `is_channel` (bool)- this marks the command as being used for an in-game channel. This is, by default, set by all Channel objects and you should not need to set it manually unless you make your own Channel system. is used for optimization and allows the cmdhandler to easily disregard this command when its cmdset has its `no_channels` flag set.

2
docs/source/Custom-Protocols.md
View file

@ -206,7 +206,7 @@ The message will pass through the system such that the sessionhandler will dig o
### Receiving data
Just because the protocol is there, does not mean Evennia knows what to do with it. An [Inputfunc]([Inputfunc](Inputfunc)) must exist to receive it. In the case of the `text` input exemplified above, Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So handle that you need to simply add a cmdset with commands on your receiving Session (and/or the Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the [Inputfunc]([Inputfunc](Inputfunc)) page for how to do this.
Just because the protocol is there, does not mean Evennia knows what to do with it. An [Inputfunc](Inputfuncs) must exist to receive it. In the case of the `text` input exemplified above, Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So handle that you need to simply add a cmdset with commands on your receiving Session (and/or the Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the [Inputfunc](Inputfuncs) page for how to do this.
These might not be as clear-cut in all protocols, but the principle is there. These four basic
components - however they are accessed - links to the *Portal Session*, which is the actual common

20
docs/source/Default-Command-Help.md
View file

@ -1,8 +1,6 @@
# Default Command Help
[](Auto-generated-listing-of-default-Evennia-commands)
> *This page is auto-generated. Do not modify - your changes will be lost. Report problems to the
[issue tracker](https://github.com/evennia/evennia/issues).*
@ -109,15 +107,15 @@ information about how commands work can be found in the documentation for [Comma
## A-Z by source file
- [account.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#accountpy)
- [admin.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#adminpy)
- [batchprocess.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#batchprocesspy)
- [building.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#buildingpy)
- [comms.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#commspy)
- [general.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#generalpy)
- [help.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#helppy)
- [system.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#systempy)
- [unloggedin.py](https://github.com/evennia/evennia/wiki/Default-Command-Help#unloggedinpy)
- [account.py](Default-Command-Help#accountpy)
- [admin.py](Default-Command-Help#adminpy)
- [batchprocess.py](Default-Command-Help#batchprocesspy)
- [building.py](Default-Command-Help#buildingpy)
- [comms.py](Default-Command-Help#commspy)
- [general.py](Default-Command-Help#generalpy)
- [help.py](Default-Command-Help#helppy)
- [system.py](Default-Command-Help#systempy)
- [unloggedin.py](Default-Command-Help#unloggedinpy)
## Command details

10
docs/source/Developer-Central.md
View file

@ -9,7 +9,7 @@ This page serves as a central nexus for information on using Evennia as well as
- [Evennia Licensing FAQ](Licensing)
- [Contributing to Evennia](Contributing)
- [Code Style Guide](https://github.com/evennia/evennia/blob/master/CODING_STYLE.md) (Important!)
- [Policy for 'MUX-like' default commands](Using-MUX-As-a-Standard)
- [Policy for 'MUX-like' default commands](Using-MUX-as-a-Standard)
- [Setting up a Git environment for coding](Version-Control)
- [Getting started with Travis and Github for continuous integration testing](Using-Travis)
- [Planning your own Evennia game](Game-Planning)
@ -58,7 +58,7 @@ This page serves as a central nexus for information on using Evennia as well as
- [Scripts](Scripts)
- [Global Scripts](Scripts#Global-Scripts)
- [TickerHandler](TickerHandler)
- [utils.delay](https://github.com/evennia/evennia/wiki/Coding-Utils#utilsdelay)
- [utils.delay](Coding-Utils#utilsdelay)
- [MonitorHandler](MonitorHandler)
- [Attributes](Attributes)
- [Nicks](Nicks)
@ -78,13 +78,13 @@ This page serves as a central nexus for information on using Evennia as well as
- [Help System](Help-System)
- [Signals](Signals)
- [General coding utilities](Coding-Utils)
- [Utils in evennia.utils.utils](evennia.utils.utils)
- [Utils in evennia.utils.utils](api:evennia.utils.utils)
- [Game time](Coding-Utils#game-time)
- [Game Menus](EvMenu) (EvMenu)
- [Text paging/scrolling](EvMore) (EvMore)
- [Text Line Editor](EvEditor) (EvEditor)
- [Text Tables](code:evennia.utils.evtable) (EvTable)
- [Text Form generation](code:evennia.utils.evform) (EvForm)
- [Text Tables](github:evennia.utils.evtable) (EvTable)
- [Text Form generation](github:evennia.utils.evform) (EvForm)
- [Spawner and Prototypes](Spawner-and-Prototypes)
- [Inlinefuncs](TextTags#inline-functions)
- [Asynchronous execution](Async-Process)

4
docs/source/Directory-Overview.md
View file

@ -33,10 +33,10 @@ The `bin/` directory holds OS-specific binaries that will be used when installin
- `locale/` - Language files ([i18n](Internationalization)).
- [`locks/`](Locks) - Lock system for restricting access to in-game entities.
- [`objects/`](Objects) - In-game entities (all types of items and Characters).
- [`prototypes/`](https://github.com/evennia/evennia/wiki/Spawner-and-Prototypes) - Object Prototype/spawning system and OLC menu
- [`prototypes/`](Spawner-and-Prototypes) - Object Prototype/spawning system and OLC menu
- [`accounts/`](Accounts) - Out-of-game Session-controlled entities (accounts, bots etc)
- [`scripts/`](Scripts) - Out-of-game entities equivalence to Objects, also with timer support.
- [`server/`](Portal-and-Server) - Core server code and Session handling.
- [`server/`](Portal-And-Server) - Core server code and Session handling.
- `portal/` - Portal proxy and connection protocols.
- [`settings_default.py`](Server-Conf#Settings-file) - Root settings of Evennia. Copy settings from here to `mygame/server/settings.py` file.
- [`typeclasses/`](Typeclasses) - Abstract classes for the typeclass storage and database system.

4
docs/source/Dynamic-In-Game-Map.md
View file

@ -12,7 +12,7 @@ In this tutorial we'll instead do it the other way around; We will dynamically d
There are at least two requirements needed for this tutorial to work.
1. The structure of your mud has to follow a logical layout. Evennia supports the layout of your world to be 'logically' impossible with rooms looping to themselves or exits leading to the other side of the map. Exits can also be named anything, from "jumping out the window" to "into the fifth dimension". This tutorial assumes you can only move in the cardinal directions (N, E, S and W).
2. Rooms must be connected and linked together for the map to be generated correctly. Vanilla Evennia comes with a admin command [@tunnel](https://github.com/evennia/evennia/wiki/Default-Command-Help#tunnel-cmdtunnel) that allows a user to create rooms in the cardinal directions, but additional work is needed to assure that rooms are connected. For example, if you `@tunnel east` and then immediately do `@tunnel west` you'll find that you have created two completely stand-alone rooms. So care is needed if you want to create a "logical" layout. In this tutorial we assume you have such a grid of rooms that we can generate the map from.
2. Rooms must be connected and linked together for the map to be generated correctly. Vanilla Evennia comes with a admin command [@tunnel](Default-Command-Help#tunnel-cmdtunnel) that allows a user to create rooms in the cardinal directions, but additional work is needed to assure that rooms are connected. For example, if you `@tunnel east` and then immediately do `@tunnel west` you'll find that you have created two completely stand-alone rooms. So care is needed if you want to create a "logical" layout. In this tutorial we assume you have such a grid of rooms that we can generate the map from.
## Concept
@ -297,7 +297,7 @@ class Room(DefaultRoom):
Obviously this method of generating maps doesn't take into account of any doors or exits that are hidden.. etc.. but hopefully it serves as a good base to start with. Like previously mentioned, it is very important to have a solid foundation on rooms before implementing this. You can try this on vanilla evennia by using @tunnel and essentially you can just create a long straight/edgy non-looping rooms that will show on your in-game map.
The above example will display the map above the room description. You could also use an [EvTable](code:evennia.utils.evtable) to place description and map next to each other. Some other things you can do is to have a [Command](Commands) that displays with a larger radius, maybe with a legend and other features.
The above example will display the map above the room description. You could also use an [EvTable](github:evennia.utils.evtable) to place description and map next to each other. Some other things you can do is to have a [Command](Commands) that displays with a larger radius, maybe with a legend and other features.
Below is the whole `map.py` for your reference. You need to update your `Room` typeclass (see above) to actually call it. Remember that to see different symbols for a location you also need to set the `sector_type` Attribute on the room to one of the keys in the `SYMBOLS` dictionary. So in this example, to make a room be mapped as `[.]` you would set the room's `sector_type` to `"SECT_INSIDE"`. Try it out with `@set here/sector_type = "SECT_INSIDE"`. If you wanted all new rooms to have a given sector symbol, you could change the default in the `SYMBOLS´ dictionary below, or you could add the Attribute in the Room's `at_object_creation` method.

38
docs/source/EvMenu.md
View file

@ -241,7 +241,7 @@ EvMenu accepts one important special `key` given only as `"_default"`. This key
enters something that does not match any other fixed keys. It is particularly useful for getting
user input:
```
```python
def node_readuser(caller, raw_string, **kwargs):
text = "Please enter your name"
@ -251,6 +251,7 @@ def node_readuser(caller, raw_string, **kwargs):
return text, options
```
A `"_default"` option does not show up in the menu, so the above will just be a node saying
`"Please enter your name"`. The name they entered will appear as `raw_string` in the next node.
@ -271,28 +272,27 @@ are three ways to write it
def _action_two(caller, raw_string, **kwargs):
# do things ...
return calculated_node_to_go_to
return "calculated_node_to_go_to"
def _action_three(caller, raw_string, **kwargs):
# do things ...
return "node_four", {"mode": 4}
def node_select(caller, raw_string, **kwargs):
text = ("select one",
"help: they all do different things ...")
"help - they all do different things ...")
options = ({"desc": "Option one",
"goto": "node_one"},
{"desc": "Option two",
"goto": _action_two}
{"desc": "Option three",
"goto": (_action_three, {"key": 1, "key2": 2})
"goto": "node_one"},
{"desc": "Option two",
"goto": _action_two},
{"desc": "Option three",
"goto": (_action_three, {"key": 1, "key2": 2})}
)
return text, options
```
As seen above, `goto` could just be pointing to a single `nodename` string - the name of the node to
@ -300,7 +300,7 @@ go to. When given like this, EvMenu will look for a node named like this and cal
function as
```python
nodename(caller, raw_string, **kwargs)`
nodename(caller, raw_string, **kwargs)
```
Here, `raw_string` is always the input the user entered to make that choice and `kwargs` are the
@ -414,14 +414,14 @@ See `evennia/utils/evmenu.py` for the details of their default implementations.
## Examples:
- **[Simple branching menu](#example-simple-branching-menu)** - choose from options
- **[Dynamic goto](#example-dynamic-goto)** - jumping to different nodes based on response
- **[Set caller properties](#example-set-caller-properties)** - a menu that changes things
- **[Getting arbitrary input](#example-get-arbitrary-input)** - entering text
- **[Storing data between nodes](#example-storing-data-between-nodes)** - keeping states and information while in the menu
- **[Repeating the same node](#example-repeating-the-same-node)** - validating within the node before moving to the next
- **[Full Menu](#example-full-menu):** a complete example
- **[Yes/No prompt](#example-yesno-prompt)** - entering text with limited possible responses (this is *not* using EvMenu but the conceptually similar yet technically unrelated `get_input` helper function accessed as `evennia.utils.evmenu.get_input`).
- **[Simple branching menu](EvMenu#example-simple-branching-menu)** - choose from options
- **[Dynamic goto](EvMenu#example-dynamic-goto)** - jumping to different nodes based on response
- **[Set caller properties](EvMenu#example-set-caller-properties)** - a menu that changes things
- **[Getting arbitrary input](EvMenu#example-get-arbitrary-input)** - entering text
- **[Storing data between nodes](EvMenu#example-storing-data-between-nodes)** - keeping states and information while in the menu
- **[Repeating the same node](EvMenu#example-repeating-the-same-node)** - validating within the node before moving to the next
- **[Full Menu](EvMenu#example-full-menu):** a complete example
- **[Yes/No prompt](EvMenu#example-yesno-prompt)** - entering text with limited possible responses (this is *not* using EvMenu but the conceptually similar yet technically unrelated `get_input` helper function accessed as `evennia.utils.evmenu.get_input`).
### Example: Simple branching menu

2
docs/source/EvMore.md
View file

@ -34,5 +34,5 @@ commands to jump to previous pages, to the top or bottom of the document as well
paging.
The pager takes several more keyword arguments for controlling the message output. See the
[evmore-API](code:evennia.utils.evmore) for more info.
[evmore-API](github:evennia.utils.evmore) for more info.

4
docs/source/Evennia-API.md
View file

@ -3,7 +3,7 @@
Evennia makes much of its programming tools available directly from the top-level `evennia` package. This is often referred to as Evennia's "flat" [Application Programming Interface](https://en.wikipedia.org/wiki/Application_programming_interface) (API). The flat API tries to collect and bring the most commonly used resources to the front in a way where everything is available at a glance (in a flat display), making it a good place to start to learn Evennia.
> Evennia's flat (and full) API can be perused through the auto-generated [API Library refence](code:evennia).
> Evennia's flat (and full) API can be perused through the auto-generated [API Library refence](github:evennia).
A good, interactive way to explore the flat API is to use [IPython](http://ipython.org/), a more flexible version of the default Python shell. Inside your virtual environment you can install IPython simply by
@ -26,7 +26,7 @@ Followed by
evennia.<TAB>
That is, write `evennia.` and press the TAB key. What pops up is the contents of the `evennia` top-level package - in other words [the "flat" API](https://github.com/evennia/evennia/wiki/evennia#the-flat-api).
That is, write `evennia.` and press the TAB key. What pops up is the contents of the `evennia` top-level package - in other words [the "flat" API](github:evennia#the-flat-api).
evennia.DefaultObject?

10
docs/source/Evennia-for-roleplaying-sessions.md
View file

@ -21,7 +21,7 @@ We will assume you start from scratch. You need Evennia installed, as per the [G
## The Game Master role
### Short version
In brief:
* Simplest way: Being an admin, just give one account `Admins` permission using the standard `@perm` command.
* Better but more work: Make a custom command to set/unset the above, while tweaking the Character to show your renewed GM status to the other accounts.
@ -200,7 +200,7 @@ Finally, issue the `@reload` command to update the server to your changes. Devel
## Character sheet
### Short version
In brief:
* Use Evennia's EvTable/EvForm to build a Character sheet
* Tie individual sheets to a given Character.
@ -215,7 +215,7 @@ There are many ways to build a Character sheet in text, from manually pasting st
#### Making a sheet with EvTable
[EvTable](code:evennia.utils.evtable) is a text-table generator. It helps with displaying text in ordered rows and columns. This is an example of using it in code:
[EvTable](github:evennia.utils.evtable) is a text-table generator. It helps with displaying text in ordered rows and columns. This is an example of using it in code:
````python
# this can be tried out in a Python shell like iPython
@ -232,7 +232,7 @@ table = evtable.EvTable("Attr", "Value",
], align='r', border="incols")
````
Above, we create a two-column table by supplying the two columns directly. We also tell the table to be right-aligned and to use the "incols" border type (borders drawns only in between columns). The `EvTable` class takes a lot of arguments for customizing its look, you can see [some of the possible keyword arguments here](code:evennia.utils.evtable#evtable__init__). Once you have the `table` you could also retroactively add new columns and rows to it with `table.add_row()` and `table.add_column()`: if necessary the table will expand with empty rows/columns to always remain rectangular.
Above, we create a two-column table by supplying the two columns directly. We also tell the table to be right-aligned and to use the "incols" border type (borders drawns only in between columns). The `EvTable` class takes a lot of arguments for customizing its look, you can see [some of the possible keyword arguments here](github:evennia.utils.evtable#evtable__init__). Once you have the `table` you could also retroactively add new columns and rows to it with `table.add_row()` and `table.add_column()`: if necessary the table will expand with empty rows/columns to always remain rectangular.
The result from printing the above table will be
@ -255,7 +255,7 @@ This is a minimalistic but effective Character sheet. By combining the `table_st
#### Making a sheet with EvForm
[EvForm](code:evennia.utils.evform) allows the creation of a two-dimensional "graphic" made by text characters. On this surface, one marks and tags rectangular regions ("cells") to be filled with content. This content can be either normal strings or `EvTable` instances (see the previous section, one such instance would be the `table` variable in that example).
[EvForm](github:evennia.utils.evform) allows the creation of a two-dimensional "graphic" made by text characters. On this surface, one marks and tags rectangular regions ("cells") to be filled with content. This content can be either normal strings or `EvTable` instances (see the previous section, one such instance would be the `table` variable in that example).
In the case of a Character sheet, these cells would be comparable to a line or box where you could enter the name of your character or their strength score. EvMenu also easily allows to update the content of those fields in code (it use EvTables so you rebuild the table first before re-sending it to EvForm).

2
docs/source/Gametime-Tutorial.md
View file

@ -234,6 +234,6 @@ Reload your game with the `@reload` command. You should now see the `time` comm
You could display it a bit more prettily with names for months and perhaps even days, if you want. And if "months" are called "moons" in your game, this is where you'd add that.
#### Time-related events
#### Time-related events in custom gametime
The `custom_gametime` module also has a way to schedule game-related events, taking into account your game time (and your custom calendar). It can be used to have a specific message every day at 6:00 AM, to show the sun rises, for instance. The `custom_gametime.schedule` function works in the same way as described for the default one above.

34
docs/source/Getting-Started.md
View file

@ -7,14 +7,14 @@ This will help you download, install and start Evennia for the first time.
> test out Evennia. Apart from downloading and updating you don't even need an
> internet connection until you feel ready to share your game with the world.
- [Quick Start](#quick-start)
- [Requirements](#requirements)
- [Linux Install](#linux-install)
- [Mac Install](#mac-install)
- [Windows Install](#windows-install)
- [Quick Start](Getting-Started#quick-start)
- [Requirements](Getting-Started#requirements)
- [Linux Install](Getting-Started#linux-install)
- [Mac Install](Getting-Started#mac-install)
- [Windows Install](Getting-Started#windows-install)
- [Running in Docker](Running-Evennia-in-Docker)
- [Where to Go Next](#where-to-go-next)
- [Troubleshooting](#troubleshooting)
- [Where to Go Next](Getting-Started#where-to-go-next)
- [Troubleshooting](Getting-Started#troubleshooting)
- [Glossary of terms](Glossary)
## Quick Start
@ -64,10 +64,10 @@ updating Evennia itself - Mac users can use the
## Linux Install
If you run into any issues during the installation and first start, please
check out [Linux Troubleshooting](#linux-troubleshooting).
check out [Linux Troubleshooting](Getting-Started#linux-troubleshooting).
For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the [dependencies](#requirements):
install the [dependencies](Getting-Started#requirements):
```
sudo apt-get update
@ -137,7 +137,7 @@ pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](Glossary#pip). If
install failed with any issues, see [Linux Troubleshooting](#linux-troubleshooting).
install failed with any issues, see [Linux Troubleshooting](Getting-Started#linux-troubleshooting).
Next we'll start our new game, here called "mygame". This will create yet
another new folder where you will be creating your new game:
@ -169,7 +169,7 @@ evennia start # (create a superuser when asked. Email is optional.)
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](#where-to-go-next).
created. Check out [where to go next](Getting-Started#where-to-go-next).
## Mac Install
@ -177,7 +177,7 @@ created. Check out [where to go next](#where-to-go-next).
The Evennia server is a terminal program. Open the terminal e.g. from
*Applications->Utilities->Terminal*. [Here is an introduction to the Mac terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
if you are unsure how it works. If you run into any issues during the
installation, please check out [Mac Troubleshooting](#mac-troubleshooting).
installation, please check out [Mac Troubleshooting](Getting-Started#mac-troubleshooting).
* Python should already be installed but you must make sure it's a high enough version.
([This](http://docs.python-guide.org/en/latest/starting/install/osx/) discusses
@ -247,7 +247,7 @@ pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](Glossary#pip). If
install failed with any issues, see [Mac Troubleshooting](#mac-troubleshooting).
install failed with any issues, see [Mac Troubleshooting](Getting-Started#mac-troubleshooting).
Next we'll start our new game. We'll call it "mygame" here. This creates a new
folder where you will be creating your new game:
@ -280,13 +280,13 @@ evennia start # (create a superuser when asked. Email is optional.)
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](#where-to-go-next).
created. Check out [where to go next](Getting-Started#where-to-go-next).
## Windows Install
If you run into any issues during the installation, please check out
[Windows Troubleshooting](#windows-troubleshooting).
[Windows Troubleshooting](Getting-Started#windows-troubleshooting).
> If you are running Windows10, consider using the Windows Subsystem for Linux
> ([WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)) instead.
@ -381,7 +381,7 @@ folders when you use the `dir` command) and run
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](Glossary#pip). If
the install failed with any issues, see [Windows Troubleshooting](#windows-troubleshooting).
the install failed with any issues, see [Windows Troubleshooting](Getting-Started#windows-troubleshooting).
Next we'll start our new game, we'll call it "mygame" here. This creates a new folder where you will be
creating your new game:
@ -413,7 +413,7 @@ evennia start # (create a superuser when asked. Email is optional.)
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](#where-to-go-next).
created. Check out [where to go next](Getting-Started#where-to-go-next).
## Where to Go Next

112
docs/source/Glossary.md
View file

@ -3,89 +3,89 @@
This explains common recurring terms used in the Evennia docs. It will be expanded as needed.
- _[account](#account)_ - the player's account on the game
- _[admin-site](#admin-site)_ - the Django web page for manipulating the database
- _[attribute](#attribute)_ - persistent, custom data stored on typeclasses
- _[channel](#channel)_ - game communication channels
- _[character](#character)_ - the player's avatar in the game, controlled from _[account](#account)_
- _[core](#core)_ - a term used for the code distributed with Evennia proper
- _[django](#django)_ - web framework Evennia uses for database access and web integration
- _[field](#field)_ - a _[typeclass](#typeclass)_ property representing a database column
- _[git](#git)_ - the version-control system we use
- _[github](#github)_ - the online hosting of our source code
- _[migrate](#migrate)_ - updating the database schema
- _[account](Glossary#account)_ - the player's account on the game
- _[admin-site](Glossary#admin-site)_ - the Django web page for manipulating the database
- _[attribute](Glossary#attribute)_ - persistent, custom data stored on typeclasses
- _[channel](Glossary#channel)_ - game communication channels
- _[character](Glossary#character)_ - the player's avatar in the game, controlled from _[account](Glossary#account)_
- _[core](Glossary#core)_ - a term used for the code distributed with Evennia proper
- _[django](Glossary#django)_ - web framework Evennia uses for database access and web integration
- _[field](Glossary#field)_ - a _[typeclass](Glossary#typeclass)_ property representing a database column
- _[git](Glossary#git)_ - the version-control system we use
- _[github](Glossary#github)_ - the online hosting of our source code
- _[migrate](Glossary#migrate)_ - updating the database schema
- _[multisession mode`](#multisession-mode)_ - a setting defining how users connect to Evennia
- _[object](#object)_ - Python instance, general term or in-game _[typeclass](#typeclass)_
- _[pip](#pip)_ - the Python installer
- _[object](Glossary#object)_ - Python instance, general term or in-game _[typeclass](Glossary#typeclass)_
- _[pip](Glossary#pip)_ - the Python installer
- _player_ - the human connecting to the game with their client
- _[puppet](#puppet)_ - when an [account](#account) controls an in-game [object](#object)
- _[property](#property)_ - a python property
- _evenv_ - see _[virtualenv](#virtualenv)_
- _[repository](#repository)_ - a store of source code + source history
- _[script](#script)_ - a building block for custom storage, systems and time-keepint
- _[session](#session)_ - represents one client connection
- _[ticker](#ticker)_ - Allows to run events on a steady 'tick'
- _[twisted](#twisted)_ - networking engine responsible for Evennia's event loop and communications
- _[typeclass](#typeclass)_ - Evennia's database-connected Python class
- _upstream_ - see _[github](#github)_
- _[virtualenv](#virtualenv)_ - a Python program and way to make an isolated Python install
- _[puppet](Glossary#puppet)_ - when an [account](Glossary#account) controls an in-game [object](Glossary#object)
- _[property](Glossary#property)_ - a python property
- _evenv_ - see _[virtualenv](Glossary#virtualenv)_
- _[repository](Glossary#repository)_ - a store of source code + source history
- _[script](Glossary#script)_ - a building block for custom storage, systems and time-keepint
- _[session](Glossary#session)_ - represents one client connection
- _[ticker](Glossary#ticker)_ - Allows to run events on a steady 'tick'
- _[twisted](Glossary#twisted)_ - networking engine responsible for Evennia's event loop and communications
- _[typeclass](Glossary#typeclass)_ - Evennia's database-connected Python class
- _upstream_ - see _[github](Glossary#github)_
- _[virtualenv](Glossary#virtualenv)_ - a Python program and way to make an isolated Python install
---
### _account_
The term 'account' refers to the [player's](#player) unique account on the game. It is represented by the `Account` [typeclass](#typeclass) and holds things like email, password, configuration etc.
The term 'account' refers to the [player's](Glossary#player) unique account on the game. It is represented by the `Account` [typeclass](Glossary#typeclass) and holds things like email, password, configuration etc.
When a player connects to the game, they connect to their account. The account has *no* representation in the game world. Through their Account they can instead choose to [puppet](#puppet) one (or more, depending on game mode) [Characters](#character) in the game.
When a player connects to the game, they connect to their account. The account has *no* representation in the game world. Through their Account they can instead choose to [puppet](Glossary#puppet) one (or more, depending on game mode) [Characters](Glossary#character) in the game.
In the default [multisession mode](Sessions#multisession-mode) of Evennia, you immediately start puppeting a Character with the same name as your Account when you log in - mimicking how older servers used to work.
### _admin-site_
This usually refers to [Django's](#django) *Admin site* or database-administration web page ([link to Django docs](https://docs.djangoproject.com/en/2.1/ref/contrib/admin/)). The admin site is an automatically generated web interface to the database (it can be customized extensively). It's reachable from the `admin` link on the default Evennia website you get with your server.
This usually refers to [Django's](Glossary#django) *Admin site* or database-administration web page ([link to Django docs](https://docs.djangoproject.com/en/2.1/ref/contrib/admin/)). The admin site is an automatically generated web interface to the database (it can be customized extensively). It's reachable from the `admin` link on the default Evennia website you get with your server.
### _attribute_
The term _Attribute_ should not be confused with ([properties](#property) or [fields](#field). The `Attribute` represents arbitrary pieces of data that can be attached to any [typeclassed](#typeclass) entity in Evennia. Attributes allows storing new persistent data on typeclasses without changing their underlying database schemas. [Read more about Attributes here](Attributes).
The term _Attribute_ should not be confused with ([properties](Glossary#property) or [fields](Glossary#field). The `Attribute` represents arbitrary pieces of data that can be attached to any [typeclassed](Glossary#typeclass) entity in Evennia. Attributes allows storing new persistent data on typeclasses without changing their underlying database schemas. [Read more about Attributes here](Attributes).
### _channel_
A _Channel_ refers to an in-game communication channel. It's an entity that people subscribe to and which re-distributes messages between all subscribers. Such subscribers default to being [Accounts](#account), for out-of-game communication but could also be [Objects (usually Characters)](#character) if one wanted to adopt Channels for things like in-game walkie-talkies or phone systems. It is represented by the `Channel` typeclass. [You can read more about the comm system here](Communications#channels).
A _Channel_ refers to an in-game communication channel. It's an entity that people subscribe to and which re-distributes messages between all subscribers. Such subscribers default to being [Accounts](Glossary#account), for out-of-game communication but could also be [Objects (usually Characters)](Glossary#character) if one wanted to adopt Channels for things like in-game walkie-talkies or phone systems. It is represented by the `Channel` typeclass. [You can read more about the comm system here](Communications#channels).
### _character_
The _Character_ is the term we use for the default avatar being [puppeted](#puppet) by the [account](#account) in the game world. It is represented by the `Character` typeclass (which is a child of [Object](#object)). Many developers use children of this class to represent monsters and other NPCs. You can [read more about it here](Objects#subclasses-of-object).
The _Character_ is the term we use for the default avatar being [puppeted](Glossary#puppet) by the [account](Glossary#account) in the game world. It is represented by the `Character` typeclass (which is a child of [Object](Glossary#object)). Many developers use children of this class to represent monsters and other NPCs. You can [read more about it here](Objects#subclasses-of-object).
### _django_
[Django](https://www.djangoproject.com/) is a professional and very popular Python web framework, similar to Rails for the Ruby language. It is one of Evennia's central library dependencies (the other one is [Twisted](#twisted)). Evennia uses Django for two main things - to map all database operations to Python and for structuring our web site.
[Django](https://www.djangoproject.com/) is a professional and very popular Python web framework, similar to Rails for the Ruby language. It is one of Evennia's central library dependencies (the other one is [Twisted](Glossary#twisted)). Evennia uses Django for two main things - to map all database operations to Python and for structuring our web site.
Through Django, we can work with any supported database (SQlite3, Postgres, MySQL ...) using generic Python instead of database-specific SQL: A database table is represented in Django as a Python class (called a *model*). An Python instance of such a class represents a row in that table.
There is usually no need to know the details of Django's database handling in order to use Evennia - it will handle most of the complexity for you under the hood using what we call [typeclasses](#typeclass). But should you need the power of Django you can always get it. Most commonly people want to use "raw" Django when doing more advanced/custom database queries than offered by Evennia's [default search functions](Tutorial-Searching-For-Objects). One will then need to read about Django's _querysets_. Querysets are Python method calls on a special form that lets you build complex queries. They get converted into optimized SQL queries under the hood, suitable for your current database. [Here is our tutorial/explanation of Django queries](https://github.com/evennia/evennia/wiki/Tutorial-Searching-For-Objects#queries-in-django).
There is usually no need to know the details of Django's database handling in order to use Evennia - it will handle most of the complexity for you under the hood using what we call [typeclasses](Glossary#typeclass). But should you need the power of Django you can always get it. Most commonly people want to use "raw" Django when doing more advanced/custom database queries than offered by Evennia's [default search functions](Tutorial-Searching-For-Objects). One will then need to read about Django's _querysets_. Querysets are Python method calls on a special form that lets you build complex queries. They get converted into optimized SQL queries under the hood, suitable for your current database. [Here is our tutorial/explanation of Django queries](Tutorial-Searching-For-Objects#queries-in-django).
> By the way, Django (and Evennia) does allow you to fall through and send raw SQL if you really want to. It's highly unlikely to be needed though; the Django database abstraction is very, very powerful.
The other aspect where Evennia uses Django is for web integration. On one end Django gives an infrastructure for wiring Python functions (called *views*) to URLs: the view/function is called when a user goes that URL in their browser, enters data into a form etc. The return is the web page to show. Django also offers templating with features such as being able to add special markers in HTML where it will insert the values of Python variables on the fly (like showing the current player count on the web page). [Here is one of our tutorials on wiring up such a web page](Add-a-simple-new-web-page). Django also comes with the [admin site](#admin-site), which automatically maps the database into a form accessible from a web browser.
The other aspect where Evennia uses Django is for web integration. On one end Django gives an infrastructure for wiring Python functions (called *views*) to URLs: the view/function is called when a user goes that URL in their browser, enters data into a form etc. The return is the web page to show. Django also offers templating with features such as being able to add special markers in HTML where it will insert the values of Python variables on the fly (like showing the current player count on the web page). [Here is one of our tutorials on wiring up such a web page](Add-a-simple-new-web-page). Django also comes with the [admin site](Glossary#admin-site), which automatically maps the database into a form accessible from a web browser.
### _core_
This term is sometimes used to represent the main Evennia library code suite, *excluding* its [contrib](#contrib) directory. It can sometimes come up in code reviews, such as
This term is sometimes used to represent the main Evennia library code suite, *excluding* its [contrib](Glossary#contrib) directory. It can sometimes come up in code reviews, such as
> Evennia is game-agnostic but this feature is for a particular game genre. So it does not belong in core. Better make it a contrib.
### _field_
A _field_ or _database field_ in Evennia refers to a [property](#property) on a [typeclass](#typeclass) directly linked to an underlying database column. Only a few fixed properties per typeclass are database fields but they are often tied to the core functionality of that base typeclass (for example [Objects](#object) store its location as a field). In all other cases, [attributes](#attribute) are used to add new persistent data to the typeclass. [Read more about typeclass properties here](Typeclasses#about-typeclass-properties).
A _field_ or _database field_ in Evennia refers to a [property](Glossary#property) on a [typeclass](Glossary#typeclass) directly linked to an underlying database column. Only a few fixed properties per typeclass are database fields but they are often tied to the core functionality of that base typeclass (for example [Objects](Glossary#object) store its location as a field). In all other cases, [attributes](Glossary#attribute) are used to add new persistent data to the typeclass. [Read more about typeclass properties here](Typeclasses#about-typeclass-properties).
### _git_
[Git](https://git-scm.com/) is a [version control](https://en.wikipedia.org/wiki/Version_control) tool. It allows us to track the development of the Evennia code by dividing it into units called *commits*. A 'commit' is sort of a save-spot - you save the current state of your code and can then come back to it later if later changes caused problems. By tracking commits we know what 'version' of the code we are currently using.
Evennia's source code + its source history is jointly called a [repository](#repository). This is centrally stored at our online home on [GitHub](#github). Everyone using or developing Evennia makes a 'clone' of this repository to their own computer - everyone automatically gets everything that is online, including all the code history.
Evennia's source code + its source history is jointly called a [repository](Glossary#repository). This is centrally stored at our online home on [GitHub](Glossary#github). Everyone using or developing Evennia makes a 'clone' of this repository to their own computer - everyone automatically gets everything that is online, including all the code history.
> Don't confuse Git and [GitHub](#github). The former is the version control system. The latter is a website (run by a company) that allows you to upload source code controlled by Git for others to see (among other things).
> Don't confuse Git and [GitHub](Glossary#github). The former is the version control system. The latter is a website (run by a company) that allows you to upload source code controlled by Git for others to see (among other things).
Git allows multiple users from around the world to efficiently collaborate on Evennia's code: People can make local commits on their cloned code. The commits they do can then be uploaded to GitHub and reviewed by the Evennia lead devs - and if the changes look ok they can be safely *merged* into the central Evennia code - and everyone can *pull* those changes to update their local copies.
@ -99,11 +99,11 @@ Common usage (for non-Evennia developers):
### _migrate_
This term is used for upgrading the database structure (it's _schema_ )to a new version. Most often this is due to Evennia's [upstream](#github) schema changing. When that happens you need to migrate that schema to the new version as well. Once you have used [git](#git) to pull the latest changes, just `cd` into your game dir and run
This term is used for upgrading the database structure (it's _schema_ )to a new version. Most often this is due to Evennia's [upstream](Glossary#github) schema changing. When that happens you need to migrate that schema to the new version as well. Once you have used [git](Glossary#git) to pull the latest changes, just `cd` into your game dir and run
evennia migrate
That should be it (see [virtualenv](#virtualenv) if you get a warning that the `evennia` command is not available). See also [Updating your game](Updating-Your-Game) for more details.
That should be it (see [virtualenv](Glossary#virtualenv) if you get a warning that the `evennia` command is not available). See also [Updating your game](Updating-Your-Game) for more details.
> Technically, migrations are shipped as little Python snippets of code that explains which database actions must be taken to upgrade from one version of the schema to the next. When you run the command above, those snippets are run in sequence.
@ -113,15 +113,15 @@ This term refers to the `MULTISESSION_MODE` setting, which has a value of 0 to 3
### _github_
[Github](https://github.com/evennia) is where Evennia's source code and documentation is hosted. This online [repository](#repository) of code we also sometimes refer to as _upstream_.
[Github](https://github.com/evennia) is where Evennia's source code and documentation is hosted. This online [repository](Glossary#repository) of code we also sometimes refer to as _upstream_.
GitHub is a business, offering free hosting to Open-source projects like Evennia. Despite the similarity in name, don't confuse GitHub the website with [Git](#git), the versioning system. Github hosts Git [repositories](#repository) online and helps with collaboration and infrastructure. Git itself is a separate project.
GitHub is a business, offering free hosting to Open-source projects like Evennia. Despite the similarity in name, don't confuse GitHub the website with [Git](Glossary#git), the versioning system. Github hosts Git [repositories](Glossary#repository) online and helps with collaboration and infrastructure. Git itself is a separate project.
### _object_
In general Python (and other [object-oriented languages](https://en.wikipedia.org/wiki/Object-oriented_programming)), an `object` is what we call the instance of a *class*. But one of Evennia's core [typeclasses](#typeclasss) is also called "Object". To separate these in the docs we try to use `object` to refer to the general term and capitalized `Object` when we refer to the typeclass.
In general Python (and other [object-oriented languages](https://en.wikipedia.org/wiki/Object-oriented_programming)), an `object` is what we call the instance of a *class*. But one of Evennia's core [typeclasses](Glossary#typeclasss) is also called "Object". To separate these in the docs we try to use `object` to refer to the general term and capitalized `Object` when we refer to the typeclass.
The `Object` is a typeclass that represents all *in-game* entities, including [Characters](#character), rooms, trees, weapons etc. [Read more about Objects here](Objects).
The `Object` is a typeclass that represents all *in-game* entities, including [Characters](Glossary#character), rooms, trees, weapons etc. [Read more about Objects here](Objects).
### _pip_
@ -135,33 +135,33 @@ Common usage:
- `pip install <folder>` - install a Python package you have downloaded earlier (or cloned using git).
- `pip install -e <folder>` - install a local package by just making a soft link to the folder. This means that if the code in `<folder>` changes, the installed Python package is immediately updated. If not using `-e`, one would need to run `pip install --upgrade <folder>` every time to make the changes available when you import this package into your code. Evennia is installed this way.
For development, `pip` is usually used together with a [virtualenv](#virtualenv) to install all packages and dependencies needed for a project in one, isolated location on the hard drive.
For development, `pip` is usually used together with a [virtualenv](Glossary#virtualenv) to install all packages and dependencies needed for a project in one, isolated location on the hard drive.
### _puppet_
An [account](#account) can take control and "play as" any [Object](#object). When doing so, we call this _puppeting_, (like [puppeteering](https://en.wikipedia.org/wiki/Puppeteer)). Normally the entity being puppeted is of the [Character](#character) subclass but it does not have to be.
An [account](Glossary#account) can take control and "play as" any [Object](Glossary#object). When doing so, we call this _puppeting_, (like [puppeteering](https://en.wikipedia.org/wiki/Puppeteer)). Normally the entity being puppeted is of the [Character](Glossary#character) subclass but it does not have to be.
### _property_
A _property_ is a general term used for properties on any Python object. The term also sometimes refers to the `property` built-in function of Python ([read more here](https://www.python-course.eu/python3_properties.php)). Note the distinction between properties, [fields](#field) and [Attributes](#attribute).
A _property_ is a general term used for properties on any Python object. The term also sometimes refers to the `property` built-in function of Python ([read more here](https://www.python-course.eu/python3_properties.php)). Note the distinction between properties, [fields](Glossary#field) and [Attributes](Glossary#attribute).
### _repository_
A _repository_ is a version control/[git](#git) term. It represents a folder containing source code plus its versioning history.
A _repository_ is a version control/[git](Glossary#git) term. It represents a folder containing source code plus its versioning history.
> In Git's case, that history is stored in a hidden folder `.git`. If you ever feel the need to look into this folder you probably already know enough Git to know why.
The `evennia` folder you download from us with `git clone` is a repository. The code on [GitHub](#github) is often referred to as the 'online repository' (or the _upstream_ repository). If you put your game dir under version control, that of course becomes a repository as well.
The `evennia` folder you download from us with `git clone` is a repository. The code on [GitHub](Glossary#github) is often referred to as the 'online repository' (or the _upstream_ repository). If you put your game dir under version control, that of course becomes a repository as well.
### _script_
When we refer to _Scripts_, we generally refer to the `Script` [typeclass](Typeclasses). Scripts are the mavericks of Evennia - they are like [Objects](#object) but without any in-game existence. They are useful as custom places to store data but also as building blocks in persistent game systems. Since the can be initialized with timing capabilities they can also be used for long-time persistent time keeping (for fast updates other types of timers may be better though). [Read more about Scripts here](Scripts)
When we refer to _Scripts_, we generally refer to the `Script` [typeclass](Typeclasses). Scripts are the mavericks of Evennia - they are like [Objects](Glossary#object) but without any in-game existence. They are useful as custom places to store data but also as building blocks in persistent game systems. Since the can be initialized with timing capabilities they can also be used for long-time persistent time keeping (for fast updates other types of timers may be better though). [Read more about Scripts here](Scripts)
### _session_
A [Session](Sessions) is a Python object representing a single client connection to the server. A given human player could connect to the game from different clients and each would get a Session (even if you did not allow them to actually log in and get access to an [account](#account)).
A [Session](Sessions) is a Python object representing a single client connection to the server. A given human player could connect to the game from different clients and each would get a Session (even if you did not allow them to actually log in and get access to an [account](Glossary#account)).
Sessions are _not_ [typeclassed](#typeclass) and has no database persistence. But since they always exist (also when not logged in), they share some common functionality with typeclasses that can be useful for certain game states.
Sessions are _not_ [typeclassed](Glossary#typeclass) and has no database persistence. But since they always exist (also when not logged in), they share some common functionality with typeclasses that can be useful for certain game states.
### _ticker_
@ -169,15 +169,15 @@ The [Ticker handler](TickerHandler) runs Evennia's optional 'ticker' system. In
### _typeclass_
The [typeclass](Typeclasses) is an Evennia-specific term. A typeclass allows developers to work with database-persistent objects as if they were normal Python objects. It makes use of specific [Django](#django) features to link a Python class to a database table. Sometimes we refer to such code entities as _being typeclassed_.
The [typeclass](Typeclasses) is an Evennia-specific term. A typeclass allows developers to work with database-persistent objects as if they were normal Python objects. It makes use of specific [Django](Glossary#django) features to link a Python class to a database table. Sometimes we refer to such code entities as _being typeclassed_.
Evennia's main typeclasses are [Account](#account), [Object](#object), [Script](#script) and [Channel](#channel). Children of the base class (such as [Character](#character)) will use the same database table as the parent, but can have vastly different Python capabilities (and persistent features through [Attributes](#attributes) and [Tags](#tags). A typeclass can be coded and treated pretty much like any other Python class except it must inherit (at any distance) from one of the base typeclasses. Also, creating a new instance of a typeclass will add a new row to the database table to which it is linked.
Evennia's main typeclasses are [Account](Glossary#account), [Object](Glossary#object), [Script](Glossary#script) and [Channel](Glossary#channel). Children of the base class (such as [Character](Glossary#character)) will use the same database table as the parent, but can have vastly different Python capabilities (and persistent features through [Attributes](Glossary#attributes) and [Tags](Glossary#tags). A typeclass can be coded and treated pretty much like any other Python class except it must inherit (at any distance) from one of the base typeclasses. Also, creating a new instance of a typeclass will add a new row to the database table to which it is linked.
The [core](#core) typeclasses in the Evennia library are all named `DefaultAccount`, `DefaultObject` etc. When you initialize your [game dir] you automatically get empty children of these, called `Account`, `Object` etc that you can start working with.
The [core](Glossary#core) typeclasses in the Evennia library are all named `DefaultAccount`, `DefaultObject` etc. When you initialize your [game dir] you automatically get empty children of these, called `Account`, `Object` etc that you can start working with.
### _twisted_
[Twisted](https://twistedmatrix.com/trac/) is a heavy-duty asynchronous networking engine. It is one of Evennia's two major library dependencies (the other one is [Django](#django)). Twisted is what "runs" Evennia - it handles Evennia's event loop. Twisted also has the building blocks we need to construct network protocols and communicate with the outside world; such as our MUD-custom version of Telnet, Telnet+SSL, SSH, webclient-websockets etc. Twisted also runs our integrated web server, serving the Django-based website for your game.
[Twisted](https://twistedmatrix.com/trac/) is a heavy-duty asynchronous networking engine. It is one of Evennia's two major library dependencies (the other one is [Django](Glossary#django)). Twisted is what "runs" Evennia - it handles Evennia's event loop. Twisted also has the building blocks we need to construct network protocols and communicate with the outside world; such as our MUD-custom version of Telnet, Telnet+SSL, SSH, webclient-websockets etc. Twisted also runs our integrated web server, serving the Django-based website for your game.
### _virtualenv_
@ -190,7 +190,7 @@ Usage:
- `<folder_name>\Scripts\activate` (windows)
- `deactivate` - turn off the currently activated virtualenv.
A virtualenv is 'activated' only for the console/terminal it was started in, but it's safe to activate the same virtualenv many times in different windows if you want. Once activated, all Python packages now installed with [pip](#pip) will install to `evenv` rather than to a global location like `/usr/local/bin` or `C:\Program Files`.
A virtualenv is 'activated' only for the console/terminal it was started in, but it's safe to activate the same virtualenv many times in different windows if you want. Once activated, all Python packages now installed with [pip](Glossary#pip) will install to `evenv` rather than to a global location like `/usr/local/bin` or `C:\Program Files`.
> Note that if you have root/admin access you *could* install Evennia globally just fine, without using a virtualenv. It's strongly discouraged and considered bad practice though. Experienced Python developers tend to rather create one new virtualenv per project they are working on, to keep the varying installs cleanly separated from one another.

2
docs/source/Help-System.md
View file

@ -53,7 +53,7 @@ Alternatively, you can keep the advantages of *auto-help* in commands, but contr
## Database help entries
These are all help entries not involving commands (this is handled automatically by the [Command Auto-help system](#command-auto-help-system)). Non-automatic help entries describe how your particular game is played - its rules, world descriptions and so on.
These are all help entries not involving commands (this is handled automatically by the [Command Auto-help system](Help-System#command-auto-help-system)). Non-automatic help entries describe how your particular game is played - its rules, world descriptions and so on.
A help entry consists of four parts:

3
docs/source/IRC.md
View file

@ -1,8 +1,7 @@
# IRC
_Disambiguation: This page is related to using IRC inside an Evennia game. To join the official Evennia IRC chat, connect to irc.freenode.net and join #evennia. Alternatively, you can [join our Discord](https://discord.gg/NecFePw), which is mirrored to IRC._
[](Connecting-your-game-to-an-external-IRC-channel.)
_Disambiguation: This page is related to using IRC inside an Evennia game. To join the official Evennia IRC chat, connect to irc.freenode.net and join #evennia. Alternatively, you can [join our Discord](https://discord.gg/NecFePw), which is mirrored to IRC._
[IRC (Internet Relay Chat)](http://en.wikipedia.org/wiki/Internet_Relay_Chat) is a long standing chat protocol used by many open-source projects for communicating in real time. By connecting one of Evennia's [Channels](Communications) to an IRC channel you can communicate also with people not on an mud themselves. You can also use IRC if you are only running your Evennia MUD locally on your computer (your game doesn't need to be open to the public)! All you need is an internet connection. For IRC operation you also need [twisted.words](http://twistedmatrix.com/trac/wiki/TwistedWords). This is available simply as a package *python-twisted-words* in many Linux distros, or directly downloadable from the link.

2
docs/source/Installing-on-Android.md
View file

@ -67,7 +67,7 @@ Install the latest Evennia in a way that lets you edit the source
(evenv) $ pip install --upgrade -e 'git+https://github.com/evennia/evennia#egg=evennia'
```
This step will possibly take quite a while - we are downloading Evennia and are then installing it, building all of the requirements for Evennia to run. If you run into trouble on this step, please see [Troubleshooting](#troubleshooting).
This step will possibly take quite a while - we are downloading Evennia and are then installing it, building all of the requirements for Evennia to run. If you run into trouble on this step, please see [Troubleshooting](Installing-on-Android#troubleshooting).
You can go to the dir where Evennia is installed with `cd $VIRTUAL_ENV/src/evennia`. `git grep (something)` can be handy, as can `git diff`

2
docs/source/Links.md
View file

@ -107,4 +107,4 @@
### Credits
- Wiki [Home]([Home](index)) Icons made by [Freepik](http://www.freepik.com"-title="Freepik">Freepik) from [flaticon.com](http://www.flaticon.com), licensed under [Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0).
- Wiki [Home](index) Icons made by [Freepik](http://www.freepik.com"-title="Freepik">Freepik) from [flaticon.com](http://www.flaticon.com), licensed under [Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0).

2
docs/source/Locks.md
View file

@ -240,7 +240,7 @@ Here is how you use `perm` to give an account more permissions:
perm/account Tommy = Builders
perm/account/del Tommy = Builders # remove it again
Note the use of the `/account` switch. It means you assign the permission to the [Accounts]([Accounts](Account)) Tommy instead of any [Character](Objects) that also happens to be named "Tommy".
Note the use of the `/account` switch. It means you assign the permission to the [Accounts](Accounts) Tommy instead of any [Character](Objects) that also happens to be named "Tommy".
Putting permissions on the *Account* guarantees that they are kept, *regardless* of which Character they are currently puppeting. This is especially important to remember when assigning permissions from the *hierarchy tree* - as mentioned above, an Account's permissions will overrule that of its character. So to be sure to avoid confusion you should generally put hierarchy permissions on the Account, not on their Characters (but see also [quelling](Locks#Quelling)).

6
docs/source/Manually-Configuring-Color.md
View file

@ -17,7 +17,7 @@ So here's how to allow those users to remove color. It basically means you imple
Create a new module in `mygame/typeclasses` named, for example, `mycharacter.py`. Alternatively you can simply add a new class to 'mygamegame/typeclasses/characters.py'.
In your new module(or characters.py), create a new [Typeclass](../typeclasses) inheriting from `evennia.DefaultCharacter`. We will also import `evennia.utils.ansi`, which we will use later.
In your new module(or characters.py), create a new [Typeclass](Typeclasses) inheriting from `evennia.DefaultCharacter`. We will also import `evennia.utils.ansi`, which we will use later.
```python
from evennia import Character
@ -29,7 +29,7 @@ In your new module(or characters.py), create a new [Typeclass](../typeclasses) i
self.db.config_color = True
```
Above we set a simple config value as an [Attribute](../Attributes).
Above we set a simple config value as an [Attribute](Attributes).
Let's make sure that new characters are created of this type. Edit your `mygame/server/conf/settings.py` file and add/change `BASE_CHARACTER_TYPECLASS` to point to your new character class. Observe that this will only affect *new* characters, not those already created. You have to convert already created characters to the new typeclass by using the `@typeclass` command (try on a secondary character first though, to test that everything works - you don't want to render your root user unusable!).
@ -127,7 +127,7 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
## More colors
Apart from ANSI colors, Evennia also supports **Xterm256** colors (See [Colors](../TextTags#colored-text)). The `msg()` method supports the `xterm256` keyword for manually activating/deactiving xterm256. It should be easy to expand the above example to allow players to customize xterm256 regardless of if Evennia thinks their client supports it or not.
Apart from ANSI colors, Evennia also supports **Xterm256** colors (See [Colors](TextTags#colored-text)). The `msg()` method supports the `xterm256` keyword for manually activating/deactiving xterm256. It should be easy to expand the above example to allow players to customize xterm256 regardless of if Evennia thinks their client supports it or not.
To get a better understanding of how `msg()` works with keywords, you can try this as superuser:

24
docs/source/Messagepath.md
View file

@ -15,7 +15,7 @@ We'll start by tracing data from the client to the server. Here it is in short:
ServerSession ->
Inputfunc
### Client
### Client (ingoing)
The client sends data to Evennia in two ways.
@ -31,18 +31,18 @@ The client sends data to Evennia in two ways.
the client may send commands based on a timer or some trigger.
Exactly how the inputcommand looks when it travels from the client to Evennia
depends on the [Protocol](Client-APIs) used:
depends on the [Protocol](Custom-Protocols) used:
- Telnet: A string. If GMCP or MSDP OOB protocols are used, this string will
be formatted in a special way, but it's still a raw string. If Telnet SSL is
active, the string will be encrypted.
- SSH: An encrypted string
- Webclient: A JSON-serialized string.
### Portal Session
### Portal Session (ingoing)
Each client is connected to the game via a *Portal Session*, one per connection. This Session is different depending on the type of connection (telnet, webclient etc) and thus know how to handle that particular data type. So regardless of how the data arrives, the Session will identify the type of the instruction and any arguments it should have. For example, the telnet protocol will figure that anything arriving normally over the wire should be passed on as a "text" type.
### PortalSessionHandler
### PortalSessionHandler (ingoing)
The *PortalSessionhandler* manages all connected Sessions in the Portal. Its `data_in` method (called by each Portal Session) will parse the command names and arguments from the protocols and convert them to a standardized form we call the *inputcommand*:
@ -58,11 +58,11 @@ All inputcommands must have a name, but they may or may not have arguments and k
This inputcommand-structure is pickled together with the unique session-id of the Session to which it belongs. This is then sent over the AMP connection.
### ServerSessionHandler
### ServerSessionHandler (ingoing)
On the Server side, the AMP unpickles the data and associates the session id with the server-side [Session]([Session](Session)). Data and Session are passed to the server-side `SessionHandler.data_in`. This in turn calls `ServerSession.data_in()`
On the Server side, the AMP unpickles the data and associates the session id with the server-side [Session](Sessions). Data and Session are passed to the server-side `SessionHandler.data_in`. This in turn calls `ServerSession.data_in()`
### ServerSession
### ServerSession (ingoing)
The method `ServerSession.data_in` is meant to offer a single place to override if they want to examine *all* data passing into the server from the client. It is meant to call the `ssessionhandler.call_inputfuncs` with the (potentially processed) data (so this is technically a sort of detour back to the sessionhandler).
@ -121,11 +121,11 @@ Note the form of the `mycommand` outputfunction. This explicitly defines the arg
> Note: The `msg` method sits on your Object- and Account typeclasses. It means you can easily override `msg` and make custom- or per-object modifications to the flow of data as it passes through.
### Session
### ServerSession (outgoing)
Nothing is processed on the Session, it just serves as a gathering points for all different `msg`. It immediately passes the data on to ...
### ServerSessionHandler
### ServerSessionHandler (outgoing)
In the *ServerSessionhandler*, the keywords from the `msg` method are collated into one or more *outputcommands* on a standardized form (identical to inputcommands):
@ -137,7 +137,7 @@ This will intelligently convert different input to the same form. So `msg("Hello
This is also the point where [Inlinefuncs](TextTags#inline-functions) are parsed, depending on the session to receive the data. Said data is pickled together with the Session id then sent over the AMP bridge.
### PortalSessionHandler
### PortalSessionHandler (outgoing)
After the AMP connection has unpickled the data and paired the session id to the matching PortalSession, the handler next determines if this Session has a suitable method for handling the outputcommand.
@ -145,11 +145,11 @@ The situation is analogous to how inputfuncs work, except that protocols are fix
For example, the common sending of text expects a PortalSession method `send_text`. This will be called as `send_text(*("Hello",), **{})`. If the "prompt" outputfunction was used, send_prompt is called. In all other cases the `send_default(cmdname, *args, **kwargs)` will be called - this is the case for all client-custom outputcommands, like when wanting to tell the client to update a graphic or play a sound.
### PortalSession
### PortalSession (outgoing)
At this point it is up to the session to convert the command into a form understood by this particular protocol. For telnet, `send_text` will just send the argument as a string (since that is what telnet clients expect when "text" is coming). If `send_default` was called (basically everything that is not traditional text or a prompt), it will pack the data as an GMCP or MSDP command packet if the telnet client supports either (otherwise it won't send at all). If sending to the webclient, the data will get packed into a JSON structure at all times.
### Client
### Client (outgoing)
Once arrived at the client, the outputcommand is handled in the way supported by the client (or it may be quietly ignored if not). "text" commands will be displayed in the main window while others may trigger changes in the GUI or play a sound etc.

4
docs/source/OOB.md
View file

@ -33,7 +33,7 @@ Which commands you can send depends on the client. If the client does not suppor
> Remember that a given message may go to multiple clients with different capabilities. So unless you turn off telnet completely and only rely on the webclient, you should never rely on non-`text` OOB messages always reaching all targets.
[Inputfuncs]([Inputfuncs](Inputfunc)) lists the default inputfuncs available to handle incoming OOB messages. To accept more you need to add more inputfuncs (see that page for more info).
[Inputfuncs](Inputfuncs) lists the default inputfuncs available to handle incoming OOB messages. To accept more you need to add more inputfuncs (see that page for more info).
## Supported OOB protocols
@ -111,4 +111,4 @@ Our web client uses pure JSON structures for all its communication, including `t
["cmdname, ["arg"], {}]
Since JSON is native to Javascript, this becomes very easy for the webclient to handle.
Since JSON is native to Javascript, this becomes very easy for the webclient to handle.

2
docs/source/Objects.md
View file

@ -70,7 +70,7 @@ The Object also has a host of useful utility functions. See the function headers
- `delete()` - deletes this object, first calling `clear_exits()` and
`clear_contents()`.
The Object Typeclass defines many more *hook methods* beyond `at_object_creation`. Evennia calls these hooks at various points. When implementing your custom objects, you will inherit from the base parent and overload these hooks with your own custom code. See `evennia.objects.objects` for an updated list of all the available hooks or the [API for DefaultObject here](evennia.objects.objects#defaultobject).
The Object Typeclass defines many more *hook methods* beyond `at_object_creation`. Evennia calls these hooks at various points. When implementing your custom objects, you will inherit from the base parent and overload these hooks with your own custom code. See `evennia.objects.objects` for an updated list of all the available hooks or the [API for DefaultObject here](api:evennia.objects.objects#defaultobject).
## Subclasses of `Object`

4
docs/source/Online-Setup.md
View file

@ -162,7 +162,7 @@ WEBSOCKET_CLIENT_URL = "wss://fqdn:4002"
### Let's Encrypt
[Let's Encrypt](letsencrypt.org) is a certificate authority offering free certificates to secure a website with HTTPS. To get started issuing a certificate for your web server using Let's Encrypt, see these links:
[Let's Encrypt](https://letsencrypt.org) is a certificate authority offering free certificates to secure a website with HTTPS. To get started issuing a certificate for your web server using Let's Encrypt, see these links:
- [Let's Encrypt - Getting Started](https://letsencrypt.org/getting-started/)
- The [CertBot Client](https://certbot.eff.org/) is a program for automatically obtaining a certificate, use it and maintain it with your website.
@ -199,7 +199,7 @@ What we showed above is by far the simplest and probably cheapest option: Run Ev
#### Setting up your own machine as a server
[The first section](#connecting-from-the-outside) of this page describes how to do this and allow users to connect to the IP address of your machine/router.
[The first section](Online-Setup#connecting-from-the-outside) of this page describes how to do this and allow users to connect to the IP address of your machine/router.
A complication with using a specific IP address like this is that your home IP might not remain the same. Many ISPs (Internet Service Providers) allocates a *dynamic* IP to you which could change at any time. When that happens, that IP you told people to go to will be worthless. Also, that long string of numbers is not very pretty, is it? It's hard to remember and not easy to use in marketing your game. What you need is to alias it to a more sensible domain name - an alias that follows you around also when the IP changes.

36
docs/source/Python-basic-introduction.md
View file

@ -3,11 +3,11 @@
This is the first part of our beginner's guide to the basics of using Python with Evennia. It's aimed at you with limited or no programming/Python experience. But also if you are an experienced programmer new to Evennia or Python you might still pick up a thing or two. It is by necessity brief and low on detail. There are countless Python guides and tutorials, books and videos out there for learning more in-depth - use them!
**Contents:**
- [Evennia Hello world](#evennia-hello-world)
- [Importing modules](#importing-modules)
- [Parsing Python errors](#parsing-python-errors)
- [Our first function](#our-first-function)
- [Looking at the log](#looking-at-the-log)
- [Evennia Hello world](Python-basic-introduction#evennia-hello-world)
- [Importing modules](Python-basic-introduction#importing-modules)
- [Parsing Python errors](Python-basic-introduction#parsing-python-errors)
- [Our first function](Python-basic-introduction#our-first-function)
- [Looking at the log](Python-basic-introduction#looking-at-the-log)
- (continued in [part 2](Python-basic-tutorial-part-two))
This quickstart assumes you have [gotten Evennia started](Getting-Started). You should make sure that you are able to see the output from the server in the console from which you started it. Log into the game either with a mud client on `localhost:4000` or by pointing a web browser to `localhost:4001/webclient`. Log in as your superuser (the user you created during install).
@ -18,16 +18,12 @@ Below, lines starting with a single `>` means command input.
The `py` (or `!` which is an alias) command allows you as a superuser to run raw Python from in-game. From the game's input line, enter the following:
```python
> py print("Hello World!")
```
> py print("Hello World!")
You will see
```
>>> print("Hello world!")
Hello World
```
> print("Hello world!")
Hello World
To understand what is going on: some extra info: The `print(...)` *function* is the basic, in-built way to output text in Python. The quotes `"..."` means you are inputing a *string* (i.e. text). You could also have used single-quotes `'...'`, Python accepts both.
@ -37,10 +33,8 @@ The first return line (with `>>>`) is just `py` echoing what you input (we won't
The `print` command is a standard Python structure. We can use that here in the `py` command, and it's great for debugging and quick testing. But if you need to send a text to an actual player, `print` won't do, because it doesn't know _who_ to send to. Try this:
```python
> py me.msg("Hello world!")
> py me.msg("Hello world!")
Hello world!
```
This looks the same as the `print` result, but we are now actually messaging a specific *object*, `me`. The `me` is something uniquely available in the `py` command (we could also use `self`, it's an alias). It represents "us", the ones calling the `py` command. The `me` is an example of an *Object instance*. Objects are fundamental in Python and Evennia. The `me` object not only represents the character we play in the game, it also contains a lot of useful resources for doing things with that Object. One such resource is `msg`. `msg` works like `print` except it sends the text to the object it is attached to. So if we, for example, had an object `you`, doing `you.msg(...)` would send a message to the object `you`.
@ -147,17 +141,13 @@ Now that we are moving onto multi-line Python code, there are some important thi
First, `reload` your game to make it aware of the updated Python module. Now we have defined our first function, let's use it.
```python
> reload
> py import world.test
```
> reload
> py import world.test
Nothing happened! That is because the function in our module won't do anything just by importing it. It will only act when we *call* it. We will need to enter the module we just imported and do so.
```python
> @py import world.test ; world.test.hello_world(me)
Hello world!
```
> py import world.test ; world.test.hello_world(me)
Hello world!
There is our "Hello World"! The `;` is the way to put multiple Python-statements on one line.

87
docs/source/Python-basic-tutorial-part-two.md
View file

@ -3,41 +3,35 @@
[In the first part](Python-basic-introduction) of this Python-for-Evennia basic tutorial we learned how to run some simple Python code from inside the game. We also made our first new *module* containing a *function* that we called. Now we're going to start exploring the very important subject of *objects*.
**Contents:**
- [On the subject of objects](#on-the-subject-of-objects)
- [Exploring the Evennia library](#exploring-the-evennia-library)
- [Tweaking our Character class](#tweaking-our-character-class)
- [The Evennia shell](#the-evennia-shell)
- [Where to go from here](#where-to-go-from-here)
- [On the subject of objects](Python-basic-tutorial-part-two#on-the-subject-of-objects)
- [Exploring the Evennia library](Python-basic-tutorial-part-two#exploring-the-evennia-library)
- [Tweaking our Character class](Python-basic-tutorial-part-two#tweaking-our-character-class)
- [The Evennia shell](Python-basic-tutorial-part-two#the-evennia-shell)
- [Where to go from here](Python-basic-tutorial-part-two#where-to-go-from-here)
### On the subject of objects
In the first part of the tutorial we did things like
```python
> py me.msg("Hello World!")
```
> py me.msg("Hello World!")
To learn about functions and imports we also passed that `me` on to a function `hello_world` in another module.
Let's learn some more about this `me` thing we are passing around all over the place. In the following we assume that we named our superuser Character "Christine".
```python
> py me
> py me
Christine
> py me.key
> py me.key
Christine
```
These returns look the same at first glance, but not if we examine them more closely:
```python
> py type(me)
> py type(me)
<class 'typeclasses.characters.Character'>
> py type(me.key)
> py type(me.key)
<type str>
```
> Note: In some MU* clients, such as Mudlet and MUSHclient simply returning `type(me)`, you may not see the proper return from the above commands. This is likely due to the HTML-like tags `<...>`, being swallowed by the client.
> Note: In some MU clients, such as Mudlet and MUSHclient simply returning `type(me)`, you may not see the proper return from the above commands. This is likely due to the HTML-like tags `<...>`, being swallowed by the client.
The `type` function is, like `print`, another in-built function in Python. It
tells us that we (`me`) are of the *class* `typeclasses.characters.Character`.
@ -82,6 +76,7 @@ class Character(DefaultCharacter):
(Doc string for class)
"""
pass
```
There is `Character`, the last part of the path. Note how empty this file is. At first glance one would think a Character had no functionality at all. But from what we have used already we know it has at least the `key` property and the method `msg`! Where is the code? The answer is that this 'emptiness' is an illusion caused by something called *inheritance*. Read on.
@ -128,9 +123,9 @@ The structure of the library directly reflects how you import from it.
- You could also do `import evennia`. You would then have to enter the full `evennia.utils.utils.justify(...)` every time you use it. Using `from` to only import the things you need is usually easier and more readable.
- See [this overview](http://effbot.org/zone/import-confusion.htm) about the different ways to import in Python.
Now, remember that our `characters.py` module did `from evennia import DefaultCharacter`. But if we look at the contents of the `evennia` folder, there is no `DefaultCharacter` anywhere! This is because Evennia gives a large number of optional "shortcuts", known as [the "flat" API](https://github.com/evennia/evennia/wiki/Evennia-API). The intention is to make it easier to remember where to find stuff. The flat API is defined in that weirdly named `__init__.py` file. This file just basically imports useful things from all over Evennia so you can more easily find them in one place.
Now, remember that our `characters.py` module did `from evennia import DefaultCharacter`. But if we look at the contents of the `evennia` folder, there is no `DefaultCharacter` anywhere! This is because Evennia gives a large number of optional "shortcuts", known as [the "flat" API](Evennia-API). The intention is to make it easier to remember where to find stuff. The flat API is defined in that weirdly named `__init__.py` file. This file just basically imports useful things from all over Evennia so you can more easily find them in one place.
We could [just look at the documenation](code:evennia#typeclasses) to find out where we can look at our `DefaultCharacter` parent. But for practice, let's figure it out. Here is where `DefaultCharacter` [is imported from](https://github.com/evennia/evennia/blob/master/evennia/__init__.py#L188) inside `__init__.py`:
We could [just look at the documenation](github:evennia#typeclasses) to find out where we can look at our `DefaultCharacter` parent. But for practice, let's figure it out. Here is where `DefaultCharacter` [is imported from](https://github.com/evennia/evennia/blob/master/evennia/__init__.py#L188) inside `__init__.py`:
```python
from .objects.objects import DefaultCharacter
@ -150,18 +145,26 @@ from evennia import DefaultCharacter
is the same thing, just a little easier to remember.
> To access the shortcuts of the flat API you *must* use `from evennia import ...`. Using something like `import evennia.DefaultCharacter` will not work. See [more about the Flat API here](Evennia-API).
> To access the shortcuts of the flat API you *must* use `from evennia import
> ...`. Using something like `import evennia.DefaultCharacter` will not work.
> See [more about the Flat API here](Evennia-API).
### Tweaking our Character class
In the previous section we traced the parent of our `Character` class to be `DefaultCharacter` in [evennia/objects/objects.py](https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py). Open that file and locate the `DefaultCharacter` class. It's quite a bit down in this module so you might want to search using your editor's (or browser's) search function. Once you find it, you'll find that the class starts like this:
In the previous section we traced the parent of our `Character` class to be
`DefaultCharacter` in
[evennia/objects/objects.py](https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py).
Open that file and locate the `DefaultCharacter` class. It's quite a bit down
in this module so you might want to search using your editor's (or browser's)
search function. Once you find it, you'll find that the class starts like this:
```python
class DefaultCharacter(DefaultObject):
"""
This implements an Object puppeted by a Session - that is,
a character avatar controlled by an account.
This implements an Object puppeted by a Session - that is, a character
avatar controlled by an account.
"""
def basetype_setup(self):
@ -173,7 +176,7 @@ class DefaultCharacter(DefaultObject):
Character object works).
"""
super().basetype_setup()
self.locks.add(";".join(["get:false()", # noone can pick up the character
self.locks.add(";".join(["get:false()", # noone can pick up the character
"call:false()"])) # no commands can be called on character from outside
# add the default cmdset
self.cmdset.add_default(settings.CMDSET_CHARACTER, permanent=True)
@ -188,8 +191,10 @@ class DefaultCharacter(DefaultObject):
def at_pre_puppet(self, account, session=None, **kwargs):
"""
Return the character from storage in None location in `at_post_unpuppet`.
Args:
...
"""
# ...
```
... And so on (you can see the full [class online here](https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py#L1915)). Here we have functional code! These methods may not be directly visible in `Character` back in our game dir, but they are still available since `Character` is a child of `DefaultCharacter` above. Here is a brief summary of the methods we find in `DefaultCharacter` (follow in the code to see if you can see roughly where things happen)::
@ -205,14 +210,14 @@ Reading the class we notice another thing:
```python
class DefaultCharacter(DefaultObject):
...
# ...
```
This means that `DefaultCharacter` is in *itself* a child of something called `DefaultObject`! Let's see what this parent class provides. It's in the same module as `DefaultCharacter`, you just need to [scroll up near the top](https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py#L182):
```python
class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
...
# ...
```
This is a really big class where the bulk of code defining an in-game object resides. It consists of a large number of methods, all of which thus also becomes available on the `DefaultCharacter` class below *and* by extension in your `Character` class over in your game dir. In this class you can for example find the `msg` method we have been using before.
@ -243,10 +248,8 @@ As you can see, the first argument to `at_before_say` is `self`. In Python, the
What can trip up newcomers is that you *don't* include `self` when you *call* the method. Try:
```python
> @py me.at_before_say("Hello World!")
Hello World!
```
> @py me.at_before_say("Hello World!")
Hello World!
Note that we don't send `self` but only the `message` argument. Python will automatically add `self` for us. In this case, `self` will become equal to the Character instance `me`.
@ -302,26 +305,20 @@ If you did this call from your game dir you will now be in a Python prompt manag
IPython has some very nice ways to explore what Evennia has to offer.
```python
> import evennia
> evennia.<TAB>
```
> import evennia
> evennia.<TAB>
That is, write `evennia.` and press the Tab key. You will be presented with a list of all available resources in the Evennia Flat API. We looked at the `__init__.py` file in the `evennia` folder earlier, so some of what you see should be familiar. From the IPython prompt, do:
```python
> from evennia import DefaultCharacter
> DefaultCharacter.at_before_say?
```
> from evennia import DefaultCharacter
> DefaultCharacter.at_before_say?
Don't forget that you can use `<TAB>` to auto-complete code as you write. Appending a single `?` to the end will show you the doc-string for `at_before_say` we looked at earlier. Use `??` to get the whole source code.
Let's look at our over-ridden version instead. Since we started the `evennia shell` from our game dir we can easily get to our code too:
```python
> from typeclasses.characters import Character
> Character.at_before_say??
```
> from typeclasses.characters import Character
> Character.at_before_say??
This will show us the changed code we just did. Having a window with IPython running is very convenient for quickly exploring code without having to go digging through the file structure!
@ -333,4 +330,4 @@ We have touched upon many of the concepts here but to use Evennia and to be able
Once you have familiarized yourself, or if you prefer to pick Python up as you go, continue to one of the beginning-level [Evennia tutorials](Tutorials) to gradually build up your understanding.
Good luck!
Good luck!

2
docs/source/Sessions.md
View file

@ -74,7 +74,7 @@ Evennia is split into two parts, the [Portal and the Server](Portal-And-Server).
The "Session" we normally refer to is actually the `ServerSession`. Its counter-part on the Portal side is the `PortalSession`. Whereas the server sessions deal with game states, the portal session deals with details of the connection-protocol itself. The two are also acting as backups of critical data such as when the server reboots.
New Account connections are listened for and handled by the Portal using the [protocols](session-protocols) it understands (such as telnet, ssh, webclient etc). When a new connection is established, a `PortalSession` is created on the Portal side. This session object looks different depending on which protocol is used to connect, but all still have a minimum set of attributes that are generic to all
New Account connections are listened for and handled by the Portal using the [protocols](Portal-And-Server) it understands (such as telnet, ssh, webclient etc). When a new connection is established, a `PortalSession` is created on the Portal side. This session object looks different depending on which protocol is used to connect, but all still have a minimum set of attributes that are generic to all
sessions.
These common properties are piped from the Portal, through the AMP connection, to the Server, which is now informed a new connection has been established. On the Server side, a `ServerSession` object is created to represent this. There is only one type of `ServerSession`; It looks the same regardless of how the Account connects.

6
docs/source/Spawner-and-Prototypes.md
View file

@ -61,7 +61,7 @@ If you wanted to load it into the spawner in-game you could just put all on one
> Note that the prototype dict as given on the command line must be a valid Python structure -
so you need to put quotes around strings etc. For security reasons, a dict inserted from-in game cannot have any
other advanced Python functionality, such as executable code, `lambda` etc. If builders are supposed
to be able to use such features, you need to offer them through [$protfuncs](#protfuncs), embedded runnable functions that you have full control to check and vet before running.
to be able to use such features, you need to offer them through [$protfuncs](Spawner-and-Prototypes#protfuncs), embedded runnable functions that you have full control to check and vet before running.
### Prototype keys
@ -104,7 +104,7 @@ Deprecated as of Evennia 0.8:
- `ndb_<name>` - sets the value of a non-persistent attribute (`"ndb_"` is stripped from the name).
This is simply not useful in a prototype and is deprecated.
- `exec` - This accepts a code snippet or a list of code snippets to run. This should not be used -
use callables or [$protfuncs](#protfuncs) instead (see below).
use callables or [$protfuncs](Spawner-and-Prototypes#protfuncs) instead (see below).
### Prototype values
@ -274,4 +274,4 @@ Note that no `location` will be set automatically when using `evennia.prototypes
have to specify `location` explicitly in the prototype dict.
If the prototypes you supply are using `prototype_parent` keywords, the spawner will read prototypes from modules
in `settings.PROTOTYPE_MODULES` as well as those saved to the database to determine the body of available parents. The `spawn` command takes many optional keywords, you can find its definition [in the api docs](code:evennia.prototypes.spawner#spawn).
in `settings.PROTOTYPE_MODULES` as well as those saved to the database to determine the body of available parents. The `spawn` command takes many optional keywords, you can find its definition [in the api docs](github:evennia.prototypes.spawner#spawn).

4
docs/source/Static-In-Game-Map.md
View file

@ -260,7 +260,7 @@ Log into Evennia as the superuser and run this batchcode. If everything worked o
Now, lets turn our attention towards our game's rooms. Let's use the `return_minimap` method we created above in order to include a minimap in our room descriptions. This is a little more complicated.
By itself we would have to settle for either the map being *above* the description with `room.db.desc = map_string + description_string`, or the map going *below* by reversing their order. Both options are rather unsatisfactory - we would like to have the map next to the text! For this solution we'll explore the utilities that ship with Evennia. Tucked away in `evennia\evennia\utils` is a little module called [EvTable](code:evennia.utils.evtable) . This is an advanced ASCII table creator for you to utilize in your game. We'll use it by creating a basic table with 1 row and two columns (one for our map and one for our text) whilst also hiding the borders. Open the batchfile again
By itself we would have to settle for either the map being *above* the description with `room.db.desc = map_string + description_string`, or the map going *below* by reversing their order. Both options are rather unsatisfactory - we would like to have the map next to the text! For this solution we'll explore the utilities that ship with Evennia. Tucked away in `evennia\evennia\utils` is a little module called [EvTable](github:evennia.utils.evtable) . This is an advanced ASCII table creator for you to utilize in your game. We'll use it by creating a basic table with 1 row and two columns (one for our map and one for our text) whilst also hiding the borders. Open the batchfile again
```python
# mygame\world\batchcode_world.py
@ -334,4 +334,4 @@ Log in to evennia and run `@batchcode batchcode_world` and you'll have a little
You should now have a mapped little world and a basic understanding of batchcode, EvTable and how easily new game defining features can be added to Evennia.
You can easily build from this tutorial by expanding the map and creating more rooms to explore. Why not add more features to your game by trying other tutorials: [Add weather to your world](Weather-Tutorial), [fill your world with NPC's](https://github.com/evennia/evennia/wiki/Tutorial-Aggressive-NPCs) or [implement a combat system](Turn-based-Combat-System).
You can easily build from this tutorial by expanding the map and creating more rooms to explore. Why not add more features to your game by trying other tutorials: [Add weather to your world](Weather-Tutorial), [fill your world with NPC's](Tutorial-Aggressive-NPCs) or [implement a combat system](Turn-based-Combat-System).

10
docs/source/Tutorial-Searching-For-Objects.md
View file

@ -9,7 +9,7 @@ The first thing to consider is the base type of the thing you are searching for.
So to find an entity, what can be searched for?
- The `key` is the name of the entity. While you can get this from `obj.key` the *database field* is actually named `obj.db_key` - this is useful to know only when you do [direct database queries](#queries-in-django). The one exception is `Accounts`, where the database field for `.key` is instead named `username` (this is a Django requirement). When you don't specify search-type, you'll usually search based on key. *Aliases* are extra names given to Objects using something like `@alias` or `obj.aliases.add('name')`. The main search functions (see below) will automatically search for aliases whenever you search by-key.
- The `key` is the name of the entity. While you can get this from `obj.key` the *database field* is actually named `obj.db_key` - this is useful to know only when you do [direct database queries](Tutorial-Searching-For-Objects#queries-in-django). The one exception is `Accounts`, where the database field for `.key` is instead named `username` (this is a Django requirement). When you don't specify search-type, you'll usually search based on key. *Aliases* are extra names given to Objects using something like `@alias` or `obj.aliases.add('name')`. The main search functions (see below) will automatically search for aliases whenever you search by-key.
- [Tags](Tags) are the main way to group and identify objects in Evennia. Tags can most often be used (sometimes together with keys) to uniquely identify an object. For example, even though you have two locations with the same name, you can separate them by their tagging (this is how Evennia implements 'zones' seen in other systems). Tags can also have categories, to further organize your data for quick lookups.
- An object's [Attributes](Attributes) can also used to find an object. This can be very useful but since Attributes can store almost any data they are far less optimized to search for than Tags or keys.
- The object's [Typeclass](Typeclasses) indicate the sub-type of entity. A Character, Flower or Sword are all types of Objects. A Bot is a kind of Account. The database field is called `typeclass_path` and holds the full Python-path to the class. You can usually specify the `typeclass` as an argument to Evennia's search functions as well as use the class directly to limit queries.
@ -57,11 +57,11 @@ class CmdPoke(default_cmds.MuxCommand):
```
By default, the search method of a Character will attempt to find a unique object match for the string sent to it (`self.args`, in this case, which is the arguments passed to the command by the player) in the surroundings of the Character - the room or their inventory. If there is no match found, the return value (which is assigned to `target`) will be `None`, and an appropriate failure message will be sent to the Character. If there's not a unique match, `None` will again be returned, and a different error message will be sent asking them to disambiguate the multi-match. By default, the user can then pick out a specific match using with a number and dash preceding the name of the object: `character.search("2-pink unicorn")` will try to find the second pink unicorn in the room.
The search method has many [arguments](code:evennia.objects.objects#defaultcharactersearch) that allow you to refine the search, such as by designating the location to search in or only matching specific typeclasses.
The search method has many [arguments](github:evennia.objects.objects#defaultcharactersearch) that allow you to refine the search, such as by designating the location to search in or only matching specific typeclasses.
## Searching using `utils.search`
Sometimes you will want to find something that isn't tied to the search methods of a character or account. In these cases, Evennia provides a [utility module with a number of search functions](code:evennia.utils.search). For example, suppose you want a command that will find and display all the rooms that are tagged as a 'hangout', for people to gather by. Here's a simple Command to do this:
Sometimes you will want to find something that isn't tied to the search methods of a character or account. In these cases, Evennia provides a [utility module with a number of search functions](github:evennia.utils.search). For example, suppose you want a command that will find and display all the rooms that are tagged as a 'hangout', for people to gather by. Here's a simple Command to do this:
```python
# e.g. in file mygame/commands/command.py
@ -189,13 +189,13 @@ Here are the most commonly used methods to use with the `objects` managers:
If you pass more than one keyword argument to a query method, the query becomes an `AND` relationship. For example, if we want to find characters whose names start with "A" *and* are also werewolves (have the `lycanthrope` tag), we might do:
```python
queryset = Character.objects.filter(db_key__startswith="A", db_tags__db_key="lycanthrope")`
queryset = Character.objects.filter(db_key__startswith="A", db_tags__db_key="lycanthrope")
```
To exclude lycanthropes currently in rooms tagged as hangouts, we might tack on an `.exclude` as before:
```python
queryset = quersyet.exclude(db_location__db_tags__db_key="hangout")`.
queryset = quersyet.exclude(db_location__db_tags__db_key="hangout")
```
Note the syntax of the keywords in building the queryset. For example, `db_location` is the name of the database field sitting on (in this case) the `Character` (Object). Double underscore `__` works like dot-notation in normal Python (it's used since dots are not allowed in keyword names). So the instruction `db_location__db_tags__db_key="hangout"` should be read as such:

24
docs/source/Tutorials.md
View file

@ -32,12 +32,12 @@ _Starting tutorials for you who are new to developing with Evennia._
- [Python basic introduction](Python-basic-introduction) (part 1) - Python intro using Evennia.
- [Python basic introduction](Python-basic-tutorial-part-two) (part 2) - More on objects, classes and finding where things are.
- [Tutorial: First Steps Coding](https://github.com/evennia/evennia/wiki/First%20Steps%20Coding) - learn each basic feature on their own through step-by-step instruction.
- [Tutorial: First Steps Coding](First-Steps-Coding) - learn each basic feature on their own through step-by-step instruction.
- [Tutorial: A small first game](Tutorial-for-basic-MUSH-like-game) - learn basic features as part of building a small but working game from scratch.
- [Tutorial: Adding new commands](Adding-Command-Tutorial) - focuses specifically on how to add new commands.
- [Tutorial: Parsing command argument](Parsing-command-arguments,-theory-and-best-practices).
- [Tutorial: Adding new objects](Adding-Object-Typeclass-Tutorial) - focuses specifically on how to add new objects.
- [Tutorial: Searching objects in the database](https://github.com/evennia/evennia/wiki/Tutorial-Searching-For-Objects) - how to find existing objects so you can operate on them.
- [Tutorial: Searching objects in the database](Tutorial-Searching-For-Objects) - how to find existing objects so you can operate on them.
### Custom objects and typeclasses
@ -45,13 +45,13 @@ _Starting tutorials for you who are new to developing with Evennia._
_Examples of designing new objects for your game world_
- [Tutorial: Rooms with Weather](Weather-Tutorial)
- [Tutorial: Aggressive NPC's](https://github.com/evennia/evennia/wiki/Tutorial-Aggressive-NPCs)
- [Tutorial: Listening NPC's](https://github.com/evennia/evennia/wiki/Tutorial-NPCs-listening)
- [Tutorial: Creating a vehicle](https://github.com/evennia/evennia/wiki/Tutorial-Vehicles)
- [Tutorial: Aggressive NPC's](Tutorial-Aggressive-NPCs)
- [Tutorial: Listening NPC's](Tutorial-NPCs-listening)
- [Tutorial: Creating a vehicle](Tutorial-Vehicles)
- [Tutorial: Making an NPC shop](NPC-shop-Tutorial) (also advanced [EvMenu](EvMenu) usage)
- [Tutorial: Implementing a Static In Game Map](Static-In-Game-Map) (also [Batch Code](Batch-Code-Processor) usage)
- [Tutorial: Implementing a Dynamic In Game Map](Dynamic-In-Game-Map)
- [Tutorial: Writing your own unit tests](https://github.com/evennia/evennia/wiki/Unit-Testing#testing-for-game-development-mini-tutorial)
- [Tutorial: Writing your own unit tests](Unit-Testing#testing-for-game-development-mini-tutorial)
### Game mechanics tutorials
@ -68,17 +68,17 @@ _Design various game systems and achieve particular effects._
- [FAQ](Coding-FAQ): A place for users to enter their own hints on achieving various goals in Evennia.
- [Tutorial: Adding a Command prompt](Command-Prompt)
- [Tutorial: Creating a Zoning system](Zones)
- [Tutorial: Letting players manually configure color settings](https://github.com/evennia/evennia/wiki/Manually-Configuring-Color)
- [Hints: Asking the user a question and dealing with the result](https://github.com/evennia/evennia/wiki/EvMenu#ask-for-simple-input)
- [Tutorial: Letting players manually configure color settings](Manually-Configuring-Color)
- [Hints: Asking the user a question and dealing with the result](EvMenu#ask-for-simple-input)
- [Hints: Designing commands that take time to finish](Command-Duration)
- [Hints: Adding cooldowns to commands](Command-Cooldown)
- [Tutorial: Mass and weight for objects](Mass-and-weight-for-objects)
- [Hints: Show a different message when trying a non-existent exit](Default-Exit-Errors)
- [Tutorial: Make automatic tweets of game statistics](https://github.com/evennia/evennia/wiki/Tutorial-Tweeting-Game-Stats)
- [Tutorial: Make automatic tweets of game statistics](Tutorial-Tweeting-Game-Stats)
- [Tutorial: Handling virtual time in your game](Gametime-Tutorial)
- [Tutorial: Setting up a coordinate system for rooms](Coordinates)
- [Tutorial: customize the way channels and channel commands work in your game](Customize-channels)
- [Tutorial: Adding unit tests to your game project](https://github.com/evennia/evennia/wiki/Unit-Testing#testing-for-game-development-mini-tutorial)
- [Tutorial: Adding unit tests to your game project](Unit-Testing#testing-for-game-development-mini-tutorial)
### Contrib
@ -99,8 +99,8 @@ _Expanding Evennia's web presence._
- [Tutorial: Build a web page displaying a game character](Web-Character-View-Tutorial) - make a way to view your character on the web page.
- [Tutorial: access your help system from your website](Help-System-Tutorial)
- [Tutorial: add a wiki on your website](Add-a-wiki-on-your-website)
- [Tutorial: Web Character Generation](https://github.com/evennia/evennia/wiki/Web-Character-Generation/) - make a web-based character application form.
- [Tutorial: Bootstrap Components and Utilities](https://github.com/evennia/evennia/wiki/Bootstrap-Components-and-Utilities) - Describes some common Bootstrap Components and Utilities that might help in designing for Evennia
- [Tutorial: Web Character Generation](Web-Character-Generation/) - make a web-based character application form.
- [Tutorial: Bootstrap Components and Utilities](Bootstrap-Components-and-Utilities) - Describes some common Bootstrap Components and Utilities that might help in designing for Evennia
### Evennia for [Engine]-Users

2
docs/source/Typeclasses.md
View file

@ -228,7 +228,7 @@ obj_to_change.swap_typeclass(new_typeclass_path, clean_attributes=False,
run_start_hooks="all", no_default=True, clean_cmdsets=False)
```
The arguments to this method are described [in the API docs here](code:evennia.typeclasses.models#typedobjectswap_typeclass).
The arguments to this method are described [in the API docs here](github:evennia.typeclasses.models#typedobjectswap_typeclass).
## How typeclasses actually work

2
docs/source/Version-Control.md
View file

@ -216,7 +216,7 @@ password <my_github_password>
_Contributing_ can mean both bug-fixes or adding new features to Evennia. Please note that if your change is not already listed and accepted in the [Issue Tracker](https://github.com/evennia/evennia/issues), it is recommended that you first hit the developer mailing list or IRC chat to see beforehand if your feature is deemed suitable to include as a core feature in the engine. When it comes to bug-fixes, other developers may also have good input on how to go about resolving the issue.
To contribute you need to have [forked Evennia](#forking-evennia) first. As described above you should do your modification in a separate local branch (not in the master branch). This branch is what you then present to us (as a *Pull request*, PR, see below). We can then merge your change into the upstream master and you then do `git pull` to update master usual. Now that the master is updated with your fixes, you can safely delete your local work branch. Below we describe this work flow.
To contribute you need to have [forked Evennia](Version-Control#forking-evennia) first. As described above you should do your modification in a separate local branch (not in the master branch). This branch is what you then present to us (as a *Pull request*, PR, see below). We can then merge your change into the upstream master and you then do `git pull` to update master usual. Now that the master is updated with your fixes, you can safely delete your local work branch. Below we describe this work flow.
First update the Evennia master branch to the latest Evennia version:

10
docs/source/Web-Character-Generation.md
View file

@ -51,7 +51,7 @@ Next, navigate to `mygame/server/conf/settings.py` and add or edit the following
After this, we will get into defining our *models* (the description of the database storage), *views* (the server-side website content generators), *urls* (how the web browser finds the pages) and *templates* (how the web page should be structured).
### Checkpoint:
### Installing - Checkpoint:
* you should have a folder named `chargen` or whatever you chose in your mygame/web/ directory
* you should have your application name added to your INSTALLED_APPS in settings.py
@ -92,7 +92,7 @@ class CharApp(models.Model):
You should consider how you are going to link your application to your account. For this tutorial, we are using the account_id attribute on our character application model in order to keep track of which characters are owned by which accounts. Since the account id is a primary key in Evennia, it is a good candidate, as you will never have two of the same IDs in Evennia. You can feel free to use anything else, but for the purposes of this guide, we are going to use account ID to join the character applications with the proper account.
### Checkpoint:
### Model - Checkpoint:
* you should have filled out `mygame/web/chargen/models.py` with the model class shown above (eventually adding fields matching what you need for your game).
@ -293,7 +293,7 @@ def creating(request):
return render(request, 'chargen/create.html', {'form': form})
```
### Checkpoint:
### Create Views - Checkpoint:
* you’ve defined a `views.py` that has an index, detail, and creating functions.
* you’ve defined a forms.py with the `AppForm` class needed by the `creating` function of `views.py`.
@ -344,7 +344,7 @@ urlpatterns += [
urlpatterns = custom_patterns + urlpatterns
```
### Checkpoint:
### URLs - Checkpoint:
* You’ve created a urls.py file in the `mygame/web/chargen` directory
* You have edited the main `mygame/web/urls.py` file to include urls to the `chargen` directory.
@ -432,7 +432,7 @@ Our create HTML template will use the Django form we defined back in views.py/fo
{% endblock %}
```
### Checkpoint:
### Templates - Checkpoint:
* Create a `index.html`, `detail.html` and `create.html` template in your `mygame/web/chargen/templates/chargen` directory

6
docs/source/Webclient-brainstorm.md
View file

@ -154,7 +154,7 @@ For now, good night!
Relates to the activity happening relating to the [Webclient extensions task #614](https://github.com/evennia/evennia/issues/614).
## Griatch Jan 23, 2017
## Griatch Jan 23, 2017 post 2
These are my ideas for the functionality of Evennia's webclient in the (possibly distant) future. It assumes the webclient options have been implemented as per [#1172](https://github.com/evennia/evennia/pull/1172).
@ -214,7 +214,7 @@ The panes themselves can work differently depending on the content though:
logging: do you mean have a "save to log" item in the pane menu?
## Griatch Jan 23, 2017
## Griatch Jan 23, 2017, post 1
It makes sense that different types of panes would have different functionality. I was thinking that something like `inventory` would be very specific to a given game. But titeuf87 has a point - maybe you can get a rather generalized behavior just by defining if a pane should replace or append to the existing data.
@ -248,4 +248,4 @@ I'm trying to figure out where to put each split's configuration - maybe a dropd
I would suggest that, assuming the game dev allows the user to modify their GUI in the first place, that modification is a "mode". I picture that 99% of the time a user doesn't need to modify their interface. They only want to click whatever game-related buttons etc are present in the pane without risk of resizing things accidentally.
So I'd say that normally the panes are all fixed, with minimal spacing between them, no handles etc. But you can enter the client settings window and choose *Customize GUI mode* (or something like that). When you do, then separators get handles and the dropdown menu markers appear (permanently) in the corner of each pane. This means that if a user *wants* to easily tweak their window they could stay in this mode, but they could also "lock" the gui layout at any time.
So I'd say that normally the panes are all fixed, with minimal spacing between them, no handles etc. But you can enter the client settings window and choose *Customize GUI mode* (or something like that). When you do, then separators get handles and the dropdown menu markers appear (permanently) in the corner of each pane. This means that if a user *wants* to easily tweak their window they could stay in this mode, but they could also "lock" the gui layout at any time.

151
docs/source/Wiki-Index.md
View file

@ -1,151 +0,0 @@
# Wiki Index
*This wiki index is automatically generated. Do not modify, your changes will be lost.*
## A-Z
There are 141 entries in the wiki.
- [A voice operated elevator using events](A-voice-operated-elevator-using-events) - Adding-an-elevator-using-the-in-game-Python-system
- [Accounts](Accounts) - This-stores-passwords-and-acts-as-the-'account'-that-controls-in-game-characters.
- [Add a simple new web page](Add-a-simple-new-web-page) - Simple-tutorial-for-getting-going-with-the-web-components-of-evennia
- [Add a wiki on your website](Add-a-wiki-on-your-website) - Add-a-wiki-on-your-website-through-Django-wiki
- [Adding command tutorial](Adding-Command-Tutorial) - First-steps-for-changing-commands.
- [Adding object typeclass tutorial](Adding-Object-Typeclass-Tutorial) - Describes-adding-a-simple-typeclass.
- [Administrative docs](Administrative-Docs) - Administration-section-index.
- [Apache config](Apache-Config) - Optional-info-for-using-Apache-as-a-webserver-instead-of-Evennia's-own.
- [Api refactoring](API-refactoring) - A page about Api refactoring.
- [Arxcode installing help](Arxcode-installing-help) - A page about Arxcode installing help.
- [Async process](Async-Process) - Using-asynchronous-techniques-to-avoid-blocking-the-server-(advanced).
- [Attributes](Attributes) - Used-for-storing-arbitrary-data,-using-for-example-obj.db.name=value.
- [Banning](Banning) - How-to-get-rid-of-unwanted-players.
- [Batch code processor](Batch-Code-Processor) - Running-code-snippets-for-building-by-reading-from-a-text-file.
- [Batch command processor](Batch-Command-Processor) - Running-building-game-commands-from-a-text-file.
- [Batch processors](Batch-Processors) - Overview-of-the-mechanism-for-reading-build-instructions-from-text-files.
- [Bootstrap & evennia](Bootstrap-&-Evennia) - A page about Bootstrap & evennia.
- [Bootstrap components and utilities](Bootstrap-Components-and-Utilities) - A page about Bootstrap components and utilities.
- [Builder docs](Builder-Docs) - Index-for-all-pages-related-to-building-a-game-world.
- [Building a mech tutorial](Building-a-mech-tutorial) - A page about Building a mech tutorial.
- [Building menus](Building-menus) - Describe-building-menus-in-a-tutorial.
- [Building permissions](Building-Permissions) - Changing-account's-access-and-describes-the-permission-hierarchy.
- [Building quickstart](Building-Quickstart) - Introduces-some-basic-commands-and-builds-some-example-objects.
- [Choosing an sql server](Choosing-An-SQL-Server) - Information-about-the-various-database-systems-which-are-supported.
- [Client support grid](Client-Support-Grid) - A page about Client support grid.
- [Coding faq](Coding-FAQ) - A page about Coding faq.
- [Coding introduction](Coding-Introduction) - Some-brief-points-to-think-about-when-starting-to-use-the-system.
- [Coding utils](Coding-Utils) - A-non-complete-list-of-some-of-the-useful-code-utilities-in-src/utils.
- [Command cooldown](Command-Cooldown) - A-tutorial-for-making-commands-that-cannot-be-repeated-until-after-a-cooldown-time-has-passed.
- [Command duration](Command-Duration) - A-tutorial-for-creating-commands-that-take-time-to-complete-(advanced).
- [Command prompt](Command-Prompt) - A-little-hint-for-how-to-add-a-command-prompt-for-players-to-see.
- [Command sets](Command-Sets) - Containers-for-commands,-merges-to-describe-which-commands-are-available-at-any-moment.
- [Command system](Command-System) - A page about Command system.
- [Commands](Commands) - Main-technical-description-of-commands-and-how-they-work.
- [Communications](Communications) - How-to-code-with-Channels,-Messages-and-other-systems-for-sending-info-to-others.
- [Connection screen](Connection-Screen) - Describes-how-to-change-the-connection-screen-you-see-when-first-connecting.
- [Continuous integration](Continuous-Integration) - A page about Continuous integration.
- [Contributing](Contributing) - How-to-help-out-in-the-development-of-Evennia.
- [Coordinates](Coordinates) - A page about Coordinates.
- [Custom protocols](Custom-Protocols) - Implementing-new-server-protocols-(advanced).
- [Customize channels](Customize-channels) - A-tutorial-on-customizing-channel-commands.
- [Debugging](Debugging) - Debugging-code-with-pdb
- [Default command help](Default-Command-Help) - A page about Default command help.
- [Default exit errors](Default-Exit-Errors) - A-tutorial-for-changing-what-error-you-get-when-walking-in-a-non-existing-direction.
- [Developer central](Developer-Central) - Main-hub-for-all-technical-developer-and-coding-information.
- [Dialogues in events](Dialogues-in-events) - Adding-dialogues-using-the-in-game-Python-system
- [Directory overview](Directory-Overview) - Shows-where-everything-is-in-the-codebase.
- [Docs refactoring](Docs-refactoring) - A page about Docs refactoring.
- [Dynamic in game map](Dynamic-In-Game-Map) - Tutorial-for-making-a-dynamically-updating-map
- [Eveditor](EvEditor) - Describes-the-use-of-the-Line-editor
- [Evennia api](Evennia-API) - The-top-level-evennia-API-module.
- [Evennia for diku users](Evennia-for-Diku-Users) - Introduction-of-Evennia-for-users-of-the-Diku-codebase
- [Evennia for mush users](Evennia-for-MUSH-Users) - Soft-introduction-of-Evennia-for-MUSH-users
- [Evennia for roleplaying sessions](Evennia-for-roleplaying-sessions) - A page about Evennia for roleplaying sessions.
- [Evennia game index](Evennia-Game-Index) - Connecting-the-game-to-the-Evennia-game-index
- [Evennia introduction](Evennia-Introduction) - The-first-introduction-to-what-Evennia-is.-You-should-have-read-this-already.
- [Evmenu](EvMenu) - Describes-the-built-in-menu-creation-tool
- [Evmore](EvMore) - Describes-the-pager-utility
- [Execute python code](Execute-Python-Code) - How-to-run-snippets-of-Python-code-from-inside-the-game,-for-testing-and-experimenting.
- [First steps coding](First-Steps-Coding) - Tutorial-describing-the-very-first-steps-for-setting-everything-up-before-you-can-start-to-code.
- [Game planning](Game-Planning) - A-list-of-things-to-think-about-before-jumping-into-making-your-first-game.
- [Gametime tutorial](Gametime-Tutorial) - A-tutorial-on-using-tools-to-handle-game-time.
- [Getting started](Getting-Started) - Explains-how-to-download,-install-and-start-Evennia-for-the-first-time.
- [Glossary](Glossary) - Indexed-explanations-of-common-terms
- [Grapevine](Grapevine) - Connecting-your-game-to-the-Grapevine-chat-network.
- [Guest logins](Guest-Logins) - Setting-up-guest-accounts
- [Haproxy config (optional)](HAProxy-Config-(Optional)) - A page about Haproxy config (optional).
- [Help system](Help-System) - How-to-use-and-add-help-files-to-the-game.
- [Help system tutorial](Help-System-Tutorial) - Create-a-page-to-see-your-game-help-online
- [Home]([Home](index)) - Wiki-front-page.
- [How to connect evennia to twitter](How-to-connect-Evennia-to-Twitter) - Connecting-your-game-to-a-twitter-account.
- [How to get and give help](How-To-Get-And-Give-Help) - Summing-up-how-to-best-get-help-or-give-it.
- [Implementing a game rule system](Implementing-a-game-rule-system) - Tutorial-giving-ideas-about-creating-a-game-rule-system
- [Inputfuncs](Inputfuncs) - These-handle-incoming-requests-from-the-client
- [Installing on android](Installing-on-Android) - Describes-how-to-install-Evennia-on-an-Android-phone
- [Internationalization](Internationalization) - How-to-modify-Evennia's-core-strings-to-use-another-language-than-English.
- [Irc](IRC) - Connecting-your-game-to-an-external-IRC-channel.
- [Learn python for evennia the hard way](Learn-Python-for-Evennia-The-Hard-Way) - A page about Learn python for evennia the hard way.
- [Licensing](Licensing) - Tells-you-how-free-you-are-to-use-Evennia-to-your-personal-whims.-Really!
- [Links](Links) - A-long-list-of-Evennia,-MU*-and-other-game-related-resources.
- [Locks](Locks) - How-to-check-for-access-and-define-what-gives-access-or-not.
- [Manually configuring color](Manually-Configuring-Color) - A-tutorial-on-how-to-make-it-so-players-can-turn-on-and-off-color-in-your-game.
- [Mass and weight for objects](Mass-and-weight-for-objects) - A-tutorial-on-how-to-add-mass-attributes-to-objects-and-calculate-total-weight-of-object-and-its-contents.
- [Messagepath](Messagepath) - Describes-the-path-messages-take-through-the-server
- [Monitorhandler](MonitorHandler) - An-explaination-of-the-monitor-handler-system-to-watch-for-attribute-changes-on-objects
- [New models](New-Models) - Expanding-the-database-with-new-models-(advanced).
- [Nicks](Nicks) - Re-naming-how-to-access-and-find-other-entities,-without-modifying-them.
- [Npc shop tutorial](NPC-shop-Tutorial) - A page about Npc shop tutorial.
- [Objects](Objects) - Describes-the-basic-Object-typeclass,-the-base-for-all-in-game-things.
- [Online setup](Online-Setup) - Goes-through-the-options-for-getting-your-game-visible-online-and-how-to-do-it.
- [Oob](OOB) - A page about Oob.
- [Parsing command arguments, theory and best practices](Parsing-command-arguments,-theory-and-best-practices) - Parsing-command-arguments-best-practices
- [Portal and server](Portal-And-Server) - The-two-processes-that-make-up-the-running-Evennia-server-are-described.
- [Profiling](Profiling) - A page about Profiling.
- [Python 3](Python-3) - A page about Python 3.
- [Python basic introduction](Python-basic-introduction) - A page about Python basic introduction.
- [Python basic tutorial part two](Python-basic-tutorial-part-two) - A page about Python basic tutorial part two.
- [Quirks](Quirks) - Some-less-than-intuitive-things-we-know-people-have-trouble-getting-their-heads-around.
- [Roadmap](Roadmap) - A-tentative-list-of-future-Evennia-milestones
- [Rss](RSS) - How-to-connect-your-game-to-an-external-RSS-feed.
- [Running evennia in docker](Running-Evennia-in-Docker) - A page about Running evennia in docker.
- [Screenshot](Screenshot) - A-screenshot-of-Evennia-running.
- [Scripts](Scripts) - Controls-time-and-can-store-data-that-has-no-in-game-existence.
- [Security](Security) - A page about Security.
- [Server conf](Server-Conf) - Some-things-to-remember-when-dealing-with-the-settings.py-file.
- [Sessions](Sessions) - Summarizes-the-use-of-Sessions.
- [Setting up pycharm](Setting-up-PyCharm) - A page about Setting up pycharm.
- [Signals](Signals) - Signals-fired-at-particular-times
- [Soft code](Soft-Code) - Details-Evennia's-position-on-using-Softcode-along-with-some-history.
- [Spawner and prototypes](Spawner-and-Prototypes) - Describing-how-to-create-objects-with-the-spawner.
- [Start stop reload](Start-Stop-Reload) - How-to-control-the-Server-and-Portal-process-from-the-terminal-and-inside-the-game.
- [Static in game map](Static-In-Game-Map) - Tutorial-for-creating-static-map-view
- [Tags](Tags) - These-are-used-to-quickly-group-and-later-retrieve-game-entities.
- [Text encodings](Text-Encodings) - Technical-discussion-about-how-to-deal-with-text-using-different-character-sets.
- [Texttags](TextTags) - Describes-the-markup-for-adding-colours-and-other-tags-to-text.
- [Tickerhandler](TickerHandler) - Used-to-repeatedly-'tick'-a-method-on-an-Object.
- [Turn based combat system](Turn-based-Combat-System) - Describes-how-to-build-a-combat-system-from-scratch
- [Tutorial aggressive npcs](Tutorial-Aggressive-NPCs) - A-tutorial-on-making-NPC's-do-things-(like-attack)-when-a-character-enters.
- [Tutorial for basic mush like game](Tutorial-for-basic-MUSH-like-game) - A-long-tutorial-for-building-a-simple-MUSH-in-Evennia,-from-scratch.
- [Tutorial npcs listening](Tutorial-NPCs-listening) - A-tutorial-on-making-NPC's-do-things-(like-reply)-when-a-character-says-something.
- [Tutorial searching for objects](Tutorial-Searching-For-Objects) - Searching-For-Objects.
- [Tutorial tweeting game stats](Tutorial-Tweeting-Game-Stats) - A-tutorial-on-tweeting-game-stats-automatically.
- [Tutorial vehicles](Tutorial-Vehicles) - Creating-vehicles
- [Tutorial world introduction](Tutorial-World-Introduction) - This-is-a-small-single-player-quest-with-code-you-can-learn-from.
- [Tutorials](Tutorials) - Overview-of-all-tutorial-type-documentation.
- [Typeclasses](Typeclasses) - The-main-technical-description-of-a-core-concept.-how-Typeclasses-are-used-and-work.
- [Understanding color tags](Understanding-Color-Tags) - A page about Understanding color tags.
- [Unit testing](Unit-Testing) - Describes-how-to-expand-the-code-with-automatic-testing-suites.
- [Updating your game](Updating-Your-Game) - Describes-how-to-update-the-source-from-the-repo-and-how-to-reset-the-database.
- [Using mux as a standard](Using-MUX-as-a-Standard) - A-policy-discussion-about-how-why-the-default-commands-look-the-way-they-do.
- [Using travis](Using-Travis) - A page about Using travis.
- [Version control](Version-Control) - A-tutorial-on-using-version-control-for-your-own-sanity-and-safety.
- [Weather tutorial](Weather-Tutorial) - A-tutorial-on-using-tickers-to-make-days-go-by.
- [Web character generation](Web-Character-Generation) - A-tutorial-for-making-a-web-based-chargen-app-for-your-game.
- [Web character view tutorial](Web-Character-View-Tutorial) - Create-a-new-web-page-displaying-character-info
- [Web features](Web-Features) - Gets-you-started-on-using-Evennia's-web-integration-abilities.
- [Web tutorial](Web-Tutorial) - Gives-examples-on-how-to-customize-the-web-interface.
- [Webclient](Webclient) - A page about Webclient.
- [Webclient brainstorm](Webclient-brainstorm) - A page about Webclient brainstorm.
- [Wiki index](Wiki-Index) - This very index.
- [Zones](Zones) - Using-Tags-to-implement-game-Zones.

15
docs/source/conf.py
View file

@ -144,19 +144,23 @@ smv_branch_whitelist = r"^static-file-docs$|^static-file-dev$"
smv_outputdir_format = "versions" + sep + "{config.release}"
# recommonmark
# reroute to github links or to the api
_github_code_root = "https://github.com/evennia/evennia/blob/master/"
_github_doc_root = "https://github.com/evennia/tree/master/docs/sources/"
_github_issue_choose = "https://github.com/evennia/evennia/issues/new/choose"
# recommonmark
def url_resolver(url):
urlstart = "code:"
urlstart = "github:"
apistart = "api:"
choose_issue = ("feature-request", "report-bug", "issue")
if url.startswith(urlstart):
if url.lower().strip() in choose_issue:
return _github_issue_choose
elif url.startswith(urlstart):
return _github_code_root + url[len(urlstart):]
elif url.startswith(apistart):
return "api/" + url[len(apistart):] + ".html"
@ -164,12 +168,15 @@ def url_resolver(url):
return _github_doc_root + url
# auto-create TOCs if a list of links is under these headers
auto_toc_sections = ["Contents", "Toc", "Index"]
recommonmark_config = {
"enable_auto_toc_tree": True,
"url_resolver": url_resolver,
"auto_toc_tree_section": ["Contents", "Toc", "Index"],
"code_highlight_options": {"force": True,
"linenos": True}
}

6
docs/source/index.md
View file

@ -11,16 +11,16 @@ suggestion box][form]!
There is [a lengthier introduction](Evennia-Introduction) to read. You might also want to read about
[how to get and give help](How-To-Get-And-Give-Help).
| [![Getting Started][icon_new]](Getting-Started)| [![Admin Docs][icon_admin]](Administrative-Docs) | [![Builder Docs][icon_builder]](Builder-Docs) | [![Developer-Central][icon_devel]](Developer-Central) | [![tutorial][icon_tutorial]](Tutorials) | [![API][icon_API]](evennia) |
| [![Getting Started][icon_new]](Getting-Started)| [![Admin Docs][icon_admin]](Administrative-Docs) | [![Builder Docs][icon_builder]](Builder-Docs) | [![Developer-Central][icon_devel]](Developer-Central) | [![tutorial][icon_tutorial]](Tutorials) | [![API][icon_API]](api:evennia) |
|-----------------|----------------------|--------------------------|----------------------|----------------------------|--------------------|
|[Getting Started](Getting-Started)| [Admin Docs](Administrative-Docs) | [Builder Docs](Builder-Docs) | [Developer Central](Developer-Central) | [Tutorials & Examples](Tutorials) | [API](evennia) |
|[Getting Started](Getting-Started)| [Admin Docs](Administrative-Docs) | [Builder Docs](Builder-Docs) | [Developer Central](Developer-Central) | [Tutorials & Examples](Tutorials) | [API](api:evennia) |
- The [Getting Started](Getting-Started) page helps installing and starting Evennia for the first time.
- The [Admin Docs](Administrative-Docs) covers running and maintaining an Evennia server.
- The [Builder Docs](Builder-Docs) helps for starting to build a game world using Evennia.
- The [Developer Central](Developer-Central) describes how Evennia works and is used by coders.
- The [Tutorials & Examples](Tutorials) contains help pages on a step-by-step or tutorial format.
- The [API](evennia) documentation is created from the latest source code.
- The [API](api:evennia) documentation is created from the latest source code.
[search]: https://www.google.com/cse/publicurl?cx=010440404980795145992:6ztkvqc46je
[group]: https://groups.google.com/forum/#%21forum/evennia

1
docs/source/toc.md
View file

@ -139,5 +139,4 @@
* [Web Tutorial](Web-Tutorial.md)
* [Webclient brainstorm](Webclient-brainstorm.md)
* [Webclient](Webclient.md)
* [Wiki Index](Wiki-Index.md)
* [Zones](Zones.md)