Evennia launcher program

This is the start point for running Evennia.

Sets the appropriate environmental variables for managing an Evennia game. It will start and connect to the Portal, through which the Server is also controlled. This pprogram

Run the script with the -h flag to see usage information.

class evennia.server.evennia_launcher.MsgStatus(**kw)[source]

Bases: twisted.protocols.amp.Command

Ping between AMP services

key = 'MsgStatus'
arguments: List[Tuple[bytes, twisted.protocols.amp.Argument]] = [(b'status', <twisted.protocols.amp.String object>)]
errors: Dict[Type[Exception], bytes] = {<class 'Exception'>: b'EXCEPTION'}
response: List[Tuple[bytes, twisted.protocols.amp.Argument]] = [(b'status', <twisted.protocols.amp.String object>)]
allErrors = {<class 'Exception'>: b'EXCEPTION'}
commandName = b'MsgStatus'
reverseErrors = {b'EXCEPTION': <class 'Exception'>}
class evennia.server.evennia_launcher.MsgLauncher2Portal(**kw)[source]

Bases: twisted.protocols.amp.Command

Message Launcher -> Portal

key = 'MsgLauncher2Portal'
arguments: List[Tuple[bytes, twisted.protocols.amp.Argument]] = [(b'operation', <twisted.protocols.amp.String object>), (b'arguments', <twisted.protocols.amp.String object>)]
errors: Dict[Type[Exception], bytes] = {<class 'Exception'>: b'EXCEPTION'}
response: List[Tuple[bytes, twisted.protocols.amp.Argument]] = []
allErrors = {<class 'Exception'>: b'EXCEPTION'}
commandName = b'MsgLauncher2Portal'
reverseErrors = {b'EXCEPTION': <class 'Exception'>}
class evennia.server.evennia_launcher.AMPLauncherProtocol[source]

Bases: twisted.protocols.amp.AMP

Defines callbacks to the launcher


Initialize self. See help(type(self)) for accurate signature.


Register a waiter for a status return.


Get a status signal from portal - fire next queued callback

evennia.server.evennia_launcher.send_instruction(operation, arguments, callback=None, errback=None)[source]

Send instruction and handle the response.


Send status ping to portal


Wait for an explicit STATUS signal to be sent back from Evennia.

evennia.server.evennia_launcher.wait_for_status(portal_running=True, server_running=True, callback=None, errback=None, rate=0.5, retries=20)[source]

Repeat the status ping until the desired state combination is achieved.

  • portal_running (bool or None) – Desired portal run-state. If None, any state is accepted.

  • server_running (bool or None) – Desired server run-state. If None, any state is accepted. The portal must be running.

  • callback (callable) – Will be called with portal_state, server_state when condition is fulfilled.

  • errback (callable) – Will be called with portal_state, server_state if the request is timed out.

  • rate (float) – How often to retry.

  • retries (int) – How many times to retry before timing out and calling errback.


Run the collectstatic django command

evennia.server.evennia_launcher.start_evennia(pprofiler=False, sprofiler=False)[source]

This will start Evennia anew by launching the Evennia Portal (which in turn will start the Server)

evennia.server.evennia_launcher.reload_evennia(sprofiler=False, reset=False)[source]

This will instruct the Portal to reboot the Server component. We do this manually by telling the server to shutdown (in reload mode) and wait for the portal to report back, at which point we start the server again. This way we control the process exactly.


This instructs the Portal to stop the Server and then itself.

evennia.server.evennia_launcher.reboot_evennia(pprofiler=False, sprofiler=False)[source]

This is essentially an evennia stop && evennia start except we make sure the system has successfully shut down before starting it again.

If evennia was not running, start it.


Tell portal to start server (debug)


Start the Server under control of the launcher process (foreground)


Start the Portal under control of the launcher process (foreground)


In a normal start, the launcher waits for the Portal to start, then tells it to start the Server. Since we can’t do this here, we instead start the Server first and then starts the Portal - the Server will auto-reconnect to the Portal. To allow the Server to be reloaded, this relies on a fixed server server-cmdline stored as a fallback on the portal application in evennia/server/portal/portal.py.

evennia.server.evennia_launcher.stop_server_only(when_stopped=None, interactive=False)[source]

Only stop the Server-component of Evennia (this is not useful except for debug)

  • when_stopped (callable) – This will be called with no arguments when Server has stopped (or if it had already stopped when this is called).

  • interactive (bool, optional) – Set if this is called as part of the interactive reload mechanism.


Display the info strings from the running Evennia

evennia.server.evennia_launcher.tail_log_files(filename1, filename2, start_lines1=20, start_lines2=20, rate=1)[source]

Tail two logfiles interactively, combining their output to stdout

When first starting, this will display the tail of the log files. After that it will poll the log files repeatedly and display changes.

  • filename1 (str) – Path to first log file.

  • filename2 (str) – Path to second log file.

  • start_lines1 (int) – How many lines to show from existing first log.

  • start_lines2 (int) – How many lines to show from existing second log.

  • rate (int, optional) – How often to poll the log file.


Get the Evennia version info from the main package.


Checks and imports the Evennia dependencies. This must be done already before the paths are set up.


not_error (bool) – True if no dependency error was found.


Set GAMEDIR based on path, by figuring out where the setting file is inside the directory tree. This allows for running the launcher from elsewhere than the top of the gamedir folder.


Randomly create the secret key for the settings file

evennia.server.evennia_launcher.create_settings_file(init=True, secret_settings=False)[source]

Uses the template settings file to build a working settings file.

  • init (bool) – This is part of the normal evennia –init operation. If false, this function will copy a fresh template file in (asking if it already exists).

  • secret_settings (bool, optional) – If False, create settings.py, otherwise create the secret_settings.py file.


Initialize a new game directory named dirname at the current path. This means copying the template directory from evennia’s root.


dirname (str) – The directory name to create.


Create the superuser account


Check so the database exists.


always_return (bool, optional) – If set, will always return True/False also on critical errors. No output will be printed.


exists (bool)True if the database exists, otherwise False.


Get current environment and add PYTHONPATH.


env (dict) – Environment global dict.

evennia.server.evennia_launcher.get_pid(pidfile, default=None)[source]

Get the PID (Process ID) by trying to access an PID file.

  • pidfile (str) – The path of the pid file.

  • default (int, optional) – What to return if file does not exist.


pid (str) – The process id or default.


The pidfile should normally be removed after a process has finished, but when sending certain signals they remain, so we need to clean them manually.


pidfile (str) – The path of the pid file.

evennia.server.evennia_launcher.kill(pidfile, component='Server', callback=None, errback=None, killsignal=<Signals.SIGINT: 2>)[source]

Send a kill signal to a process based on PID. A customized success/error message will be returned. If clean=True, the system will attempt to manually remove the pid file. On Windows, no arguments are useful since Windows has no ability to direct signals except to all children of a console.

  • pidfile (str) – The path of the pidfile to get the PID from. This is ignored on Windows.

  • component (str, optional) – Usually one of ‘Server’ or ‘Portal’. This is ignored on Windows.

  • errback (callable, optional) – Called if signal failed to send. This is ignored on Windows.

  • callback (callable, optional) – Called if kill signal was sent successfully. This is ignored on Windows.

  • killsignal (int, optional) – Signal identifier for signal to send. This is ignored on Windows.


Display version info.


about (bool) – Include ABOUT info as well as version numbers.


version_info (str) – A complete version info string.


Import settings modules in settings. This will raise exceptions on pure python-syntax issues which are hard to catch gracefully with exceptions in the engine (since they are formatting errors in the python source files themselves). Best they fail already here before we get any further.

Keyword Arguments

show_warnings (bool) – If non-fatal warning messages should be shown.

evennia.server.evennia_launcher.init_game_directory(path, check_db=True, need_gamedir=True)[source]

Try to analyze the given path to find settings.py - this defines the game directory and also sets PYTHONPATH as well as the django path.

  • path (str) – Path to new game directory, including its name.

  • check_db (bool, optional) – Check if the databae exists.

  • need_gamedir (bool, optional) – set to False if Evennia doesn’t require to be run in a valid game directory.


Start an instance of the dummyrunner


number_of_dummies (int) – The number of dummy accounts to start.


The dummy accounts’ behavior can be customized by adding a dummyrunner_settings.py config file in the game’s conf/ directory.


Run the linking wizard, for adding new external connections.


Display the server settings. We only display the Evennia specific settings here. The result will be printed to the terminal.


keys (str or list) – Setting key or keys to inspect.

evennia.server.evennia_launcher.run_custom_commands(option, *args)[source]

Inject a custom option into the evennia launcher command chain.

  • option (str) – Incoming option - the first argument after evennia on the command line.

  • *args – All args will passed to a found callable.__dict__


bool – If a custom command was found and handled the option.


Provide new commands in settings with

CUSTOM_EVENNIA_LAUNCHER_COMMANDS = {“mycmd”: “path.to.callable”, …}

The callable will be passed any *args given on the command line and is expected to handle/validate the input correctly. Use like any other evennia command option on in the terminal/console, for example:

evennia mycmd foo bar


This launches an interactive menu.


Run the evennia launcher main program.