Start Stop Reload

Griatch edited this page Dec 19, 2016 · 33 revisions
Clone this wiki locally

You control Evennia from your game folder (we refer to it as mygame/ 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

evennia -h 

to give you a brief help and

evennia menu

to give you a menu with options.

Starting Evennia

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.

 evennia start

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 the terminal.

You can also 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 -i flag:

 evennia -i start 

This will start Evennia as a foreground process. You can then stop it completely with Ctrl-C.


The act of reloading means the Server program is shut down and then restarted again. With the default commands you initiate a reload with the @reload command from inside the game. Everyone will get a message and the game will be briefly paused for all players 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 calls 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:

 evennia reload

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 @reload from in-game. You can also use evennia stop && evennia start for a cold restart. A cold restart will kick everyone but may be necessary if you introduced a syntax error causing the in-game @reload command 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 players will be disconnected during a reset. A reset will however purge all non-persistent scripts and will call 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

Shutting down

A full shutdown closes Evennia completely, both Server and Portal. All players will be booted and systems saved and turned off cleanly. From inside the game you initiate a shutdown with the @shutdown command.

From command line you do

 evennia stop

You will see messages of both Server and Portal closing down. All players will see the shutdown message and then be disconnected. The same effect happens if you press Ctrl+C while the server runs in interactive mode.

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 Y over and over you can press Ctrl+C once to bypass the questions. There are supposedly third-party replacements for the Windows Console that allows to turn this off, report your findings!

Django options

The 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 Evennia:

  • 1 x - This is a process started by the evennia launcher. The instance 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 ... - 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/ to determine which is the main process of the two.
  • 2 x twistd ... - 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/ to 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

evennia start

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 mygame/server/ and mygame/server/

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:

evennia stop

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 - just delete and/or 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 @reload (or 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 bin/unix/ This is how you use it:

  1. Copy to some place in mygame, for example mygame/server (but it could really go anywhere).
  2. Open the copied file in a text editor and change the variables GAMENAME, VIRTUALENV and GAMEDIR to fit your game setup. You should use absolute paths.
  3. Make it executable by you with chmod u+x

Make sure your game is not running and then start Evennia using ./ 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:

screen -ls 

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 is, hold Ctrl-a and then press d). Actually killing Screen is done by 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 script 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 bin/unix/

To use the script, do the following:

  1. Copy bin/unix/ to a temporary place so you can edit it without modifying the original.
  2. Edit the script and change the lines for SCRIPTPATH and USER to match your setup. SCRIPTPATH is the absolute path to your working script from the previous section. The USER must 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:

  1. Copy (as root/sudo) your edited copy to /etc/init.d/ and rename it to just evennia: sudo cp /etc/init.d/evennia
  2. cd /etc/init.d
  3. Make the script owned by root: sudo chown root:root evennia
  4. Make the script executable: sudo chmod 755 evennia
  5. 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.