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

Refactor 1.0 docs with new toctree structure and inheritance

Browse source
This commit is contained in:
Griatch 2022-02-06 19:27:15 +01:00
parent 62477eac50
commit 628afe9367
142 changed files with 3967 additions and 3024 deletions
Download patch file Download diff file Expand all files Collapse all files

44
docs/pylib/auto_link_remapper.py
View file

@ -38,18 +38,18 @@ TXT_REMAPS = {
}
URL_REMAPS = {
"Developer-Central": "Components/Components-Overview",
"Tutorials": "Howto/Howto-Overview",
"../Howto/Starting/Directory-Overview": "Gamedir-Overview",
"Howto/Starting/Directory-Overview": "Gamedir-Overview",
"Starting/Directory-Overview": "Gamedir-Overview",
"Tutorials": "Howtos/Howtos-Overview",
"../Howtos/Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
"Howtos/Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
"Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
"Directory-Overview": "Gamedir-Overview",
"../Setup/Getting-Started": "Setup-Quickstart",
"Setup/Getting-Started": "Setup-Quickstart",
"Getting-Started": "Setup-Quickstart",
"First-Steps-Coding": "Starting-Part1",
"../Howto/Starting/Adding-Command-Tutorial": "Adding-Commands",
"Howto/Starting/Adding-Command-Tutorial": "Adding-Commands",
"Starting/Adding-Command-Tutorial": "Adding-Commands",
"First-Steps-Coding": "Beginner-Tutorial-Part1",
"../Howtos/Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
"Howtos/Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
"Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
"Adding-Command-Tutorial": "Adding-Commands",
"CmdSet": "Command-Sets",
"Spawner": "Prototypes",
@ -248,26 +248,26 @@ def auto_link_remapper(no_autodoc=False):
print(f" ORPHANED DOC: no refs found to {src_url}.md")
# write tocfile
with open(_TOC_FILE, "w") as fil:
fil.write("```{toctree}\n")
# with open(_TOC_FILE, "w") as fil:
# fil.write("```{toctree}\n")
if not no_autodoc:
fil.write("- [API root](api/evennia-api.rst)")
# if not no_autodoc:
# fil.write("- [API root](api/evennia-api.rst)")
for ref in sorted(toc_map.values()):
# for ref in sorted(toc_map.values()):
if ref == "toc":
continue
# if ref == "toc":
# continue
# if not "/" in ref:
# ref = "./" + ref
# # if not "/" in ref:
# # ref = "./" + ref
# linkname = ref.replace("-", " ")
fil.write(f"\n{ref}") # - [{linkname}]({ref})")
# # linkname = ref.replace("-", " ")
# fil.write(f"\n{ref}") # - [{linkname}]({ref})")
# we add a self-reference so the toc itself is also a part of a toctree
fil.write("\n```\n\n```{toctree}\n :hidden:\n\ntoc\n```")
print(" -- File toc.md updated.")
# # we add a self-reference so the toc itself is also a part of a toctree
# fil.write("\n```\n\n```{toctree}\n :hidden:\n\ntoc\n```")
# print(" -- File toc.md updated.")
print(" -- Auto-Remapper finished.")

38
docs/pylib/contrib_readmes2docs.py
View file

@ -12,8 +12,11 @@ _DOCS_PATH = pathjoin(_EVENNIA_PATH, "docs")
_SOURCE_DIR = pathjoin(_EVENNIA_PATH, "evennia", "contrib")
_OUT_DIR = pathjoin(_DOCS_PATH, "source", "Contribs")
_OUT_INDEX_FILE = pathjoin(_OUT_DIR, "Contrib-Overview.md")
_OUT_INDEX_FILE = pathjoin(_OUT_DIR, "Contribs-Overview.md")
_FILE_STRUCTURE = """{header}
{categories}
{footer}"""
_CATEGORY_DESCS = {
"base_systems": """
@ -79,19 +82,19 @@ If you want to contribute yourself, see [here](Contributing)!
"""
TOCTREE = """
```{{toctree}}
TOCTREE = """```{{toctree}}
:maxdepth: 1
{listing}
```
"""
```"""
CATEGORY = """
## {category}
_{category_desc}_
{toctree}
{blurbs}
@ -168,9 +171,9 @@ def readmes2docs(directory=_SOURCE_DIR):
# build the index with blurbs
lines = [HEADER]
filenames = []
category_sections = []
for category in sorted(categories):
filenames = []
contrib_tups = categories[category]
catlines = []
for tup in sorted(contrib_tups, key=lambda tup: tup[0].lower()):
@ -183,22 +186,23 @@ def readmes2docs(directory=_SOURCE_DIR):
code_location=tup[4]
)
)
filenames.append(f"Contribs{sep}{tup[3]}")
lines.append(
filenames.append(f"{tup[3]}")
toctree = TOCTREE.format(listing="\n".join(filenames))
category_sections.append(
CATEGORY.format(
category=category,
category_desc=_CATEGORY_DESCS[category].strip(),
blurbs="\n".join(catlines)
blurbs="\n".join(catlines),
toctree=toctree
)
)
lines.append(TOCTREE.format(
listing="\n ".join(filenames))
text = _FILE_STRUCTURE.format(
header=HEADER,
categories="\n".join(category_sections),
footer=INDEX_FOOTER
)
lines.append(INDEX_FOOTER)
text = "\n".join(lines)
with open(_OUT_INDEX_FILE, 'w') as fil:
fil.write(text)

2
docs/pylib/update_dynamic_pages.py
View file

@ -17,7 +17,7 @@ def update_changelog():
"""
sourcefile = pathjoin(ROOTDIR, "CHANGELOG.md")
targetfile = pathjoin(DOCSRCDIR, "Setup", "Changelog.md")
targetfile = pathjoin(DOCSRCDIR, "Coding", "Changelog.md")
with open(sourcefile) as fil:
txt = fil.read()

0
docs/source/Setup/Changelog.md → docs/source/Coding/Changelog.md
View file

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

@ -7,14 +7,14 @@ Here are some pointers to get you going.
## Start with the tutorial
It's highly recommended that you jump in on the [Starting Tutorial](../Howto/Starting/Part1/Starting-Part1.md). Even if
It's highly recommended that you jump in on the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md). Even if
you only the beginning or some part of it, it covers much of the things needed to get started.
## Python
Evennia is developed using Python. Even if you are more of a designer than a coder, it is wise to
learn how to read and understand basic Python code. If you are new to Python, or need a refresher,
take a look at our [Python introduction](../Howto/Starting/Part1/Python-basic-introduction.md).
take a look at our [Python introduction](../Howtos/Beginner-Tutorial/Part1/Python-basic-introduction.md).
## Explore Evennia interactively
@ -74,7 +74,7 @@ After this you can import and access all of the Evennia system, same as with `ev
### More exploration
You can complement your exploration by peeking at the sections of the much more detailed
[Evennia Component overview](../Components/Components-Overview.md). The [Tutorials](../Howto/Howto-Overview.md) section also contains a growing collection
[Evennia Component overview](../Components/Components-Overview.md). The [Tutorials](../Howtos/Howtos-Overview.md) section also contains a growing collection
of system- or implementation-specific help.
## Use a python syntax checker
@ -91,7 +91,7 @@ using such a checker can be a good start to weed out the simple problems.
## Plan before you code
Before you start coding away at your dream game, take a look at our [Game Planning](../Howto/Starting/Part2/Game-Planning.md)
Before you start coding away at your dream game, take a look at our [Game Planning](../Howtos/Beginner-Tutorial/Part2/Game-Planning.md)
page. It might hopefully help you avoid some common pitfalls and time sinks.
## Code in your game folder, not in the evennia/ repository

44
docs/source/Coding/Coding-Overview.md
View file

@ -5,26 +5,38 @@ make your game, also if you never coded before. If you are an experienced coder,
to you, but some things may still be useful.
## Find your way
- [Directory-Overview](../Howto/Starting/Part1/Gamedir-Overview.md)
- [Quirks of Evennia](./Quirks.md)
## Setting up a workflow
- [Setting up PyCharm](./Setting-up-PyCharm.md)
- [Using Version-Control](./Version-Control.md)
- [Updating Evennia sources](./Updating-Your-Game.md)
See also the [Beginner Tutorial](../Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md).
```{toctree}
:maxdepth: 2
Version-Control.md
Updating-Your-Game.md
```
## Coding away
- [Coding Introduction](./Coding-Introduction.md)
- [Ways to Debug](./Debugging.md)
- [Adding unit-tests](./Unit-Testing.md)
- [Things to remember when importing from evennia](./Flat-API.md)
```{toctree}
:maxdepth: 2
## Advanced concepts
Coding-Introduction.md
Debugging.md
Unit-Testing.md
Profiling.md
Quirks.md
Changelog.md
- [Continuous Integration](./Continuous-Integration.md)
- [Using Travis](./Using-Travis.md)
- [Profiling](./Profiling.md)
```
## Third-party integrations
```{toctree}
:maxdepth: 2
Continuous-Integration.md
Setting-up-PyCharm.md
```

198
docs/source/Coding/Continuous-Integration-TeamCity.md Normal file
View file

@ -0,0 +1,198 @@
# Continuous Integration - TeamCity (linux)
This sets up a TeamCity build integration environment on Linux.
## Prerequisites
- Follow [TeamCity](https://www.jetbrains.com/teamcity/) 's in-depth
[Setup Guide](https://confluence.jetbrains.com/display/TCD8/Installing+and+Configuring+the+TeamCity+Server).
- You need to use [Version Control](./Version-Control.md).
After meeting the preparation steps for your specific environment, log on to your teamcity interface
at `http://<your server>:8111/`.
Create a new project named "Evennia" and in it construct a new template called `continuous-integration`.
## A Quick Overview
_Templates_ are fancy objects in TeamCity that allow an administrator to define build steps that are
shared between one or more build projects. Assigning a VCS Root (Source Control) is unnecessary at
this stage, primarily you'll be worrying about the build steps and your default parameters (both
visible on the tabs to the left.)
## Template Setup
In this template, you'll be outlining the steps necessary to build your specific game. (A number of
sample scripts are provided under this section below!) Click Build Steps and prepare your general
flow. For this example, we will be doing a few basic example steps:
* Transforming the Settings.py file - We do this to update ports or other information that make your production
environment unique from your development environment.
* Making migrations and migrating the game database.
* Publishing the game files.
* Reloading the server.
For each step we'll being use the "Command Line Runner" (a fancy name for a shell script executor).
Create a build step with the name: "Transform Configuration" and add the script:
```bash
#!/bin/bash
# Replaces the game configuration with one
# appropriate for this deployment.
CONFIG="%system.teamcity.build.checkoutDir%/server/conf/settings.py"
MYCONF="%system.teamcity.build.checkoutDir%/server/conf/my.cnf"
sed -e 's/TELNET_PORTS = [4000]/TELNET_PORTS = [%game.ports%]/g' "$CONFIG" > "$CONFIG".tmp && mv
"$CONFIG".tmp "$CONFIG"
sed -e 's/WEBSERVER_PORTS = [(4001, 4002)]/WEBSERVER_PORTS = [%game.webports%]/g' "$CONFIG" >
"$CONFIG".tmp && mv "$CONFIG".tmp "$CONFIG"
``````
```bash
# settings.py MySQL DB configuration
echo Configuring Game Database...
echo "" >> "$CONFIG"
echo "######################################################################" >> "$CONFIG"
echo "# MySQL Database Configuration" >> "$CONFIG"
echo "######################################################################" >> "$CONFIG"
echo "DATABASES = {" >> "$CONFIG"
echo " 'default': {" >> "$CONFIG"
echo " 'ENGINE': 'django.db.backends.mysql'," >> "$CONFIG"
echo " 'OPTIONS': {" >> "$CONFIG"
echo " 'read_default_file': 'server/conf/my.cnf'," >> "$CONFIG"
echo " }," >> "$CONFIG"
echo " }" >> "$CONFIG"
echo "}" >> "$CONFIG"
# Create the My.CNF file.
echo "[client]" >> "$MYCONF"
echo "database = %mysql.db%" >> "$MYCONF"
echo "user = %mysql.user%" >> "$MYCONF"
echo "password = %mysql.pass%" >> "$MYCONF"
echo "default-character-set = utf8" >> "$MYCONF"
```
If you look at the parameters side of the page after saving this script, you'll notice that some new
parameters have been populated for you. This is because we've included new teamcity configuration
parameters that are populated when the build itself is ran. When creating projects that inherit this
template, we'll be able to fill in or override those parameters for project-specific configuration.
Go ahead and create another build step called "Make Database Migration"
If you're using Sqlite3 for your game (default database), it's prudent to change working directory on this
step to your game dir.
```bash
#!/bin/bash
# Update the DB migration
LOGDIR="server/logs"
. %evenv.dir%/bin/activate
# Check that the logs directory exists.
if [ ! -d "$LOGDIR" ]; then
# Control will enter here if $LOGDIR doesn't exist.
mkdir "$LOGDIR"
fi
evennia makemigrations
```
Create yet another build step, this time named: "Execute Database Migration":
If you're using Sqlite3 for your game (default database), it's prudent to change working directory on this
step to your game dir.
```bash
#!/bin/bash
# Apply the database migration.
LOGDIR="server/logs"
. %evenv.dir%/bin/activate
# Check that the logs directory exists.
if [ ! -d "$LOGDIR" ]; then
# Control will enter here if $LOGDIR doesn't exist.
mkdir "$LOGDIR"
fi
evennia migrate
```
Our next build step is where we actually publish our build. Up until now, all work on game has been
done in a 'work' directory on TeamCity's build agent. From that directory we will now copy our files
to where our game actually exists on the local server.
Create a new build step called "Publish Build". If you're using SQlite3 on your game, be sure to order this step ABOVE
the Database Migration steps. The build order will matter!
```bash
#!/bin/bash
# Publishes the build to the proper build directory.
DIRECTORY="<game_dir>"
if [ ! -d "$DIRECTORY" ]; then
# Control will enter here if $DIRECTORY doesn't exist.
mkdir "$DIRECTORY"
fi
# Copy all the files.
cp -ruv %teamcity.build.checkoutDir%/* "$DIRECTORY"
chmod -R 775 "$DIRECTORY"
```
Finally the last script will reload our game for us.
Create a new script called "Reload Game":
The working directory on this build step will be: `%game.dir%`
```bash
#!/bin/bash
# Apply the database migration.
LOGDIR="server/logs"
PIDDIR="server/server.pid"
. %evenv.dir%/bin/activate
# Check that the logs directory exists.
if [ ! -d "$LOGDIR" ]; then
# Control will enter here if $LOGDIR doesn't exist.
mkdir "$LOGDIR"
fi
# Check that the server is running.
if [ -d "$PIDDIR" ]; then
# Control will enter here if the game is running.
evennia reload
fi
```
Now the template is ready for use! It would be useful this time to revisit the parameters page and
set the evenv parameter to the directory where your virtualenv exists: IE "/srv/mush/evenv".
### Creating the Project
Now it's time for the last few steps to set up a CI environment.
* Return to the Evennia Project overview/administration page.
* Create a new Sub-Project called "Production". This will be the category that holds our actual game.
* Create a new Build Configuration in Production with the name of your MUSH. Base this configuration off of the
continuous-integration template we made earlier.
* In the build configuration, enter VCS roots and create a new VCS root that points to the
branch/version control that you are using.
* Go to the parameters page and fill in the undefined parameters for your specific configuration.
* If you wish for the CI to run every time a commit is made, go to the VCS triggers and add one for
"On Every Commit".
And you're done! At this point, you can return to the project overview page and queue a new build
for your game. If everything was set up correctly, the build will complete successfully. Additional
build steps could be added or removed at this point, adding some features like Unit Testing or more!

30
docs/source/Coding/Using-Travis.md → docs/source/Coding/Continuous-Integration-Travis.md
View file

@ -1,10 +1,11 @@
# Using Travis
# Continuous integration with Travis
Evennia uses [Travis CI](https://travis-ci.org/) to check that it's building successfully after every
commit to its Github repository (you can for example see the `build: passing` badge at the top of
Evennia's [Readme file](https://github.com/evennia/evennia)). If your game is open source on Github
you may also use Travis for free. See [the Travis docs](https://docs.travis-ci.com/user/getting-
started/) for how to get started.
[Travis CI](https://travis-ci.org/) is an online service for checking, validating and potentially
deploying code automatically. It can check that every commit is building successfully after every
commit to its Github repository.
If your game is open source on Github you may use Travis for free.
See [the Travis docs](https://docs.travis-ci.com/user/getting- started/) for how to get started.
After logging in you will get to point Travis to your repository on github. One further thing you
need to set up yourself is a Travis config file named `.travis.yml` (note the initial period `.`).
@ -15,7 +16,7 @@ scratch and then run validation tests on it. Here is an example:
``` yaml
language: python
python:
- "2.7"
- "3.10"
install:
- git clone https://github.com/evennia/evennia.git
- cd evennia
@ -23,15 +24,16 @@ install:
- cd $TRAVIS_BUILD_DIR
script:
- evennia migrate
- evennia test evennia
- evennia test
- evennia test --settings settings.py .
```
This will tell travis how to download Evennia, install it, set up a database and then run the test
suite.
This will tell travis how to download Evennia, install it, set up a database and then run
your own test suite (inside the game dir). Use `evennia test evennia` if you also want to
run the Evennia full test suite.
You need to add this file to git (`git add .travis.yml`) and then commit your changes before Travis
will be able to see it.
For properly testing your game you of course also need to write unittests. [We have a page](Unit-
Testing) on how we set those up for Evennia, you should be able to refer to that for making tests
fitting your game.
For properly testing your game you of course also need to write unittests.
The [Unit testing](./Unit-Testing.md) doc page gives some ideas on how to set those up for Evennia.
You should be able to refer to that for making tests fitting your game.

220
docs/source/Coding/Continuous-Integration.md
View file

@ -1,17 +1,17 @@
# Continuous Integration
One of the advantages of Evennia over traditional MUSH development systems is that Evennia is
capable of integrating into enterprise level integration environments and source control. Because of
this, it can also be the subject of automation for additional convenience, allowing a more
streamlined development environment.
One of the advantages of Evennia over traditional MU* development systems is that Evennia can
integrate into enterprise-level integration environments and source control.
## What is Continuous Integration?
## What is Continuous Integration (CI)?
[Continuous Integration (CI)](https://www.thoughtworks.com/continuous-integration) is a development
practice that requires developers to integrate code into a shared repository several times a day.
Each check-in is then verified by an automated build, allowing teams to detect problems early.
practice that requires developers to integrate code into a shared repository.
Each check-in is then verified by an automated build, allowing teams to detect problems early. This
can be set up to safely deploy data to a production server only after tests have passed, for example.
For Evennia, continuous integration allows an automated build process to:
* Pull down a latest build from Source Control.
* Run migrations on the backing SQL database.
* Automate additional unique tasks for that project.
@ -19,204 +19,18 @@ For Evennia, continuous integration allows an automated build process to:
* Publish those files to the server directory
* Reload the game.
## Preparation
To prepare a CI environment for your `MU*`, it will be necessary to set up some prerequisite
software for your server.
## List of continuous integration tools
Among those you will need:
* A Continuous Integration Environment.
* I recommend [TeamCity](https://www.jetbrains.com/teamcity/) which has an in-depth [Setup
Guide](https://confluence.jetbrains.com/display/TCD8/Installing+and+Configuring+the+TeamCity+Server)
* [Source Control](./Version-Control.md)
* This could be Git or SVN or any other available SC.
There are a lot of tools and services providing CI functionality. Here are a few that people have used
with Evennia:
## Linux TeamCity Setup
For this part of the guide, an example setup will be provided for administrators running a TeamCity
build integration environment on Linux.
```{toctree}
:maxdepth: 1
After meeting the preparation steps for your specific environment, log on to your teamcity interface
at `http://<your server>:8111/`.
Continuous-Integration-Travis.md
Continuous-Integration-TeamCity.md
Create a new project named "Evennia" and in it construct a new template called continuous-
integration.
```
### A Quick Overview
Templates are fancy objects in TeamCity that allow an administrator to define build steps that are
shared between one or more build projects. Assigning a VCS Root (Source Control) is unnecessary at
this stage, primarily you'll be worrying about the build steps and your default parameters (both
visible on the tabs to the left.)
### Template Setup
In this template, you'll be outlining the steps necessary to build your specific game. (A number of
sample scripts are provided under this section below!) Click Build Steps and prepare your general
flow. For this example, we will be doing a few basic example steps:
* Transforming the Settings.py file
* We do this to update ports or other information that make your production environment unique
from your development environment.
* Making migrations and migrating the game database.
* Publishing the game files.
* Reloading the server.
For each step we'll being use the "Command Line Runner" (a fancy name for a shell script executor).
* Create a build step with the name: Transform Configuration
* For the script add:
```bash
#!/bin/bash
# Replaces the game configuration with one
# appropriate for this deployment.
CONFIG="%system.teamcity.build.checkoutDir%/server/conf/settings.py"
MYCONF="%system.teamcity.build.checkoutDir%/server/conf/my.cnf"
sed -e 's/TELNET_PORTS = [4000]/TELNET_PORTS = [%game.ports%]/g' "$CONFIG" > "$CONFIG".tmp && mv
"$CONFIG".tmp "$CONFIG"
sed -e 's/WEBSERVER_PORTS = [(4001, 4002)]/WEBSERVER_PORTS = [%game.webports%]/g' "$CONFIG" >
"$CONFIG".tmp && mv "$CONFIG".tmp "$CONFIG"
# settings.py MySQL DB configuration
echo Configuring Game Database...
echo "" >> "$CONFIG"
echo "######################################################################" >> "$CONFIG"
echo "# MySQL Database Configuration" >> "$CONFIG"
echo "######################################################################" >> "$CONFIG"
echo "DATABASES = {" >> "$CONFIG"
echo " 'default': {" >> "$CONFIG"
echo " 'ENGINE': 'django.db.backends.mysql'," >> "$CONFIG"
echo " 'OPTIONS': {" >> "$CONFIG"
echo " 'read_default_file': 'server/conf/my.cnf'," >> "$CONFIG"
echo " }," >> "$CONFIG"
echo " }" >> "$CONFIG"
echo "}" >> "$CONFIG"
# Create the My.CNF file.
echo "[client]" >> "$MYCONF"
echo "database = %mysql.db%" >> "$MYCONF"
echo "user = %mysql.user%" >> "$MYCONF"
echo "password = %mysql.pass%" >> "$MYCONF"
echo "default-character-set = utf8" >> "$MYCONF"
```
If you look at the parameters side of the page after saving this script, you'll notice that some new
parameters have been populated for you. This is because we've included new teamcity configuration
parameters that are populated when the build itself is ran. When creating projects that inherit this
template, we'll be able to fill in or override those parameters for project-specific configuration.
* Go ahead and create another build step called "Make Database Migration"
* If you're using SQLLite on your game, it will be prudent to change working directory on this
step to: %game.dir%
* In this script include:
```bash
#!/bin/bash
# Update the DB migration
LOGDIR="server/logs"
. %evenv.dir%/bin/activate
# Check that the logs directory exists.
if [ ! -d "$LOGDIR" ]; then
# Control will enter here if $LOGDIR doesn't exist.
mkdir "$LOGDIR"
fi
evennia makemigrations
```
* Create yet another build step, this time named: "Execute Database Migration":
* If you're using SQLLite on your game, it will be prudent to change working directory on this
step to: %game.dir%
```bash
#!/bin/bash
# Apply the database migration.
LOGDIR="server/logs"
. %evenv.dir%/bin/activate
# Check that the logs directory exists.
if [ ! -d "$LOGDIR" ]; then
# Control will enter here if $LOGDIR doesn't exist.
mkdir "$LOGDIR"
fi
evennia migrate
```
Our next build step is where we actually publish our build. Up until now, all work on game has been
done in a 'work' directory on TeamCity's build agent. From that directory we will now copy our files
to where our game actually exists on the local server.
* Create a new build step called "Publish Build":
* If you're using SQLLite on your game, be sure to order this step ABOVE the Database Migration
steps. The build order will matter!
```bash
#!/bin/bash
# Publishes the build to the proper build directory.
DIRECTORY="%game.dir%"
if [ ! -d "$DIRECTORY" ]; then
# Control will enter here if $DIRECTORY doesn't exist.
mkdir "$DIRECTORY"
fi
# Copy all the files.
cp -ruv %teamcity.build.checkoutDir%/* "$DIRECTORY"
chmod -R 775 "$DIRECTORY"
```
Finally the last script will reload our game for us.
* Create a new script called "Reload Game":
* The working directory on this build step will be: %game.dir%
```bash
#!/bin/bash
# Apply the database migration.
LOGDIR="server/logs"
PIDDIR="server/server.pid"
. %evenv.dir%/bin/activate
# Check that the logs directory exists.
if [ ! -d "$LOGDIR" ]; then
# Control will enter here if $LOGDIR doesn't exist.
mkdir "$LOGDIR"
fi
# Check that the server is running.
if [ -d "$PIDDIR" ]; then
# Control will enter here if the game is running.
evennia reload
fi
```
Now the template is ready for use! It would be useful this time to revisit the parameters page and
set the evenv parameter to the directory where your virtualenv exists: IE "/srv/mush/evenv".
### Creating the Project
Now it's time for the last few steps to set up a CI environment.
* Return to the Evennia Project overview/administration page.
* Create a new Sub-Project called "Production"
* This will be the category that holds our actual game.
* Create a new Build Configuration in Production with the name of your MUSH.
* Base this configuration off of the continuous-integration template we made earlier.
* In the build configuration, enter VCS roots and create a new VCS root that points to the
branch/version control that you are using.
* Go to the parameters page and fill in the undefined parameters for your specific configuration.
* If you wish for the CI to run every time a commit is made, go to the VCS triggers and add one for
"On Every Commit".
And you're done! At this point, you can return to the project overview page and queue a new build
for your game. If everything was set up correctly, the build will complete successfully. Additional
build steps could be added or removed at this point, adding some features like Unit Testing or more!
[This is an overview of other tools](https://www.atlassian.com/continuous-delivery/continuous-integration/tools)
(external link).

37
docs/source/Coding/Flat-API.md
View file

@ -1,37 +0,0 @@
# Things to remember about the flat API
The flat API is a series of 'shortcuts' on the `evennia` main library root (defined in
`evennia/__init__.py`). Its componentas are documented [as part of the auto-documentation](../Evennia-API.md).
## To remember when importing from `evennia`
Properties on the root of the `evennia` package are *not* modules in their own right. They are just
shortcut properties stored in the `evennia/__init__.py` module. That means that you cannot use dot-
notation to `import` nested module-names over `evennia`. The rule of thumb is that you cannot use
`import` for more than one level down. Hence you can do
```python
import evennia
print(evennia.default_cmds.CmdLook)
```
or import one level down
```python
from evennia import default_cmds
print(default_cmds.CmdLook)
```
but you *cannot* import two levels down
```python
from evennia.default_cmds import CmdLook # error!
```
This will give you an `ImportError` telling you that the module `default_cmds` cannot be found -
this is becasue `default_cmds` is just a *variable* stored in `evennia.__init__.py`; this cannot be
imported from. If you really want full control over which level of package you import you can always
bypass the root package and import directly from from the real location. For example
`evennia.DefaultObject` is a shortcut to `evennia.objects.objects.DefaultObject`. Using this full
path will have the import mechanism work normally. See `evennia/__init__.py` to see where the
package imports from.

47
docs/source/Coding/Quirks.md
View file

@ -4,7 +4,7 @@
This is a list of various quirks or common stumbling blocks that people often ask about or report
when using (or trying to use) Evennia. They are not bugs.
## Forgetting to use @reload to see changes to your typeclasses
## Forgetting to use `reload` to see changes to your typeclasses
Firstly: Reloading the server is a safe and usually quick operation which will *not* disconnect any
accounts.
@ -104,17 +104,40 @@ can result in very inconsistent and hard-to-diagnose errors.
The moral of the story-- it can be dangerous to tinker with magic methods on typeclassed objects.
Try to avoid doing so.
## Known upstream bugs
## Things to remember about the flat API
- There is currently (Autumn 2017) a bug in the `zope.interface` installer on some Linux Ubuntu
distributions (notably Ubuntu 16.04 LTS). Zope is a dependency of Twisted. The error manifests in
the server not starting with an error that `zope.interface` is not found even though `pip list`
shows it's installed. The reason is a missing empty `__init__.py` file at the root of the zope
package. If the virtualenv is named "evenv" as suggested in the [Setup Quickstart](../Setup/Installation.md)
instructions, use the following command to fix it:
The flat API is a series of 'shortcuts' on the `evennia` main library root (defined in
`evennia/__init__.py`). Its componentas are documented [as part of the auto-documentation](../Evennia-API.md).
```shell
touch evenv/local/lib/python2.7/site-packages/zope/__init__.py
```
### To remember when importing from `evennia`
This will create the missing file and things should henceforth work correctly.
Properties on the root of the `evennia` package are *not* modules in their own right. They are just
shortcut properties stored in the `evennia/__init__.py` module. That means that you cannot use dot-
notation to `import` nested module-names over `evennia`. The rule of thumb is that you cannot use
`import` for more than one level down. Hence you can do
```python
import evennia
print(evennia.default_cmds.CmdLook)
```
or import one level down
```python
from evennia import default_cmds
print(default_cmds.CmdLook)
```
but you *cannot* import two levels down
```python
from evennia.default_cmds import CmdLook # error!
```
This will give you an `ImportError` telling you that the module `default_cmds` cannot be found -
this is becasue `default_cmds` is just a *variable* stored in `evennia.__init__.py`; this cannot be
imported from. If you really want full control over which level of package you import you can always
bypass the root package and import directly from from the real location. For example
`evennia.DefaultObject` is a shortcut to `evennia.objects.objects.DefaultObject`. Using this full
path will have the import mechanism work normally. See `evennia/__init__.py` to see where the
package imports from.

4
docs/source/Coding/Setting-up-PyCharm.md
View file

@ -1,6 +1,4 @@
# Setting up PyCharm
# Directions for setting up PyCharm with Evennia
# Setting up PyCharm with Evennia
[PyCharm](https://www.jetbrains.com/pycharm/) is a Python developer's IDE from Jetbrains available
for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down

2
docs/source/Components/Accounts.md
View file

@ -10,7 +10,7 @@ Exactly how many Sessions can interact with an Account and its Puppets at once i
Evennia's [MULTISESSION_MODE](./Sessions.md#multisession-mode) setting.
Apart from storing login information and other account-specific data, the Account object is what is
chatting on [Channels](./Communications.md). It is also a good place to store [Permissions](./Locks.md) to be
chatting on [Channels](./Channels.md). It is also a good place to store [Permissions](./Locks.md) to be
consistent between different in-game characters as well as configuration options. The Account
object also has its own [CmdSet](./Command-Sets.md), the `AccountCmdSet`.

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

@ -2,8 +2,8 @@
Bootstrap provides many utilities and components you can use when customizing Evennia's web
presence. We'll go over a few examples here that you might find useful.
> Please take a look at either [the basic web tutorial](../Howto/Starting/Part5/Add-a-simple-new-web-page.md) or
>[the web character view tutorial](../Howto/Web-Character-View-Tutorial.md)
> Please take a look at either [the basic web tutorial](../Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md) or
>[the web character view tutorial](../Howtos/Web-Character-View-Tutorial.md)
> to get a feel for how to add pages to Evennia's website to test these examples.
## General Styling
@ -77,4 +77,4 @@ width of the page - Evennia's base site uses the former.
### 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.](../Howto/Web-Character-Generation.md)
over [the web character gen tutorial.](../Howtos/Web-Character-Generation.md)

6
docs/source/Components/Command-Sets.md
View file

@ -26,7 +26,7 @@ on. The tutorial world included with Evennia showcases a dark room that replaces
commands with its own versions because the Character cannot see.
If you want a quick start into defining your first commands and using them with command sets, you
can head over to the [Adding Command Tutorial](../Howto/Starting/Part1/Adding-Commands.md) which steps through things
can head over to the [Adding Command Tutorial](../Howtos/Beginner-Tutorial/Part1/Adding-Commands.md) which steps through things
without the explanations.
## Defining Command Sets
@ -112,7 +112,7 @@ back even if all other cmdsets fail or are removed. It is always persistent and
by `cmdset.delete()`. To remove a default cmdset you must explicitly call `cmdset.remove_default()`.
Command sets are often added to an object in its `at_object_creation` method. For more examples of
adding commands, read the [Step by step tutorial](../Howto/Starting/Part1/Adding-Commands.md). Generally you can
adding commands, read the [Step by step tutorial](../Howtos/Beginner-Tutorial/Part1/Adding-Commands.md). Generally you can
customize which command sets are added to your objects by using `self.cmdset.add()` or
`self.cmdset.add_default()`.
@ -215,7 +215,7 @@ included if `no_objs` option is active in the merge stack.
`no_objs` option is active in the merge stack.
- The cmdsets of Exits in the location. Merge priority `+101`. Will not be included if `no_exits`
*or* `no_objs` option is active in the merge stack.
- The [channel](./Communications.md) cmdset containing commands for posting to all channels the account
- The [channel](./Channels.md) cmdset containing commands for posting to all channels the account
or character is currently connected to. Merge priority `+101`. Will not be included if `no_channels`
option is active in the merge stack.

2
docs/source/Components/Command-System.md
View file

@ -6,4 +6,4 @@
See also:
- [Default Commands](./Default-Commands.md)
- [Adding Command Tutorial](../Howto/Starting/Part1/Adding-Commands.md)
- [Adding Command Tutorial](../Howtos/Beginner-Tutorial/Part1/Adding-Commands.md)

6
docs/source/Components/Commands.md
View file

@ -29,7 +29,7 @@ object in various ways. Consider a "Tree" object with a cmdset defining the comm
This page goes into full detail about how to use Commands. To fully use them you must also read the
page detailing [Command Sets](./Command-Sets.md). There is also a step-by-step
[Adding Command Tutorial](../Howto/Starting/Part1/Adding-Commands.md) that will get you started quickly without the
[Adding Command Tutorial](../Howtos/Beginner-Tutorial/Part1/Adding-Commands.md) that will get you started quickly without the
extra explanations.
## Defining Commands
@ -392,7 +392,7 @@ class CmdWait(Command):
def func(self):
"""Command execution."""
self.msg("Starting to wait ...")
self.msg("Beginner-Tutorial to wait ...")
yield 5
self.msg("... This shows after 5 seconds. Waiting ...")
yield 2
@ -484,7 +484,7 @@ display the "Huh?" error message.
matches.
- User is not allowed to execute the command (`syscmdkeys.CMD_NOPERM`) - Default is to display the
"Huh?" error message.
- Channel (`syscmdkeys.CMD_CHANNEL`) - This is a [Channel](./Communications.md) name of a channel you are
- Channel (`syscmdkeys.CMD_CHANNEL`) - This is a [Channel](./Channels.md) name of a channel you are
subscribing to - Default is to relay the command's argument to that channel. Such commands are
created by the Comm system on the fly depending on your subscriptions.
- New session connection (`syscmdkeys.CMD_LOGINSTART`). This command name should be put in the

8
docs/source/Components/Communications.md
View file

@ -1,8 +0,0 @@
# Communications
TODO: Remove this page?
- [Channels](./Channels.md) - are used for implementing in-game chat rooms.
- [Msg](./Msg.md)-objects are used for storing messages in the database (email-like)
and is a building block for implementing other game systems. It's used by the
`page` command by default.

108
docs/source/Components/Components-Overview.md
View file

@ -5,50 +5,82 @@ than, the doc-strings of each component in the [API](../Evennia-API.md).
## Database entites
- [Typeclasses](./Typeclasses.md)
- [Sessions](./Sessions.md)
- [Acccounts](./Accounts.md)
- [Guests](../Concepts/Guest-Logins.md)
- [Objects](./Objects.md)
- [Scripts](./Scripts.md)
- [Channels and Messages](./Communications.md)
- [Attributes](./Attributes.md)
- [Nicks](./Nicks.md)
- [Tags](./Tags.md)
- [Spawner and prototypes](./Prototypes.md)
- [Help entries](./Help-System.md)
```{toctree}
:maxdepth: 2
Typeclasses.md
Sessions.md
Accounts.md
Objects.md
Scripts.md
Channels.md
Msg.md
Attributes.md
Nicks.md
Tags.md
Prototypes.md
Help-System.md
Permissions.md
```
## Commands
- [Available Default Commands](./Default-Commands.md)
- [Command system](./Command-System.md)
- [Commands](./Commands.md)
- [Command-Sets](./Command-Sets.md)
- [The Connection Screen](./Connection-Screen.md)
- [Batch-Processors](./Batch-Processors.md)
- [Batch-Code-Processor](./Batch-Code-Processor.md)
- [Batch-Command-Processor](./Batch-Command-Processor.md)
```{toctree}
:maxdepth: 2
Command-System.md
Commands.md
Command-Sets.md
Default-Commands.md
Connection-Screen.md
Batch-Processors.md
Batch-Code-Processor.md
Batch-Command-Processor.md
```
## Utils and tools
- [Misc Utils](./Coding-Utils.md)
- [EvEditor](./EvEditor.md)
- [EvMenu](./EvMenu.md)
- [EvMore](./EvMore.md)
- [MonitorHandler](./MonitorHandler.md)
- [TickerHandler](./TickerHandler.md)
- [Lock system](./Locks.md)
- [FuncParser](./FuncParser.md)
```{toctree}
:maxdepth: 2
Coding-Utils.md
EvEditor.md
EvMenu.md
EvMore.md
MonitorHandler.md
TickerHandler.md
Locks.md
FuncParser.md
```
## Web components
```{toctree}
:maxdepth: 2
Website.md
Web-API.md
Web-Admin.md
```
## Server and network
- [Portal](./Portal-And-Server.md)
- [Inputfuncs](./Inputfuncs.md)
- [Outputfuncs](./Outputfuncs.md)
- [Protocols](../Concepts/Custom-Protocols.md)
- [Server](./Server.md)
- [Server conf object](../Setup/Server-Conf.md)
- [Webserver](./Webserver.md)
- [Webclient](./Webclient.md)
- [Bootstrap](./Bootstrap-Components-and-Utilities.md)
- [Signals](./Signals.md)
```{toctree}
:maxdepth: 2
Portal-And-Server.md
Inputfuncs.md
Outputfuncs.md
Server.md
Setup/Server-Conf.md
Webserver.md
Webclient.md
Bootstrap-Components-and-Utilities.md
Signals.md
```

2
docs/source/Components/EvMenu.md
View file

@ -1115,7 +1115,7 @@ function - for example you can't use other Python keywords like `if` inside the
Unless you are dealing with a relatively simple dynamic menu, defining menus with lambda's is
probably more work than it's worth: You can create dynamic menus by instead making each node
function more clever. See the [NPC shop tutorial](../Howto/NPC-shop-Tutorial.md) for an example of this.
function more clever. See the [NPC shop tutorial](../Howtos/NPC-shop-Tutorial.md) for an example of this.
## Ask for simple input

2
docs/source/Components/Nicks.md
View file

@ -101,7 +101,7 @@ offers effective error checking, searches and conversion.
In a command definition you can reach the nick handler through `self.caller.nicks`. See the `nick`
command in `evennia/commands/default/general.py` for more examples.
As a last note, The Evennia [channel](./Communications.md) alias systems are using nicks with the
As a last note, The Evennia [channel](./Channels.md) alias systems are using nicks with the
`nick_type="channel"` in order to allow users to create their own custom aliases to channels.
# Advanced note

2
docs/source/Components/Tags.md
View file

@ -53,7 +53,7 @@ free up the *category* property for any use you desire.
## Adding/Removing Tags
You can tag any *typeclassed* object, namely [Objects](./Objects.md), [Accounts](./Accounts.md),
[Scripts](./Scripts.md) and [Channels](./Communications.md). General tags are added by the *Taghandler*. The
[Scripts](./Scripts.md) and [Channels](./Channels.md). General tags are added by the *Taghandler*. The
tag handler is accessed as a property `tags` on the relevant entity:
```python

2
docs/source/Components/TickerHandler.md
View file

@ -104,7 +104,7 @@ may store.
When testing, you can stop all tickers in the entire game with `tickerhandler.clear()`. You can also
view the currently subscribed objects with `tickerhandler.all()`.
See the [Weather Tutorial](../Howto/Weather-Tutorial.md) for an example of using the TickerHandler.
See the [Weather Tutorial](../Howtos/Weather-Tutorial.md) for an example of using the TickerHandler.
### When *not* to use TickerHandler

9
docs/source/Components/Typeclasses.md
View file

@ -1,7 +1,6 @@
# Typeclasses
*Typeclasses* form the core of Evennia data storage. It allows Evennia to represent any number of
*Typeclasses* form the core of Evennia's data storage. It allows Evennia to represent any number of
different game entities as Python classes, without having to modify the database schema for every
new type.
@ -193,7 +192,7 @@ database.
Each of the typeclassed entities then extend this list with their own properties. Go to the
respective pages for [Objects](./Objects.md), [Scripts](./Scripts.md), [Accounts](./Accounts.md) and
[Channels](./Communications.md) for more info. It's also recommended that you explore the available
[Channels](./Channels.md) for more info. It's also recommended that you explore the available
entities using [Evennia's flat API](../Evennia-API.md) to explore which properties and methods they have
available.
@ -245,7 +244,7 @@ matches = ScriptDB.objects.filter(db_key__contains="Combat")
When querying from the database model parent you don't need to use `filter_family` or `get_family` -
you will always query all children on the database model.
# Updating existing typeclass instances
## Updating existing typeclass instances
If you already have created instances of Typeclasses, you can modify the *Python code* at any time -
due to how Python inheritance works your changes will automatically be applied to all children once
@ -317,7 +316,7 @@ The arguments to this method are described [in the API docs
here](github:evennia.typeclasses.models#typedobjectswap_typeclass).
# How typeclasses actually work
## How typeclasses actually work
*This is considered an advanced section.*

2
docs/source/Concepts/Async-Process.md
View file

@ -139,7 +139,7 @@ sleep.
```
This will delay the execution of the callback for 10 seconds. This function is explored much more in
the [Command Duration Tutorial](../Howto/Command-Duration.md).
the [Command Duration Tutorial](../Howtos/Command-Duration.md).
You can also try the following snippet just see how it works:

4
docs/source/Concepts/Colors.md
View file

@ -14,7 +14,7 @@ equipment by people who are blind or have otherwise diminished eyesight.
So a good rule of thumb is to use colour to enhance your game but don't *rely* on it to display
critical information. If you are coding the game, you can add functionality to let users disable
colours as they please, as described [here](../Howto/Manually-Configuring-Color.md).
colours as they please, as described [here](../Howtos/Manually-Configuring-Color.md).
To see which colours your client support, use the default `@color` command. This will list all
available colours for ANSI and Xterm256 along with the codes you use for them. You can find a list
@ -178,6 +178,6 @@ to activate some features manually.
## More reading
There is an [Understanding Color Tags](../Howto/Understanding-Color-Tags.md) tutorial which expands on the
There is an [Understanding Color Tags](../Howtos/Understanding-Color-Tags.md) tutorial which expands on the
use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags in the same context.

59
docs/source/Concepts/Concepts-Overview.md
View file

@ -4,28 +4,59 @@ This documentation cover more over-arching concepts of Evennia, often involving
## General concepts
- [Asynchronous processing](./Async-Process.md)
- [On Soft-Code](./Soft-Code.md)
- [Using MUX as standard for default commands](./Using-MUX-as-a-Standard.md)
```{toctree}
:maxdepth: 2
Async-Process.md
Soft-Code.md
Using-MUX-as-a-Standard.md
Messagepath.md
OOB.md
```
## Access
- [Multisession modes](./Multisession-modes.md)
- [Permissions](./Building-Permissions.md)
- [Banning](./Banning.md)
```{toctree}
:maxdepth: 2
Multisession-modes.md
Building-Permissions.md
Guest-Logins.md
Banning.md
```
## Extending the Server
- [Custom Protocols](./Custom-Protocols.md)
- [Bootstrap](./Bootstrap-&-Evennia.md)
- [Creating new models](./New-Models.md)
```{toctree}
:maxdepth: 2
Custom-Protocols.md
Bootstrap-&-Evennia.md
New-Models.md
Zones.md
```
## Text processing
```{toctree}
:maxdepth: 2
Internationalization.md
Text-Encodings.md
TextTags.md
Change-Messages-Per-Receiver.md
Clickable-Links.md
Colors.md
```
- [Change the language of the server](./Internationalization.md)
- [Server text-encoding](./Text-Encodings.md)
- [Text tags](./TextTags.md)
- [Change Messages Per receiver](./Change-Messages-Per-Receiver.md)
## Web features
```{toctree}
:maxdepth: 2
Web-Features.md
```
- [Web features](./Web-Features.md)

2
docs/source/Concepts/Web-Features.md
View file

@ -42,7 +42,7 @@ Example: To override or modify `evennia/web/website/template/website/index.html`
add/modify `mygame/web/template_overrides/website/index.html`.
The detailed description on how to customize the website is best described in tutorial form. See the
[Web Tutorial](../Howto/Starting/Part5/Web-Tutorial.md) for more information.
[Web Tutorial](../Howtos/Beginner-Tutorial/Part5/Web-Tutorial.md) for more information.
### Overloading Django views

1233
docs/source/Contribs/Building-menus.md
View file

File diff suppressed because it is too large Load diff

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

@ -29,7 +29,7 @@ of storage space on S3, making the current total cost of running this plugin
them to many users, caveat emptor on a total cost of ownership - check AWS's
pricing structure.
# Technical details
## Technical details
This is a drop-in replacement that operates deeper than all of Evennia's code,
so your existing code does not need to change at all to support it.
@ -52,9 +52,9 @@ other contributions or custom code. Simply work how you would normally, Django
will handle the rest.
# Installation
## Installation
## Set up AWS account
### Set up AWS account
If you don't have an AWS S3 account, you should create one at
https://aws.amazon.com/ - documentation for AWS S3 is available at:
@ -161,7 +161,7 @@ checking the source of any image (for instance, the logo). It should read
`https://your-bucket-name.s3.amazonaws.com/path/to/file`. If so, the system
works and you shouldn't need to do anything else.
# Uninstallation
## Uninstallation
If you haven't made changes to your static files (uploaded images, etc),
you can simply remove the lines you added to `secret_settings.py`. If you
@ -170,7 +170,7 @@ your files from your S3 bucket and put them in /static/ in the evennia
directory.
# License
## License
Draws heavily from code provided by django-storages, for which these contributors
are authors:
@ -221,7 +221,7 @@ Andrew Perry (Bug fixes in SFTPStorage)
The repurposed code from django-storages is released under BSD 3-Clause,
same as Evennia, so for detailed licensing, refer to the Evennia license.
# Versioning
## Versioning
This is confirmed to work for Django 2 and Django 3.

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

File diff suppressed because it is too large Load diff

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

@ -1,9 +1,9 @@
# Color markups
# Additional Color markups
Contrib by Griatch, 2017
Additional color markup styles for Evennia (extending or replacing the default
`|r`, `|234`). Adds support for MUSH-style (`%cr`, `%c123`) and/or legacy-Evennia
`|r`, `|234`). Adds support for MUSH-style (`%cr`, `%c123`) and/or legacy-Evennia
(`{r`, `{123`).

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

@ -3,8 +3,8 @@
Contribution by owllex, 2021
Cooldowns are used to model rate-limited actions, like how often a
character can perform a given action; until a certain time has passed their
command can not be used again. This contrib provides a simple cooldown
character can perform a given action; until a certain time has passed their
command can not be used again. This contrib provides a simple cooldown
handler that can be attached to any typeclass. A cooldown is a lightweight persistent
asynchronous timer that you can query to see if a certain time has yet passed.
@ -38,7 +38,7 @@ def cooldowns(self):
return CooldownHandler(self, db_attribute="cooldowns")
```
# Example
## Example
Assuming you've installed cooldowns on your Character typeclasses, you can use a
cooldown to limit how often you can perform a command. The following code

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

@ -3,7 +3,7 @@
Contrib by vlgeoff, 2017 - based on Griatch's core original
This reimplements the `evennia.utils.gametime` module but with a _custom_
calendar (unusual number of days per week/month/year etc) for your game world.
calendar (unusual number of days per week/month/year etc) for your game world.
Like the original, it allows for scheduling events to happen at given
in-game times, but now taking this custom calendar into account.

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

@ -1,14 +1,14 @@
# Dice
# Dice roller
Contribution by Griatch, 2012
A dice roller for any number and side of dice. Adds in-game dice rolling
(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target)
and functions for rolling dice in code. Command also supports hidden or secret
A dice roller for any number and side of dice. Adds in-game dice rolling
(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target)
and functions for rolling dice in code. Command also supports hidden or secret
rolls for use by a human game master.
# Installation:
## Installation:
Add the `CmdDice` command from this module to your character's cmdset
@ -28,7 +28,7 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
```
# Usage:
## Usage:
> roll 1d100 + 2
> roll 1d20
@ -53,7 +53,7 @@ was.
Is a hidden roll that does not inform the room it happened.
## Rolling dice from code
### Rolling dice from code
To roll dice in code, use the `roll` function from this module:

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

@ -3,7 +3,7 @@
Contrib by Griatch, 2012
This is a variant of the login system that asks for an email-address
instead of a username to login. Note that it does not verify the email,
instead of a username to login. Note that it does not verify the email,
it just uses it as the identifier rather than a username.
This used to be the default Evennia login before replacing it with a

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

@ -2,10 +2,10 @@
Contribution by Griatch, 2019
A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
spawn and join puzzle rooms that track their state independently. Any number of players
can join to solve a room together. This is the engine created for 'EvscapeRoom', which won
the MUD Coders Guild "One Room" Game Jam in April-May, 2019. The contrib has no game
A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
spawn and join puzzle rooms that track their state independently. Any number of players
can join to solve a room together. This is the engine created for 'EvscapeRoom', which won
the MUD Coders Guild "One Room" Game Jam in April-May, 2019. The contrib has no game
content but contains the utilities and base classes and an empty example room.
The original code for the contest is found at
@ -16,13 +16,13 @@ instead. A copy of the full game can also be played on the Evennia demo server
at https://demo.evennia.com - just connect to the server and write `evscaperoom`
in the first room to start!
# Introduction
## Introduction
Evscaperoom is, as it sounds, an escaperoom in text form. You start locked into
a room and have to figure out how to get out. This engine contains everything
needed to make a fully-featured puzzle game of this type!
# Installation
## Installation
The Evscaperoom is installed by adding the `evscaperoom` command to your
character cmdset. When you run that command in-game you're ready to play!
@ -44,7 +44,7 @@ class CharacterCmdSet(...):
Reload the server and the `evscaperoom` command will be available. The contrib
comes with a small (very small) escape room as an example.
# Making your own evscaperoom
## Making your own evscaperoom
To do this, you need to make your own states. First make sure you can play the
simple example room installed above.
@ -63,7 +63,7 @@ the following to your `mygame/server/conf/settings.py` file:
Reload and the example evscaperoom should still work, but you can now modify and
expand it from your game dir!
## Other useful settings
### Other useful settings
There are a few other settings that may be useful:
@ -74,7 +74,7 @@ There are a few other settings that may be useful:
the room without an argument. The original is found at the top of
`evennia/contrib/full_systems/evscaperoom/commands.py`.
# Playing the game
## Playing the game
You should start by `look`ing around and at objects.
@ -87,7 +87,7 @@ focus.
There is also a full hint system.
# Technical
## Technical
When connecting to the game, the user has the option to join an existing room
(which may already be in some state of ongoing progress), or may create a fresh
@ -102,7 +102,7 @@ the logic and (in principle) inject new puzzles later.
Once no players remain in the room, the room and its state will be wiped.
# Design Philosophy
## Design Philosophy
Some basic premises inspired the design of this.

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

@ -17,10 +17,39 @@ An object can have the following genders:
## Installation
Import and add the `SetGender` command to your default cmdset in
`mygame/commands/default_cmdset.py`
`mygame/commands/default_cmdset.py`:
```python
# mygame/commands/default_cmdsets.py
# ...
from evennia.contrib.game_systems.gendersub import SetGender # <---
# ...
class CharacterCmdSet(default_cmds.CharacterCmdSet):
# ...
def at_cmdset_creation(self):
# ...
self.add(SetGender()) # <---
```
Make your `Character` inherit from `GenderCharacter`.
```python
# mygame/typeclasses/characters.py
# ...
from evennia.contrib.game_systems.gendersub import GenderCharacter # <---
class Character(GenderCharacter): # <---
# ...
```
Reload the server (`evennia reload` or `reload` from inside the game).
## Usage

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

@ -3,8 +3,8 @@
Contribution by Tim Ashley Jenkins, 2017
The function provided in this module lets you easily display visual
bars or meters as a colorful bar instead of just a number. A "health bar"
is merely the most obvious use for this, but the bar is highly customizable
bars or meters as a colorful bar instead of just a number. A "health bar"
is merely the most obvious use for this, but the bar is highly customizable
and can be used for any sort of appropriate data besides player health.
Today's players may be more used to seeing statistics like health,

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

@ -895,6 +895,15 @@ The in-game Python system will still be accessible (you will have access to the
but no event will be called automatically.
```{toctree}
:hidden:
Contrib-Ingame-Python-Tutorial-Dialogue
Contrib-Ingame-Python-Tutorial-Elevator
```
----
<small>This document page is generated from `evennia/contrib/base_systems/ingame_python/README.md`. Changes to this

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

@ -4,7 +4,7 @@ Contribution by grungies1138 2016
A simple Brandymail style mail system that uses the `Msg` class from Evennia
Core. It has two Commands for either sending mails between Accounts (out of game)
or between Characters (in-game). The two types of mails can be used together or
or between Characters (in-game). The two types of mails can be used together or
on their own.
- `CmdMail` - this should sit on the Account cmdset and makes the `mail` command
@ -21,27 +21,28 @@ Install one or both of the following (see above):
- CmdMail (IC + OOC mail, sent between players)
```python
# mygame/commands/default_cmds.py
from evennia.contrib.game_systems import mail
# in AccountCmdSet.at_cmdset_creation:
self.add(mail.CmdMail())
```
- CmdMailCharacter (optional, IC only mail, sent between characters)
```python
# mygame/commands/default_cmds.py
from evennia.contrib.game_systems import mail
# in CharacterCmdSet.at_cmdset_creation:
self.add(mail.CmdMailCharacter())
```
Once installed, use `help mail` in game for help with the mail command. Use
ic/ooc to switch in and out of IC/OOC modes.
----
<small>This document page is generated from `evennia/contrib/game_systems/mail/README.md`. Changes to this

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

@ -52,7 +52,7 @@ references to rooms previously created is passed to the build commands.
You then call the command in-game using the path to the MAP and MAP_LEGEND vars
The path you provide is relative to the evennia or mygame folder.
# Installation
## Installation
Use by importing and including the command in your default_cmdsets module.
For example:
@ -68,14 +68,14 @@ For example:
```
# Usage:
## Usage:
mapbuilder[/switch] <path.to.file.MAPNAME> <path.to.file.MAP_LEGEND>
one - execute build instructions once without automatic exit creation.
two - execute build instructions twice without automatic exit creation.
# Examples
## Examples
mapbuilder world.gamemap.MAP world.maplegend.MAP_LEGEND
mapbuilder evennia.contrib.grid.mapbuilder.EXAMPLE1_MAP EXAMPLE1_LEGEND
@ -86,7 +86,7 @@ Below are two examples showcasing the use of automatic exit generation and
custom exit generation. Whilst located, and can be used, from this module for
convenience The below example code should be in mymap.py in mygame/world.
## Example One
### Example One
```python
@ -190,7 +190,7 @@ EXAMPLE1_LEGEND = {
}
```
## Example Two
### Example Two
```python
# @mapbuilder/two evennia.contrib.grid.mapbuilder.EXAMPLE2_MAP EXAMPLE2_LEGEND

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

@ -1,9 +1,9 @@
# Unix-like Command style parent
# Unix-like Command style
Contribution by Vincent Le Geoff (vlgeoff), 2017
This module contains a command class with an alternate syntax parser implementing
Unix-style command syntax in-game. This means `--options`, positional arguments
This module contains a command class with an alternate syntax parser implementing
Unix-style command syntax in-game. This means `--options`, positional arguments
and stuff like `-n 10`. It might not the best syntax for the average player
but can be really useful for builders when they need to have a single command do
many things with many options. It uses the `ArgumentParser` from Python's standard

153
docs/source/Contribs/Contrib-Overview.md → docs/source/Contribs/Contribs-Overview.md
View file

@ -25,6 +25,20 @@ _This category contains systems that are not necessarily tied to a specific
in-game mechanic but is useful for the game as a whole. Examples include
login systems, new command syntaxes, and build helpers._
```{toctree}
:maxdepth: 1
Contrib-AWSStorage.md
Contrib-Building-Menu.md
Contrib-Color-Markups.md
Contrib-Custom-Gametime.md
Contrib-Email-Login.md
Contrib-Ingame-Python.md
Contrib-Menu-Login.md
Contrib-Mux-Comms-Cmds.md
Contrib-Unixcommand.md
```
### Contrib: `awsstorage`
@ -58,7 +72,7 @@ that will edit any default object, offering to change its key and description.
_Contrib by Griatch, 2017_
Additional color markup styles for Evennia (extending or replacing the default
`|r`, `|234`). Adds support for MUSH-style (`%cr`, `%c123`) and/or legacy-Evennia
`|r`, `|234`). Adds support for MUSH-style (`%cr`, `%c123`) and/or legacy-Evennia
(`{r`, `{123`).
[Read the documentation](./Contrib-Color-Markups.md) - [Browse the Code](evennia.contrib.base_systems.color_markups)
@ -70,7 +84,7 @@ Additional color markup styles for Evennia (extending or replacing the default
_Contrib by vlgeoff, 2017 - based on Griatch's core original_
This reimplements the `evennia.utils.gametime` module but with a _custom_
calendar (unusual number of days per week/month/year etc) for your game world.
calendar (unusual number of days per week/month/year etc) for your game world.
Like the original, it allows for scheduling events to happen at given
in-game times, but now taking this custom calendar into account.
@ -83,7 +97,7 @@ in-game times, but now taking this custom calendar into account.
_Contrib by Griatch, 2012_
This is a variant of the login system that asks for an email-address
instead of a username to login. Note that it does not verify the email,
instead of a username to login. Note that it does not verify the email,
it just uses it as the identifier rather than a username.
[Read the documentation](./Contrib-Email-Login.md) - [Browse the Code](evennia.contrib.base_systems.email_login)
@ -137,8 +151,8 @@ main `channel` command is still called under the hood.
_Contribution by Vincent Le Geoff (vlgeoff), 2017_
This module contains a command class with an alternate syntax parser implementing
Unix-style command syntax in-game. This means `--options`, positional arguments
This module contains a command class with an alternate syntax parser implementing
Unix-style command syntax in-game. This means `--options`, positional arguments
and stuff like `-n 10`. It might not the best syntax for the average player
but can be really useful for builders when they need to have a single command do
many things with many options. It uses the `ArgumentParser` from Python's standard
@ -156,15 +170,21 @@ library under the hood.
_This category contains 'complete' game engines that can be used directly
to start creating content without no further additions (unless you want to)._
```{toctree}
:maxdepth: 1
Contrib-Evscaperoom.md
```
### Contrib: `evscaperoom`
_Contribution by Griatch, 2019_
A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
spawn and join puzzle rooms that track their state independently. Any number of players
can join to solve a room together. This is the engine created for 'EvscapeRoom', which won
the MUD Coders Guild "One Room" Game Jam in April-May, 2019. The contrib has no game
A full engine for creating multiplayer escape-rooms in Evennia. Allows players to
spawn and join puzzle rooms that track their state independently. Any number of players
can join to solve a room together. This is the engine created for 'EvscapeRoom', which won
the MUD Coders Guild "One Room" Game Jam in April-May, 2019. The contrib has no game
content but contains the utilities and base classes and an empty example room.
[Read the documentation](./Contrib-Evscaperoom.md) - [Browse the Code](evennia.contrib.full_systems.evscaperoom)
@ -181,6 +201,20 @@ crafting, mail, combat and more. Each system is meant to be adopted
piecemeal and adopted for your game. This does not include
roleplaying-specific systems, those are found in the `rpg` folder._
```{toctree}
:maxdepth: 1
Contrib-Barter.md
Contrib-Clothing.md
Contrib-Cooldowns.md
Contrib-Crafting.md
Contrib-Gendersub.md
Contrib-Mail.md
Contrib-Multidescer.md
Contrib-Puzzles.md
Contrib-Turnbattle.md
```
### Contrib: `barter`
@ -214,8 +248,8 @@ look of these clothes are appended to the character's description when worn.
_Contribution by owllex, 2021_
Cooldowns are used to model rate-limited actions, like how often a
character can perform a given action; until a certain time has passed their
command can not be used again. This contrib provides a simple cooldown
character can perform a given action; until a certain time has passed their
command can not be used again. This contrib provides a simple cooldown
handler that can be attached to any typeclass. A cooldown is a lightweight persistent
asynchronous timer that you can query to see if a certain time has yet passed.
@ -255,7 +289,7 @@ _Contribution by grungies1138 2016_
A simple Brandymail style mail system that uses the `Msg` class from Evennia
Core. It has two Commands for either sending mails between Accounts (out of game)
or between Characters (in-game). The two types of mails can be used together or
or between Characters (in-game). The two types of mails can be used together or
on their own.
[Read the documentation](./Contrib-Mail.md) - [Browse the Code](evennia.contrib.game_systems.mail)
@ -314,6 +348,17 @@ the participants until the fight ends.
_Systems related to the game world's topology and structure. This has
contribs related to rooms, exits and map building._
```{toctree}
:maxdepth: 1
Contrib-Extended-Room.md
Contrib-Mapbuilder.md
Contrib-Simpledoor.md
Contrib-Slow-Exit.md
Contrib-Wilderness.md
Contrib-XYZGrid.md
```
### Contrib: `extended_room`
@ -399,14 +444,23 @@ current location (useful for displaying the grid as an in-game, updating map).
_These are systems specifically related to roleplaying
and rule implementation like character traits, dice rolling and emoting._
```{toctree}
:maxdepth: 1
Contrib-Dice.md
Contrib-Health-Bar.md
Contrib-RPSystem.md
Contrib-Traits.md
```
### Contrib: `dice`
_Contribution by Griatch, 2012_
A dice roller for any number and side of dice. Adds in-game dice rolling
(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target)
and functions for rolling dice in code. Command also supports hidden or secret
A dice roller for any number and side of dice. Adds in-game dice rolling
(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target)
and functions for rolling dice in code. Command also supports hidden or secret
rolls for use by a human game master.
[Read the documentation](./Contrib-Dice.md) - [Browse the Code](evennia.contrib.rpg.dice)
@ -418,8 +472,8 @@ rolls for use by a human game master.
_Contribution by Tim Ashley Jenkins, 2017_
The function provided in this module lets you easily display visual
bars or meters as a colorful bar instead of just a number. A "health bar"
is merely the most obvious use for this, but the bar is highly customizable
bars or meters as a colorful bar instead of just a number. A "health bar"
is merely the most obvious use for this, but the bar is highly customizable
and can be used for any sort of appropriate data besides player health.
[Read the documentation](./Contrib-Health-Bar.md) - [Browse the Code](evennia.contrib.rpg.health_bar)
@ -467,6 +521,17 @@ _Helper resources specifically meant to teach a development concept or
to exemplify an Evennia system. Any extra resources tied to documentation
tutorials are found here. Also the home of the Tutorial World demo adventure._
```{toctree}
:maxdepth: 1
Contrib-Batchprocessor.md
Contrib-Bodyfunctions.md
Contrib-Mirror.md
Contrib-Red-Button.md
Contrib-Talking-Npc.md
Contrib-Tutorial-World.md
```
### Contrib: `batchprocessor`
@ -547,6 +612,15 @@ is a great way to start learning the system.
_Miscellaneous, optional tools for manipulating text, auditing connections
and more._
```{toctree}
:maxdepth: 1
Contrib-Auditing.md
Contrib-Fieldfill.md
Contrib-Random-String-Generator.md
Contrib-Tree-Select.md
```
### Contrib: `auditing`
@ -603,51 +677,6 @@ instance from a multi-line string passed to one function.
```{toctree}
Contribs/Contrib-AWSStorage.md
Contribs/Contrib-Building-Menu.md
Contribs/Contrib-Color-Markups.md
Contribs/Contrib-Custom-Gametime.md
Contribs/Contrib-Email-Login.md
Contribs/Contrib-Ingame-Python.md
Contribs/Contrib-Menu-Login.md
Contribs/Contrib-Mux-Comms-Cmds.md
Contribs/Contrib-Unixcommand.md
Contribs/Contrib-Evscaperoom.md
Contribs/Contrib-Barter.md
Contribs/Contrib-Clothing.md
Contribs/Contrib-Cooldowns.md
Contribs/Contrib-Crafting.md
Contribs/Contrib-Gendersub.md
Contribs/Contrib-Mail.md
Contribs/Contrib-Multidescer.md
Contribs/Contrib-Puzzles.md
Contribs/Contrib-Turnbattle.md
Contribs/Contrib-Extended-Room.md
Contribs/Contrib-Mapbuilder.md
Contribs/Contrib-Simpledoor.md
Contribs/Contrib-Slow-Exit.md
Contribs/Contrib-Wilderness.md
Contribs/Contrib-XYZGrid.md
Contribs/Contrib-Dice.md
Contribs/Contrib-Health-Bar.md
Contribs/Contrib-RPSystem.md
Contribs/Contrib-Traits.md
Contribs/Contrib-Batchprocessor.md
Contribs/Contrib-Bodyfunctions.md
Contribs/Contrib-Mirror.md
Contribs/Contrib-Red-Button.md
Contribs/Contrib-Talking-Npc.md
Contribs/Contrib-Tutorial-World.md
Contribs/Contrib-Auditing.md
Contribs/Contrib-Fieldfill.md
Contribs/Contrib-Random-String-Generator.md
Contribs/Contrib-Tree-Select.md
```
----

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

@ -56,19 +56,19 @@ primarily be accessed as link refs (e.g. `Component/Accounts`)
the Evennia version on a new branch.
# Editing syntax
## Editing syntax
The format used for Evennia's docs is [Markdown][commonmark-help] (Commonmark). While markdown
supports a few alternative forms for some of these, we try to stick to the below forms for consistency.
## Italic/Bold
### Italic/Bold
We generally use underscores for italics and double-asterisks for bold:
- `_Italic text_` - _Italic text_
- `**Bold Text**` - **Bold text**
## Headings
### Headings
We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get
smaller and smaller font).
@ -82,7 +82,7 @@ smaller and smaller font).
does not prevent it, it will make it impossible to refer to that heading uniquely.
The Evennia documentation preparser will detect this and give you an error.
## Lists
### Lists
One can create both bullet-point lists and numbered lists:
@ -106,7 +106,7 @@ One can create both bullet-point lists and numbered lists:
2. Numbered point two
3. Numbered point three
## Blockquotes
### Blockquotes
A blockquote will create an indented block. It's useful for emphasis and is
added by starting one or more lines with `>`. For 'notes' you can also use
@ -120,11 +120,11 @@ an explicit [Note](#note).
> Note: This is an important
> thing to remember.
## Links
### Links
The link syntax is `[linktext](url_or_ref)` - this gives a clickable link [linktext](#links).
### Internal links
#### Internal links
Most links will be to other pages of the documentation or to Evennia's API docs. Each document
heading can be referenced. The reference always starts with `#`. The heading-name is always
@ -156,7 +156,7 @@ Some more text...
> It's fine to not include the `.md` file ending in the reference. The Evennia doc-build process
> will correct for this (and also insert any needed relative paths in the reference).
### API links
#### API links
The documentation contains auto-generated documentation for all of Evennia's source code. You
can direct the reader to the sources by just giving the python-path to the location of the
@ -169,7 +169,7 @@ resource under the `evennia/` repository:
Note that you can't refer to files in the `mygame` folder this way. The game folder is generated
dynamically and is not part of the api docs. Refer to the parent classes in `evennia` where possible.
### External links
#### External links
These are links to resources outside of the documentation. We also provide some convenient shortcuts.
@ -202,7 +202,7 @@ This is a [clickable link][mylink]. This is [another link][1].
This makes the main text a little shorter.
## Tables
### Tables
A table is done like this:
@ -224,7 +224,7 @@ As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up
include the heading separators and make sure to add the correct number of `|` on every line.
## Verbatim text
### Verbatim text
It's common to want to mark something to be displayed verbatim - just as written - without any
Markdown parsing. In running text, this is done using backticks (\`), like \`verbatim text\` becomes
@ -330,7 +330,7 @@ evennia/ mygame/
evennia start --log
## MyST directives
### MyST directives
Markdown is easy to read and use. But while it does most of what we need, there are some things it's
not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is
@ -365,7 +365,7 @@ Also the important/warning notes indents like this.
```
### Important
#### Important
This is for particularly important and visible notes.
@ -379,7 +379,7 @@ This is for particularly important and visible notes.
This is important because it is!
```
### Warning
#### Warning
A warning block is used to draw attention to particularly dangerous things, or features easy to
mess up.
@ -394,7 +394,7 @@ mess up.
Be careful about this ...
```
### Version changes and deprecations
#### Version changes and deprecations
These will show up as one-line warnings that suggest an added, changed or deprecated
feature beginning with particular version.
@ -425,7 +425,7 @@ feature beginning with particular version.
```{deprecated} 1.0
```
### Sidebar
#### Sidebar
This will display an informative sidebar that floats to the side of regular content. This is useful
for example to remind the reader of some concept relevant to the text.
@ -461,7 +461,7 @@ squeezed to the left of the sidebar), one can embed a plain HTML string in the m
<div style="clear: right;"></div>
### A more flexible code block
#### A more flexible code block
The regular Markdown Python codeblock is usually enough but for more direct control over the style, one
can also use the `{code-block}` directive that takes a set of additional `:options:`:
@ -506,7 +506,7 @@ block through the link that will appear (so it should be unique for a given docu
### eval-rst directive
#### eval-rst directive
As a last resort, we can also fall back to writing [ReST][ReST] directives directly:
@ -552,7 +552,7 @@ make us able to express more complex displays than plain Markdown can.
For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon]
extension to understand our friendly Google-style docstrings used in classes and functions etc.
# Building the docs locally
## Building the docs locally
The sources in `evennia/docs/source/` are built into a documentation using the
[Sphinx][sphinx] static generator system. To do this locally you need to use a
@ -713,7 +713,6 @@ After deployment finishes, the updated live documentation will be
available at https://evennia.github.io/evennia/latest/.
[sphinx]: https://www.sphinx-doc.org/en/master/
[MyST]: https://myst-parser.readthedocs.io/en/latest/syntax/reference.html
[commonmark]: https://spec.commonmark.org/current/
@ -729,4 +728,4 @@ available at https://evennia.github.io/evennia/latest/.
[linkdemo]: #Links
[retext]: https://github.com/retext-project/retext
[grip]: https://github.com/joeyespo/grip
[pycharm]: https://www.jetbrains.com/pycharm/
[pycharm]: https://www.jetbrains.com/pycharm/

6
docs/source/Contributing.md
View file

@ -29,7 +29,7 @@ great help!
we don't know about them, we can't fix them!
- If you want to help edit the docs directly, [check here](./Contributing-Docs.md)
on how to do it.
- If you have knowledge to share, how about writing a new [Tutorial](Howto/Howto-Overview.md)?
- If you have knowledge to share, how about writing a new [Tutorial](Howtos/Howtos-Overview.md)?
## Helping with code
@ -80,7 +80,7 @@ like [Pastebin](https://pastebin.com/) and just supply the link.
### Making an Evennia contrib
Evennia has a [contrib](Contribs/Contrib-Overview.md) directory which contains
Evennia has a [contrib](Contribs/Contribs-Overview.md) directory which contains
user-shared code organized by category. You can contribute anything that you
think may be useful to another dev, also highly game-specific code. A contrib
must always be added via a forked respository.
@ -118,7 +118,7 @@ must always be added via a forked respository.
it easier to access them (this may vary though).
The `README.md` will be parsed and converted into a document linked from
[the contrib overview page](Contribs/Contrib-Overview.md). It should follow
[the contrib overview page](Contribs/Contribs-Overview.md). It should follow
the following structure:
```markdown

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

@ -24,7 +24,7 @@ The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__
### Main config
- [evennia.settings_default](github:evennia/settings_default.py) - all settings (modify/override in `mygame/server/settings.py`)
- [evennia.settings_default](Settings-Default) - all settings (modify/override in `mygame/server/settings.py`)
### Search functions
@ -98,3 +98,9 @@ The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__
- [evennia.contrib](https://github.com/evennia/evennia/blob/master/evennia/contrib/) -
game-specific contributions and plugins ([docs](https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md))
```{toctree}
:hidden:
api/evennia-api.md
```

14
docs/source/Evennia-Introduction.md
View file

@ -26,7 +26,7 @@ Evennia is *fully persistent*, that means things you drop on the ground somewher
there a dozen server reboots later. Through Django we support a large variety of different database
systems (a database is created for you automatically if you use the defaults).
We also include a growing list of *optional* [contribs](Contribs/Contrib-Overview.md) you can use for your game
We also include a growing list of *optional* [contribs](Contribs/Contribs-Overview.md) you can use for your game
would you want something to build from.
Using the full power of Python throughout the server offers some distinct advantages. All your
@ -49,7 +49,7 @@ connect to the demo via your telnet client you can do so at `demo.evennia.com`,
Once you installed Evennia yourself it comes with its own tutorial - this shows off some of the
possibilities _and_ gives you a small single-player quest to play. The tutorial takes only one
single in-game command to install as explained [here](Howto/Starting/Part1/Tutorial-World.md).
single in-game command to install as explained [here](Howtos/Beginner-Tutorial/Part1/Tutorial-World.md).
## What you need to know to work with Evennia
@ -71,8 +71,8 @@ Evennia's source code is extensively documented and is [viewable
online](https://github.com/evennia/evennia). We also have a comprehensive [online
manual](https://evennia.com/docs) with lots of examples. But while Python is
considered a very easy programming language to get into, you do have a learning curve to climb if
you are new to programming. Evennia's [Starting-tutorial](Howto/Starting/Part1/Starting-Part1.md) has a [basic introduction
to Python](Howto/Starting/Part1/Python-basic-introduction.md) but you should probably also sit down
you are new to programming. Evennia's [Starting-tutorial](Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) has a [basic introduction
to Python](Howtos/Beginner-Tutorial/Part1/Python-basic-introduction.md) but you should probably also sit down
with a full Python beginner's tutorial at some point (there are plenty of them on
the web if you look around). See also our [link
page](./Links.md) for some reading suggestions. To efficiently code your dream game in
@ -111,7 +111,7 @@ presence (a website and a mud web client) to play around with ...
### Where to from here?
From here you can continue browsing the [online documentation](./index.md) to
find more info about Evennia. Or you can jump into the [Tutorials](Howto/Howto-Overview.md) and get your hands
find more info about Evennia. Or you can jump into the [Tutorials](Howtos/Howtos-Overview.md) and get your hands
dirty with code right away. You can also read the lead developer's [dev blog](https://evennia.blogspot.com/) for many tidbits and snippets about Evennia's development and
structure.
@ -124,9 +124,9 @@ chat](https://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE
on IRC. This allows you to chat directly with other developers new and old as well as with the devs
of Evennia itself. This chat is logged (you can find links on https://www.evennia.com) and can also
be searched from the same place for discussion topics you are interested in.
2. Read the [Game Planning](Howto/Starting/Part2/Game-Planning.md) wiki page. It gives some ideas for your work flow and the
2. Read the [Game Planning](Howtos/Beginner-Tutorial/Part2/Game-Planning.md) wiki page. It gives some ideas for your work flow and the
state of mind you should aim for - including cutting down the scope of your game for its first
release.
3. Do the [Tutorial for basic MUSH-like game](Howto/Starting/Part3/Tutorial-for-basic-MUSH-like-game.md) carefully from
3. Do the [Tutorial for basic MUSH-like game](Howtos/Tutorial-for-basic-MUSH-like-game.md) carefully from
beginning to end and try to understand what does what. Even if you are not interested in a MUSH for
your own game, you will end up with a small (very small) game that you can build or learn from.

4
docs/source/Glossary.md
View file

@ -100,7 +100,7 @@ There is usually no need to know the details of Django's database handling in or
it will handle most of the complexity for you under the hood using what we call
[typeclasses](./Glossary.md#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](Howto/Starting/Part1/Searching-Things.md). One will then need
offered by Evennia's [default search functions](Howtos/Beginner-Tutorial/Part1/Searching-Things.md). 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-
@ -129,7 +129,7 @@ core. Better make it a contrib.
## _contrib_
Game-specific code and examples are distributed in evennia's [contribs/](Contribs/Contrib-Overview.md) folder.
Game-specific code and examples are distributed in evennia's [contribs/](Contribs/Contribs-Overview.md) folder.
This is game-specific, optional code created by the Evennia community.
## _field_

122
docs/source/Howto/Default-Exit-Errors.md
View file

@ -1,122 +0,0 @@
# Default Exit Errors
Evennia allows for exits to have any name. The command "kitchen" is a valid exit name as well as
"jump out the window" or "north". An exit actually consists of two parts: an [Exit Object](../Components/Objects.md)
and an [Exit Command](../Components/Commands.md) stored on said exit object. The command has the same key and aliases
as the object, which is why you can see the exit in the room and just write its name to traverse it.
If you try to enter the name of a non-existing exit, it is thus the same as trying a non-exising
command; Evennia doesn't care about the difference:
> jump out the window
Command 'jump out the window' is not available. Type "help" for help.
Many games don't need this type of freedom however. They define only the cardinal directions as
valid exit names (Evennia's `@tunnel` command also offers this functionality). In this case, the
error starts to look less logical:
> west
Command 'west' is not available. Maybe you meant "@set" or "@reset"?
Since we for our particular game *know* that west is an exit direction, it would be better if the
error message just told us that we couldn't go there.
## Adding default error commands
To solve this you need to be aware of how to [write and add new commands](Starting/Part1/Adding-Commands.md).
What you need to do is to create new commands for all directions you want to support in your game.
In this example all we'll do is echo an error message, but you could certainly consider more
advanced uses. You add these commands to the default command set. Here is an example of such a set
of commands:
```python
# for example in a file mygame/commands/movecommands.py
from evennia import default_cmds
class CmdExitError(default_cmds.MuxCommand):
"Parent class for all exit-errors."
locks = "cmd:all()"
arg_regex = r"\s|$"
auto_help = False
def func(self):
"returns the error"
self.caller.msg(f"You cannot move {self.key}.")
class CmdExitErrorNorth(CmdExitError):
key = "north"
aliases = ["n"]
class CmdExitErrorEast(CmdExitError):
key = "east"
aliases = ["e"]
class CmdExitErrorSouth(CmdExitError):
key = "south"
aliases = ["s"]
class CmdExitErrorWest(CmdExitError):
key = "west"
aliases = ["w"]
```
Make sure to add the directional commands (not their parent) to the `CharacterCmdSet` class in
`mygame/commands/default_cmdsets.py`:
```python
# in mygame/commands/default_cmdsets.py
from commands import movecommands
# [...]
class CharacterCmdSet(default_cmds.CharacterCmdSet):
# [...]
def at_cmdset_creation(self):
# [...]
self.add(movecommands.CmdExitErrorNorth())
self.add(movecommands.CmdExitErrorEast())
self.add(movecommands.CmdExitErrorSouth())
self.add(movecommands.CmdExitErrorWest())
```
After a `@reload` these commands (assuming you don't get any errors - check your log) will be
loaded. What happens henceforth is that if you are in a room with an Exitobject (let's say it's
"north"), the proper Exit-command will overload your error command (also named "north"). But if you
enter an direction without having a matching exit for it, you will fallback to your default error
commands:
> east
You cannot move east.
Further expansions by the exit system (including manipulating the way the Exit command itself is
created) can be done by modifying the [Exit typeclass](../Components/Typeclasses.md) directly.
## Additional Comments
So why didn't we create a single error command above? Something like this:
```python
class CmdExitError(default_cmds.MuxCommand):
"Handles all exit-errors."
key = "error_cmd"
aliases = ["north", "n",
"east", "e",
"south", "s",
"west", "w"]
#[...]
```
The anwer is that this would *not* work and understanding why is important in order to not be
confused when working with commands and command sets.
The reason it doesn't work is because Evennia's [command system](../Components/Commands.md) compares commands *both*
by `key` and by `aliases`. If *either* of those match, the two commands are considered *identical*
as far as cmdset merging system is concerned.
So the above example would work fine as long as there were no Exits at all in the room. But what
happens when we enter a room with an exit "north"? The Exit's cmdset is merged onto the default one,
and since there is an alias match, the system determines our `CmdExitError` to be identical. It is
thus overloaded by the Exit command (which also correctly defaults to a higher priority). The result
is that you can go through the north exit normally but none of the error messages for the other
directions are available since the single error command was completely overloaded by the single
matching "north" exit-command.

105
docs/source/Howto/Howto-Overview.md
View file

@ -1,105 +0,0 @@
# Tutorials and Howto's
The documents in this section aims to teach how to use Evennia in a tutorial or
a step-by-step way. They often give hints on about solving a problem or implementing
a particular feature or concept. They will often refer to the
[components](../Components/Components-Overview.md) or [concepts](../Concepts/Concepts-Overview.md)
docs for those that want to dive deeper.
## The Starting Tutorial
Recommended starting point! This will take you from absolute beginner to making
a small, but full, game with Evennia. Even if you have a very different game style
in mind for your own game, this will give you a good start.
### Part 1: What we have
1. [Introduction & Overview](Starting/Part1/Starting-Part1.md)
1. [Building stuff](Starting/Part1/Building-Quickstart.md)
1. [The Tutorial World](Starting/Part1/Tutorial-World.md)
1. [Python basics](Starting/Part1/Python-basic-introduction.md)
1. [Game dir overview](Starting/Part1/Gamedir-Overview.md)
1. [Python classes and objects](Starting/Part1/Python-classes-and-objects.md)
1. [Accessing the Evennia library](Starting/Part1/Evennia-Library-Overview.md)
1. [Typeclasses - Persistent objects](Starting/Part1/Learning-Typeclasses.md)
1. [Making our first own commands](Starting/Part1/Adding-Commands.md)
1. [Parsing and replacing default Commands](Starting/Part1/More-on-Commands.md)
1. [Creating things](Starting/Part1/Creating-Things.md)
1. [Searching for things](Starting/Part1/Searching-Things.md)
1. [Advanced searching with Django queries](Starting/Part1/Django-queries.md)
### Part 2: What we want
1. [Introduction & Overview](Starting/Part2/Starting-Part2.md)
1. [On planning a game](Starting/Part2/Game-Planning.md)
1. [Planning to use some useful Contribs](Starting/Part2/Planning-Some-Useful-Contribs.md)
### Part3: How we get there
1. [Introduction & Overview](Starting/Part3/Starting-Part3.md)
1. [Making a custom Character](Starting/Part3/Implementing-a-game-rule-system.md)
1. [Character generation](../Unimplemented.md)
1. [Resolving skills and challenges](../Unimplemented.md)
1. [NPCs and mobiles](./Coordinates.md)
1. [Quests and Zones](../Unimplemented.md)
1. [A Combat system](../Unimplemented.md)
### Part 4: Using what we created
1. [Introduction & Overview](Starting/Part4/Starting-Part4.md)
1. [Building the tech demo](../Unimplemented.md)
1. [Creating a game world](../Unimplemented.md)
### Part 5: Showing the world
1. [Introduction & Overview](Starting/Part5/Starting-Part5.md)
1. [Add a web page](Starting/Part5/Add-a-simple-new-web-page.md)
1. [More on adding web features](Starting/Part5/Web-Tutorial.md)
1. [Taking your game online](../Unimplemented.md)
1. [Next steps](../Unimplemented.md)
## FAQs
- [Coding FAQ](./Coding-FAQ.md)
## Howto's
- [Giving Exits a default error](./Default-Exit-Errors.md)
- [Add a command prompt](./Command-Prompt.md)
- [Don't allow spamming commands](./Command-Cooldown.md)
- [Commands that take time](./Command-Duration.md)
- [Configuring color](./Manually-Configuring-Color.md)
- [Tweet game stats](./Tutorial-Tweeting-Game-Stats.md)
## Mobs and NPCs
- [NPCs that listen to you](./Tutorial-NPCs-listening.md)
- [Mobs that attack you](./Tutorial-Aggressive-NPCs.md)
- [Shopkeepers](./NPC-shop-Tutorial.md)
## Vehicles
- [Building a mech](./Building-a-mech-tutorial.md)
- [Building a train](./Tutorial-Vehicles.md)
## Systems
- [Understanding In-game time](./Gametime-Tutorial.md)
- [Understanding the Help system](./Help-System-Tutorial.md)
- [Adding mass to objects](./Mass-and-weight-for-objects.md)
- [Add weather](./Weather-Tutorial.md)
## Web-related tutorials
- [Add a wiki](./Add-a-wiki-on-your-website.md)
- [A web-based character generation](./Web-Character-Generation.md)
- [View Character on website](./Web-Character-View-Tutorial.md)
## Deep-dives
- [Parsing command inputs](./Parsing-commands-tutorial.md)
- [Understanding color-tags](./Understanding-Color-Tags.md)
- [Play paper&pen RPGs online with Evennia](./Evennia-for-roleplaying-sessions.md)
- [Evennia for Diku Users](./Evennia-for-Diku-Users.md)
- [Evennia for MUSH-Users](./Evennia-for-MUSH-Users.md)

131
docs/source/Howto/Starting/Part1/Starting-Part1.md
View file

@ -1,131 +0,0 @@
# Starting Tutorial (Part 1)
```{eval-rst}
.. sidebar:: Tutorial Parts
**Part 1: What we have**
A tour of Evennia and how to use the tools, including an introduction to Python.
Part 2: `What we want <../Part2/Starting-Part2.html>`_
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <../Part3/Starting-Part3.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Starting-Part4.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Starting-Part5.html>`_
Taking our new game online and let players try it out
```
Welcome to Evennia! This multi-part Tutorial will help you get off the ground. It consists
of five parts, each with several lessons. You can pick what seems interesting, but if you
follow through to the end you will have created a little online game of your own to play
and share with others!
## Lessons of Part 1 - "What we have"
1. Introduction (you are here)
1. [Building stuff](./Building-Quickstart.md)
1. [The Tutorial World](./Tutorial-World.md)
1. [Python basics](./Python-basic-introduction.md)
1. [Game dir overview](./Gamedir-Overview.md)
1. [Python classes and objects](./Python-classes-and-objects.md)
1. [Accessing the Evennia library](./Evennia-Library-Overview.md)
1. [Typeclasses and Persistent objects](./Learning-Typeclasses.md)
1. [Making first own Commands](./Adding-Commands.md)
1. [Parsing and replacing default Commands](./More-on-Commands.md)
1. [Creating things](./Creating-Things.md)
1. [Searching for things](./Searching-Things.md)
1. [Advanced searching with Django queries](./Django-queries.md)
In this first part we'll focus on what we get out of the box in Evennia - we'll get used to the tools,
and how to find things we are looking for. We will also dive into some of things you'll
need to know to fully utilize the system, including giving you a brief rundown of Python concepts. If you are
an experienced Python programmer, some sections may feel a bit basic, but you will at least not have seen
these concepts in the context of Evennia before.
## Things you will need
### A Command line
First of all, you need to know how to find your Terminal/Console in your OS. The Evennia server can be controlled
from in-game, but you _will_ need to use the command-line to get anywhere. Here are some starters:
- [Django-girls' Intro to the Command line for different OS:es](https://tutorial.djangogirls.org/en/intro_to_command_line/)
> Note that we only use forward-slashes `/` to show file system paths in this documentation. Windows users need
> to convert this to back-slashes `\` in their heads.
### A MUD client
You might already have a MUD-client you prefer. Check out the [grid of supported clients](../../../Setup/Client-Support-Grid.md) for aid.
If telnet's not your thing, you can also just use Evennia's web client in your browser.
> In this documentation we often use 'MUD' and 'MU' or 'MU*' interchangeably
as labels to represent all the historically different forms of text-based multiplayer game-styles,
like MUD, MUX, MUSH, MUCK, MOO and others. Evennia can be used to create all those game-styles
and more.
### An Editor
You need a text-editor to edit Python source files. Most everything that can edit and output raw
text works (so not Word).
- [Here's a blog post summing up some of the alternatives](https://www.elegantthemes.com/blog/resources/best-code-editors) - these
things don't change much from year to year. Popular choices for Python are PyCharm, VSCode, Atom, Sublime Text and Notepad++.
Evennia is to a very large degree coded in VIM, but that's not suitable for beginners.
> Hint: When setting up your editor, make sure that pressing TAB inserts _4 spaces_ rather than a Tab-character. Since
> Python is whitespace-aware, this will make your life a lot easier.
### Set up a game dir for the tutorial
Next you should make sure you have [installed Evennia](../../../Setup/Installation.md). If you followed the instructions
you will already have created a game-dir. You could use that for this tutorial or you may want to do the
tutorial in its own, isolated game dir; it's up to you.
- If you want a new gamedir for the tutorial game and already have Evennia running with another gamedir,
first enter that gamedir and run
evennia stop
> If you want to run two parallel servers, that'd be fine too, but one would have to use
> different ports from the defaults, or there'd be a clash. We will go into changing settings later.
- Now go to where you want to create your tutorial-game. We will always refer to it as `mygame` so
it may be convenient if you do too:
evennia --init mygame
cd mygame
evennia migrate
evennia start --log
Add your superuser name and password at the prompt (email is optional). Make sure you can
go to `localhost:4000` in your MUD client or to [http://localhost:4001](http://localhost:4001)
in your web browser (Mac users: Try `127.0.0.1` instead of `localhost` if you have trouble).
The above `--log` flag will have Evennia output all its logs to the terminal. This will block
the terminal from other input. To leave the log-view, press `Ctrl-C` (`Cmd-C` on Mac). To see
the log again just run
evennia --log
You should now be good to go!
```{toctree}
:hidden:
Building-Quickstart
Tutorial-World-Introduction
Python-basic-introduction
Gamedir-Overview
Python-classes-and-objects
Evennia-Library-Overview
Learning-Typeclasses
Adding-Commands
More-on-Commands
Creating-Things
Searching-Things
Django-queries
../Part2/Starting-Part2
```

41
docs/source/Howto/Starting/Part2/Starting-Part2.md
View file

@ -1,41 +0,0 @@
# Evennia Starting Tutorial (Part 2)
```{eval-rst}
.. sidebar:: Tutorial Parts
Part 1: `What we have <../Part1/Starting-Part1.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
**Part 2: What we want**
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <../Part3/Starting-Part3.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Starting-Part4.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Starting-Part5.html>`_
Taking our new game online and let players try it out
```
## Lessons for Part 2
In Part two of the Starting tutorial we'll step back and plan out the kind of tutorial
game we want to make. This is a more 'theoretical' part where we won't do any hands-on
programming.
1. Introduction & Overview (you are here)
1. [Where do I begin](./Planning-Where-Do-I-Begin.md)
1. [On planning a game](./Game-Planning.md)
1. [Planning to use some useful Contribs](./Planning-Some-Useful-Contribs.md)
In the process we'll go through the common questions of "where to start"
and "what to think about" when creating a multiplayer online text game.
```{toctree}
:hidden:
Planning-Where-Do-I-Begin
Game-Planning
Planning-Some-Useful-Contribs
../Part3/Starting-Part3
```

2
docs/source/Howto/Add-a-wiki-on-your-website.md → docs/source/Howtos/Add-a-wiki-on-your-website.md
View file

@ -2,7 +2,7 @@
**Before doing this tutorial you will probably want to read the intro in
[Basic Web tutorial](Starting/Part5/Web-Tutorial.md).** Reading the three first parts of the
[Basic Web tutorial](Beginner-Tutorial/Part5/Web-Tutorial.md).** Reading the three first parts of the
[Django tutorial](https://docs.djangoproject.com/en/1.9/intro/tutorial01/) might help as well.
This tutorial will provide a step-by-step process to installing a wiki on your website.

2
docs/source/Contribs/Arxcode-Installation.md → docs/source/Howtos/Arxcode-Installation.md
View file

@ -54,7 +54,7 @@ A new folder `myarx` should appear next to the ones you already had. You could r
something else if you want.
`cd` into `myarx`. If you wonder about the structure of the game dir, you can
[read more about it here](../Howto/Starting/Part1/Gamedir-Overview.md).
[read more about it here](Beginner-Tutorial/Part1/Gamedir-Overview.md).
### Clean up settings

116
docs/source/Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md Normal file
View file

@ -0,0 +1,116 @@
# Beginner Tutorial
```{eval-rst}
.. sidebar:: Tutorial Parts
**Introduction**
Getting set up.
Part 1: `What we have <Part1/Beginner-Tutorial-Part1-Intro.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
Part 2: `What we want <Part2/Beginner-Tutorial-Part2-Intro.html>`_
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <Part3/Beginner-Tutorial-Part3-Intro.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <Part4/Beginner-Tutorial-Part4-Intro.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <Part5/Beginner-Tutorial-Part5-Intro.html>`_
Taking our new game online and let players try it out
```
Welcome to Evennia! This multi-part Beginner Tutorial will help you get off the ground. It consists
of five parts, each with several lessons. You can pick what seems interesting, but if you
follow through to the end you will have created a little online game of your own to play
and share with others!
Use the menu on the right to get the index of each tutorial-part. Use the [next](Part1/Beginner-Tutorial-Part1-Intro.md)
and [previous](../Howtos-Overview.md) links to step from lesson to lesson.
## Things you need
- A Command line
- A MUD client (or web browser)
- A text-editor/IDE
- Evennia installed and a game-dir initialized
### A Command line
You need to know how to find your Terminal/Console in your OS. The Evennia server can be controlled
from in-game, but you _will_ need to use the command-line to get anywhere. Here are some starters:
- [Django-girls' Intro to the Command line for different OS:es](https://tutorial.djangogirls.org/en/intro_to_command_line/)
Note that we usually only show forward-slashes `/` for file system paths. Windows users should mentally convert this to
back-slashes `\` instead.
### A MUD client
You might already have a MUD-client you prefer. Check out the [grid of supported clients](../../Setup/Client-Support-Grid.md) for aid.
If telnet's not your thing, you can also just use Evennia's web client in your browser.
> In this documentation we often use the terms 'MUD', 'MU' or 'MU*' interchangeably
to represent all the historically different forms of text-based multiplayer game-styles,
like MUD, MUX, MUSH, MUCK, MOO and others. Evennia can be used to create all those game-styles
and more.
### An Editor
You need a text-editor to edit Python source files. Most everything that can edit and output raw
text works (so not Word).
- [Here's a blog post summing up some of the alternatives](https://www.elegantthemes.com/blog/resources/best-code-editors) - these
things don't change much from year to year. Popular choices for Python are PyCharm, VSCode, Atom, Sublime Text and Notepad++.
Evennia is to a very large degree coded in VIM, but that's not suitable for beginners.
> Hint: When setting up your editor, make sure that pressing TAB inserts _4 spaces_ rather than a Tab-character. Since
> Python is whitespace-aware, this will make your life a lot easier.
### Set up a game dir for the tutorial
Next you should make sure you have [installed Evennia](../../Setup/Installation.md). If you followed the instructions
you will already have created a game-dir. You could use that for this tutorial or you may want to do the
tutorial in its own, isolated game dir; it's up to you.
- If you want a new gamedir for the tutorial game and already have Evennia running with another gamedir,
first enter that gamedir and run
evennia stop
> If you want to run two parallel servers, that'd be fine too, but one would have to use
> different ports from the defaults, or there'd be a clash. We will go into changing settings later.
- Now go to where you want to create your tutorial-game. We will always refer to it as `mygame` so
it may be convenient if you do too:
evennia --init mygame
cd mygame
evennia migrate
evennia start --log
Add your superuser name and password at the prompt (email is optional). Make sure you can
go to `localhost:4000` in your MUD client or to [http://localhost:4001](http://localhost:4001)
in your web browser (Mac users: Try `127.0.0.1` instead of `localhost` if you have trouble).
The above `--log` flag will have Evennia output all its logs to the terminal. This will block
the terminal from other input. To leave the log-view, press `Ctrl-C` (`Cmd-C` on Mac). To see
the log again just run
evennia --log
You should now be good to go on to [the first part of the tutorial](Part1/Beginner-Tutorial-Part1-Intro.md).
Good luck!
<details>
<summary>
Click here to expand a list of all Beginner-Tutorial sections (all parts).
</summary>
```{toctree}
Part1/Beginner-Tutorial-Part1-Intro
Part2/Beginner-Tutorial-Part2-Intro
Part3/Beginner-Tutorial-Part3-Intro
Part4/Beginner-Tutorial-Part4-Intro
Part5/Beginner-Tutorial-Part5-Intro
```
</details>

2
docs/source/Howto/Starting/Part1/Adding-Commands.md → docs/source/Howtos/Beginner-Tutorial/Part1/Adding-Commands.md
View file

@ -1,4 +1,4 @@
# Our own commands
# Adding custom commands
In this lesson we'll learn how to create our own Evennia _Commands_. If you are new to Python you'll
also learn some more basics about how to manipulate strings and get information out of Evennia.

66
docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md Normal file
View file

@ -0,0 +1,66 @@
# Part 1: What we have
```{eval-rst}
.. sidebar:: Beginner Tutorial Parts
`Introduction <../Beginner-Tutorial-Intro.html>`_
Getting set up.
**Part 1: What we have**
A tour of Evennia and how to use the tools, including an introduction to Python.
Part 2: `What we want <../Part2/Beginner-Tutorial-Part2-Intro.html>`_
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <../Part3/Beginner-Tutorial-Part3-Intro.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Beginner-Tutorial-Part4-Intro.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Beginner-Tutorial-Part5-Intro.html>`_
Taking our new game online and let players try it out
```
In this first part we'll focus on what we get out of the box in Evennia - we'll get used to the tools,
and how to find things we are looking for. We will also dive into some of things you'll
need to know to fully utilize the system, including giving you a brief rundown of Python concepts. If you are
an experienced Python programmer, some sections may feel a bit basic, but you will at least not have seen
these concepts in the context of Evennia before.
## Lessons
```{toctree}
:maxdepth: 1
:numbered:
Building-Quickstart
Tutorial-World
Python-basic-introduction
Gamedir-Overview
Python-classes-and-objects
Evennia-Library-Overview
Learning-Typeclasses
Adding-Commands
More-on-Commands
Creating-Things
Searching-Things
Django-queries
```
## Table of Contents
```{toctree}
:maxdepth: 2
Building-Quickstart
Tutorial-World
Python-basic-introduction
Gamedir-Overview
Python-classes-and-objects
Evennia-Library-Overview
Learning-Typeclasses
Adding-Commands
More-on-Commands
Creating-Things
Searching-Things
Django-queries
```

11
docs/source/Howto/Starting/Part1/Building-Quickstart.md → docs/source/Howtos/Beginner-Tutorial/Part1/Building-Quickstart.md
View file

@ -1,4 +1,4 @@
# Using the game and building stuff
# Using commands and building stuff
In this lesson we will test out what we can do in-game out-of-the-box. Evennia ships with
[around 90 default commands](../../../Components/Default-Commands.md), and while you can override those as you please,
@ -82,10 +82,9 @@ This created a new 'box' (of the default object type) in your inventory. Use the
name box = very large box;box;very;crate
```{warning} MUD clients and semi-colon
Some traditional MUD clients use the semi-colon `;` to separate client inputs. If so,
the above line will give an error. You need to change your client to use another command-separator
or to put it in 'verbatim' mode. If you still have trouble, use the Evennia web client instead.
Some traditional MUD clients use the semi-colon `;` to separate client inputs. If so,
the above line will give an error. You need to change your client to use another command-separator
or to put it in 'verbatim' mode. If you still have trouble, use the Evennia web client instead.
```
@ -309,4 +308,4 @@ You will now find your new `History` entry in the `help` list and read your help
## Adding a World
After this brief introduction to building and using in-game commands you may be ready to see a more fleshed-out
example. Evennia comes with a tutorial world for you to explore. We will try that out in the next section.
example. Evennia comes with a tutorial world for you to explore. We will try that out in the next lesson.

1
docs/source/Howto/Starting/Part1/Creating-Things.md → docs/source/Howtos/Beginner-Tutorial/Part1/Creating-Things.md
View file

@ -1,6 +1,5 @@
# Creating things
We have already created some things - dragons for example. There are many different things to create
in Evennia though. In the last lesson we learned about typeclasses, the way to make objects persistent in the database.

2
docs/source/Howto/Starting/Part1/Django-queries.md → docs/source/Howtos/Beginner-Tutorial/Part1/Django-queries.md
View file

@ -1,4 +1,4 @@
# Django Database queries
# Advanced searching - Django Database queries
```{important} More advanced lesson!

4
docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md → docs/source/Howtos/Beginner-Tutorial/Part1/Evennia-Library-Overview.md
View file

@ -51,11 +51,11 @@ This the the structure of the Evennia library:
- evennia
- [`__init__.py`](../../../Evennia-API.md#shortcuts) - The "flat API" of Evennia resides here.
- [`settings_default.py`](../../../Setup/Server-Conf.md#settings-file) - Root settings of Evennia. Copy settings
- [`settings_default.py`](../../../Setup/Settings.md#settings-file) - Root settings of Evennia. Copy settings
from here to `mygame/server/settings.py` file.
- [`commands/`](../../../Components/Commands.md) - The command parser and handler.
- `default/` - The [default commands](../../../Components/Default-Commands.md) and cmdsets.
- [`comms/`](../../../Components/Communications.md) - Systems for communicating in-game.
- [`comms/`](../../../Components/Channels.md) - Systems for communicating in-game.
- `contrib/` - Optional plugins too game-specific for core Evennia.
- `game_template/` - Copied to become the "game directory" when using `evennia --init`.
- [`help/`](../../../Components/Help-System.md) - Handles the storage and creation of help entries.

0
docs/source/Howto/Starting/Part1/Gamedir-Overview.md → docs/source/Howtos/Beginner-Tutorial/Part1/Gamedir-Overview.md
View file

2
docs/source/Howto/Starting/Part1/Learning-Typeclasses.md → docs/source/Howtos/Beginner-Tutorial/Part1/Learning-Typeclasses.md
View file

@ -1,4 +1,4 @@
# Persistent objects and typeclasses
# Making objects persistent
Now that we have learned a little about how to find things in the Evennia library, let's use it.

2
docs/source/Howto/Starting/Part1/More-on-Commands.md → docs/source/Howtos/Beginner-Tutorial/Part1/More-on-Commands.md
View file

@ -1,4 +1,4 @@
# More about Commands
# Parsing Command input
In this lesson we learn some basics about parsing the input of Commands. We will
also learn how to add, modify and extend Evennia's default commands.

76
docs/source/Howto/Starting/Part1/Python-basic-introduction.md → docs/source/Howtos/Beginner-Tutorial/Part1/Python-basic-introduction.md
View file

@ -1,4 +1,4 @@
# Starting to code Evennia
# Intro to using Python with Evennia
Time to dip our toe into some coding! Evennia is written and extended in [Python](https://python.org),
which is a mature and professional programming language that is very fast to work with.
@ -16,7 +16,6 @@ superuser powers back:
unquell
## Evennia Hello world
The `py` Command (or `!`, which is an alias) allows you as a superuser to execute raw Python from in-
@ -27,8 +26,8 @@ game. This is useful for quick testing. From the game's input line, enter the fo
```{sidebar} Command input
The line with `>` indicates input to enter in-game, while the lines below are the
expected return from that input.
The line with `>` indicates input to enter in-game, while the lines below are the
expected return from that input.
```
You will see
@ -65,6 +64,8 @@ A string multiplied with a number will repeat that string as many times:
> py print("A" + "a" * 5 + "rgh!")
Aaaaaargh!
### .format()
While combining different strings is useful, even more powerful is the ability to modify the contents
of the string in-place. There are several ways to do this in Python and we'll show two of them here. The first
is to use the `.format` _method_ of the string:
@ -114,11 +115,10 @@ To separate two Python instructions on the same line, you use the semi-colon, `;
```{warning} MUD clients and semi-colon
Some MUD clients use the semi-colon `;` to split client-inputs
into separate sends. If so, the above will give an error. Most clients allow you to
run in 'verbatim' mode or to remap to use some other separator than `;`. If you still have
trouble, just use the Evennia web client for now. In real Python code you'll pretty much never use
the semi-colon.
Some MUD clients use the semi-colon `;` to split client-inputs
into separate sends. If so, the above will give an error. Most clients allow you to
run in 'verbatim' mode or to remap to use some other separator than `;`. If you still have
trouble, use the Evennia web client.
```
What happened here was that we _assigned_ the string `"awesome sauce"` to a _variable_ we chose
@ -129,12 +129,14 @@ instead.
Here's the stat-example again, moving the stats to variables (here we just set them, but in a real
game they may be changed over time, or modified by circumstance):
> py stren, dex, intel = 13, 14, 8 ; print("STR: {}, DEX: {dex}, INT: {}".format(stren, dex, intel))
> py stren, dext, intel = 13, 14, 8 ; print("STR: {}, DEX: {}, INT: {}".format(stren, dext, intel))
STR: 13, DEX: 14, INT: 8
The point is that even if the values of the stats change, the print() statement would not change - it just keeps
pretty-printing whatever is given to it.
### f-strings
Using `.format()` is convenient (and there is a [lot more](https://www.w3schools.com/python/ref_string_format.asp)
you can do with it). But the _f-string_ can be even more convenient. An
f-string looks like a normal string ... except there is an `f` front of it, like this:
@ -149,12 +151,14 @@ An f-string on its own is just like any other string. But let's redo the example
We could just insert that `a` variable directly into the f-string using `{a}`. Fewer parentheses to
remember and arguable easier to read as well.
> py stren, dex, intel = 13, 14, 8 ; print(f"STR: {stren}, DEX: {dex}, INT: {intel}")
> py stren, dext, intel = 13, 14, 8 ; print(f"STR: {stren}, DEX: {dext}, INT: {intel}")
STR: 13, DEX: 14, INT: 8
We will be exploring more complex string concepts when we get to creating Commands and need to
parse and understand player input.
### Colored text
Python itself knows nothing about colored text, this is an Evennia thing. Evennia supports the
standard color schemes of traditional MUDs.
@ -163,7 +167,7 @@ standard color schemes of traditional MUDs.
Adding that `|r` at the start will turn our output bright red. `|R` will make it dark red. `|n`
gives the normal text color. You can also use RGB (Red-Green-Blue) values from 0-5 (Xterm256 colors):
> py print("|043This is a blue-green color.|[530|003 This is dark blue text on orange background.")
> py print("|043This is a blue-green color.|[530|003 Now dark blue text on orange background.")
> If you don't see the expected color, your client or terminal may not support Xterm256 (or
color at all). Use the Evennia webclient.
@ -194,10 +198,9 @@ print("Hello World!")
```{sidebar} Python module
This is a text file with the `.py` file ending. A module
contains Python source code and from within Python one can
access its contents by importing it via its python-path.
This is a text file with the `.py` file ending. A module
contains Python source code and from within Python one can
access its contents by importing it via its python-path.
```
Don't forget to _save_ the file. We just created our first Python _module_!
@ -358,10 +361,10 @@ NameError: name 'me' is not defined
```{sidebar} Errors in the logs
In regular use, tracebacks will often appear in the log rather than
in the game. Use `evennia --log` to view the log in the terminal. Make
sure to scroll back if you expect an error and don't see it. Use
`Ctrl-C` (or `Cmd-C` on Mac) to exit the log-view.
In regular use, tracebacks will often appear in the log rather than
in the game. Use `evennia --log` to view the log in the terminal. Make
sure to scroll back if you expect an error and don't see it. Use
`Ctrl-C` (or `Cmd-C` on Mac) to exit the log-view.
```
@ -434,9 +437,9 @@ On the game command-line, let's create a mirror:
```{sidebar} Creating objects
The `create` command was first used to create boxes in the
`Building Stuff <Building-Quickstart>`_ tutorial. Note how it
uses a "python-path" to describe where to load the mirror's code from.
The `create` command was first used to create boxes in the
`Building Stuff <Building-Quickstart>`_ tutorial. Note how it
uses a "python-path" to describe where to load the mirror's code from.
```
A mirror should appear in your location.
@ -469,10 +472,10 @@ as the `me` object is. If it can't find anything you'll see an error.
```{sidebar} Function returns
Whereas a function like `print` only prints its arguments, it's very common
for functions/methods to `return` a result of some kind. Think of the function
as a machine - you put something in and out comes a result you can use. In the case
of `me.search`, it will perform a database search and spit out the object it finds.
Whereas a function like `print` only prints its arguments, it's very common
for functions/methods to `return` a result of some kind. Think of the function
as a machine - you put something in and out comes a result you can use. In the case
of `me.search`, it will perform a database search and spit out the object it finds.
```
> py me.search("dummy")
@ -527,10 +530,10 @@ the `>>>`). For brevity in this tutorual we'll turn the echo off. First exit `py
```{sidebar} interactive py
- Start with `py`.
- Use `py/noecho` if you don't want your input to be echoed for every line.
- All your inputs will now be interpreted as Python code.
- Exit with `quit()`.
- Start with `py`.
- Use `py/noecho` if you don't want your input to be echoed for every line.
- All your inputs will now be interpreted as Python code.
- Exit with `quit()`.
```
We can now enter multi-line Python code:
@ -633,13 +636,13 @@ As for the normal python interpreter, use `Ctrl-D`/`Cmd-D` or `quit()` to exit i
```{important} Persistent code
Common for both `py` and `python`/`ipython` is that the code you write is not persistent - it will
be gone after you shut down the interpreter (but ipython will remember your input history). For making long-lasting
Python code, we need to save it in a Python module, like we did for `world/test.py`.
Common for both `py` and `python`/`ipython` is that the code you write is not persistent - it will
be gone after you shut down the interpreter (but ipython will remember your input history). For making long-lasting
Python code, we need to save it in a Python module, like we did for `world/test.py`.
```
# Conclusions
## Conclusions
This covers quite a lot of basic Python usage. We printed and formatted strings, defined our own
first function, fixed an error and even searched and talked to a mirror! Being able to access
@ -647,5 +650,4 @@ python inside and outside of the game is an important skill for testing and debu
practice you will be writing most your code in Python modules.
To that end we also created a first new Python module in the `mygame/` game dir, then imported and used it.
Now let's look at the rest of the stuff you've got going on inside that `mygame/` folder ...
Now let's look at the rest of the stuff you've got going on inside that `mygame/` folder ...

2
docs/source/Howto/Starting/Part1/Python-classes-and-objects.md → docs/source/Howtos/Beginner-Tutorial/Part1/Python-classes-and-objects.md
View file

@ -1,4 +1,4 @@
# Python Classes and objects
# Introduction to Python classes and objects
We have now learned how to run some simple Python code from inside (and outside) your game server.
We have also taken a look at what our game dir looks and what is where. Now we'll start to use it.

0
docs/source/Howto/Starting/Part1/Searching-Things.md → docs/source/Howtos/Beginner-Tutorial/Part1/Searching-Things.md
View file

50
docs/source/Howto/Starting/Part1/Tutorial-World.md → docs/source/Howtos/Beginner-Tutorial/Part1/Tutorial-World.md
View file

@ -11,15 +11,23 @@ Stand in the Limbo room and install it with
What this does is to run the build script
[evennia/contrib/tutorial_world/build.ev](github:evennia/contrib/tutorial_world/build.ev).
This is pretty much just a list of build-commands executed in sequence by the `batchcommand` command.
Wait for the building to complete and don't run it twice. A new exit should have appeared named _Tutorial_.
Wait for the building to complete and don't run it twice.
> After having run the batchcommand, the `intro` command also becomes available in Limbo. Try it out to
> for in-game help and to get an example of [EvMenu](../../../Components/EvMenu.md), Evennia's in-built
> menu generation system!
The game consists of a single-player quest and has some 20 rooms that you can explore as you seek
to discover the whereabouts of a mythical weapon. Make sure you don't play as superuser:
to discover the whereabouts of a mythical weapon.
quell
A new exit should have appeared named _Tutorial_. Enter by writing `tutorial`.
Enter the new exit by writing `tutorial`. Enjoy! If you succeed you will eventually
end up back in Limbo.
You will automatically `quell` when you enter (and `unquell` when you leave), so you can play the way it was intended.
Both if you are triumphant or if you use the `give up` command you will eventually end up back in Limbo.
```{important}
Only LOSERS and QUITTERS use the `give up` command.
```
## Gameplay
@ -34,26 +42,27 @@ this is a chance to adventure that you cannot turn down!*
face you stand where the moor meets the sea along a high, rocky coast ...*
---
### Hints:
- Look at everything. While a demo, this is not necessarily trivial, depending on your experience with
text-based adventure games. Just remember that everything can be solved or bypassed.
- Some things cannot be damaged by mortal weapons. In that case it's OK to run away. Expect
to be chased though.
### Gameplay hints
- Use the command `tutorial` to get code insight behind the scenes of every room.
- Look at everything. While a demo, the Tutorial World is not necessarily trivial to solve - it depends
on your experience with text-based adventure games. Just remember that everything can be solved or bypassed.
- Some objects are interactive in more than one way. Use the normal `help` command to get a feel for
which commands are available at any given time.
- Use the command `tutorial` to get insight behind the scenes of the game.
- In order to fight, you need to first find some type of weapon.
- *slash* is a normal attack
- *stab* launches an attack that makes more damage but has a lower chance to hit.
- *defend* will lower the chance to taking damage on your enemy's next attack.
- Some things _cannot_ be hurt by mundane weapons. In that case it's OK to run away. Expect
to be chased though.
- Being defeated is a part of the experience. You can't actually die, but getting knocked out
means being left in the dark ...
## Once you are done (or had enough)
Afterwards you'll either have conquered the old ruin and returned in glory and triumph ... or
you returned limping and whimpering from the challenge through `telport limbo`.
you returned limping and whimpering from the challenge by using the `give up` command.
Either way you should now be back in Limbo, able to reflect on the experience.
Some features exemplified by the tutorial world:
@ -74,17 +83,16 @@ Some features exemplified by the tutorial world:
```{sidebar} Extra Credit
If you have previous programming experience (or after you have gone
through this Starter tutorial) it may be instructive to dig a little deeper into the Tutorial-world
code to learn how it achieves what it does. The code is heavily documented.
You can find all the code in `evennia/contrib/tutorial_world <../../api/evennia.contrib.tutorial_world.html>`_,
the build-script is `here <https://github.com/evennia/evennia/blob/master/evennia/contrib/tutorial_world/build.ev>`_.
If you have previous programming experience (or after you have gone
through this Starter tutorial) it may be instructive to dig a little deeper into the Tutorial-world
code to learn how it achieves what it does. The code is heavily documented.
You can find all the code in [evennia/contrib/tutorials/tutorial_world](evennia.contrib.tutorials.tutorial_world).
The build-script is [here](github:evennia/contrib/tutorials/tutorial_world/build.ev).
When reading and learning from the code, however, keep in mind that *Tutorial World* was created with a very
specific goal in mind: to install easily and to not permanently modify the rest of the server. It therefore
goes to some length to use only temporary solutions and to clean up after itself. This is not something
you will usually need to worry about when making your own game.
When reading the code, remember that the Tutorial World was designed to install easily and to not permanently modify
the rest of the game. It therefore makes sure to only use temporary solutions and to clean up after itself. This is
not something you will often need to worry about when making your own game.
```
Quite a lot of stuff crammed in such a small area!

46
docs/source/Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Part2-Intro.md Normal file
View file

@ -0,0 +1,46 @@
# Part 2: What we want
```{eval-rst}
.. sidebar:: Beginner Tutorial Parts
`Introduction <../Beginner-Tutorial-Intro.html>`_
Getting set up.
Part 1: `What we have <../Part1/Beginner-Tutorial-Part1-Intro.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
**Part 2: What we want**
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <../Part3/Beginner-Tutorial-Part3-Intro.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Beginner-Tutorial-Part4-Intro.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Beginner-Tutorial-Part5-Intro.html>`_
Taking our new game online and let players try it out
```
In Part two of the Beginner Tutorial we'll take a step back and plan out the kind of tutorial
game we want to make. This is a more 'theoretical' part where we won't do any hands-on
programming.
In the process we'll go through the common questions of "where to start"
and "what to think about" when creating a multiplayer online text game.
## Lessons
```{toctree}
:maxdepth: 1
Planning-Where-Do-I-Begin.md
Game-Planning.md
Planning-Some-Useful-Contribs.md
Planning-The-Tutorial-Game.md
```
## Table of Contents
```{toctree}
Planning-Where-Do-I-Begin.md
Game-Planning.md
Planning-Some-Useful-Contribs.md
Planning-The-Tutorial-Game.md
```

0
docs/source/Howto/Starting/Part2/Game-Planning.md → docs/source/Howtos/Beginner-Tutorial/Part2/Game-Planning.md
View file

2
docs/source/Howto/Starting/Part2/Planning-Some-Useful-Contribs.md → docs/source/Howtos/Beginner-Tutorial/Part2/Planning-Some-Useful-Contribs.md
View file

@ -8,7 +8,7 @@ That said, Evennia _does_ offer some more game-opinionated _optional_ stuff. The
and is an ever-growing treasure trove of code snippets, concepts and even full systems you can pick and choose
from to use, tweak or take inspiration from when you make your game.
The [Contrib overview](../../../Contribs/Contrib-Overview.md) page gives the full list of the current roster of contributions. On
The [Contrib overview](../../../Contribs/Contribs-Overview.md) page gives the full list of the current roster of contributions. On
this page we will review a few contribs we will make use of for our game. We will do the actual installation
of them when we start coding in the next part of this tutorial series. While we will introduce them here, you
are wise to read their doc-strings yourself for the details.

0
docs/source/Howto/Starting/Part2/Planning-The-Tutorial-Game.md → docs/source/Howtos/Beginner-Tutorial/Part2/Planning-The-Tutorial-Game.md
View file

0
docs/source/Howto/Starting/Part2/Planning-Where-Do-I-Begin.md → docs/source/Howtos/Beginner-Tutorial/Part2/Planning-Where-Do-I-Begin.md
View file

0
docs/source/Howto/Starting/Part3/A-Sittable-Object.md → docs/source/Howtos/Beginner-Tutorial/Part3/A-Sittable-Object.md
View file

56
docs/source/Howto/Starting/Part3/Starting-Part3.md → docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Part3-Intro.md
View file

@ -1,25 +1,43 @@
# Evennia Starting Tutorial (Part 3)
# Part 3: How we get there
```{eval-rst}
.. sidebar:: Beginner Tutorial Parts
sidebar:: Tutorial Parts
Part 1: `What we have <../Part1/Starting-Part1.html>`_
`Introduction <../Beginner-Tutorial-Intro.html>`_
Getting set up.
Part 1: `What we have <../Part1/Beginner-Tutorial-Part1-Intro.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
Part 2: `What we want <../Part2/Starting-Part2.html>`_
Part 2: `What we want <../Part2/Beginner-Tutorial-Part2-Intro.html>`_
Planning our tutorial game and what to think about when planning your own in the future.
**Part 3: How we get there**
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Starting-Part4.html>`_
Part 4: `Using what we created <../Part4/Beginner-Tutorial-Part4-Intro.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Starting-Part5.html>`_
Part 5: `Showing the world <../Part5/Beginner-Tutorial-Part5-Intro.html>`_
Taking our new game online and let players try it out
```
In part three of the Evennia Starting tutorial we will go through the creation of several key parts
of our tutorial game _EvAdventure_. As we go, we will test each part and create a simple "tech demo" to
show off all the moving parts.
1. Introduction & Overview (you are here)
In part three of the Evennia Beginner tutorial we will go through the creation of several key parts of our tutorial
game _EvAdventure_. This is a pretty big part with plenty of examples.
If you followed the previous parts of this tutorial you will have some notions about Python and where to find
and make use of things in Evennia. We also have a good idea of the type of game we want.
Even if this is not the game-style you are interested in, following along will give you a lot of experience
with using Evennia. This be of much use when doing your own thing later.
## Lessons
_TODO_
```{toctree}
:maxdepth: 1
Implementing-a-game-rule-system
Turn-based-Combat-System
A-Sittable-Object
```
1. [Changing settings](../../../Unimplemented.md)
1. [Applying contribs](../../../Unimplemented.md)
1. [Creating a rule module](../../../Unimplemented.md)
@ -31,17 +49,15 @@ show off all the moving parts.
1. [Questing and rewards](../../../Unimplemented.md)
1. [Overview of Tech demo](../../../Unimplemented.md)
If you followed the previous parts of this tutorial you will have some notions about Python and where to find
and make use of things in Evennia. We also have a good idea of the type of game we want.
Even if this is not the game-style you are interested in, following along will give you a lot of experience
with using Evennia. This be of much use when doing your own thing later.
## Table of Contents
_TODO_
```{toctree}
:maxdepth: 1
```{toctree}
:hidden:
../../../Unimplemented
Implementing-a-game-rule-system
Turn-Based-Combat-System
A-Sittable-Object
```

0
docs/source/Howto/Starting/Part3/Implementing-a-game-rule-system.md → docs/source/Howtos/Beginner-Tutorial/Part3/Implementing-a-game-rule-system.md
View file

0
docs/source/Howto/Starting/Part3/Turn-based-Combat-System.md → docs/source/Howtos/Beginner-Tutorial/Part3/Turn-based-Combat-System.md
View file

30
docs/source/Howto/Starting/Part4/Starting-Part4.md → docs/source/Howtos/Beginner-Tutorial/Part4/Beginner-Tutorial-Part4-Intro.md
View file

@ -1,17 +1,19 @@
# Evennia Starting Tutorial (Part 4)
# Part 4: Using what we created
```{eval-rst}
sidebar:: Tutorial Parts
..sidebar:: Beginner Tutorial Parts
Part 1: `What we have <../Part1/Starting-Part1.html>`_
`Introduction <../Beginner-Tutorial-Intro.html>`_
Getting set up.
Part 1: `What we have <../Part1/Beginner-Tutorial-Part1-Intro.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
Part 2: `What we want <../Part2/Starting-Part2.html>`_
Part 2: `What we want <../Part2/Beginner-Tutorial-Part2-Intro.html>`_
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <../Part3/Starting-Part3.html>`_
Part 3: `How we get there <../Part3/Beginner-Tutorial-Part3-Intro.html>`_
Getting down to the meat of extending Evennia to make our game to make a tech-demo
**Part 4: Using what we created**
Using the tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Starting-Part5.html>`_
Part 5: `Showing the world <../Part5/Beginner-Tutorial-Part5-Intro.html>`_
Taking our new game online and let players try it out
```
@ -21,4 +23,20 @@ point - we need to actually make a world.
In part four we will expand our tech demo into a more full-fledged (if small) game by use of batchcommand
and batchcode processors.
## Lessons
_TODO_
```{toctree}
:maxdepth: 1
```
## Table of Contents
_TODO_
```{toctree}
```

0
docs/source/Howto/Starting/Part5/Add-a-simple-new-web-page.md → docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md
View file

36
docs/source/Howto/Starting/Part5/Starting-Part5.md → docs/source/Howtos/Beginner-Tutorial/Part5/Beginner-Tutorial-Part5-Intro.md
View file

@ -1,15 +1,17 @@
# Evennia Starting Tutorial (part 5)
# Part 5: Showing the world
```{eval-rst}
.. sidebar:: Tutorial Parts
.. sidebar:: Beginner Tutorial Parts
Part 1: `What we have <../Part1/Starting-Part1.html>`_
`Introduction <../Beginner-Tutorial-Intro.html>`_
Getting set up.
Part 1: `What we have <../Part1/Beginner-Tutorial-Part1-Intro.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
Part 2: `What we want <../Part2/Starting-Part2.html>`_
Part 2: `What we want <../Part2/Beginner-Tutorial-Part2-Intro.html>`_
Planning our tutorial game and what to think about when planning your own in the future.
Part 3: `How we get there <../Part3/Starting-Part3.html>`_
Part 3: `How we get there <../Part3/Beginner-Tutorial-Part3-Intro.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Starting-Part4.html>`_
Part 4: `Using what we created <../Part4/Beginner-Tutorial-Part4-Intro.html>`_
Building a tech-demo and world content to go with our code
**Part 5: Showing the world**
Taking our new game online and let players try it out
@ -19,4 +21,26 @@ You have a working game! In part five we will look at the web-components of Even
to fit your game. We will also look at hosting your game and if you feel up to it we'll also go through how
to bring your game online so you can invite your first players.
## Lessons
_TODO_
```{toctree}
:maxdepth: 1
Add-a-simple-new-web-page.md
Web-Tutorial.md
```
## Table of Contents
_TODO_
```{toctree}
Add-a-simple-new-web-page.md
Web-Tutorial.md
```

0
docs/source/Howto/Starting/Part5/Web-Tutorial.md → docs/source/Howtos/Beginner-Tutorial/Part5/Web-Tutorial.md
View file

0
docs/source/Howto/Building-a-mech-tutorial.md → docs/source/Howtos/Building-a-mech-tutorial.md
View file

4
docs/source/Howto/Coding-FAQ.md → docs/source/Howtos/Coding-FAQ.md
View file

@ -28,7 +28,7 @@ Character [Command Set](../Components/Command-Sets.md)?
**A:** Go to `mygame/commands/default_cmdsets.py`. Find the `CharacterCmdSet` class. It has one
method named `at_cmdset_creation`. At the end of that method, add the following line:
`self.remove(default_cmds.CmdGet())`. See the [Adding Commands Tutorial](Starting/Part1/Adding-Commands.md)
`self.remove(default_cmds.CmdGet())`. See the [Adding Commands Tutorial](Beginner-Tutorial/Part1/Adding-Commands.md)
for more info.
## Preventing character from moving based on a condition
@ -156,7 +156,7 @@ class CmdWerewolf(Command):
def func(self):
# ...
```
Add this to the [default cmdset as usual](Starting/Part1/Adding-Commands.md). The `is_full_moon` [lock
Add this to the [default cmdset as usual](Beginner-Tutorial/Part1/Adding-Commands.md). The `is_full_moon` [lock
function](../Components/Locks.md#lock-functions) does not yet exist. We must create that:
```python

0
docs/source/Howto/Command-Cooldown.md → docs/source/Howtos/Command-Cooldown.md
View file

0
docs/source/Howto/Command-Duration.md → docs/source/Howtos/Command-Duration.md
View file

0
docs/source/Howto/Command-Prompt.md → docs/source/Howtos/Command-Prompt.md
View file

0
docs/source/Howto/Coordinates.md → docs/source/Howtos/Coordinates.md
View file

130
docs/source/Howtos/Default-Exit-Errors.md Normal file
View file

@ -0,0 +1,130 @@
# Default Exit Errors
Evennia allows for exits to have any name. The command "kitchen" is a valid exit name as well as "jump out the window"
or "north". An exit actually consists of two parts: an [Exit Object](../Components/Objects.md) and
an [Exit Command](../Components/Commands.md) stored on said exit object. The command has the same key and aliases as the
exit-object, which is why you can see the exit in the room and just write its name to traverse it.
So if you try to enter the name of a non-existing exit, Evennia treats is the same way as if you were trying to
use a non-existing command:
> jump out the window
Command 'jump out the window' is not available. Type "help" for help.
Many games don't need this type of freedom however. They define only the cardinal directions as valid exit names (
Evennia's `tunnel` command also offers this functionality). In this case, the error starts to look less logical:
> west
Command 'west' is not available. Maybe you meant "set" or "reset"?
Since we for our particular game *know* that west is an exit direction, it would be better if the error message just
told us that we couldn't go there.
> west
You cannot move west.
## Adding default error commands
The way to do this is to give Evennia an _alternative_ Command to use when no Exit-Command is found
in the room. See [Adding Commands](Beginner-Tutorial/Part1/Adding-Commands.md) for more info about the
process of adding new Commands to Evennia.
In this example all we'll do is echo an error message.
```python
# for example in a file mygame/commands/movecommands.py
from evennia import default_cmds, CmdSet
class CmdExitError(default_cmds.MuxCommand):
"""Parent class for all exit-errors."""
locks = "cmd:all()"
arg_regex = r"\s|$"
auto_help = False
def func(self):
"""Returns error based on key"""
self.caller.msg(f"You cannot move {self.key}.")
class CmdExitErrorNorth(CmdExitError):
key = "north"
aliases = ["n"]
class CmdExitErrorEast(CmdExitError):
key = "east"
aliases = ["e"]
class CmdExitErrorSouth(CmdExitError):
key = "south"
aliases = ["s"]
class CmdExitErrorWest(CmdExitError):
key = "west"
aliases = ["w"]
# you could add each command on its own to the default cmdset,
# but putting them all in a cmdset here allows you to
# just add this and makes it easier to expand with more
# exit-errors in the future
class MovementFailCmdSet(CmdSet):
def at_cmdset_creation(self):
self.add(CmdExitErrorNorth())
self.add(CmdExitErrorEast())
self.add(CmdExitErrorWest())
self.add(CmdExitErrorSouth())
```
We pack our commands in a new little cmdset; if we add this to our
`CharacterCmdSet`, we can just add more errors to `MovementFailCmdSet`
later without having to change code in two places.
```python
# in mygame/commands/default_cmdsets.py
from commands import movecommands
# [...]
class CharacterCmdSet(default_cmds.CharacterCmdSet):
# [...]
def at_cmdset_creation(self):
# [...]
# this adds all the commands at once
self.add(movecommands.MovementFailCmdSet)
```
`reload` the server. What happens henceforth is that if you are in a room with an Exitobject (let's say it's "north"),
the proper Exit-command will _overload_ your error command (also named "north"). But if you enter a direction without
having a matching exit for it, you will fall back to your default error commands:
> east
You cannot move east.
Further expansions by the exit system (including manipulating the way the Exit command itself is created) can be done by
modifying the [Exit typeclass](../Components/Typeclasses.md) directly.
## Why not a single command?
So why didn't we create a single error command above? Something like this:
```python
class CmdExitError(default_cmds.MuxCommand):
"Handles all exit-errors."
key = "error_cmd"
aliases = ["north", "n",
"east", "e",
"south", "s",
"west", "w"]
#[...]
```
The reason is that this would *not* work. Understanding why is important.
Evennia's [command system](../Components/Commands.md) compares commands by key and/or aliases. If _any_ key or alias
match, the two commands are considered _identical_. When the cmdsets merge, priority will then decide which of these
'identical' commandss replace which.
So the above example would work fine as long as there were _no Exits at all_ in the room. But when we enter
a room with an exit "north", its Exit-command (which has a higher priority) will override the single `CmdExitError`
with its alias 'north'. So the `CmdExitError` will be gone and while "north" will work, we'll again get the normal
"Command not recognized" error for the other directions.

0
docs/source/Howto/Dynamic-In-Game-Map.md → docs/source/Howtos/Dynamic-In-Game-Map.md
View file

0
docs/source/Howto/Evennia-for-Diku-Users.md → docs/source/Howtos/Evennia-for-Diku-Users.md
View file

6
docs/source/Howto/Evennia-for-MUSH-Users.md → docs/source/Howtos/Evennia-for-MUSH-Users.md
View file

@ -203,7 +203,7 @@ developer changing the underlying Python code.
## Next steps
If you are a *Developer* and are interested in making a more MUSH-like Evennia game, a good start is
to look into the Evennia [Tutorial for a first MUSH-like game](Starting/Part3/Tutorial-for-basic-MUSH-like-game.md).
to look into the Evennia [Tutorial for a first MUSH-like game](./Tutorial-for-basic-MUSH-like-game.md).
That steps through building a simple little game from scratch and helps to acquaint you with the
various corners of Evennia. There is also the [Tutorial for running roleplaying sessions](Evennia-
for-roleplaying-sessions) that can be of interest.
@ -211,8 +211,8 @@ for-roleplaying-sessions) that can be of interest.
An important aspect of making things more familiar for *Players* is adding new and tweaking existing
commands. How this is done is covered by the [Tutorial on adding new commands](Adding-Command-
Tutorial). You may also find it useful to shop through the `evennia/contrib/` folder. The
[Tutorial world](Starting/Part1/Tutorial-World.md) is a small single-player quest you can try (it’s not very MUSH-
like but it does show many Evennia concepts in action). Beyond that there are [many more tutorials](./Howto-Overview.md)
[Tutorial world](Beginner-Tutorial/Part1/Tutorial-World.md) is a small single-player quest you can try (it’s not very MUSH-
like but it does show many Evennia concepts in action). Beyond that there are [many more tutorials](./Howtos-Overview.md)
to try out. If you feel you want a more visual overview you can also look at
[Evennia in pictures](https://evennia.blogspot.se/2016/05/evennia-in-pictures.html).

4
docs/source/Howto/Evennia-for-roleplaying-sessions.md → docs/source/Howtos/Evennia-for-roleplaying-sessions.md
View file

@ -31,7 +31,7 @@ instructions. Initialize a new game directory with `evennia init
<gamedirname>`. In this tutorial we assume your game dir is simply named `mygame`. You can use the
default database and keep all other settings to default for now. Familiarize yourself with the
`mygame` folder before continuing. You might want to browse the
[First Steps Coding](Starting/Part1/Starting-Part1.md) tutorial, just to see roughly where things are modified.
[First Steps Coding](Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) tutorial, just to see roughly where things are modified.
## The Game Master role
@ -686,7 +686,7 @@ implemented.
## Rooms
Evennia comes with rooms out of the box, so no extra work needed. A GM will automatically have all
needed building commands available. A fuller go-through is found in the [Building tutorial](Starting/Part1/Building-Quickstart.md).
needed building commands available. A fuller go-through is found in the [Building tutorial](Beginner-Tutorial/Part1/Building-Quickstart.md).
Here are some useful highlights:
* `@dig roomname;alias = exit_there;alias, exit_back;alias` - this is the basic command for digging

0
docs/source/Howto/Gametime-Tutorial.md → docs/source/Howtos/Gametime-Tutorial.md
View file

0
docs/source/Howto/Help-System-Tutorial.md → docs/source/Howtos/Help-System-Tutorial.md
View file

91
docs/source/Howtos/Howtos-Overview.md Normal file
View file

@ -0,0 +1,91 @@
# Tutorials and Howto's
The documents in this section aims to teach how to use Evennia in a tutorial or
a step-by-step way. They often give hints on about solving a problem or implementing
a particular feature or concept. They will often refer to the
[components](../Components/Components-Overview.md) or [concepts](../Concepts/Concepts-Overview.md)
docs for those that want to dive deeper.
## Beginner Tutorial
Recommended starting point! This will take you from absolute beginner to making
a small, but full, game with Evennia. Even if you have a very different game style
in mind for your own game, this will give you a good start.
```{toctree}
:maxdepth: 1
./Beginner-Tutorial/Beginner-Tutorial-Intro
```
## Howto's
```{toctree}
:maxdepth: 1
Coding-FAQ.md
Command-Prompt.md
Command-Cooldown.md
Command-Duration.md
Default-Exit-Errors.md
Manually-Configuring-Color.md
Tutorial-Tweeting-Game-Stats.md
```
## Mobs and NPCs
```{toctree}
:maxdepth: 1
Tutorial-NPCs-listening.md
Tutorial-Aggressive-NPCs.md
NPC-shop-Tutorial.md
```
## Vehicles
```{toctree}
:maxdepth: 1
Building-a-mech-tutorial.md
Tutorial-Vehicles.md
```
## Systems
```{toctree}
:maxdepth: 1
Gametime-Tutorial.md
Help-System-Tutorial.md
Mass-and-weight-for-objects.md
Weather-Tutorial.md
Coordinates.md
Dynamic-In-Game-Map.md
Static-In-Game-Map.md
Arxcode-Installation.md
```
## Web-related tutorials
```{toctree}
:maxdepth: 1
Add-a-wiki-on-your-website.md
Web-Character-Generation.md
Web-Character-View-Tutorial.md
```
## Deep-dives
```{toctree}
:maxdepth: 1
Parsing-commands-tutorial.md
Understanding-Color-Tags.md
Evennia-for-roleplaying-sessions.md
Evennia-for-Diku-Users.md
Evennia-for-MUSH-Users.md
Tutorial-for-basic-MUSH-like-game.md
```

0
docs/source/Howto/Manually-Configuring-Color.md → docs/source/Howtos/Manually-Configuring-Color.md
View file

0
docs/source/Howto/Mass-and-weight-for-objects.md → docs/source/Howtos/Mass-and-weight-for-objects.md
View file

0
docs/source/Howto/NPC-shop-Tutorial.md → docs/source/Howtos/NPC-shop-Tutorial.md
View file

4
docs/source/Howto/Parsing-commands-tutorial.md → docs/source/Howtos/Parsing-commands-tutorial.md
View file

@ -2,7 +2,7 @@
This tutorial will elaborate on the many ways one can parse command arguments. The first step after
[adding a command](Starting/Part1/Adding-Commands.md) usually is to parse its arguments. There are lots of
[adding a command](Beginner-Tutorial/Part1/Adding-Commands.md) usually is to parse its arguments. There are lots of
ways to do it, but some are indeed better than others and this tutorial will try to present them.
If you're a Python beginner, this tutorial might help you a lot. If you're already familiar with
@ -652,7 +652,7 @@ about... what is this `"book"`?
To get an object from a string, we perform an Evennia search. Evennia provides a `search` method on
all typeclassed objects (you will most likely use the one on characters or accounts). This method
supports a very wide array of arguments and has [its own tutorial](Starting/Part1/Searching-Things.md).
supports a very wide array of arguments and has [its own tutorial](Beginner-Tutorial/Part1/Searching-Things.md).
Some examples of useful cases follow:
### Local searches

Some files were not shown because too many files have changed in this diff Show more