Start Stop Reload¶
You control Evennia from your game folder (we refer to it as
here), using the
evennia program. If the
evennia program is not
available on the command line you must first install Evennia as
described in the Getting Started page.
A common reason for not seeing the
evennia command is to forget to
(re)start the virtual environment (in a folder called
pyenv if you
followed the Getting Started page). You need to do this every time you
start a new terminal/console and should see
(pyenv) at the beginning
of the line. The virtualenv allows to install all Python dependencies
without needing root or disturbing the global packages in the repo
(which are often older).
source pyenv/bin/activate (Linux/Unix) pyenv/Scripts/activate` (Windows)
Below are described the various management options. Run
to give you a brief help and
to give you a menu with options.
Evennia consists of two components, the Evennia Server and Portal. Briefly, the Server is what is running the mud. It handles all game-specific things but doesn’t care exactly how players connect, only that they have. The Portal is a gateway to which players connect. It knows everything about telnet, ssh, webclient protocols etc but very little about the game. Both are required for a functioning mud.
The above command automatically starts both Portal and Server at the
same time. The Server will log to the terminal (
stdout), while the
Portal will log to its log file in
mygame/server/log. This is the
most useful mode for development since you see logged errors directly in
You can start the two components one at a time:
evennia start server evennia start portal
You can also start the server in interactive mode with the
evennia -i start
This will start Evennia as a foreground process. You can then stop it
Starting Evennia fully detached¶
Logging to the terminal is useful in development. But on a remote server you’ll generally log out of the console from which you started Evennia. You might also want to close the terminal when running locally. If you need this you must either deploy Evennia as a docker image, start Evennia in a terminal multiplexer like Screen/Tmux or simply make sure to redirect the server output to a file:
# linux/mac evennia start > server/logs/server.log # windows evennia start > server\logs\server.log
If you don’t, the server will work fine after closing the console but it won’t come back up after a reload.
The act of reloading means the Server program is shut down and then
restarted again. With the default commands you initiate a reload with
@reload command from inside the game. Everyone will get a
message and the game will be briefly paused for all accounts as the
server reboots. Since they are connected to the Portal, their
connections are not lost.
Reloading is as close to a “warm reboot” you can get. It reinitializes
all code of Evennia, but doesn’t kill “persistent” scripts. It also
at_server_reload() hooks on all objects so you can save
eventual temporary properties you want.
You can also reload the server from outside the game:
This is very useful if you are testing new functionality and introduce
some critical error that makes it impossible for Evennia to load your
module. If the module in question is, for example, describing your
in-game Character, this may mean that you can’t enter commands in-game
anymore. A terminal-line
evennia reload (or
evennia start if the
server itself couldn’t recover from the error) will get everything going
again once the bug in your code is fixed.
External reloading from the command line is not supported on the Windows platform. This is due to limitations in Windows signal handling. To reload the server on Windows, use
@reloadfrom in-game. You can also use
evennia stop && evennia startfor a cold restart. A cold restart will kick everyone but may be necessary if you introduced a syntax error causing the in-game
@reloadcommand to not be possible to load.
Resetting is the equivalent of a “cold reboot” of the Server component
- it will restart but will behave as if it was fully shut down. You
initiate a reset using the
@reset command from inside the game. As
opposed to a “real” shutdown, no accounts will be disconnected during a
reset. A reset will however purge all non-persistent scripts and will
at_server_shutdown() hooks. It can be a good way to clean
unsafe scripts during development, for example.
A reset is equivalent to
evennia stop server evennia start server
A full shutdown closes Evennia completely, both Server and Portal. All
accounts will be booted and systems saved and turned off cleanly. From
inside the game you initiate a shutdown with the
From command line you do
You will see messages of both Server and Portal closing down. All
accounts will see the shutdown message and then be disconnected. The
same effect happens if you press
Ctrl+C while the server runs in
If you run Windows you will be asked “Terminate batch job (Y/N)?” multiple times in a row. This is an annoying practice of Windows console that can’t be turned off. Instead of entering
Yover and over you can press
Ctrl+Conce to bypass the questions. There are supposedly third-party replacements for the Windows Console that allows to turn this off, report your findings!
evennia program will also pass-through options used by the
django-admin. These operate on the database in various ways.
evennia migrate # migrate the database evennia shell # launch an interactive, django-aware python shell evennia dbshell # launch database shell
For (many) more options, see the django-admin docs.
Advanced handling of Evennia processes¶
If you should need to manually manage Evennia’s processors (or view them
in a task manager program such as Linux’
top or the more advanced
htop), you will find the following processes to be related to
- 1 x
evennia_runner.py- This is a process started by the
evennia_runner.pyinstance watches the Server and Portal processes respectively (but commonly only the Server). When the other process shuts down the runner will check if a “restart” is desired and if so restart it again. This is how reloading the server works.
- 2 x
twistd ... server.py- One of these processes manages Evennia’s Server component, the main game. The second process (with the same name but different process id) handle’s Evennia’s internal web server. You can look at
mygame/server/server.pidto determine which is the main process of the two.
- 2 x
twistd ... portal.py- One of these processes maintains the Portal component and all external-facing protocols. The second process (with the same name but a different process id) handles the AMP client that communicates data between the Portal and the Server. You can look at
mygame/server/portal.pidto determine which is the main process of the two.
Syntax errors during live development¶
During development, you will usually modify code and then reload the server to see your changes. This is done by Evennia re-importing your custom modules from disk. Usually bugs in a module will just have you see a traceback in the game, in the log or on the command line. For some really serious syntax errors though, your module might not even be recognized as valid Python. Evennia may then fail to restart correctly.
From inside the game you see a text about the Server restarting followed by an ever growing list of “…”. Usually this only lasts a very short time (up to a few seconds). If it seems to go on, it means the Portal is still running (you are still connected to the game) but the Server-component of Evennia failed to restart (that is, it remains in a shut-down state). Look at your log files or terminal to see what the problem is - you will usually see a clear traceback showing what went wrong.
Fix your bug then run
Assuming the bug was fixed, this will start the Server manually (while not restarting the Portal). In-game you should now get the message that the Server has successfully restarted.
Recovering from critical shutdowns¶
If your server died unexpectedly it may not have had time to clean up
after itself correctly. This can happen if you shut down your computer
with Evennia running or force-killed the process (such as with
killall -9 twistd under Linux). What then happens is that two small
files that should have been deleted remain behind. These are
You notice this by Evennia telling you that the Server/Portal is “already running” despite it clearly does not. First try to stop it manually:
If there is a problem Evennia will tell you it cannot signal the system
to close and that the pid files are “stale”. Fixing this is simple -
server.pid and start anew.
Optional: Server startup script (Linux only)¶
This is considered an advanced section. First make sure Evennia starts normally.
If you start Evennia on a remote server and then disconnect you will
likely find that
evennia reload) no longer works.
The server will shut down and just not come back up again. The reason
for this is that when you started Evennia, a silent little program
called the runner also started in the background. The runner’s job is
to catch the Server shutdown and kick it back into gear if you wanted a
reload. If you kill the terminal you will also kill this little runner
program and thus the Server can’t restart.
Enter Gnu Screen. Screen is a standard Linux/Unix program for
managing terminal sessions. If you control the server you can install it
(on Debian derivatives) with
apt-get install screen. Most remote
server solutions will offer screen by default or you should easily be
able to request it to be installed. When you are running under Screen,
logging off will not kill the terminal but just disconnect from it -
it (and the runner) will keep running happily without you. You can later
“attach” to it again and continue where you were.
Evennia supplies a bash script for managing the server under Screen. It
assumes you installed Evennia according to the Getting Started
instructions and have it running already. The script is found in the
evennia repository’s top level, as
is how you use it:
evennia-screen.shto some place in
mygame, for example
mygame/server(but it could really go anywhere).
- Open the copied file in a text editor and change the variables
GAMEDIRto fit your game setup. You should use absolute paths.
- Make it executable by you with
chmod u+x evennia-screen.sh
Make sure your game is not running and then start Evennia using
./evennia-screen.sh start. Apart from a short message nothing will
appear to happen. But behind the scenes a new Screen session was started
and Evennia launched inside it. To see the availabe Screen sessions,
enter this in the terminal:
You should get back some lines including this one:
19989.mygame (12/08/2016 10:31:31 PM) (Detached)
The exact numbers will vary, but the
GAMENAME you entered in the
script should be seen as the name of the session (“mygame” here). Now we
connect to the session:
screen -r mygame
Boom - you are now inside the Screen session and should see the Evennia
startup messages. You are already inside the virtualenv and can operate
the server normally. If you close the window, the Screen session will
just “detach”. To detach without logging out, press
Ctrl-a d (that
Ctrl-a and then press
d). Actually killing Screen is
Ctrl-d (the normal Unix disrupt signal).
Screen is a powerful program with a lot of very useful features. you are wise to read up more on it if you work remotely on any server.
Optional: init.d startup script (Linux only)¶
This is considered an advanced section.
For the final steps of this section you will need root access to your server, or be able to ask someone with root access to help you. You will also need a working
evennia-screen.shscript from the previous section, so make sure to do that first.
When running on a remote server you may want Evennia to start automatically when the server starts. This could be important for unexpected power outages for example. You may also want to run the server as an isolated user for security reasons.
Evennia supplies a bash script for use with the common System V init
system (if you have
/etc/init.d this is what you use. This was
tested with Debian-derived distros). The script is found at the root of
the evennia repository, as
To use the script, do the following:
bin/unix/evennia-screen-initd.shto a temporary place so you can edit it without modifying the original.
- Edit the script and change the lines for
USERto match your setup.
SCRIPTPATHis the absolute path to your working
evennia-screen.shscript from the previous section. The
USERmust have access to launching Evennia. It’s commonly your own user name but you might also consider creating a separate low-privilege account only for Evennia. Obs: Never put ``USER`` to “root”, Evennia should never be run as root!.
If you have root access on the server, you then do the following, otherwise you need to ask a server admin to them for you:
- Copy (as root/sudo) your edited copy to
/etc/init.d/and rename it to just
sudo cp evennia-screen-initd.sh /etc/init.d/evennia
- Make the script owned by root:
sudo chown root:root evennia
- Make the script executable:
sudo chmod 755 evennia
- Make script run when the server starts (late in the startup):
sudo update-rc.d evennia defaults 91
To test things work, reboot the server if you have the right to do so.
When it comes back up, Evennia should be running in its (detached)
Screen Session and you can connect to it as described in the previous
section. If you have root access you can now also operate Evennia as a
global service with
sudo service evennia start|stop|reload.