Installation¶
Important
If you are converting an existing game from a previous Evennia version, you will need to upgrade.
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 or use docker. Some users have also experimented with installing Evennia on Android.
If you are converting an existing game, please follow the upgrade instructions.
Requirements¶
Evennia requires Python 3.10, 3.11 or 3.12 (recommended). Any OS that supports Python should work.
Windows: In the installer, make sure to select
add python to path
. If you have multiple versions of Python installed, usepy
command instead ofpython
to have Windows automatically use the latest.
Don’t install Evennia as administrator or superuser.
If you run into trouble, see installation troubleshooting.
Install with pip
¶
Important
You are recommended to setup a light-weight Python virtualenv to install Evennia in. Using a virtualenv is standard practice in Python and allows you to install what you want in isolation from other programs. The virtualenv system is a part of Python and will make your life easier!
You re recommended to setup a light-weight Python virtualenv first.
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python installed—and after activating your virtualenv if you are using one—install Evennia with:
pip install evennia
Optional: If you use a contrib that warns you that it needs additional packages, you can install all extra dependencies with:
pip install evennia[extra]
To update Evennia later, do the following:
pip install --upgrade evennia
Note
Windows users only -
You now must run python -m evennia
once. This should permanently make the evennia
command available in your environment.
Once installed, make sure the evennia
command works. Use evennia -h
for usage help. If you are using a virtualenv, make sure it is active whenever you need to use the evennia
command later.
Initialize a New Game¶
We will create a new “game dir” in which to create your game. Here, and in the rest of the Evennia documentation, we refer to this game dir as mygame
, but you should, of course, name your game whatever you like. To create the new mygame
folder—or whatever you choose—in your current location:
evennia --init mygame
The resultant folder contains all the empty templates and default settings needed to start the Evennia server.
Start the New Game¶
First, create the default database (Sqlite3):
cd mygame
evennia migrate
The resulting database file is created in mygame/server/evennia.db3
. If you ever want to start from a fresh database, just delete this file and re-run the evennia migrate
command.
Next, start the Evennia server with:
evennia start
When prompted, enter a username and password for the in-game “god” or “superuser.” Providing an email address is optional.
You can also automate creation of the superuser.
If all went well, your new Evennia server is now up and running! To play your new—albeit empty—game, point a legacy MUD/telnet client to localhost:4000
or a web browser to http://localhost:4001. You may log in as a new account or use the superuser account you created above.
Restarting and Stopping¶
You can restart the server (without disconnecting players) by issuing:
evennia restart
And, to do a full stop and restart (with disconnecting players) use:
evennia reboot
A full stop of the server (use evennia start
to restart) is achieved with:
evennia stop
See the Server start-stop-reload documentation page for details.
View Server Logs¶
Log files are located in mygame/server/logs
. You can tail the logging in real-time with:
evennia --log
or just:
evennia -l
Press Ctrl-C
(Cmd-C
for Mac) to stop viewing the live log.
You may also begin viewing the real-time log immediately by adding -l/--log
to evennia
commands, such as when starting the server:
evennia start -l
Server Configuration¶
Your server’s configuration file is mygame/server/conf/settings.py
. It’s empty by default. Copy and paste only the settings you want/need from the default settings file to your server’s settings.py
. See the Settings documentation for more information before configuring your server at this time.
Register with the Evennia Game Index (optional)¶
To let the world know that you are working on a new Evennia-based game, you may register your server with the Evennia game index by issuing:
evennia connections
Then, just follow the prompts. You don’t have to be open for players to do this — simply mark your game as closed and “pre-alpha.”
See here for more instructions and please check out the index beforehand to make sure you don’t pick a game name that is already taken — be nice!
Next Steps¶
You are good to go!
Next, why not head over to the Starting Tutorial to learn how to begin making your new game!