mirror/evennia
3
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2025-10-29 11:26:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Cleaned up Coding and style guides, improved contribs

Browse Source
This commit is contained in:
Griatch 2022-11-25 19:47:32 +01:00
parent 5e5fe1dcde
commit 00035c15d5
30 changed files with 1135 additions and 1360 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
CODING_STYLE.md
View File

@ -1,32 +1,34 @@
# Evennia Code Style
All code submitted or committed to the Evennia project should aim to
follow the guidelines outlined in [Python PEP 8][pep8]. Keeping the code style
uniform makes it much easier for people to collaborate and read the
code.
All code submitted or committed to the Evennia project should aim to follow the
guidelines outlined in [Python PEP 8][pep8]. Keeping the code style uniform
makes it much easier for people to collaborate and read the code.
A good way to check if your code follows PEP8 is to use the [PEP8 tool][pep8tool]
on your sources.
## A quick list of code style points
## Main code style specification
* 4-space indentation, NO TABS!
* Unix line endings.
* 100 character line widths
* CamelCase is only used for classes, nothing else.
* All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.
* Module-level global variables (only) are to be in CAPITAL letters.
* (Evennia-specific): Imports should normally be done in this order:
* Imports should be done in this order:
- Python modules (builtins and standard library)
- Twisted modules
- Django modules
- Evennia library modules (`evennia`)
- Evennia contrib modules (`evennia.contrib`)
* All modules, classes, functions and modules should have doc
strings formatted as described below
* All modules, classes, functions and methods should have doc strings formatted
as outlined below.
* All default commands should have a consistent docstring formatted as
outlined below.
## Doc strings
## Code Docstrings
All modules, classes, functions and methods should have docstrings
formatted with [Google style][googlestyle] -inspired indents, using
@ -129,14 +131,18 @@ indents to be 4 spaces wide (no tabs!).
Here are all the supported block headers:
```
Args/Keyword Args:
argname (freeform type): text
"""
Args
argname (freeform type): Description endind with period.
Keyword Args:
argname (freeform type): Description.
Returns/Yields:
type: text
type: Description.
Raises:
Exceptiontype: text
Exceptiontype: Description.
Notes/Note/Examples/Example:
freeform text
Freeform text.
"""
```
Parts marked with "freeform" means that you can in principle put any
@ -152,43 +158,114 @@ documented.
Note that
```
"""
Args:
argname (type, optional): text
argname (type, optional): Description.
"""
```
and
```
Kwargs:
argname (type): text
"""
Keyword Args:
sargname (type): Description.
"""
```
mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
`**kwargs` block in the function, using the `Kwargs:` block may be a
`**kwargs` block in the function, using the `Keyword Args:` block may be a
good idea, for a small number of arguments though, just using `Args:`
and marking keywords as `optional` will shorten the docstring and make
it easier to read.
### Default Commands
## Default Command Docstrings
These represent a special case since Commands in Evennia use their
class docstrings to represent the in-game help entry for that command.
For the default look of Command class docstrings see instead
[the default command documentation policy][command-docstrings].
These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.
### Automatic docstring templating
All the commands in the _default command_ sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
style for contrib-command docstrings as well.
The Python IDE [Pycharm][pycharm] will generate Evennia-friendly
docstring stubs automatically for you, but the default format is
reStructuredText. To change it to Evennia's Google-style, follow
[this guide][pycharm-guide].
```python
"""
Short header
## Ask Questions!
Usage:
key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
Switches:
switch1 - description
switch2 - description
Examples:
Usage example and output
Longer documentation detailing the command.
"""
```
- Two spaces are used for *indentation* in all default commands.
- Square brackets `[ ]` surround *optional, skippable arguments*.
- Angled brackets `< >` surround a _description_ of what to write rather than the exact syntax.
- Explicit choices are separated by `|`. To avoid this being parsed as a color code, use `||` (this
will come out as a single `|`) or put spaces around the character ("` | `") if there's plenty of room.
- The `Switches` and `Examples` blocks are optional and based on the Command.
Here is the `nick` command as an example:
```python
"""
Define a personal alias/nick
Usage:
nick[/switches] <nickname> = [<string>]
alias ''
Switches:
object - alias an object
account - alias an account
clearall - clear all your aliases
list - show all defined aliases (also "nicks" works)
Examples:
nick hi = say Hello, I'm Sarah!
nick/object tom = the tall man
A 'nick' is a personal shortcut you create for your own use [...]
"""
```
For commands that *require arguments*, the policy is for it to return a `Usage:`
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of
```python
if not self.args:
self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
return
```
## Tools for auto-linting
### black
Automatic pep8 compliant formatting and linting can be performed using the
`black` formatter:
black --line-length 100
### PyCharm
The Python IDE [Pycharm][pycharm] can auto-generate empty doc-string stubs. The
default is to use `reStructuredText` form, however. To change to Evennia's
Google-style docstrings, follow [this guide][pycharm-guide].
If any of the rules outlined in PEP 8 or in the sections above doesn't
make sense, please don't hesitate to ask on the Evennia mailing list
or in the chat.
[pep8]: http://www.python.org/dev/peps/pep-0008

9
docs/pylib/contrib_readmes2docs.py
View File

@ -80,7 +80,7 @@ Each contrib contains installation instructions for how to integrate it
with your other code. If you want to tweak the code of a contrib, just
copy its entire folder to your game directory and modify/use it from there.
If you want to contribute yourself, see [here](Contributing)!
If you want to add a contrib, see [the contrib guidelines](Contribs-Guidelines)!
[forum]: https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets
@ -90,7 +90,12 @@ If you want to contribute yourself, see [here](Contributing)!
"""
TOCTREE = """```{{toctree}}
TOCTREE = """
```{{toctree}}
:hidden:
Contribs-Guidelines.md
```
```{{toctree}}
:maxdepth: 1
{listing}

20
docs/pylib/update_dynamic_pages.py
View File

@ -12,9 +12,26 @@ DOCSRCDIR = pathjoin(DOCDIR, "source")
EVENNIADIR = pathjoin(ROOTDIR, "evennia")
def update_code_style():
"""
Plain CODING_STYLE.md copy
"""
sourcefile = pathjoin(ROOTDIR, "CODING_STYLE.md")
targetfile = pathjoin(DOCSRCDIR, "Coding", "Evennia-Code-Style.md")
with open(sourcefile) as fil:
txt = fil.read()
with open(targetfile, "w") as fil:
fil.write(txt)
print(" -- Updated Evennia-Code-Style.md")
def update_changelog():
"""
Plain CHANGELOG copy
Plain CHANGELOG.md copy
"""
@ -77,6 +94,7 @@ def update_dynamic_pages():
"""
update_changelog()
update_default_settings()
update_code_style()
if __name__ == "__main__":

149
docs/source/Coding/Coding-FAQ.md
View File

@ -4,27 +4,8 @@
the docs if you can rather than too lengthy explanations. Don't forget to check if an answer already
exists before answering - maybe you can clarify that answer rather than to make a new Q&A section.*
## Table of Contents
- [Removing default commands](./Coding-FAQ.md#removing-default-commands)
- [Preventing character from moving based on a condition](./Coding-FAQ.md#preventing-character-from-
moving-based-on-a-condition)
- [Reference initiating object in an EvMenu command](./Coding-FAQ.md#reference-initiating-object-in-an-
evmenu-command)
- [Adding color to default Evennia Channels](./Coding-FAQ.md#adding-color-to-default-evennia-channels)
- [Selectively turn off commands in a room](./Coding-FAQ.md#selectively-turn-off-commands-in-a-room)
- [Select Command based on a condition](./Coding-FAQ.md#select-command-based-on-a-condition)
- [Automatically updating code when reloading](./Coding-FAQ.md#automatically-updating-code-when-
reloading)
- [Changing all exit messages](./Coding-FAQ.md#changing-all-exit-messages)
- [Add parsing with the "to" delimiter](./Coding-FAQ.md#add-parsing-with-the-to-delimiter)
- [Store last used session IP address](./Coding-FAQ.md#store-last-used-session-ip-address)
- [Use wide characters with EvTable](./Coding-FAQ.md#non-latin-characters-in-evtable)
## Removing default commands
**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](../Components/Commands.md) from the
Character [Command Set](../Components/Command-Sets.md)?
**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](../Components/Commands.md) from the 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:
@ -70,32 +51,6 @@ class MyObjectCommand(Command):
Inside the menu you can now access the object through `caller.ndb._evmenu.stored_obj`.
## Adding color to default Evennia Channels
**Q:** How do I add colors to the names of Evennia channels?
**A:** The Channel typeclass' `channel_prefix` method decides what is shown at the beginning of a
channel send. Edit `mygame/typeclasses/channels.py` (and then `@reload`):
```python
# define our custom color names
CHANNEL_COLORS = {"public": "|015Public|n",
"newbie": "|550N|n|551e|n|552w|n|553b|n|554i|n|555e|n",
"staff": "|010S|n|020t|n|030a|n|040f|n|050f|n"}
# Add to the Channel class
# ...
def channel_prefix(self, msg, emit=False):
if self.key in COLORS:
p_str = CHANNEL_COLORS.get(self.key.lower())
else:
p_str = self.key.capitalize()
return f"[{p_str}] "
```
Additional hint: To make colors easier to change from one place you could instead put the
`CHANNEL_COLORS` dict in your settings file and import it as `from django.conf.settings import
CHANNEL_COLORS`.
## Selectively turn off commands in a room
**Q:** I want certain commands to turn off in a given room. They should still work normally for
staff.
@ -130,18 +85,16 @@ class BlockingRoom(Room):
# are NOT Builders or higher
self.locks.add("call:not perm(Builders)")
```
After `@reload`, make some `BlockingRooms` (or switch a room to it with `@typeclass`). Entering one
After `reload`, make some `BlockingRooms` (or switch a room to it with `@typeclass`). Entering one
will now replace the given commands for anyone that does not have the `Builders` or higher
permission. Note that the 'call' lock is special in that even the superuser will be affected by it
(otherwise superusers would always see other player's cmdsets and a game would be unplayable for
superusers).
(otherwise superusers would always see other player's cmdsets and a game would be unplayable for superusers).
## Select Command based on a condition
**Q:** I want a command to be available only based on a condition. For example I want the "werewolf"
command to only be available on a full moon, from midnight to three in-game time.
**A:** This is easiest accomplished by putting the "werewolf" command on the Character as normal,
but to [lock](../Components/Locks.md) it with the "cmd" type lock. Only if the "cmd" lock type is passed will the
**A:** This is easiest accomplished by putting the "werewolf" command on the Character as normal, but to [lock](../Components/Locks.md) it with the "cmd" type lock. Only if the "cmd" lock type is passed will the
command be available.
```python
@ -156,8 +109,7 @@ class CmdWerewolf(Command):
def func(self):
# ...
```
Add this to the [default cmdset as usual](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md). The `is_full_moon` [lock
function](../Components/Locks.md#lock-functions) does not yet exist. We must create that:
Add this to the [default cmdset as usual](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md). The `is_full_moon` [lock function](../Components/Locks.md#lock-functions) does not yet exist. We must create that:
```python
# in mygame/server/conf/lockfuncs.py
@ -169,17 +121,17 @@ def is_full_moon(accessing_obj, accessed_obj,
# return True or False
```
After a `@reload`, the `werewolf` command will be available only at the right time, that is when the
After a `reload`, the `werewolf` command will be available only at the right time, that is when the
`is_full_moon` lock function returns True.
## Automatically updating code when reloading
**Q:** I have a development server running Evennia. Can I have the server update its code-base when
I reload?
**A:** Having a development server that pulls updated code whenever you reload it can be really
useful if you have limited shell access to your server, or want to have it done automatically. If
you have your project in a configured Git environment, it's a matter of automatically calling `git
pull` when you reload. And that's pretty straightforward:
you have your project in a configured Git environment, it's a matter of automatically calling `git pull` when you reload. And that's pretty straightforward:
In `/server/conf/at_server_startstop.py`:
@ -196,45 +148,30 @@ def at_server_reload_stop():
process = subprocess.call(["git", "pull"], shell=False)
```
That's all. We call `subprocess` to execute a shell command (that code works on Windows and Linux,
assuming the current directory is your game directory, which is probably the case when you run
Evennia). `call` waits for the process to complete, because otherwise, Evennia would reload on
partially-modified code, which would be problematic.
That's all. We call `subprocess` to execute a shell command (that code works on Windows and Linux, assuming the current directory is your game directory, which is probably the case when you run Evennia). `call` waits for the process to complete, because otherwise, Evennia would reload on partially-modified code, which would be problematic.
Now, when you enter `@reload` on your development server, the game repository is updated from the
configured remote repository (Github, for instance). Your development cycle could resemble
something like:
Now, when you enter `reload` on your development server, the game repository is updated from the configured remote repository (Github, for instance). Your development cycle could resemble something like:
1. Coding on the local machine.
2. Testing modifications.
3. Committing once, twice or more (being sure the code is still working, unittests are pretty useful
here).
3. Committing once, twice or more (being sure the code is still working, unittests are pretty useful here).
4. When the time comes, login to the development server and run `@reload`.
The reloading might take one or two additional seconds, since Evennia will pull from your remote Git
repository. But it will reload on it and you will have your modifications ready, without needing
The reloading might take one or two additional seconds, since Evennia will pull from your remote Git repository. But it will reload on it and you will have your modifications ready, without needing
connecting to your server using SSH or something similar.
## Changing all exit messages
**Q:** How can I change the default exit messages to something like "XXX leaves east" or "XXX
arrives from the west"?
**A:** the default exit messages are stored in two hooks, namely `announce_move_from` and
`announce_move_to`, on the `Character` typeclass (if what you want to change is the message other
characters will see when a character exits).
**A:** the default exit messages are stored in two hooks, namely `announce_move_from` and `announce_move_to`, on the `Character` typeclass (if what you want to change is the message other characters will see when a character exits).
These two hooks provide some useful features to easily update the message to be displayed. They
take both the default message and mapping as argument. You can easily call the parent hook with
these information:
These two hooks provide some useful features to easily update the message to be displayed. They take both the default message and mapping as argument. You can easily call the parent hook with these information:
* The message represents the string of characters sent to characters in the room when a character
leaves.
* The mapping is a dictionary containing additional mappings (you will probably not need it for
simple customization).
* The message represents the string of characters sent to characters in the room when a character leaves.
* The mapping is a dictionary containing additional mappings (you will probably not need it for simple customization).
It is advisable to look in the [code of both
hooks](https://github.com/evennia/evennia/tree/master/evennia/objects/objects.py), and read the
hooks' documentation. The explanations on how to quickly update the message are shown below:
It is advisable to look in the [code of both hooks](evennia.objects.objects.DefaultCharacter), and read the hooks' documentation. The explanations on how to quickly update the message are shown below:
```python
# In typeclasses/characters.py
@ -295,18 +232,13 @@ class Character(DefaultCharacter):
super().announce_move_to(source_location, msg="{object} arrives from the {exit}.")
```
We override both hooks, but call the parent hook to display a different message. If you read the
provided docstrings, you will better understand why and how we use mappings (information between
braces). You can provide additional mappings as well, if you want to set a verb to move, for
instance, or other, extra information.
We override both hooks, but call the parent hook to display a different message. If you read the provided docstrings, you will better understand why and how we use mappings (information between braces). You can provide additional mappings as well, if you want to set a verb to move, for instance, or other, extra information.
## Add parsing with the "to" delimiter
**Q:** How do I change commands to undestand say `give obj to target` as well as the default `give
obj = target`?
**Q:** How do I change commands to undestand say `give obj to target` as well as the default `give obj = target`?
**A:** You can make change the default `MuxCommand` parent with your own class making a small change
in its `parse` method:
**A:** You can make change the default `MuxCommand` parent with your own class making a small change in its `parse` method:
```python
# in mygame/commands/command.py
@ -324,42 +256,9 @@ Next you change the parent of the default commands in settings:
COMMAND_DEFAULT_CLASS = "commands.command.MuxCommand"
```
Do a `@reload` and all default commands will now use your new tweaked parent class. A copy of the
Do a `reload` and all default commands will now use your new tweaked parent class. A copy of the
MuxCommand class is also found commented-out in the `mygame/commands/command.py` file.
## Store last used session IP address
**Q:** If a user has already logged out of an Evennia account, their IP is no longer visible to
staff that wants to ban-by-ip (instead of the user) with `@ban/ip`?
**A:** One approach is to write the IP from the last session onto the "account" account object.
`typeclasses/accounts.py`
```python
def at_post_login(self, session=None, **kwargs):
super().at_post_login(session=session, **kwargs)
self.db.lastsite = self.sessions.all()[-1].address
```
Adding timestamp for login time and appending to a list to keep the last N login IP addresses and
timestamps is possible, also. Additionally, if you don't want the list to grow beyond a
`do_not_exceed` length, conditionally pop a value after you've added it, if the length has grown too
long.
**NOTE:** You'll need to add `import time` to generate the login timestamp.
```python
def at_post_login(self, session=None, **kwargs):
super().at_post_login(session=session, **kwargs)
do_not_exceed = 24 # Keep the last two dozen entries
session = self.sessions.all()[-1] # Most recent session
if not self.db.lastsite:
self.db.lastsite = []
self.db.lastsite.insert(0, (session.address, int(time.time())))
if len(self.db.lastsite) > do_not_exceed:
self.db.lastsite.pop()
```
This only stores the data. You may want to interface the `@ban` command or make a menu-driven viewer
for staff to browse the list and display how long ago the login occurred.
## Non-latin characters in EvTable
**Q:** When using e.g. Chinese characters in EvTable, some lines appear to be too wide, for example
@ -370,8 +269,4 @@ for staff to browse the list and display how long ago the login occurred.
| | |
+~~~~~~+~~~~~~+
```
**A:** The reason for this is because certain non-latin characters are *visually* much wider than
their len() suggests. There is little Evennia can (reliably) do about this. If you are using such
characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You
can set this in your web client and need to recommend it for telnet-client users. See [this
discussion](https://github.com/evennia/evennia/issues/1522) where some suitable fonts are suggested.
**A:** The reason for this is because certain non-latin characters are *visually* much wider than their len() suggests. There is little Evennia can (reliably) do about this. If you are using such characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You can set this in your web client and need to recommend it for telnet-client users. See [this discussion](https://github.com/evennia/evennia/issues/1522) where some suitable fonts are suggested.

121
docs/source/Coding/Coding-Introduction.md
View File

@ -1,121 +0,0 @@
# Coding Introduction
Evennia allows for a lot of freedom when designing your game - but to code efficiently you still
need to adopt some best practices as well as find a good place to start to learn.
Here are some pointers to get you going.
## Start with the tutorial
It's highly recommended that you jump in on the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Overview.md). Even if
you only the beginning or some part of it, it covers much of the things needed to get started, including giving you are first introduction to Python.
## Explore Evennia interactively
As mentioned in the Starting tutorial, it's a good idea to use [ipython](https://ipython.org/) to explore things using a python shell:
# [open a new console/terminal]
cd mygame
evennia shell
This will open an Evennia-aware python shell (using ipython). From within this shell, try
import evennia
evennia.<TAB>
### Jupyter Notebook Support
You can also explore evennia interactively in a [Jupyter notebook](https://jupyter.readthedocs.io/en/latest/index.html#). This offers
an in-browser view of your code similar to Matlab or similar programs. There are
a few extra steps that must be taken in order for this to work:
# [open a new console/terminal]
# [activate your evennia virtualenv in this console/terminal]
cd evennia
pip install -r requirements_extra.txt # if not done already above
Next, `cd` to your game folder. _It's important that you are in the _root_ of this folder for the next command_:
evennia shell_plus --notebook &
The `&` at the end starts the process as a background process on Linux/Unix.
Skip it if your OS doesn't support this syntax. Your browser should now open
with the Jupyter interface. If not, open a browser to the link given on the
command line.
In the window, open the `new` menu in the top right and start a `Django Shell-Plus` notebook (or
open an existing one if you had one from before). In the first cell you must initialize
Evennia like so:
```python
import evennia
evennia._init()
```
_Note that the above initialization must be run every time a new new notebook/kernel is started or restarted._
After this you can import and access all of the Evennia system, same as with `evennia shell`.
### 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](../Howtos/Howtos-Overview.md) section also contains a growing collection
of system- or implementation-specific help.
## Use a python syntax checker
Evennia works by importing your own modules and running them as part of the server. Whereas Evennia
should just gracefully tell you what errors it finds, it can nevertheless be a good idea for you to
check your code for simple syntax errors *before* you load it into the running server. There are
many python syntax checkers out there. A fast and easy one is
[pyflakes](https://pypi.python.org/pypi/pyflakes), a more verbose one is
[pylint](https://www.pylint.org/). You can also check so that your code looks up to snuff using
[pep8](https://pypi.python.org/pypi/pep8). Even with a syntax checker you will not be able to catch
every possible problem - some bugs or problems will only appear when you actually run the code. But
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](../Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-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
As part of the Evennia setup you will create a game folder to host your game code. This is your
home. You should *never* need to modify anything in the `evennia` library (anything you download
from us, really). You import useful functionality from here and if you see code you like, copy&paste
it out into your game folder and edit it there.
If you find that Evennia doesn't support some functionality you need, make a Feature Request about it. Same goes for bugs. If you add features or fix bugs yourself, please consider [Contributing](../Contributing.md) your changes upstream!
## Learn to read tracebacks
Python is very good at reporting when and where things go wrong. A *traceback* shows everything you
need to know about crashing code. The text can be pretty long, but you usually are only interested
in the last bit, where it says what the error is and at which module and line number it happened -
armed with this info you can resolve most problems.
Evennia will usually not show the full traceback in-game though. Instead the server outputs errors
to the terminal/console from which you started Evennia in the first place. If you want more to show
in-game you can add `IN_GAME_ERRORS = True` to your settings file. This will echo most (but not all)
tracebacks both in-game as well as to the terminal/console. This is a potential security problem
though, so don't keep this active when your game goes into production.
> A common confusing error is finding that objects in-game are suddenly of the type `DefaultObject`
rather than your custom typeclass. This happens when you introduce a critical Syntax error to the
module holding your custom class. Since such a module is not valid Python, Evennia can't load it at
all. Instead of crashing, Evennia will then print the full traceback to the terminal/console and
temporarily fall back to the safe `DefaultObject` until you fix the problem and reload.
## Docs are here to help you
Some people find reading documentation extremely dull and shun it out of principle. That's your
call, but reading docs really *does* help you, promise! Evennia's documentation is pretty thorough
and knowing what is possible can often give you a lot of new cool game ideas. That said, if you
can't find the answer in the docs, don't be shy to ask questions! The [discussion
group](https://sites.google.com/site/evenniaserver/discussions) and the [irc
chat](https://webchat.freenode.net/?channels=evennia) are also there for you.
## The most important point
And finally, of course, have fun!

18
docs/source/Coding/Coding-Overview.md
View File

@ -3,29 +3,17 @@
This documentation aims to help you set up a sane development environment to
make your game, also if you never coded before. If you are an experienced coder, much of this will be familiar to you, but some things may still be useful.
## Setting up a workflow
See also the [Beginner Tutorial](../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.md).
```{toctree}
:maxdepth: 2
Version-Control.md
Updating-Your-Game.md
```
## Coding away
```{toctree}
:maxdepth: 2
Coding-Introduction.md
Coding-FAQ.md
Debugging.md
Unit-Testing.md
Profiling.md
Evennia-Code-Style.md
Coding-FAQ.md
Quirks.md
```
@ -40,7 +28,7 @@ Changelog.md
## Third-party integrations
```{toctree}
:maxdepth: 2
:maxdepth: 1
Continuous-Integration.md
Setting-up-PyCharm.md

20
docs/source/Coding/Continuous-Integration.md
View File

@ -1,14 +1,8 @@
# Continuous Integration
# Continuous Integration (CI)
One of the advantages of Evennia over traditional MU* development systems is that Evennia can
integrate into enterprise-level integration environments and source control.
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 (CI)?
[Continuous Integration (CI)](https://www.thoughtworks.com/continuous-integration) is a development
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.
[Continuous Integration (CI)](https://www.thoughtworks.com/continuous-integration) is a development 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:
@ -19,10 +13,9 @@ For Evennia, continuous integration allows an automated build process to:
* Publish those files to the server directory
* Reload the game.
## List of continuous integration tools
## List of CI Evennia tutorials
There are a lot of tools and services providing CI functionality. Here are a few that people have used
with Evennia:
There are a lot of tools and services providing CI functionality. Here are a few that people have used with Evennia:
```{toctree}
:maxdepth: 1
@ -32,5 +25,4 @@ Continuous-Integration-TeamCity.md
```
[This is an overview of other tools](https://www.atlassian.com/continuous-delivery/continuous-integration/tools)
(external link).
[This is an overview of other tools](https://www.atlassian.com/continuous-delivery/continuous-integration/tools) (external link).

86
docs/source/Coding/Debugging.md
View File

@ -1,12 +1,8 @@
# Debugging
Sometimes, an error is not trivial to resolve. A few simple `print` statements is not enough to find the cause of the issue. The traceback is not informative or even non-existing.
Sometimes, an error is not trivial to resolve. A few simple `print` statements is not enough to find
the cause of the issue. Running a *debugger* can then be very helpful and save a lot of time.
Debugging
means running Evennia under control of a special *debugger* program. This allows you to stop the
action at a given point, view the current state and step forward through the program to see how its
logic works.
Running a *debugger* can then be very helpful and save a lot of time. Debugging means running Evennia under control of a special *debugger* program. This allows you to stop the action at a given point, view the current state and step forward through the program to see how its logic works.
Evennia natively supports these debuggers:
@ -24,11 +20,8 @@ To run Evennia with the debugger, follow these steps:
```python
from evennia import set_trace;set_trace()
```
2. (Re-)start Evennia in interactive (foreground) mode with `evennia istart`. This is important -
without this step the debugger will not start correctly - it will start in this interactive
terminal.
3. Perform the steps that will trigger the line where you added the `set_trace()` call. The debugger
will start in the terminal from which Evennia was interactively started.
2. (Re-)start Evennia in interactive (foreground) mode with `evennia istart`. This is important - without this step the debugger will not start correctly - it will start in this interactive terminal.
3. Perform the steps that will trigger the line where you added the `set_trace()` call. The debugger will start in the terminal from which Evennia was interactively started.
The `evennia.set_trace` function takes the following arguments:
@ -37,8 +30,7 @@ The `evennia.set_trace` function takes the following arguments:
evennia.set_trace(debugger='auto', term_size=(140, 40))
```
Here, `debugger` is one of `pdb`, `pudb` or `auto`. If `auto`, use `pudb` if available, otherwise
use `pdb`. The `term_size` tuple sets the viewport size for `pudb` only (it's ignored by `pdb`).
Here, `debugger` is one of `pdb`, `pudb` or `auto`. If `auto`, use `pudb` if available, otherwise use `pdb`. The `term_size` tuple sets the viewport size for `pudb` only (it's ignored by `pdb`).
## A simple example using pdb
@ -71,9 +63,7 @@ class CmdTest(Command):
```
If you type `test` in your game, everything will freeze. You won't get any feedback from the game,
and you won't be able to enter any command (nor anyone else). It's because the debugger has started
in your console, and you will find it here. Below is an example with `pdb`.
If you type `test` in your game, everything will freeze. You won't get any feedback from the game, and you won't be able to enter any command (nor anyone else). It's because the debugger has started in your console, and you will find it here. Below is an example with `pdb`.
```
...
@ -83,13 +73,11 @@ in your console, and you will find it here. Below is an example with `pdb`.
```
`pdb` notes where it has stopped execution and, what line is about to be executed (in our case, `obj
= self.search(self.args)`), and ask what you would like to do.
`pdb` notes where it has stopped execution and, what line is about to be executed (in our case, `obj = self.search(self.args)`), and ask what you would like to do.
### Listing surrounding lines of code
When you have the `pdb` prompt `(Pdb)`, you can type in different commands to explore the code. The
first one you should know is `list` (you can type `l` for short):
When you have the `pdb` prompt `(Pdb)`, you can type in different commands to explore the code. The first one you should know is `list` (you can type `l` for short):
```
(Pdb) l
@ -107,18 +95,13 @@ first one you should know is `list` (you can type `l` for short):
(Pdb)
```
Okay, this didn't do anything spectacular, but when you become more confident with `pdb` and find
yourself in lots of different files, you sometimes need to see what's around in code. Notice that
there is a little arrow (`->`) before the line that is about to be executed.
Okay, this didn't do anything spectacular, but when you become more confident with `pdb` and find yourself in lots of different files, you sometimes need to see what's around in code. Notice that there is a little arrow (`->`) before the line that is about to be executed.
This is important: **about to be**, not **has just been**. You need to tell `pdb` to go on (we'll
soon see how).
This is important: **about to be**, not **has just been**. You need to tell `pdb` to go on (we'll soon see how).
### Examining variables
`pdb` allows you to examine variables (or really, to run any Python instruction). It is very useful
to know the values of variables at a specific line. To see a variable, just type its name (as if
you were in the Python interpreter:
`pdb` allows you to examine variables (or really, to run any Python instruction). It is very useful to know the values of variables at a specific line. To see a variable, just type its name (as if you were in the Python interpreter:
```
(Pdb) self
@ -158,9 +141,7 @@ AttributeError: "'CmdTest' object has no attribute 'search'"
(Pdb)
```
`Pdb` is complaining that you try to call the `search` method on a command... whereas there's no
`search` method on commands. The character executing the command is in `self.caller`, so we might
change our line:
`Pdb` is complaining that you try to call the `search` method on a command... whereas there's no `search` method on commands. The character executing the command is in `self.caller`, so we might change our line:
```python
obj = self.caller.search(self.args)
@ -168,19 +149,14 @@ obj = self.caller.search(self.args)
### Letting the program run
`pdb` is waiting to execute the same instruction... it provoked an error but it's ready to try
again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a
command. To tell `pdb` to terminate and keep on running the program, use the `continue` (or `c`)
command:
`pdb` is waiting to execute the same instruction... it provoked an error but it's ready to try again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a command. To tell `pdb` to terminate and keep on running the program, use the `continue` (or `c`) command:
```
(Pdb) c
...
```
You see an error being caught, that's the error we have fixed... or hope to have. Let's reload the
game and try again. You need to run `evennia istart` again and then run `test` to get into the
command again.
You see an error being caught, that's the error we have fixed... or hope to have. Let's reload the game and try again. You need to run `evennia istart` again and then run `test` to get into the command again.
```
> .../mygame/commands/command.py(79)func()
@ -218,12 +194,11 @@ fix that bug too, it would be better):
...
```
Notice that you'll have an error in the game this time. Let's try with a valid parameter. I have
another character, `barkeep`, in this room:
Notice that you'll have an error in the game this time. Let's try with a valid parameter. I have another character, `barkeep`, in this room:
```test barkeep```
And again, the command freezes, and we have the debugger opened in the console.
And again, the command freezes, and we have the debugger opened in the console.
Let's execute this line right away:
@ -248,32 +223,16 @@ TypeError: 'get_display_name() takes exactly 2 arguments (1 given)'
(Pdb)
```
As an exercise, fix this error, reload and run the debugger again. Nothing better than some
experimenting!
As an exercise, fix this error, reload and run the debugger again. Nothing better than some experimenting!
Your debugging will often follow the same strategy:
1. Receive an error you don't understand.
2. Put a breaking point **BEFORE** the error occurs.
3. Run the code again and see the debugger open.
4. Run the program line by line,examining variables, checking the logic of instructions.
5. Continue and try again, each step a bit further toward the truth and the working feature.
### Stepping through a function
`n` is useful, but it will avoid stepping inside of functions if it can. But most of the time, when
we have an error we don't understand, it's because we use functions or methods in a way that wasn't
intended by the developer of the API. Perhaps using wrong arguments, or calling the function in a
situation that would cause a bug. When we have a line in the debugger that calls a function or
method, we can "step" to examine it further. For instance, in the previous example, when `pdb` was
about to execute `obj = self.caller.search(self.args)`, we may want to see what happens inside of
the `search` method.
To do so, use the `step` (or `s`) command. This command will show you the definition of the
function/method and you can then use `n` as before to see it line-by-line. In our little example,
stepping through a function or method isn't that useful, but when you have an impressive set of
commands, functions and so on, it might really be handy to examine some feature and make sure they
operate as planned.
3. Run `evennia istart`
4. Run the code again and see the debugger open.
5. Run the program line by line, examining variables, checking the logic of instructions.
6. Continue and try again, each step a bit further toward the truth and the working feature.
## Cheat-sheet of pdb/pudb commands
@ -292,5 +251,4 @@ this directly). |
| `<RETURN>` | Repeat the last command (don't type `n` repeatedly, just type it once and then press
`<RETURN>` to repeat it). |
If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that
topic here](https://pymotw.com/3/pdb/).
If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that topic here](https://pymotw.com/3/pdb/).

278
docs/source/Coding/Evennia-Code-Style.md Normal file
View File

@ -0,0 +1,278 @@
# Evennia Code Style
All code submitted or committed to the Evennia project should aim to follow the
guidelines outlined in [Python PEP 8][pep8]. Keeping the code style uniform
makes it much easier for people to collaborate and read the code.
A good way to check if your code follows PEP8 is to use the [PEP8 tool][pep8tool]
on your sources.
## Main code style specification
* 4-space indentation, NO TABS!
* Unix line endings.
* 100 character line widths
* CamelCase is only used for classes, nothing else.
* All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.
* Module-level global variables (only) are to be in CAPITAL letters.
* Imports should be done in this order:
- Python modules (builtins and standard library)
- Twisted modules
- Django modules
- Evennia library modules (`evennia`)
- Evennia contrib modules (`evennia.contrib`)
* All modules, classes, functions and methods should have doc strings formatted
as outlined below.
* All default commands should have a consistent docstring formatted as
outlined below.
## Code Docstrings
All modules, classes, functions and methods should have docstrings
formatted with [Google style][googlestyle] -inspired indents, using
[Markdown][githubmarkdown] formatting where needed. Evennia's `api2md`
parser will use this to create pretty API documentation.
### Module docstrings
Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module.
Example of module docstring (top of file):
```python
"""
This module handles the creation of `Objects` that
are useful in the game ...
"""
```
Sectioning (`# title`, `## subtile` etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Write just the section name bolded on its own line to mark a section.
Beyond sections markdown should be used as needed to format
the text.
Code examples should use [multi-line syntax highlighting][markdown-hilight]
to mark multi-line code blocks, using the "python" identifier. Just
indenting code blocks (common in markdown) will not produce the
desired look.
When using any code tags (inline or blocks) it's recommended that you
don't let the code extend wider than about 70 characters or it will
need to be scrolled horizontally in the wiki (this does not affect any
other text, only code).
### Class docstrings
The root class docstring should describe the over-arching use of the
class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API
develops. Don't use section markers (`#`, `##` etc).
Example of class docstring:
```python
class MyClass(object):
"""
This class describes the creation of `Objects`. It is useful
in many situations, such as ...
"""
```
### Function / method docstrings
Example of function or method docstring:
```python
def funcname(a, b, c, d=False, **kwargs):
"""
This is a brief introduction to the function/class/method
Args:
a (str): This is a string argument that we can talk about
over multiple lines.
b (int or str): Another argument.
c (list): A list argument.
d (bool, optional): An optional keyword argument.
Keyword Args:
test (list): A test keyword.
Returns:
str: The result of the function.
Raises:
RuntimeException: If there is a critical error,
this is raised.
IOError: This is only raised if there is a
problem with the database.
Notes:
This is an example function. If `d=True`, something
amazing will happen.
"""
```
The syntax is very "loose" but the indentation matters. That is, you
should end the block headers (like `Args:`) with a line break followed by
an indent. When you need to break a line you should start the next line
with another indent. For consistency with the code we recommend all
indents to be 4 spaces wide (no tabs!).
Here are all the supported block headers:
```
"""
Args
argname (freeform type): Description endind with period.
Keyword Args:
argname (freeform type): Description.
Returns/Yields:
type: Description.
Raises:
Exceptiontype: Description.
Notes/Note/Examples/Example:
Freeform text.
"""
```
Parts marked with "freeform" means that you can in principle put any
text there using any formatting except for sections markers (`#`, `##`
etc). You must also keep indentation to mark which block you are part
of. You should normally use the specified format rather than the
freeform counterpart (this will produce nicer output) but in some
cases the freeform may produce a more compact and readable result
(such as when describing an `*args` or `**kwargs` statement in general
terms). The first `self` argument of class methods should never be
documented.
Note that
```
"""
Args:
argname (type, optional): Description.
"""
```
and
```
"""
Keyword Args:
sargname (type): Description.
"""
```
mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
`**kwargs` block in the function, using the `Keyword Args:` block may be a
good idea, for a small number of arguments though, just using `Args:`
and marking keywords as `optional` will shorten the docstring and make
it easier to read.
## Default Command Docstrings
These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.
All the commands in the _default command_ sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
style for contrib-command docstrings as well.
```python
"""
Short header
Usage:
key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
Switches:
switch1 - description
switch2 - description
Examples:
Usage example and output
Longer documentation detailing the command.
"""
```
- Two spaces are used for *indentation* in all default commands.
- Square brackets `[ ]` surround *optional, skippable arguments*.
- Angled brackets `< >` surround a _description_ of what to write rather than the exact syntax.
- Explicit choices are separated by `|`. To avoid this being parsed as a color code, use `||` (this
will come out as a single `|`) or put spaces around the character ("` | `") if there's plenty of room.
- The `Switches` and `Examples` blocks are optional and based on the Command.
Here is the `nick` command as an example:
```python
"""
Define a personal alias/nick
Usage:
nick[/switches] <nickname> = [<string>]
alias ''
Switches:
object - alias an object
account - alias an account
clearall - clear all your aliases
list - show all defined aliases (also "nicks" works)
Examples:
nick hi = say Hello, I'm Sarah!
nick/object tom = the tall man
A 'nick' is a personal shortcut you create for your own use [...]
"""
```
For commands that *require arguments*, the policy is for it to return a `Usage:`
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of
```python
if not self.args:
self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
return
```
## Tools for auto-linting
### black
Automatic pep8 compliant formatting and linting can be performed using the
`black` formatter:
black --line-length 100
### PyCharm
The Python IDE [Pycharm][pycharm] can auto-generate empty doc-string stubs. The
default is to use `reStructuredText` form, however. To change to Evennia's
Google-style docstrings, follow [this guide][pycharm-guide].
[pep8]: http://www.python.org/dev/peps/pep-0008
[pep8tool]: https://pypi.python.org/pypi/pep8
[googlestyle]: https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html
[githubmarkdown]: https://help.github.com/articles/github-flavored-markdown/
[markdown-hilight]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting
[command-docstrings]: https://github.com/evennia/evennia/wiki/Using%20MUX%20As%20a%20Standard#documentation-policy
[pycharm]: https://www.jetbrains.com/pycharm/
[pycharm-guide]: https://www.jetbrains.com/help/pycharm/2016.3/python-integrated-tools.html

108
docs/source/Coding/Profiling.md
View File

@ -1,24 +1,16 @@
# Profiling
*This is considered an advanced topic mainly of interest to server developers.*
```{important}
This is considered an advanced topic. It's mainly of interest to server developers.
```
## Introduction
Sometimes it can be useful to try to determine just how efficient a particular piece of code is, or to figure out if one could speed up things more than they are. There are many ways to test the performance of Python and the running server.
Sometimes it can be useful to try to determine just how efficient a particular
piece of code is, or to figure out if one could speed up things more than they
are. There are many ways to test the performance of Python and the running
server.
Before digging into this section, remember Donald Knuth's
[words of wisdom](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize):
Before digging into this section, remember Donald Knuth's [words of wisdom](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize):
> *[...]about 97% of the time: Premature optimization is the root of all evil*.
That is, don't start to try to optimize your code until you have actually
identified a need to do so. This means your code must actually be working before
you start to consider optimization. Optimization will also often make your code
more complex and harder to read. Consider readability and maintainability and
you may find that a small gain in speed is just not worth it.
That is, don't start to try to optimize your code until you have actually identified a need to do so. This means your code must actually be working before you start to consider optimization. Optimization will also often make your code more complex and harder to read. Consider readability and maintainability and you may find that a small gain in speed is just not worth it.
## Simple timer tests
@ -36,53 +28,31 @@ could use the following code:
<<< 5.358283996582031
```
The `setup` keyword is used to set up things that should not be included in the
time measurement, like `a = []` in the first call.
The `setup` keyword is used to set up things that should not be included in the time measurement, like `a = []` in the first call.
By default the `timeit` function will re-run the given test 1000000 times and
returns the *total time* to do so (so *not* the average per test). A hint is to
not use this default for testing something that includes database writes - for
that you may want to use a lower number of repeats (say 100 or 1000) using the
`number=100` keyword.
By default the `timeit` function will re-run the given test 1000000 times and returns the *total time* to do so (so *not* the average per test). A hint is to not use this default for testing something that includes database writes - for that you may want to use a lower number of repeats (say 100 or 1000) using the `number=100` keyword.
In the example above, we see that this number of calls, using a list comprehension is about twice as fast as building a list using `.append()`.
## Using cProfile
Python comes with its own profiler, named cProfile (this is for cPython, no
tests have been done with `pypy` at this point). Due to the way Evennia's
processes are handled, there is no point in using the normal way to start the
profiler (`python -m cProfile evennia.py`). Instead you start the profiler
through the launcher:
Python comes with its own profiler, named cProfile (this is for cPython, no tests have been done with `pypy` at this point). Due to the way Evennia's processes are handled, there is no point in using the normal way to start the profiler (`python -m cProfile evennia.py`). Instead you start the profiler through the launcher:
evennia --profiler start
This will start Evennia with the Server component running (in daemon mode) under
cProfile. You could instead try `--profile` with the `portal` argument to
profile the Portal (you would then need to
[start the Server separately](../Setup/Start-Stop-Reload.md)).
This will start Evennia with the Server component running (in daemon mode) under cProfile. You could instead try `--profile` with the `portal` argument to profile the Portal (you would then need to [start the Server separately](../Setup/Running-Evennia.md)).
Please note that while the profiler is running, your process will use a lot more
memory than usual. Memory usage is even likely to climb over time. So don't
leave it running perpetually but monitor it carefully (for example using the
`top` command on Linux or the Task Manager's memory display on Windows).
Please note that while the profiler is running, your process will use a lot more memory than usual. Memory usage is even likely to climb over time. So don't leave it running perpetually but monitor it carefully (for example using the `top` command on Linux or the Task Manager's memory display on Windows).
Once you have run the server for a while, you need to stop it so the profiler
can give its report. Do *not* kill the program from your task manager or by
sending it a kill signal - this will most likely also mess with the profiler.
Instead either use `evennia.py stop` or (which may be even better), use
`@shutdown` from inside the game.
Once you have run the server for a while, you need to stop it so the profiler can give its report. Do *not* kill the program from your task manager or by sending it a kill signal - this will most likely also mess with the profiler. Instead either use `evennia.py stop` or (which may be even better), use `@shutdown` from inside the game.
Once the server has fully shut down (this may be a lot slower than usual) you
will find that profiler has created a new file `mygame/server/logs/server.prof`.
Once the server has fully shut down (this may be a lot slower than usual) you will find that profiler has created a new file `mygame/server/logs/server.prof`.
### Analyzing the profile
The `server.prof` file is a binary file. There are many ways to analyze and
display its contents, all of which has only been tested in Linux (If you are a
Windows/Mac user, let us know what works).
The `server.prof` file is a binary file. There are many ways to analyze and display its contents, all of which has only been tested in Linux (If you are a Windows/Mac user, let us know what works).
You can look at the contents of the profile file with Python's in-built `pstats`
module in the evennia shell (it's recommended you install `ipython` with `pip
install ipython` in your virtualenv first, for prettier output):
You can look at the contents of the profile file with Python's in-built `pstats` module in the evennia shell (it's recommended you install `ipython` with `pip install ipython` in your virtualenv first, for prettier output):
evennia shell
@ -97,9 +67,7 @@ p.strip_dirs().sort_stats(-1).print_stats()
```
See the
[Python profiling documentation](https://docs.python.org/3/library/profile.html#instant-user-s-manual)
for more information.
See the [Python profiling documentation](https://docs.python.org/3/library/profile.html#instant-user-s-manual) for more information.
You can also visualize the data in various ways.
- [Runsnake](https://pypi.org/project/RunSnakeRun/) visualizes the profile to
@ -112,20 +80,11 @@ You can also visualize the data in various ways.
`pyprof2calltree` via `pip` whereas KCacheGrind is something you need to get
via your package manager or their homepage.
How to analyze and interpret profiling data is not a trivial issue and depends
on what you are profiling for. Evennia being an asynchronous server can also
confuse profiling. Ask on the mailing list if you need help and be ready to be
able to supply your `server.prof` file for comparison, along with the exact
conditions under which it was obtained.
How to analyze and interpret profiling data is not a trivial issue and depends on what you are profiling for. Evennia being an asynchronous server can also confuse profiling. Ask on the mailing list if you need help and be ready to be able to supply your `server.prof` file for comparison, along with the exact conditions under which it was obtained.
## The Dummyrunner
It is difficult to test "actual" game performance without having players in your
game. For this reason Evennia comes with the *Dummyrunner* system. The
Dummyrunner is a stress-testing system: a separate program that logs into your
game with simulated players (aka "bots" or "dummies"). Once connected, these
dummies will semi-randomly perform various tasks from a list of possible
actions. Use `Ctrl-C` to stop the Dummyrunner.
It is difficult to test "actual" game performance without having players in your game. For this reason Evennia comes with the *Dummyrunner* system. The Dummyrunner is a stress-testing system: a separate program that logs into your game with simulated players (aka "bots" or "dummies"). Once connected, these dummies will semi-randomly perform various tasks from a list of possible actions. Use `Ctrl-C` to stop the Dummyrunner.
```{warning}
@ -140,9 +99,7 @@ This is the recommended process for using the dummy runner:
from evennia.server.profiling.settings_mixin import *
This will override your settings and disable Evennia's rate limiters and
DoS-protections, which would otherwise block mass-connecting clients from
one IP. Notably, it will also change to a different (faster) password hasher.
This will override your settings and disable Evennia's rate limiters and DoS-protections, which would otherwise block mass-connecting clients from one IP. Notably, it will also change to a different (faster) password hasher.
1. (recommended): Build a new database. If you use default Sqlite3 and want to
keep your existing database, just rename `mygame/server/evennia.db3` to
`mygame/server/evennia.db3_backup` and run `evennia migrate` and `evennia
@ -156,29 +113,17 @@ This is the recommended process for using the dummy runner:
Use `Ctrl-C` (or `Cmd-C`) to stop it.
If you want to see what the dummies are actually doing you can run with a single
dummy:
If you want to see what the dummies are actually doing you can run with a single dummy:
evennia --dummyrunner 1
The inputs/outputs from the dummy will then be printed. By default the runner
uses the 'looker' profile, which just logs in and sends the 'look' command
over and over. To change the settings, copy the file
`evennia/server/profiling/dummyrunner_settings.py` to your `mygame/server/conf/`
directory, then add this line to your settings file to use it in the new
location:
The inputs/outputs from the dummy will then be printed. By default the runner uses the 'looker' profile, which just logs in and sends the 'look' command over and over. To change the settings, copy the file `evennia/server/profiling/dummyrunner_settings.py` to your `mygame/server/conf/` directory, then add this line to your settings file to use it in the new location:
DUMMYRUNNER_SETTINGS_MODULE = "server/conf/dummyrunner_settings.py"
The dummyrunner settings file is a python code module in its own right - it
defines the actions available to the dummies. These are just tuples of command
strings (like "look here") for the dummy to send to the server along with a
probability of them happening. The dummyrunner looks for a global variable
`ACTIONS`, a list of tuples, where the first two elements define the
commands for logging in/out of the server.
The dummyrunner settings file is a python code module in its own right - it defines the actions available to the dummies. These are just tuples of command strings (like "look here") for the dummy to send to the server along with a probability of them happening. The dummyrunner looks for a global variable `ACTIONS`, a list of tuples, where the first two elements define the commands for logging in/out of the server.
Below is a simplified minimal setup (the default settings file adds a lot more
functionality and info):
Below is a simplified minimal setup (the default settings file adds a lot more functionality and info):
```python
# minimal dummyrunner setup file
@ -224,8 +169,7 @@ ACTIONS = (
```
At the bottom of the default file are a few default profiles you can test out
by just setting the `PROFILE` variable to one of the options.
At the bottom of the default file are a few default profiles you can test out by just setting the `PROFILE` variable to one of the options.
### Dummyrunner hints

63
docs/source/Coding/Setting-up-PyCharm.md
View File

@ -1,18 +1,14 @@
# 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
community edition and also generous licenses for OSS projects like 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 community edition and also generous licenses for OSS projects like Evennia.
> This page was originally tested on Windows (so use Windows-style path examples), but should work
the same for all platforms.
> This page was originally tested on Windows (so use Windows-style path examples), but should work the same for all platforms.
First, install Evennia on your local machine with [[Getting Started]]. If you're new to PyCharm,
loading your project is as easy as selecting the `Open` option when PyCharm starts, and browsing to
your game folder (the one created with `evennia --init`). We refer to it as `mygame` here.
First, install Evennia on your local machine with [[Getting Started]]. If you're new to PyCharm, loading your project is as easy as selecting the `Open` option when PyCharm starts, and browsing to your game folder (the one created with `evennia --init`). We refer to it as `mygame` here.
If you want to be able to examine evennia's core code or the scripts inside your virtualenv, you'll
need to add them to your project too:
1. Go to `File > Open...`
1. Select the folder (i.e. the `evennia` root)
1. Select "Open in current window" and "Add to currently opened projects"
@ -33,69 +29,46 @@ Enjoy seeing all your imports checked properly, setting breakpoints, and live va
1. Launch Evennia in your preferred way (usually from a console/terminal)
1. Open your project in PyCharm
1. In the PyCharm menu, select `Run > Attach to Local Process...`
1. From the list, pick the `twistd` process with the `server.py` parameter (Example: `twistd.exe
--nodaemon --logfile=\<mygame\>\server\logs\server.log --python=\<evennia
repo\>\evennia\server\server.py`)
1. From the list, pick the `twistd` process with the `server.py` parameter (Example: `twistd.exe --nodaemon --logfile=\<mygame\>\server\logs\server.log --python=\<evennia repo\>\evennia\server\server.py`)
Of course you can attach to the `portal` process as well. If you want to debug the Evennia launcher
or runner for some reason (or just learn how they work!), see Run Configuration below.
> NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when
you restart you have to detach from the old and then reattach to the new process that was created.
> NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when you restart you have to detach from the old and then reattach to the new process that was created.
> To make the process less tedious you can apply a filter in settings to show only the server.py process in the list. To do that navigate to: `Settings/Preferences | Build, Execution, Deployment | Python Debugger` and then in `Attach to process` field put in: `twistd.exe" --nodaemon`. This is an example for windows, I don't have a working mac/linux box.
> To make the process less tedious you can apply a filter in settings to show only the server.py
process in the list. To do that navigate to: `Settings/Preferences | Build, Execution, Deployment |
Python Debugger` and then in `Attach to process` field put in: `twistd.exe" --nodaemon`. This is an
example for windows, I don't have a working mac/linux box.
![Example process filter configuration](https://i.imgur.com/vkSheR8.png)
## Setting up an Evennia run configuration
This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also
allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you
could by running them externally and attaching. In fact by the time the server and/or portal are
running the launcher will have exited already.
This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you could by running them externally and attaching. In fact by the time the server and/or portal are running the launcher will have exited already.
1. Go to `Run > Edit Configutations...`
1. Click the plus-symbol to add a new configuration and choose Python
1. Add the script: `\<yourrepo\>\evenv\Scripts\evennia_launcher.py` (substitute your virtualenv if
it's not named `evenv`)
1. Add the script: `\<yourrepo\>\evenv\Scripts\evennia_launcher.py` (substitute your virtualenv if it's not named `evenv`)
1. Set script parameters to: `start -l` (-l enables console logging)
1. Ensure the chosen interpreter is from your virtualenv
1. Set Working directory to your `mygame` folder (not evenv nor evennia)
1. You can refer to the PyCharm documentation for general info, but you'll want to set at least a
config name (like "MyMUD start" or similar).
1. You can refer to the PyCharm documentation for general info, but you'll want to set at least a config name (like "MyMUD start" or similar).
Now set up a "stop" configuration by following the same steps as above, but set your Script
parameters to: stop (and name the configuration appropriately).
Now set up a "stop" configuration by following the same steps as above, but set your Script parameters to: stop (and name the configuration appropriately).
A dropdown box holding your new configurations should appear next to your PyCharm run button.
Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the
program run, you may need to run your "MyMUD stop" config to actually stop the server, before you'll
be able start it again.
A dropdown box holding your new configurations should appear next to your PyCharm run button. Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the program run, you may need to run your "MyMUD stop" config to actually stop the server, before you'll be able start it again.
## Alternative run configuration - utilizing logfiles as source of data
## Alternative config - utilizing logfiles as source of data
This configuration takes a bit different approach as instead of focusing on getting the data back
through logfiles. Reason for that is this way you can easily separate data streams, for example you
rarely want to follow both server and portal at the same time, and this will allow it. This will
also make sure to stop the evennia before starting it, essentially working as reload command (it
will also include instructions how to disable that part of functionality). We will start by defining
a configuration that will stop evennia. This assumes that `upfire` is your pycharm project name, and
also the game name, hence the `upfire/upfire` path.
This configuration takes a bit different approach as instead of focusing on getting the data back through logfiles. Reason for that is this way you can easily separate data streams, for example you rarely want to follow both server and portal at the same time, and this will allow it. This will also make sure to stop the evennia before starting it, essentially working as reload command (it will also include instructions how to disable that part of functionality). We will start by defining a configuration that will stop evennia. This assumes that `upfire` is your pycharm project name, and also the game name, hence the `upfire/upfire` path.
1. Go to `Run > Edit Configutations...`\
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)
1. Name the configuration as "stop evennia" and fill rest of the fields accordingly to the image:
![Stop run configuration](https://i.imgur.com/gbkXhlG.png)
1. Press `Apply`
Now we will define the start/reload command that will make sure that evennia is not running already,
and then start the server in one go.
Now we will define the start/reload command that will make sure that evennia is not running already, and then start the server in one go.
1. Go to `Run > Edit Configutations...`\
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)
1. Name the configuration as "start evennia" and fill rest of the fields accordingly to the image:
![Start run configuration](https://i.imgur.com/5YEjeHq.png)
1. Navigate to the `Logs` tab and add the log files you would like to follow. The picture shows

16
docs/source/Coding/Unit-Testing.md
View File

@ -1,19 +1,11 @@
# Unit Testing
*Unit testing* means testing components of a program in isolation from each other to make sure every
part works on its own before using it with others. Extensive testing helps avoid new updates causing
unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia
article on unit testing can be found [here](https://en.wikipedia.org/wiki/Unit_test)).
*Unit testing* means testing components of a program in isolation from each other to make sure every part works on its own before using it with others. Extensive testing helps avoid new updates causing unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia article on unit testing can be found [here](https://en.wikipedia.org/wiki/Unit_test)).
A typical unit test set calls some function or method with a given input, looks at the result and
makes sure that this result looks as expected. Rather than having lots of stand-alone test programs,
Evennia makes use of a central *test runner*. This is a program that gathers all available tests all
over the Evennia source code (called *test suites*) and runs them all in one go. Errors and
tracebacks are reported.
By default Evennia only tests itself. But you can also add your own tests to your game code and have
Evennia run those for you.
A typical unit test set calls some function or method with a given input, looks at the result and makes sure that this result looks as expected. Rather than having lots of stand-alone test programs, Evennia makes use of a central *test runner*. This is a program that gathers all available tests all over the Evennia source code (called *test suites*) and runs them all in one go. Errors and tracebacks are reported.
By default Evennia only tests itself. But you can also add your own tests to your game code and have Evennia run those for you.
## Running the Evennia test suite
To run the full Evennia test suite, go to your game folder and issue the command

134
docs/source/Coding/Updating-Your-Game.md
View File

@ -1,134 +0,0 @@
# Updating Your Game
Fortunately, it's extremely easy to keep your Evennia server up-to-date. If you haven't already, see
the [Getting Started guide](../Setup/Installation.md) and get everything running.
## Updating with the latest Evennia code changes
Very commonly we make changes to the Evennia code to improve things. There are many ways to get told
when to update: You can subscribe to the RSS feed or manually check up on the feeds from
https://www.evennia.com. You can also simply fetch the latest regularly.
When you're wanting to apply updates, simply `cd` to your cloned `evennia` root directory and type:
git pull
assuming you've got the command line client. If you're using a graphical client, you will probably
want to navigate to the `evennia` directory and either right click and find your client's pull
function, or use one of the menus (if applicable).
You can review the latest changes with
git log
or the equivalent in the graphical client. You can also see the latest changes online
[here](https://github.com/evennia/evennia/blob/master/CHANGELOG.md).
You will always need to do `evennia reload` (or `reload` from -in-game) from your game-dir to have
the new code affect your game. If you want to be really sure you should run a full `evennia reboot`
so that both Server and Portal can restart (this will disconnect everyone though, so if you know the
Portal has had no updates you don't have to do that).
## Upgrading Evennia dependencies
On occasion we update the versions of third-party libraries Evennia depend on (or we may add a new
dependency). This will be announced on the mailing list/forum. If you run into errors when starting
Evennia, always make sure you have the latest versions of everything. In some cases, like for
Django, starting the server may also give warning saying that you are using a working, but too-old
version that should not be used in production.
Upgrading `evennia` will automatically fetch all the latest packages that it now need. First `cd` to
your cloned `evennia` folder. Make sure your `virtualenv` is active and use
pip install --upgrade -e .
Remember the period (`.`) at the end - that applies the upgrade to the current location (your
`evennia` dir).
> The `-e` means that we are _linking_ the evennia sources rather than copying them into the
environment. This means we can most of the time just update the sources (with `git pull`) and see
those changes directly applied to our installed `evennia` package. Without installing/upgrading the
package with `-e`, we would have to remember to upgrade the package every time we downloaded any new
source-code changes.
Follow the upgrade output to make sure it finishes without errors. To check what packages are
currently available in your python environment after the upgrade, use
pip list
This will show you the version of all installed packages. The `evennia` package will also show the
location of its source code.
## Migrating the Database Schema
Whenever we change the database layout of Evennia upstream (such as when we add new features) you
will need to *migrate* your existing database. When this happens it will be clearly noted in the
`git log` (it will say something to the effect of "Run migrations"). Database changes will also be
announced on the Evennia [mailing list](https://groups.google.com/forum/#!forum/evennia).
When the database schema changes, you just go to your game folder and run
evennia migrate
> Hint: If the `evennia` command is not found, you most likely need to activate your
[virtualenv](../Glossary.md#virtualenv).
## Resetting your database
Should you ever want to start over completely from scratch, there is no need to re-download Evennia
or anything like that. You just need to clear your database. Once you are done, you just rebuild it
from scratch by running
evennia migrate
The first step in wiping your database is to stop Evennia completely with
evennia stop
If you run the default `SQlite3` database (to change this you need to edit your `settings.py` file),
the database is actually just a normal file in `mygame/server/` called `evennia.db3`. *Simply delete
that file* - that's it. Now run `evennia migrate` to recreate a new, fresh one.
If you run some other database system you can instead flush the database:
evennia flush
This will empty the database. However, it will not reset the internal counters of the database, so
you will start with higher dbref values. If this is okay, this is all you need.
Django also offers an easy way to start the database's own management should we want more direct
control:
evennia dbshell
In e.g. MySQL you can then do something like this (assuming your MySQL database is named "Evennia":
mysql> DROP DATABASE Evennia;
mysql> exit
> NOTE: Under Windows OS, in order to access SQLite dbshell you need to [download the SQLite
command-line shell program](https://www.sqlite.org/download.html). It's a single executable file
(sqlite3.exe) that you should place in the root of either your MUD folder or Evennia's (it's the
same, in both cases Django will find it).
## More about schema migrations
If and when an Evennia update modifies the database *schema* (that is, the under-the-hood details as
to how data is stored in the database), you must update your existing database correspondingly to
match the change. If you don't, the updated Evennia will complain that it cannot read the database
properly. Whereas schema changes should become more and more rare as Evennia matures, it may still
happen from time to time.
One way one could handle this is to apply the changes manually to your database using the database's
command line. This often means adding/removing new tables or fields as well as possibly convert
existing data to match what the new Evennia version expects. It should be quite obvious that this
quickly becomes cumbersome and error-prone. If your database doesn't contain anything critical yet
it's probably easiest to simply reset it and start over rather than to bother converting.
Enter *migrations*. Migrations keeps track of changes in the database schema and applies them
automatically for you. Basically, whenever the schema changes we distribute small files called
"migrations" with the source. Those tell the system exactly how to implement the change so you don't
have to do so manually. When a migration has been added we will tell you so on Evennia's mailing
lists and in commit messages -
you then just run `evennia migrate` to be up-to-date again.

620
docs/source/Coding/Version-Control.md
View File

@ -1,27 +1,15 @@
# Version Control
# Coding using Version Control
Version control software allows you to track the changes you make to your code, as well as being
able to easily backtrack these changes, share your development efforts and more.
[Version control](https://en.wikipedia.org/wiki/Version_control) allows you to track changes to your code. You can save 'snapshots' of your progress which means you can roll back undo things easily. Version control also allows you to easily back up your code to an online _repository_ such as Github. It also allows you to collaborate with others on the same code without clashing or worry about who changed what.
It's strongly recommended that you put your game code under version control. Version
control is also the way to contribue to Evennia itself.
```{sidebar} Do it!
It's _strongly_ recommended that you [put your game folder under version control](#putting-your-game-dir-under-version-control). Using git is is also the way to contribue to Evennia itself.
```
For an introduction to the concept, start with the Wikipedia article
[here](https://en.wikipedia.org/wiki/Version_control). Evennia uses the version
control system [Git](https://git-scm.com/) and this is what will be covered
henceforth. Note that this page primarily shows commands for Linux, but the
syntax should be the same for Windows and Mac.
For more help on using Git, please refer to the [Official GitHub
documentation](https://help.github.com/articles/set-up-git#platform-all).
Evennia uses the most commonly used version control system, [Git](https://git-scm.com/) . For additional help on using Git, please refer to the [Official GitHub documentation](https://help.github.com/articles/set-up-git#platform-all).
## Setting up Git
You can find expanded instructions for
installation [here](https://git-scm.com/book/en/Getting-Started-Installing-Git).
### Step 1: Install Git
- **Fedora Linux**
yum install git-core
@ -31,19 +19,15 @@ installation [here](https://git-scm.com/book/en/Getting-Started-Installing-Git).
apt-get install git
- **Windows**: It is recommended to use [Git for Windows](https://gitforwindows.org/).
- **Mac**: Mac platforms offer two methods for installation, one via MacPorts, which you can find
out about [here](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac), or
you can use the [Git OSX Installer](https://sourceforge.net/projects/git-osx-installer/).
- **Mac**: Mac platforms offer two methods for installation, one via MacPorts, which you can find out about [here](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac), or you can use the [Git OSX Installer](https://sourceforge.net/projects/git-osx-installer/).
### Step 2: Define user/e-mail Settings for Git
> You can find expanded instructions for installation [here](https://git-scm.com/book/en/Getting-Started-Installing-Git).
To avoid a common issue later, you will need to set a couple of settings; first you will need to
tell Git your username, followed by your e-mail address, so that when you commit code later you will
be properly credited.
```{sidebar} Git user nickname
If you ever make your code available online (or contribute to Evennia), your name will be visible to those reading the code-commit history. So if you are not comfortable with using your real, full name online, put a nickname (or your github handler) here.
```
To avoid a common issue later, you will need to set a couple of settings; first you will need to tell Git your username, followed by your e-mail address, so that when you commit code later you will be properly credited.
> Note that your commit information will be visible to everyone if you ever contribute to Evennia or
use an online service like github to host your code. So if you are not comfortable with using your
real, full name online, put a nickname here.
1. Set the default name for git to use when you commit:
@ -53,417 +37,313 @@ real, full name online, put a nickname here.
git config --global user.email "your_email@example.com"
> To get a running start with Git, here's [a good YouTube talk about it](https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s). It's a bit long but it will help you understand the underlying ideas behind GIT (which in turn makes it a lot more intuitive to use).
## Putting your game folder under version control
## Common Git commands
> Note: The game folder's version control is completely separate from Evennia's repository.
```{sidebar} Git repository
This is just a fancy name for the folder you have designated to be under version control. We will make your `mygame` game folder into such a repository. The Evennia code is also in a (separate) git repository.
```
Git can be controlled via a GUI. But it's often easier to use the base terminal/console commands, since it makes it clear if something goes wrong.
After you have set up your game you will have created a new folder to host your particular game
(let's call this folder `mygame` for now).
All these actions need to be done from inside the _git repository_ .
This folder is *not* under version control at this point.
Git may seem daunting at first. But when working with git, you'll be using the same 2-3 commands 99% of the time. And you can make git _aliases_ to have them be even easier to remember.
git init mygame
Your mygame folder is now ready for version control! Add all the content and make a first
commit:
### `git init`
cd mygame
This initializes a folder/directory on your drive as a 'git repository'
git init .
The `.` means to apply to the current directory. If you are inside `mygame`, this makes your game dir into a git repository. That's all there is to it, really. You only need to do this once.
### `git add`
git add <file>
This tells Git to start to _track_ the file under version control. You need to do this when you create a new file. You can also add all files in your current directory:
git add .
Or
git add *
All files in the current directory are now tracked by Git. You only need to do this once for every file you want to track.
### `git commit`
git commit -a -m "This is the initial commit"
This _commits_ your changes. It stores a snapshot of all (`-a`) your code at the current time, adding a message `-m` so you know what you did. Later you can _check out_ your code the way it was at a given time. The message is mandatory and you will thank yourself later if write clear and descriptive log messages. If you don't add `-m`, a text editor opens for you to write the message instead.
The `git commit` is something you'll be using all the time, so it can be useful to make a _git alias_ for it:
git config --global alias.cma 'commit -a -m'
After you've run this, you can commit much simpler, like this:
git cma "This is the initial commit"
Much easier to remember!
### `git status`, `git diff` and `git log`
git status -s
This gives a short (`-s`) of the files that changes since your last `git commit`.
git diff --word-diff`
This shows exactly what changed in each file since you last made a `git commit`. The `--word-diff` option means it will mark if a single word changed on a line.
git log
This shows the log of all `commits` done. Each log will show you who made the change, the commit-message and a unique _hash_ (like `ba214f12ab12e123...`) that uniquely describes that commit.
You can make the `log` command more succinct with some more options:
ls=log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative
This adds coloration and another fancy effects (use `git help log` to see what they mean).
Let's add aliases:
git config --global alias.st 'status -s'
git config --global alias.df 'diff --word-diff'
git config --global alias.ls 'log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative'
You can now use the much shorter
git st # short status
git dif # diff with word-marking
git ls # log with pretty formatting
for these useful functions.
### `git branch`, `checkout` and `merge`
Git allows you to work with _branches_. These are separate development paths your code may take, completely separate from each other. You can later _merge_ the code from a branch back into another branch. Evennia's `master` and `develop` branches are examples of this.
git branch -b branchaname
This creates a new branch, exactly identical to the branch you were on. It also moves you to that branch.
git branch -D branchname
Deletes a branch.
git branch
Shows all your branches, marking which one you are currently on.
git checkout branchname
This checks out another branch. As long as you are in a branch all `git commit`s will commit the code to that branch only.
git checkout .
This checks out your _current branch_ and has the effect of throwing away all your changes since your last commit. This is like undoing what you did since the last save point.
git checkout b2342bc21c124
This checks out a particular _commit_, identified by the hash you find with `git log`. This open a 'temporary branch' where the code is as it was when you made this commit. As an example, you can use this to check where a bug was introduced. Check out an existing branch to go back to your normal timeline, or use `git branch -b newbranch` to break this code off into a new branch you can continue working from.
git merge branchname
This _merges_ the code from `branchname` into the branch you are currently in. Doing so may lead to _merge conflicts_ if the same code changed in different ways in the two branches. See [how to resolve merge conflicts in git](https://phoenixnap.com/kb/how-to-resolve-merge-conflicts-in-git) for more help.
### `git glone`, `git push` and `git pull`
All of these other commands have dealt with code only sitting in your local repository-folder. These commands instead allows you to exchange code with a _remote_ repository - usually one that is online (like on github).
> How you actually set up a remote repository is described [in the next section](#pushing-your-code-online).
git clone repository/path
This copies the remote repository to your current location. If you used the [Git installation instructions](../Setup/Installation-Git.md) to install Evennia, this is what you used to get your local copy of the Evennia repository.
git pull
Once you cloned or otherwise set up a remote repository, using `git pull` will re-sync the remote with what you have locally. If what you download clashes with local changes, git will force you to `git commit` your changes before you can continue with `git pull`.
git push
This uploads your local changes _of your current branch_ to the same-named branch on the remote repository. To be able to do this you must have write-permissions to the remote repository.
### Other git commands
There are _many_ other git commands. Read up on them online:
git reflog
Shows hashes of individual git actions. This allows you to go back in the git event history itself.
git reset
Force reset a branch to an earlier commit. This could throw away some history, so be careful.
git grep -n -I -i <query>
Quickly search for a phrase/text in all files tracked by git. Very useful to quickly find where things are. Set up an alias `git gr` with
```
git config --global alias.gr 'grep -n -I -i'
```
## Putting your game dir under version control
This makes use of the git commands listed in the previous section.
```{sidebar} git aliases
If you set up the git aliases for commands suggested in the previous section, you can use them instead!
```
cd mygame
git init .
git add *
git commit -a -m "Initial commit"
In turn these commands:
- Move us into the `mygame` folder
- Tell `git` that everything `*` means everything) in this folder should be put
under version control.
- _Commit_ all (`-a`) those newly added files to git and add a message `-m` so you remember
what you did at this point. Doing a commit is like saving a snapshot of the
current state of everything.
Your game-dir is now tracked by git.
Read on for details!
### Tracking files
When working on your code or fix bugs in your local branches you may end up creating new files. If
you do you must tell Git to track them by using the add command.
git add <filename>
You only need to do this once per file.
git status
will show if you have any modified, added or otherwise changed files. Some
files, like database files, logs and temporary PID files are usually *not*
tracked in version control. These should either not show up or have a question
mark in front of them.
```{note}
You will notice that some files are not covered by your git version control,
notably your settings file (`mygame/server/conf/settings.py`) and your sqlite3
database file `mygame/server/evennia.db3`. What is auto-ignored by is controlled
by the hidden file `mygame/.gitignore`. Evennia creates this file as part of
the creation of your game directory. Everything matched in this file will be
ignored by git. If you want to, for example, include your settings file for
collaborators to access, remove that entry in `.gitignore`.
```
You will notice that some files are not covered by your git version control, notably your secret-settings file (`mygame/server/conf/secret_settings.py`) and your sqlite3 database file `mygame/server/evennia.db3`. This is intentional and controlled from the file `mygame/.gitignore`.
```{warning}
You should *never* put your sqlite3 database file into git by removing its entry
in `.gitignore`. GIT is for backing up your code, not your database. That way
lies madness and a good chance you'll confuse yourself so that after a few
commits and reverts don't know what is in your database or not. If you want to
backup your database, do so by simply copying the file on your hard drive to a
backup-name.
lies madness and a good chance you'll confuse yourself. Make one mistake or local change and after a few commits and reverts you will have lost track of what is in your database or not. If you want to backup your SQlite3 database, do so by simply copying the database file to a safe location.
```
### Committing your Code
_Committing_ your code means storing the current snapshot of your code within
git. This creates a "save point" or "history" of your development process. You
can later jump back and forth in your history, for example to figure out just
when a bug was introduced or see what results the code used to produce compared
to now. Or just wiping everything since the last commit, if you did something
stupid.
It's usually a good idea to commit your changes often. Committing is fast and
local only - you will never commit anything online at this point. To commit your
changes, use
git commit --all
Also `-a` works. This will open a text editor for you to describe your change.
Be brief but informative in your message - you'll appreciate it later. When you
save and close the editor, the commit will be saved. You can create the message
directly with
git commit -a -m "This fixes a bug in the combat code."
### Changing your mind
If you have non-committed changes that you realize you want to throw away, you
'check out' the file you want - this will re-load it from the last committed
state:
git checkout <file_to_revert>
git checkout foo/bar/dummy.py
If you want to revert _all_ changes you did since last commit, do
git checkout .
(that is, add a single `.` at the end).
### Pushing your code online
So far your code is only located on your private machine. A good idea is to back
it up online. The easiest way to do this is to push it to your own remote
repository on GitHub.
So far your code is only located on your private machine. A good idea is to back it up online. The easiest way to do this is to `git push` it to your own remote repository on GitHub. So for this you need a (free) Github account.
```{important}
Just to avoid confusion, be aware that Github's documentation has changed to
calling the primary branch 'main' rather than 'master'. While Evennia still
uses 'master' branch (and this is what we refer to below), you can use either
name for your personal primary branch - they are equivalent.
If you don't want your code to be publicly visible, Github also allows you set up a _private_ repository, only visible to you.
```{note}
Github's defaults have changed to calling the primary branch 'main' rather than 'master'. While Evennia still uses 'master' branch (and this is what we refer to below), you can use either name for your personal primary branch - they are equivalent.
```
1. Make sure you have your game directory setup under git version control as
described in the previous section. Make sure to commit any changes you did.
2. Create a new, empty repository on Github. Github explains how
[here](https://help.github.com/articles/create-a-repo/) (do *not* "Initialize
the repository with a README" or else you'll create unrelated histories).
3. From your local game dir, do `git remote add origin <github URL>` where
`<github URL>` is the URL to your online repo. This tells your game dir that
it should be pushing to the remote online dir.
4. `git remote -v` to verify the online dir.
5. `git push origin master` (or `git push origin main`) now pushes your game dir
online so you can see it on github.com.
Create a new, empty repository on Github. [Github explains how here](https://help.github.com/articles/create-a-repo/) . _Don't_ allow it to add a README, license etc, that will just clash with what we upload later.
You can commit your work locally (`git commit --all -m "Make a change that
..."`) as many times as you want. When you want to push those changes to your
online repo, you do `git push`. You can also `git clone <url_to_online_repo>`
from your online repo to somewhere else (like your production server) and
henceforth do `git pull` to update that to the latest thing you pushed.
```{sidebar} Origin
We label the remote repository 'origin'. This is the git default and means we won't need to specify it explicitly later.
```
Note that GitHub's repos are, by default publicly visible by all. Creating a
publicly visible online clone might not be what you want for all parts of your
development process - you may prefer a more private venue when sharing your
revolutionary work with your team. If that's the case you can change your
repository to "Private" in the github settings. Then your code will only be
visible to those you specifically grant access.
Make sure you are in your local game dir (previously initialized as a git repo).
git remote add origin <github URL>
## Forking Evennia
This tells Git that there is a remote repository at `<github URL>`. See the github docs as to which URL to use. Verify that the remote works with `git remote -v`
This helps you set up an online *fork* of the main Evennia repository so you can
easily commit fixes and help with upstream development. You can do this step
also if you _didn't_ put your game dir under version control like in the
previous section - the evennia repo and your game dir repo are completely
separate.
Now we push to the remote (labeled 'origin' which is the default):
### Step 1: Fork the evennia/master repository
git push
> Before proceeding with the following step, make sure you have registered and
> created an account on [GitHub.com](https://github.com/). This is necessary in order to create a fork
of Evennia's master repository, and to push your commits to your fork either for
yourself or for contributing to
Evennia.
Depending on how you set up your authentication with github, you may be asked to enter your github username and password. If you set up SSH authentication, this command will just work.
A _fork_ is a clone of the master repository that you can make your own commits
and changes to. At the top of [this page](https://github.com/evennia/evennia),
click the "Fork" button, as it appears below.
![](https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png)
You use `git push` to upload your local changes so the remote repository is in sync with your local one. If you edited a file online using the Github editor (or a collaborator pushed code), you use `git pull` to sync in the other direction.
### Step 2: Clone your online fork of Evennia
## Contributing to Evennia
The fork only exists online as of yet. In a terminal, change your directory to
the folder you wish to develop in. From this directory run the following
command:
If you want to help contributing to Evennia you must do so by _forking_ - making your own remote copy of the Evennia repository on Github. So for this, you need a (free) Github account. Doing so is a completely separate process from [putting your game dir under version control](#putting-your-game-dir-under-version-control) (which you should also do!).
git clone https://github.com/yourusername/evennia.git
At the top right of [the evennia github page](https://github.com/evennia/evennia), click the "Fork" button:
This will download your fork to your computer. It creates a new folder
`evennia/` at your current location.
![fork button](../_static/images/fork_button.png)
### Step 3: Configure remotes
This will create a new online fork Evennia under your github account.
Your Evennia-fork is now separate from upstream, 'official' Evennia. You will
want to set it up so that you can easily sync our updates and changes to your
fork.
The fork only exists online as of yet. In a terminal, `cd` to the folder you wish to develop in. This folder should _not_ be your game dir, nor the place you cloned Evennia into if you used the [Git installation](../Setup/Installation-Git.md).
We do this by setting up a new _remote_. We actually already have one remote,
that is our own github form of Evennia. This got created when you cloned the
repo and defaults to being called `origin`.
From this directory run the following command:
We will now create a new remote called `upstream`.
git clone https://github.com/yourusername/evennia.git evennia
This will download your fork to your computer. It creates a new folder `evennia/` at your current location. If you installed Evennia using the [Git installation](../Setup/Installation-Git.md), this folder will be identical in content to the `evennia` folder you cloned during that installation. The difference is that this repo is connected to your remote fork and not to the 'original' _upstream_ Evennia.
When we cloned our fork, git automatically set up a 'remote repository' labeled `origin` pointing to it. So if we do `git pull` and `git push`, we'll push to our fork.
We now want to add a second remote repository linked to the original Evennia repo. We will label this remote repository `upstream`:
cd evennia
git remote add upstream https://github.com/evennia/evennia.git
This adds a remote to the main evennia repo.
If you also want to access Evennia's `develop` branch (the bleeding edge
development) do the following:
If you also want to access Evennia's `develop` branch (the bleeding edge development) do the following:
git fetch upstream develop
git checkout develop
Use
git checkout master
git checkout develop
to switch between the branches. If you want to contribute a fix, ask first which
branch to use. Normally `master` is for bug fixes and `develop` is for new
features, but late in the development of a new Evennia version, all changes
often go into `develop`.
to switch between the branches.
To pull the latest from upstream Evennia, just checkout the branch you want and do
## Working with your Evennia fork
git pull upstream
_Branches_ are stand-alone editions of the same code. You make a commit to a
branch. Switching to a branch will change the code on-disk. You can easily
make a new branch off a parent branch, and then merge it back into the same
branch later (or throw it away). This is a very common way to work on new
features in safety and isolation.
```{sidebar} Pushing to upstream
You can't do `git push upstream` unless you have write-access to the upstream Evennia repository. So there is no risk of you accidentally pushing your own code into the main, public repository.
```
### Updating to latest Evennia
### Fixing an Evennia bug or feature
When Evennia's official repository updates, first make sure to commit all your
changes to your branch and then checkout the "clean" master branch:
git checkout master
git pull upstream master
Or, if you are working against Evennia's development branch:
git checkout develop
git pull upstream develop
The `pull` command will fetch all the changes from the "upstream" remote and
merge it into your local master/develop branch. It should now be a perfect copy
of the latest Evennia changes.
### Making changes
As a rule of thumb you should _never_ work directly in Evennia's `master` or
`develop` branches. Instead you make a _new_ branch off the branch you want
and change _that_.
This should be done in your fork of Evennia. You should _always_ do this in a _separate git branch_ based off the Evennia branch you want to improve.
git checkout master (or develop)
check checkout -b strange_bug
git branch - b myfixbranch
You now have a new branch `strange_bug` that is an exact replica of the branch you
had checked out when you created it. Here you can now make your own
modifications.
Now fix whatever needs fixing. Abide by the [Evennia code style](./Evennia-Code-Style.md). You can `git commit` commit your changes along the way as normal.
git branches
Upstream Evennia is not standing still, so you want to make sure that your work is up-to-date with upstream changes. Make sure to first commit your `myfixbranch` changes, then
will show you which branches are available and which one you are currently
using. Use `git checkout <branch>` to move between them, but remember to commit
your changes before you do.
You often want to make sure also your work-branch has the latest upstream
changes. To do this, you need to first update your copy of the
`master`/`develop` branch and then _merge_ those changes into your work branch.
Make sure you have committed everything first!
git commit -a -m "My latest changes ..." # on your strange_bug branch
git checkout master (or develop)
git pull upstream develop
git checkout strange_bug
git pull upstream
git checkout myfixbranch
git merge master (or develop)
If everything went well, your `strange_bug` branch will now have the latest version
of Evennia merged with whatever changes you have done.
Now work away on your code and commit with reasonable commit messages
git commit -a -m "Fixed the issue in ..."
git commit -a -m "Adding unit tests. This resolves #123."
Use
git diff
to see what you changed since last commit, and
git log
to see past commits (including those made by Evennia upstream, remember that
your branch is a copy of the upstream one, including its history!)
## Sharing your Evennia fixes on Github
Up to this point your `strange_bug` branch only exists on your local computer. No
one else can see it. If you want a copy of this branch to also appear in your
online fork on GitHub, make sure to have checked out your "myfixes" branch and
then run the following:
git push -u origin strange_bug
You only need to do this once, the `-u` makes this the default push-location. In
the future, you can just push things online like this:
Up to this point your `myfixbranch` branch only exists on your local computer. No
one else can see it.
git push
### Troubleshooting
This will automatically create a matching `myfixbranch` in your forked version of Evennia and push to it. On github you will be able to see appear it in the `branches` dropdown. You can keep pushing to your remote `myfixbranch` as much as you like.
If you hadn't setup a public key on GitHub or aren't asked for a
username/password, you might get an error `403: Forbidden Access` at this stage.
In that case, some users have reported that the workaround is to create a file
`.netrc` under your home directory and add your github credentials there:
Once you feel you have something to share, you need to [create a pull request](https://github.com/evennia/evennia/pulls) (PR):
This is a formal request for upstream Evennia to adopt and pull your code into the main repository.
1. Click `New pull request`
2. Choose `compare across forks`
3. Select your fork from dropdown list of `head repository` repos. Pick the right branch to `compare`.
4. On the Evennia side (to the left) make sure to pick the right `base` branch: If you want to contribute a change to the `develop` branch, you must pick `develop` as the `base`.
5. Then click `Create pull request` and fill in as much information as you can in the form.
6. Optional: Once you saved your PR, you can go into your code (on github) and add some per-line comments; this can help reviewers by explaining complex code or decisions you made.
Now you just need to wait for your code to be reviewed. Expect to get feedback and be asked to make changes, add more documentation etc. Getting as PR merged can take a few iterations.
```{sidebar} Not all PRs can merge
While most PRs get merged, Evennia can't **guarantee** that your PR code will be deemed suitable to merge into upstream Evennia. For this reason it's a good idea to check in with the community _before_ you spend a lot of time on a large piece of code (fixing bugs is always a safe bet though!)
```
## Troubleshooting
### Getting 403: Forbidden access
Some users have experienced this on `git push` to their remote repository. They are not asked for username/password (and don't have a ssh key set up).
Some users have reported that the workaround is to create a file `.netrc` under your home directory and add your github credentials there:
```bash
machine github.com
login <my_github_username>
password <my_github_password>
```
## Making an Evennia Pull Request
If you think that the fixes you did in your `strange_bug` branch should be a
part of the regular Evennia, you should create a _Pull Request_ (PR). This is a
call for the Evennia maintainer to pull your change into an upstream branch.
> It is wise to make separate branches for every fix or series of fixes you want
to contribute.
Assuming you have followed the instructions above and have pushed your changes
online, [create a pull request](https://github.com/evennia/evennia/pulls) and
follow the instructions. Make sure to specifically select your `strange_bug`
branch to be the source of the merge and use the branch you based that branch
off (`master` or `develop`) as the target.
Evennia developers will then be able to examine your request and merge it if
it's deemed suitable. They may also come back with feedback and request you do
some changes.
Once approved and merged, your change will now be available in the upstream
branch:
git checkout master (or develope)
git pull upstream master (or develop)
Since your changes are now in upstream, your local `strange_bug` branch is now
superfluous and should be deleted:
git branch -D strange_bug
You can also safely delete your online `strange_bug` branch in your fork
(you can do this from the PR page on github).
## GIT tips and tricks
Some of the GIT commands can feel a little long and clunky if you need to do them often. Luckily you
can create aliases for those. Here are some useful commands to run:
```
# git st
# - view brief status info
git config --global alias.st 'status -s'
```
Above, you only need to ever enter the `git config ...` command once - you have then added the new
alias. Afterwards, just do `git st` to get status info. All the examples below follow the same
template.
```
# git cl
# - clone a repository
git config --global alias.cl clone
```
```
# git cma "commit message"
# - commit all changes without opening editor for message
git config --global alias.cma 'commit -a -m'
```
```
# git ca
# - amend text to your latest commit message
git config --global alias.ca 'commit --amend'
```
```
# git fl
# - file log; shows diffs of files in latest commits
git config --global alias.fl 'log -u'
```
```
# git co [branchname]
# - checkout
git config --global alias.co checkout
```
```
# git br <branchname>
# - create branch
git config --global alias.br branch
```
```
# git ls
# - view log tree
git config --global alias.ls 'log --pretty=format:"%C(green)%h\ %C(yellow)[%ad]%Cred%d\
%Creset%s%Cblue\ [%cn]" --decorate --date=relative --graph'
```
```
# git diff
# - show current uncommitted changes
git config --global alias.diff 'diff --word-diff'
```
```
# git grep <query>
# - search (grep) codebase for a search criterion
git config --global alias.grep 'grep -Ii'
```
To get a further feel for GIT there is also [a good YouTube talk about it](https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s) - it's a bit long but it will help you understand the underlying ideas behind GIT
(which in turn makes it a lot more intuitive to use).
```

2
docs/source/Components/Connection-Screen.md
View File

@ -20,7 +20,7 @@ Effective, but not very exciting. You will most likely want to change this to be
your game. This is simple:
1. Edit `mygame/server/conf/connection_screens.py`.
1. [Reload](../Setup/Start-Stop-Reload.md) Evennia.
1. [Reload](../Setup/Running-Evennia.md) Evennia.
Evennia will look into this module and locate all *globally defined strings* in it. These strings
are used as the text in your connection screen and are shown to the user at startup. If more than

2
docs/source/Components/Portal-And-Server.md
View File

@ -2,7 +2,7 @@
Evennia consists of two processes, known as *Portal* and *Server*. They can be controlled from
inside the game or from the command line as described [here](../Setup/Start-Stop-Reload.md).
inside the game or from the command line as described [here](../Setup/Running-Evennia.md).
If you are new to the concept, the main purpose of separating the two is to have accounts connect to the Portal but keep the MUD running on the Server. This way one can restart/reload the game (the Server part) without Accounts getting disconnected.

69
docs/source/Concepts/Using-MUX-as-a-Standard.md
View File

@ -9,71 +9,4 @@ Evennia is *not* a MUX system though. It works very differently in many ways. Fo
deliberately lacks an online softcode language (a policy explained on our [softcode policy
page](./Soft-Code.md)). Evennia also does not shy from using its own syntax when deemed appropriate: the
MUX syntax has grown organically over a long time and is, frankly, rather arcane in places. All in
all the default command syntax should at most be referred to as "MUX-like" or "MUX-inspired".
## Documentation policy
All the commands in the default command sets should have their doc-strings formatted on a similar
form:
```python
"""
Short header
Usage:
key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
Switches:
switch1 - description
switch2 - description
Examples:
usage example and output
Longer documentation detailing the command.
"""
```
- Two spaces are used for *indentation* in all default commands.
- Square brackets `[ ]` surround *optional, skippable arguments*.
- Angled brackets `< >` surround a _description_ of what to write rather than the exact syntax.
- *Explicit choices are separated by `|`. To avoid this being parsed as a color code, use `||` (this
will come out as a single `|`) or put spaces around the character ("` | `") if there's plenty of
room.
- The `Switches` and `Examples` blocks are optional based on the Command.
Here is the `nick` command as an example:
```python
"""
Define a personal alias/nick
Usage:
nick[/switches] <nickname> = [<string>]
alias ''
Switches:
object - alias an object
account - alias an account
clearall - clear all your aliases
list - show all defined aliases (also "nicks" works)
Examples:
nick hi = say Hello, I'm Sarah!
nick/object tom = the tall man
A 'nick' is a personal shortcut you create for your own use [...]
"""
```
For commands that *require arguments*, the policy is for it to return a `Usage:` string if the
command is entered without any arguments. So for such commands, the Command body should contain
something to the effect of
```python
if not self.args:
self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
return
```
all the default command syntax should at most be referred to as "MUX-like" or "MUX-inspired".

53
docs/source/Contribs/Contrib-Clothing.md
View File

@ -36,19 +36,21 @@ And then add `ClothedCharacterCmdSet` in your character set in
```python
from evennia.contrib.game_systems.clothing import ClothedCharacterCmdSet <--
from evennia.contrib.game_systems.clothing import ClothedCharacterCmdSet # <--
class CharacterCmdSet(default_cmds.CharacterCmdSet):
# ...
at_cmdset_creation(self):
super().at_cmdset_creation()
...
# ...
self.add(ClothedCharacterCmdSet) # <--
```
From here, you can use the default builder commands to create clothes
## Usage
Once installed, you can use the default builder commands to create clothes
with which to test the system:
create a pretty shirt : evennia.contrib.game_systems.clothing.Clothing
@ -87,6 +89,51 @@ can cover any garment with almost any other, for example - but it
can easily be made more restrictive, and can even be tied into a
system for armor or other equipment.
## Configuration
The contrib has several optional configurations which you can define in your `settings.py`
Here are the settings and their default values.
```python
# Maximum character length of 'wear style' strings, or None for unlimited.
CLOTHING_WEARSTYLE_MAXLENGTH = 50
# The order in which clothing types appear on the description.
# Untyped clothing or clothing with a type not in this list goes last.
CLOTHING_TYPE_ORDERED = [
"hat",
"jewelry",
"top",
"undershirt",
"gloves",
"fullbody",
"bottom",
"underpants",
"socks",
"shoes",
"accessory",
]
# The maximum number of clothing items that can be worn, or None for unlimited.
CLOTHING_OVERALL_LIMIT = 20
# The maximum number for specific clothing types that can be worn.
# If the clothing item has no type or is not specified here, the only maximum is the overall limit.
CLOTHING_TYPE_LIMIT = {"hat": 1, "gloves": 1, "socks": 1, "shoes": 1}
# What types of clothes will automatically cover what other types of clothes when worn.
# Note that clothing only gets auto-covered if it's already being worn. It's perfectly possible
# to have your underpants showing if you put them on after your pants!
CLOTHING_TYPE_AUTOCOVER = {
"top": ["undershirt"],
"bottom": ["underpants"],
"fullbody": ["undershirt", "underpants"],
"shoes": ["socks"],
}
# Any types of clothes that can't be used to cover other clothes at all.
CLOTHING_TYPE_CANT_COVER_WITH = ["jewelry"]
```
----

30
docs/source/Contribs/Contrib-Wilderness.md
View File

@ -5,7 +5,7 @@ Contribution by titeuf87, 2017
This contrib provides a wilderness map without actually creating a large number
of rooms - as you move, you instead end up back in the same room but its description
changes. This means you can make huge areas with little database use as
long as the rooms are relatively similar (name/desc changing).
long as the rooms are relatively similar (e.g. only the names/descs changing).
## Installation
@ -29,6 +29,9 @@ All coordinates used by the wilderness map are in the format of `(x, y)`
tuples. x goes from left to right and y goes from bottom to top. So `(0, 0)`
is the bottom left corner of the map.
> You can also add a wilderness by defining a WildernessScript in your GLOBAL_SCRIPT
> settings. If you do, make sure define the map provider.
## Customisation
The defaults, while useable, are meant to be customised. When creating a
@ -37,9 +40,14 @@ python object that is smart enough to create the map.
The default provider, `WildernessMapProvider`, just creates a grid area that
is unlimited in size.
This `WildernessMapProvider` can be subclassed to create more interesting
`WildernessMapProvider` can be subclassed to create more interesting
maps and also to customize the room/exit typeclass used.
The `WildernessScript` also has an optional `preserve_items` property, which
when set to `True` will not recycle rooms that contain any objects. By default,
a wilderness room is recycled whenever there are no players left in it.
There is also no command that allows players to enter the wilderness. This
still needs to be added: it can be a command or an exit, depending on your
needs.
@ -94,7 +102,7 @@ class PyramidMapProvider(wilderness.WildernessMapProvider):
desc = "This is a room in the pyramid."
if y == 3 :
desc = "You can see far and wide from the top of the pyramid."
room.db.desc = desc
room.ndb.desc = desc
```
Now we can use our new pyramid-shaped wilderness map. From inside Evennia we
@ -105,12 +113,16 @@ create a new wilderness (with the name "default") but using our new map provider
## Implementation details
When a character moves into the wilderness, they get their own room. If they
move, instead of moving the character, the room changes to match the new
coordinates. If a character meets another character in the wilderness, then
their room merges. When one of the character leaves again, they each get their
own separate rooms. Rooms are created as needed. Unneeded rooms are stored away
to avoid the overhead cost of creating new rooms again in the future.
When a character moves into the wilderness, they get their own room. If
they move, instead of moving the character, the room changes to match the
new coordinates.
If a character meets another character in the wilderness, then their room
merges. When one of the character leaves again, they each get their own
separate rooms.
Rooms are created as needed. Unneeded rooms are stored away to avoid the
overhead cost of creating new rooms again in the future.
----

84
docs/source/Contribs/Contribs-Guidelines.md Normal file
View File

@ -0,0 +1,84 @@
# Guidelines for Evennia contribs
Evennia has a [contrib](./Contribs-Overview.md) directory which contains optional, community-shared code organized by category. Anyone is welcome to contribute.
## What is suitable for a contrib?
- In general, you can contribute anything that you think may be useful to another developer. Unlike the 'core' Evennia, contribs can also be highly game-type-specific.
- Very small or incomplete snippets of code (e.g. meant to paste into some other code) are better shared as a post in the [Community Contribs & Snippets](https://github.com/evennia/evennia/discussions/2488) discussion forum category.
- If your code is intended *primarily* as an example or to show a concept/principle rather than a working system, consider if it may be better to instead [contribute to the documentation](../Contributing-Docs.md) by writing a new tutorial or howto.
- If possible, try to make your contribution as genre-agnostic as possible and assume
your code will be applied to a very different game than you had in mind when creating it.
- The contribution should preferably work in isolation from other contribs (only make use of core Evennia) so it can easily be dropped into use. If it does depend on other contribs or third-party modules, these must be clearly documented and part of the installation instructions.
- If you are unsure about if your contrib idea is suitable or sound, *ask in discussions or chat before putting any work into it*. We are, for example, unlikely to accept contribs that require large modifications of the game directory structure.
## Layout of a contrib
- The contrib must be contained only within a single folder under one of the contrib categories below. Ask if you are unsure which category fits best for your contrib.
| | |
| --- | --- |
| `base_systems/` | _Systems that are not necessarily tied to a specific in-game mechanic but which are useful for the game as a whole. Examples include login systems, new command syntaxes, and build helpers._ |
| `full_systems/` | _‘Complete’ game engines that can be used directly to start creating content without no further additions (unless you want to)._ |
| `game_systems/` | _In-game gameplay systems like 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` category._ |
| `grid/` | _Systems related to the game world’s topology and structure. Contribs related to rooms, exits and map building._ |
| `rpg/` | _Systems specifically related to roleplaying and rule implementation like character traits, dice rolling and emoting._ |
| `tutorials/` | _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 and Evadventure demo codes._ |
| `tools/` | _Miscellaneous tools for manipulating text, security auditing, and more._|
- The folder (package) should be on the following form:
```
evennia/
contrib/
category/ # rpg/, game_systems/ etc
mycontribname/
__init__.py
README.md
module1.py
module2.py
...
tests.py
```
It's often a good idea to import useful resources in `__init__.py` to make it easier to import them.
- Your code should abide by the [Evennia Style Guide](../Coding/Evennia-Code-Style.md). Write it to be easy to read.
- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically.
- The `README.md` file will be parsed and converted into a document linked from [the contrib overview page](./Contribs-Overview.md). It needs to be on the following form:
```markdown
# MyContribName
Contribution by <yourname>, <year>
A paragraph (can be multi-line)
summarizing the contrib (required)
Optional other text
## Installation
Detailed installation instructions for using the contrib (required)
## Usage
## Examples
etc.
```
> The credit and first paragraph-summary will be automatically included on the Contrib overview page index for each contribution, so it needs to be just on this form.
## Submitting a contrib
```{sidebar} Not all PRs can be accepted
While most PRs get merged, this is not guaranteed: Merging a contrib means the Evennia project takes on the responsibility of maintaining and supporting the new code. For various reasons this may be deemed unfeasible.
If your code were to *not* be accepted for some reason, we can still link it from our links page; it can also be posted in our discussion forum.
```
- A contrib must always be presented [as a pull request](../Coding/Version-Control.md#contributing-to-evennia) (PR).
- PRs are reviewed so don't be surprised (or disheartened) if you are asked to modify or change your code before it can be merged. Your code can end up going through several iterations before it is accepted.
- To make the licensing situation clear we assume all contributions are released with the same [license as Evennia](../Licensing.md). If this is not possible for some reason, talk to us and we'll handle it on a case-by-case basis.

39
docs/source/Contribs/Contribs-Overview.md
View File

@ -18,7 +18,7 @@ Each contrib contains installation instructions for how to integrate it
with your other code. If you want to tweak the code of a contrib, just
copy its entire folder to your game directory and modify/use it from there.
If you want to contribute yourself, see [here](../Contributing.md)!
If you want to add a contrib, see [the contrib guidelines](./Contribs-Guidelines.md)!
[forum]: https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets
@ -48,6 +48,11 @@ _Systems that are not necessarily tied to a specific
in-game mechanic but which are useful for the game as a whole. Examples include
login systems, new command syntaxes, and build helpers._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -204,6 +209,11 @@ library under the hood.
_'Complete' game engines that can be used directly to start creating content
without no further additions (unless you want to)._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -235,6 +245,11 @@ 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` category._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -382,6 +397,11 @@ the participants until the fight ends.
_Systems related to the game world's topology and structure. Contribs related
to rooms, exits and map building._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -463,7 +483,7 @@ _Contribution by titeuf87, 2017_
This contrib provides a wilderness map without actually creating a large number
of rooms - as you move, you instead end up back in the same room but its description
changes. This means you can make huge areas with little database use as
long as the rooms are relatively similar (name/desc changing).
long as the rooms are relatively similar (e.g. only the names/descs changing).
[Read the documentation](./Contrib-Wilderness.md) - [Browse the Code](evennia.contrib.grid.wilderness)
@ -492,6 +512,11 @@ current location (useful for displaying the grid as an in-game, updating map).
_Systems specifically related to roleplaying
and rule implementation like character traits, dice rolling and emoting._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -593,6 +618,11 @@ to exemplify an Evennia system. Any extra resources tied to documentation
tutorials are found here. Also the home of the Tutorial-World and Evadventure
demo codes._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -699,6 +729,11 @@ is a great way to start learning the system.
_Miscellaneous, tools for manipulating text, security auditing, and more._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1

177
docs/source/Contributing.md
View File

@ -1,173 +1,40 @@
# How To Contribute And Get Help
If you cannot find what you are looking for in the documentation, here's what to do:
## Getting Help
- If you need help, want to start a discussion or get some input on something
you are working on, make a post to the [discussions forum][forum].
- If you want more direct discussions with developers and other users, drop
into our very friendly [Discord channel][chat].
- If you think the documentation is not clear enough, create a [documentation issue][issues].
- If you have trouble with a missing feature or a problem you think is a bug,
[request, or report it][issues].
If you cannot find what you are looking for in the documentation, here's where to go next:
## Community and Spreading the word
- [The Discussions forums][forum] are great for getting help, starting longer-form discussions, showing off your work or get some input on what you are working on. This is also the place to follow Evennia development.
- [The Discord server][chat] has a very helpful `#getting-help` channel for both big and small Evennia problems. It allows for more direct discussion. You can also track both the evennia code changes and the discussion forum from discord.
Being active and helpful in the [discssion forums][forum] or [chat][chat] is already a big help.
## Giving Help
Consider writing about Evennia on your blog or in your favorite (relevant)
forum. Write a review somewhere (good or bad, we like feedback either way). Rate
it on listings. Talk about it to your friends ... that kind of thing.
In general, being active and helpful in the [discssion forums][forum] or [discord chat][chat] is already a big help!
## Help with Documentation
If you want to spread the word, consider writing about Evennia on your blog or in your favorite (relevant) forum. Write a review somewhere (good or bad, we like feedback either way). Rate it on listings. Talk about it to your friends ... that kind of thing.
Evennia depends heavily on good documentation and we are always looking for
extra eyes and hands to improve it. Even small things such as fixing typos are a
great help!
### Help with Documentation
- Easiest is to just [report documentation issues][issues] as you find them. If
we don't know about them, we can't fix them!
- If you want to help editing 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](Howtos/Howtos-Overview.md)?
Evennia is highly dependent on good-quality documentation!
## Helping with code
- [Reporting a Documentation issue][issues] is the easiest way to help out. The more eyes we get on things, the better - if we don't know about the problems, we can't fix them! Even reporting typos is a great help.
- [Contributing directly to the docs](./Contributing-Docs.md) is also possible; you just need a text editor. You can fix issues or even propose a new tutorial!
If you find bugs, or have a feature-request, [make an issue][issues] for it. If
it's not in an issue, the issue will most likely be forgotten.
### Helping with code
Even if you don't feel confident with tackling a bug or feature, just
correcting typos, adjusting formatting or simply *using* the thing and reporting
when stuff doesn't make sense helps us a lot.
Even if you don't feel confident with tackling a bug or feature, just correcting typos, adjusting formatting or simply *using* the thing and reporting when stuff doesn't make sense helps us a lot!
- The code itself should follow Evennia's [Code style guidelines][codestyle] both
for code and documentation. You should write code for that others can read an understand.
- Before merging, your code will be reviewed. Merging of your code into Evennia
is not guaranteed. Be ready to receive feedback and to be asked to make
corrections or fix bugs or any documentation issues and possibly tests (this
is normal and nothing to worry about).
- [Reporting a code issue or bug][issues] is the easiest way to help out. Don't assume we are aware of a problem - if it's not written down in an issue, the problem will most likely be forgotten. Do this even if you plan to make a _Pull Request_ and fix the issue yourself.
- [Make a feature request][issues] if you want to see a new Evennia feature. You can also bring it up with the community first so you are sure it's something that would be interesting to be included with Evennia core.
- [Make a Pull Request](Coding/Version-Control.md#contributing-to-evennia) (PR) to fix bugs or new features. Make sure to follow the [Evennia Code-Style guide](Coding/Evennia-Code-Style.md).
- [The Guide for making an Evennia contrib](Contribs/Contribs-Guidelines.md) outlines how you do to make your own Evennia [contrib](Contribs/Contribs-Overview.md) to distribute with Evennia.
### Using a Forked reposity
### Helping with Donations
The most elegant way to contribute code to Evennia is to use GitHub to create a
*fork* of the Evennia repository and make your changes to that. Refer to the
[Forking Evennia](Coding/Version-Control.md#forking-evennia) version control instructions for detailed instructions.
Evennia is a free and open-source project. Any monetary donations you want to offer are _completely voluntary_. While highly appreciated, we don't expect you to donate and don't hide any secret features behind a donation-paywall. Just see it as a way of showing appreciation by dropping a few coins in the cup.
Once you have a fork set up, you can not only work on your own game in a
separate branch, you can also commit your fixes to Evennia itself.
- Make separate branches for all Evennia additions you do - don't edit your
local `master` or `develop` branches directly. It will make your life a lot easier.
- If you have a change that you think is suitable for the main Evennia
repository, issue a [Pull Request][pullrequest]. This will let Evennia devs know you have stuff to share.
- Bug fixes should generally be done against the `master` branch of Evennia,
while new features/contribs should go into the `develop` branch. If you are
unsure, just pick one and we'll figure it out.
### Contributing with Patches
To help with Evennia development it's strongly recommended to do so using a
forked repository as described above. But for small, well isolated fixes you are
also welcome to submit your suggested Evennia fixes/addendums as a
[patch][patch].
You can include your patch in an Issue or a Mailing list post. Please avoid
pasting the full patch text directly in your post though, best is to use a site
like [Pastebin](https://pastebin.com/) and just supply the link.
### Making an Evennia contrib
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 repository.
#### Guidelines for making a contrib
- If you are unsure about if your contrib idea is suitable or sound, *ask in
discussions or chat before putting any work into it*. We are, for example,
unlikely to accept contribs that require large modifications of the game
directory structure.
- If your code is intended *primarily* as an example or to show a
concept/principle rather than a working system, you _can_ add to the
`contribs/tutorials/` subfolder, but consider if it may be better to instead
write a new tutorial doc page.
- The contribution should preferably work in isolation from other contribs (only
make use of core Evennia) so it can easily be dropped into use. If it does
depend on other contribs or third-party modules, these must be clearly
documented and part of the installation instructions.
- The contrib must be contained within a separate folder under one of the
contrib categories (`game_systems`, `rpg`, `utils` etc). Ask if you are
unsure which category to put your contrib under.
- The folder (package) should be on the following form:
```
mycontribname/
__init__.py
README.md
module1.py
module2.py
...
tests.py
```
It's often a good idea to import useful resources in `__init__.py` to make
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/Contribs-Overview.md). It should follow
the following structure:
```markdown
# MyContribName
Contribution by <yourname>, <year>
A paragraph (can be multi-line)
summarizing the contrib (required)
Optional other text
## Installation
Detailed installation instructions for using the contrib (required)
## Usage
## Examples
etc.
```
The credit and first paragraph-summary will be used on the index page. Every
contrib's readme must contain an installation instruction. See existing contribs
for help.
- If possible, try to make contribution as genre-agnostic as possible and assume
your code will be applied to a very different game than you had in mind when creating it.
- To make the licensing situation clear we assume all contributions are released
with the same [license as Evennia](./Licensing.md). If this is not possible
for some reason, talk to us and we'll handle it on a case-by-case basis.
- Your contribution must be covered by [unit tests](Coding/Unit-Testing.md). Put
your tests in a module `tests.py` under your contrib folder - Evennia will
find them automatically.
- In addition to the normal review process, it's worth noting that merging a
contrib means the Evennia project takes on the responsibility of maintaining
and supporting it. For various reasons this may be deemed beyond our manpower.
- If your code were to *not* be accepted for some reason, you can ask us to
instead link to your repo from our link page so people can find your code that
way.
## Donations
Evennia is a free, open-source project and any monetary donations you want to
offer are _completely voluntary_. See it as a way of showing appreciation by
dropping a few coins in the cup.
- You can support Evennia as an [Evennia patreon][patron]. A patreon donates a
(usually small) sum every month to show continued support.
- If a monthly donation is not your thing, you can also show your appreciation
by doing a [one-time donation][donate] (this is a PayPal link but you don't need
PayPal yourself to use it).
- [Become an Evennia patron][patron] which donates a (usually small) sum every month to show continued support.
- [Make a one-time donation][paypal] if a monthly donation is not your thing. This is a PayPal link but you don't need PayPal yourself to use it.
[patron]: https://www.patreon.com/griatch
@ -181,7 +48,7 @@ dropping a few coins in the cup.
[forum]:https://github.com/evennia/evennia/discussions
[issues]:https://github.com/evennia/evennia/issues/choose
[chat]: https://discord.com/invite/AJJpcRUhtF
[paypal]: https://www.paypal.com/se/cgi-bin/webscr?cmd=_flow&SESSION=Z-VlOvfGjYq2qvCDOUGpb6C8Due7skT0qOklQEy5EbaD1f0eyEQaYlmCc8O&dispatch=5885d80a13c0db1f8e263663d3faee8d64ad11bbf4d2a5a1a0d303a50933f9b2
[paypal]: https://www.paypal.com/paypalme/GriatchEvennia
[patreon]: https://www.patreon.com/griatch
[issues-bounties]:https://github.com/evennia/evennia/labels/bounty
[bountysource]: https://www.bountysource.com/teams/evennia

2
docs/source/Glossary.md
View File

@ -185,7 +185,7 @@ latest changes, just `cd` into your game dir and run
evennia migrate
That should be it (see [virtualenv](./Glossary.md#virtualenv) if you get a warning that the `evennia`
command is not available). See also [Updating your game](Coding/Updating-Your-Game.md) for more details.
command is not available). See also [Updating your game](Setup/Updating-Evennia.md) for more details.
> Technically, migrations are shipped as little Python snippets of code that explains which database
actions must be taken to upgrade from one version of the schema to the next. When you run the

131
docs/source/Setup/Choosing-a-Database.md
View File

@ -10,13 +10,11 @@ This page gives an overview of the supported SQL databases as well as instructio
Since Evennia uses [Django](https://djangoproject.com), most of our notes are based off of what we know from the community and their documentation. While the information below may be useful, you can always find the most up-to-date and "correct" information at Django's [Notes about supported
Databases](https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases) page.
## SQLite3
## SQLite3 (default)
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database
and Evennia will set this up for you automatically if you give no other options. SQLite stores the
database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this
database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all
that's ever needed.
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database and Evennia will set this up for you automatically if you give no other options.
SQLite stores the database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all that's ever needed.
SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:
@ -44,13 +42,9 @@ To inspect the default Evennia database (once it's been created), go to your gam
This will bring you into the sqlite command line. Use `.help` for instructions and `.quit` to exit.
See [here](https://gist.github.com/vincent178/10889334) for a cheat-sheet of commands.
### Resetting SQLite3 database
### Resetting SQLite3
To reset your database and start from scratch, simply stop Evennia and delete the `mygame/server/evennia.db3`. Then run `evennia migrate` again.
```{sidebar} Hint
Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset, you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run migrations and create the superuser every time!
```
If you want to reset your SQLite3 database, see [here](./Updating-Evennia.md#sqlite3-default).
## PostgreSQL
@ -60,14 +54,10 @@ game has an very large database and/or extensive web presence through a separate
### Install and initial setup of PostgreSQL
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily
available for all distributions. You need to also get the `psql` client (this is called `postgresql-
client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql
download page](https://www.postgresql.org/download/). You should be setting up a password for your
database-superuser (always called `postgres`) when you install.
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily available for all distributions. You need to also get the `psql` client (this is called `postgresql- client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql download page](https://www.postgresql.org/download/). You should be setting up a password for your database-superuser (always called `postgres`) when you install.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install (`pip
install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install
(`pip install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
Next, start the postgres client:
@ -104,12 +94,7 @@ GRANT ALL PRIVILEGES ON DATABASE evennia TO evennia;
```
[Here](https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546) is a cheat-sheet for psql commands.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever
you want though). We then grant the 'evennia' user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
`postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above
again to recreate the database and grant privileges.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever you want though). We then grant the 'evennia' user full privileges to the new database so it can read/write etc to it. If you in the future wanted to completely wipe the database, an easy way to do is to log in as the `postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above again to recreate the database and grant privileges.
### Evennia PostgreSQL configuration
@ -134,8 +119,7 @@ If you used some other name for the database and user, enter those instead. Run
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
to populate your database. Should you ever want to inspect the database directly you can from now on also use
evennia dbshell
@ -144,7 +128,11 @@ as a shortcut to get into the postgres command line for the right database and u
With the database setup you should now be able to start start Evennia normally with your new
database.
### Advanced Postgresql Usage (Remote Server)
### Resetting PostgreSQL
If you want to reset your PostgreSQL datbase, see [here](./Updating-Evennia.md#postgresql)
### Advanced PostgreSQL Usage (Remote Server)
```{warning}
@ -153,18 +141,9 @@ database.
an Internet-accessible server.
```
The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.
The above discussion is for hosting a local server. In certain configurations it may make sense host the database on a server remote to the one Evennia is running on. One example case is where code development may be done on multiple machines by multiple users. In this configuration, a local data base (such as SQLite3) is not feasible since all the machines and developers do not have access to the file.
Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.
Choose a remote machine to host the database and PostgreSQl server. Follow the instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database. Depending on distribution, PostgreSQL will only accept connections on the local machine (localhost). In order to enable remote access, two files need to be changed.
First, determine which cluster is running your database. Use `pg_lscluster`:
@ -174,10 +153,7 @@ Ver Cluster Port Status Owner Data directory Log file
12 main 5432 online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
```
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems
in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are
what are reported in the `pg_lscluster` output. So, for the above example,
the file is `/etc/postgresql/12/main/postgresql.conf`.
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are what are reported in the `pg_lscluster` output. So, for the above example, the file is `/etc/postgresql/12/main/postgresql.conf`.
In this file, look for the line with `listen_addresses`. For example:
@ -205,8 +181,7 @@ on any interface.
for more details.)
```
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`).
Look for a line with:
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`). Look for a line with:
```
# IPv4 local connections:
host all all 127.0.0.1/32 md5
@ -226,31 +201,19 @@ Now, restart your cluster:
$ pg_ctlcluster 12 main restart
```
Finally, update the database settings in your Evennia secret_settings.py (as
described [above](#evennia-postgresql-configuration) modifying `SERVER` and
`PORT` to match your server.
Finally, update the database settings in your Evennia secret_settings.py (as described [above](#evennia-postgresql-configuration) modifying `SERVER` and `PORT` to match your server.
Now your Evennia installation should be able to connect and talk with a remote
server.
Now your Evennia installation should be able to connect and talk with a remote server.
## MySQL / MariaDB
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics
all functionality and command syntax of the former. So this section covers both.
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics all functionality and command syntax of the former. So this section covers both.
### Installing and initial setup of MySQL/MariaDB
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
`mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users
will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB
downloads](https://mariadb.org/download/) pages. You also need the respective database clients
(`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the `mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB downloads](https://mariadb.org/download/) pages. You also need the respective database clients (`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you should usually be asked to set up the database root user and password.
You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install
mysqlclient`.
You will finally also need a Python interface to allow Evennia to talk to the database. Django recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install mysqlclient`.
Start the database client (this is named the same for both mysql and mariadb):
@ -274,27 +237,15 @@ FLUSH PRIVILEGES;
```
[Here](https://gist.github.com/hofmannsven/9164408) is a mysql command cheat sheet.
Above we created a new local user and database (we called both 'evennia' here, you can name them
what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the
`evennia` database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.
Above we created a new local user and database (we called both 'evennia' here, you can name them what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the `evennia` database and make sure the privileges are applied. Exiting the client brings us back to the normal terminal/console.
> Note: If you are not using MySQL for anything else you might consider granting the 'evennia' user
full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means
you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.
> If you are not using MySQL for anything else you might consider granting the 'evennia' user full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a way of easy reset. Without this extra privilege you will be able to drop the database but not re create it without first switching to the database-root user.
## Add MySQL configuration to Evennia
### Add MySQL/MariaDB configuration to Evennia
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or
`secret_settings.py` if you don't want your db info passed around on git repositories).
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or `secret_settings.py` if you don't want your db info passed around on git repositories).
> Note: The Django documentation suggests using an external `db.cnf` or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. [issue
#1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in
your settings as below.
> The Django documentation suggests using an external `db.cnf` or other external conf- formatted file. Evennia users have however found that this leads to problems (see e.g. [issue #1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in your settings as below.
```python
#
@ -311,22 +262,24 @@ your settings as below.
}
}
```
The `mysql` backend is used by `MariaDB` as well.
Change this to fit your database setup. Next, run:
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
to populate your database. Should you ever want to inspect the database directly you can from now on also use
evennia dbshell
as a shortcut to get into the postgres command line for the right database and user.
With the database setup you should now be able to start start Evennia normally with your new
database.
With the database setup you should now be able to start start Evennia normally with your new database.
## Others
### Resetting MySQL/MariaDB
No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for [MS SQL](https://code.google.com/p/django-mssql/) and possibly a few
others. If you try other databases out, consider expanding this page with instructions.
If you want to reset your MySQL/MariaDB datbase, see [here](./Updating-Evennia.md#mysql-mariadb).
## Other databases
No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for [MS SQL](https://code.google.com/p/django-mssql/) and possibly a few others. If you try other databases out, consider contributing to this page with instructions.

10
docs/source/Setup/Installation.md
View File

@ -4,12 +4,15 @@
If you are converting an existing game from a previous Evennia version, [see here](./Installation-Upgrade.md).
```
The fastest way to install Evennia is to use the `pip` installer that comes with Python (read on).
You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Requirements
```{sidebar} Develop in isolation
Installing Evennia doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection if you want to.
```
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended)
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended). Any OS that supports Python should work.
- Windows: In the installer, make sure you select `add python to path`. If you have multiple versions of Python installed, use `py` command instead of `python` to have Windows automatically use the latest.
- Using a light-weight [Python virtual environment](./Installation-Git.md#virtualenv) is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. Using virtualenvs like this is common Python praxis.
- Don't install Evennia as administrator or superuser.
@ -17,9 +20,6 @@ Installing Evennia doesn't make anything visible online. Apart from installation
## Install with `pip`
The fastest way to install Evennia is to use the `pip` installer that comes with Python.
You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python, you install Evennia with
@ -87,7 +87,7 @@ Full stop of the server (use `evennia start` to restart):
evennia stop
See [Server start-stop-reload](./Start-Stop-Reload.md) page for more details.
See [Server start-stop-reload](./Running-Evennia.md) page for more details.
## See server logs

0
docs/source/Setup/Start-Stop-Reload.md → docs/source/Setup/Running-Evennia.md
View File

5
docs/source/Setup/Setup-Overview.md
View File

@ -14,7 +14,8 @@ Installation-Troubleshooting
Installation-Android
Installation-Upgrade
Installation-Non-Interactive
Start-Stop-Reload
Running-Evennia
Updating-Evennia
```
## Configuration
@ -31,7 +32,7 @@ Channels-to-RSS
Channels-to-Twitter
```
## Going public
## Going Online
```{toctree}
:maxdepth: 2

94
docs/source/Setup/Updating-Evennia.md Normal file
View File

@ -0,0 +1,94 @@
# Updating Evennia
When Evennia is updated to a new version you will usually see it announced in the [Discussion forum](github:discussions) and in the [dev blog](https://www.evennia.com/devblog/index.html). You can also see the changes on [github](github:) or through one of our other [linked pages](../Links.md).
## If you installed with `pip`
If you followed the [normal install instructions](./Installation.md), here's what you do to upgrade:
1. Read the [changelog](../Coding/Changelog.md) to see what changed and if it means you need to make any changes to your game code.
2. If you use a [virtualenv](#Installation-Git#virtualenv), make sure it's active.
3. `cd` to your game dir (e.g. `mygame`)
4. `evennia stop`
5. `pip install --upgrade evennia`
6. `cd` tor your game dir
7. `evennia migrate` (_ignore_ any warnings about running `makemigrations`, it should _not_ be done)
8. `evennia start`
If the upstream changes are large, you may also need to go into your gamedoor
## If you installed with `git`
This applies if you followed the [git-install instructions](./Installation-Git.md). Before Evennia 1.0, this was the only way to install Evennia.
At any time, development is either happening in the `master` branch (latest stable) or `develop` (experimental). Which one is active and 'latest' at a given time depends - after a release, `master` will see most updates, close to a new release, `develop` will usually be the fastest changing.
1. Read the [changelog](../Coding/Changelog.md) to see what changed and if it means you need to make any changes to your game code.
2. If you use a [virtualenv](#Installation-Git#virtualenv), make sure it's active.
3. `cd` to your game dir (e.g. `mygame`)
4. `evennia stop`
5. `cd` to the `evennia` repo folder you cloned during the git installation process.
6. `git pull`
7. `pip install --upgrade -e .` (remember the `.` at the end!)
9. `cd` back to your game dir
10. `evennia migrate` (_ignore_ any warnings about running `makemigrations` , it should _not_ be done)
11. `evennia start`
## If you installed with `docker`
If you followed the [docker installation instructions] you need to pull the latest docker image for the branch you want:
- `docker pull evennia/evennia` (master branch)
- `docker pull evennia/evennia:develop` (experimental `develop` branch)
Then restart your containers.
## Resetting your database
Should you ever want to start over completely from scratch, there is no need to re-download Evennia. You just need to clear your database.
First:
1. `cd` to your game dir (e.g. `mygame`)
2. `evennia stop`
### SQLite3 (default)
```{sidebar} Hint
Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset (and as long as you haven't had to run any new migrations), you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run the same migrations and create the superuser every time!
```
3. delete the file `mygame/server/evennia.db3`
4. `evennia migrate`
5. `evennia start`
### PostgreSQL
3. `evennia dbshell` (opens the psql client interface)
```
psql> DROP DATABASE evennia;
psql> exit
```
4. You should now follow the [PostgreSQL install instructions](./Choosing-a-Database.md#postgresql) to create a new evennia database.
5. `evennia migrate`
6. `evennia start`
### MySQL/MariaDB
3. `evennia dbshell` (opens the mysql client interface)
```
mysql> DROP DATABASE evennia;
mysql> exit
```
4. You should now follow the [MySQL install instructions](./Choosing-a-Database.md#mysql-mariadb) to create a new evennia database.
5. `evennia migrate`
6. `evennia start`
### What are database migrations?
If and when an Evennia update modifies the database *schema* (that is, the under-the-hood details as to how data is stored in the database), you must update your existing database correspondingly to match the change. If you don't, the updated Evennia will complain that it cannot read the database properly. Whereas schema changes should become more and more rare as Evennia matures, it may still happen from time to time.
One way one could handle this is to apply the changes manually to your database using the database's command line. This often means adding/removing new tables or fields as well as possibly convert existing data to match what the new Evennia version expects. It should be quite obvious that this quickly becomes cumbersome and error-prone. If your database doesn't contain anything critical yet it's probably easiest to simply reset it and start over rather than to bother converting.
Enter *migrations*. Migrations keeps track of changes in the database schema and applies them automatically for you. Basically, whenever the schema changes we distribute small files called "migrations" with the source. Those tell the system exactly how to implement the change so you don't have to do so manually. When a migration has been added we will tell you so on Evennia's mailing lists and in commit messages - you then just run `evennia migrate` to be up-to-date again.

BIN
docs/source/_static/images/fork_button.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.0 KiB

14
docs/source/index.md
View File

@ -13,14 +13,15 @@
This is the manual of [Evennia](https://www.evennia.com), the open source Python `MU*` creation system. Use the Search bar on the left to find or discover interesting articles.
- [Introduction](./Evennia-Introduction.md) - what is this Evennia thing?
- [Getting help and Contribute](./Contributing.md) - when you get stuck or want to chip in
- [Contributing and Getting help](./Contributing.md) - when you get stuck or want to chip in
## Setup
- [Setup Quickstart](Setup/Setup-Overview.md#installation-and-running) - installing Evennia and get going
- [Starting, Stopping and Reloading](Setup/Start-Stop-Reload.md) - how to manage the Evennia server
- [Configuration](Setup/Setup-Overview.md#configuration) - how to set up your server the way you like it
- [Going public](Setup/Setup-Overview.md#going-public) - taking your game online
- [Installation](Setup/Setup-Overview.md#installation-and-running) - getting started
- [Running the Game](Setup/Running-Evennia.md) - how to start, stop and reload Evennia
- [Updating the Server](Setup/Updating-Evennia.md) - how to update Evennia
- [Configuration](Setup/Setup-Overview.md#configuration) - how to set up Evennia the way you like it
- [Going Online](Setup/Setup-Overview.md#going-online) - bringing your game online
## Tutorials and Howtos
@ -55,7 +56,10 @@ This is the manual of [Evennia](https://www.evennia.com), the open source Python
:maxdepth: 3
Evennia-Introduction
Setup/Running-Evennia
Setup/Updating-Evennia
Setup/Setup-Overview
Howtos/Howtos-Overview
Components/Components-Overview
Concepts/Concepts-Overview