Getting Started

This will help you download, install and start Evennia for the first time.

Note: You don’t need to make anything visible to the ’net in order to run and test out Evennia. Apart from downloading and updating you don’t even need an internet connection until you feel ready to share your game with the world.

Quick start

For the impatient. If you have trouble with a step, you should jump on to the more detailed instructions for your platform.

  1. Install Python, GIT and python-virtualenv. Start a Console/Terminal.
  2. cd to some place you want to do your development (like a folder /home/anna/muddev/ on Linux or a folder in your personal user directory on Windows).
  3. virtualenv pyenv
  4. source pyenv/bin/activate (Linux, Mac), pyenv\Scripts\activate (Windows)
  5. git clone https://github.com/evennia/evennia.git
  6. pip install -e evennia
  7. evennia --init mygame
  8. cd mygame
  9. evennia migrate
  10. evennia start (make sure to make a superuser when asked) Evennia should now be running and you can connect to it by pointing a web browser to http://localhost:8000 or a MUD telnet client to localhost:4000 (use 127.0.0.1 if your OS does not recognize localhost).

Requirements

Any system with Python support should work.

  • Linux/Unix
  • Windows (2000, XP, Vista, Win7, Win8, Win10)
  • Mac OSX (>=10.5 recommended)
  • Python (v2.7+, not supporting v3.x).
  • Pip. Python installer, included with Python 2.7.9+ but can also be installed separately.
  • virtualenv for making isolated Python environments. Installed with pip install virtualenv.
  • Linux/Mac users will need the gcc and python-dev packages or equivalent.
  • Windows users need MS Visual C++ and pypiwin32.
  • GIT - version control software for getting and updating Evennia itself
  • Mac users can use the git-osx-installer or the MacPorts version.
  • Twisted (v16.0+)
  • ZopeInterface (v3.0+) - usually included in Twisted packages
  • Windows users need pypiwin32.
  • Windows users need MS Visual C++.
  • Django (v1.9+, be warned that latest dev version is usually untested with Evennia)
  • Pillow (Python Image Library). This is often distributed with Django. As a backup you can also try the older PIL, on which Pillow is based.

Linux install

If you run into any issues during the installation and first start, please check out `Linux troubleshooting`_. Also, one of our devs made a Linux install video, check it out!

For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and install the dependencies:

sudo apt-get install python python-dev git python-pip python-virtualenv gcc

You should make sure to not be root after this step, running as root is a security risk. If your Linux distro defaults to Python3 you need to install Python2.7+ explicitly (Evennia does not support Python3 at this time). Next create a folder where you want to do all your Evennia development and start a virtualenv inside:

mkdir muddev
cd muddev
# if your linux defaults to python2:
virtualenv pyenv
# if your linux defaults to python3:
virtualenv -p /usr/bin/python2.7 pyenv

Using a virtualenv is good Python practice. A new folder pyenv will appear. This folder will hold a self-contained setup of Python packages without interfering with default Python packages on your system or the Linux distro lagging behind on Python package versions. Activate the virtual environment:

source pyenv/bin/activate

The text (pyenv) should appear next to your prompt to show the virtual environment is active. You need to activate the virtualenv like this every time you start a new terminal to get access to the Evennia install. Next we fetch Evennia itself:

git clone https://github.com/evennia/evennia.git
pip install -e evennia

A new folder evennia will appear containing the Evennia library. If install failed with any issues, see `Linux Troubleshooting`_. Next we’ll start our new game, here called “mygame”, which will create yet another new folder where you will be creating your new game:

evennia --init mygame

You can configure Evennia extensively, for example for using a different database. For now we’ll just stick to the defaults though.

cd mygame
evennia migrate   # (make sure to create a superuser when asked. Email is optional.)
evennia start

Your game should now be running! Open a web browser at http://localhost:8000 or point a telnet client to localhost:4000 and log in with the user you created. Check out where to go next.

Mac install

The Evennia server is a terminal program. Open the terminal e.g. from Applications->Utilities->Terminal. Here is an introduction to the Mac terminal if you are unsure how it works. If you run into any issues during the installation, please check out `Mac troubleshooting`_.

  • Python should already be installed. (This discusses how you may upgrade it). Remember that uou need Python2.7.x, not Python3+!
  • GIT can be obtained with git-osx-installer or via MacPorts as described here.
  • If your Python version is lower than 2.7.9 you will need to install pip manually with sudo easy_install pip.
  • Fetch virtualenv with pip install virtualenv.
  • If you run into issues with installing Twisted later you may need to install gcc and the python headers.

Next create a folder where you want to do all your Evennia development and start a virtualenv inside:

mkdir muddev
cd muddev
# if your mac defaults to python2:
virtualenv pyenv
# if your mac defaults to python3:
virtualenv -p /path/to/your/python2.7 pyenv

Using a virtualenv is a good Python practice. A new folder pyenv will appear. This folder will hold a self-contained setup of Python packages without interfering with default Python packages on your system. Activate the virtual environment:

source pyenv/bin/activate

The text (pyenv) should appear next to your prompt to show the virtual environment is active. You need to activate the virtualenv like this every time you start a new terminal to get access to the Evennia install. Next we fetch Evennia itself:

git clone https://github.com/evennia/evennia.git
pip install -e evennia

If install failed with any issues, see `Mac Troubleshooting`_. Next we’ll start our new game. We’ll call it “mygame” here. This creates a new folder where you will be creating your new game:

evennia --init mygame

You can configure Evennia extensively, for example to use a different database. We’ll use the defaults here.

cd mygame
evennia migrate   (make sure to create a superuser when asked. Email is optional.)
evennia start

Your game should now be running! Open a web browser at http://localhost:8000 or point a telnet client to localhost:4000 and log in with the user you created. Check out where to go next.

Windows install

If you run into any issues during the installation, please check out `Windows troubleshooting`_.

The Evennia server itself is a command line program. In the Windows launch menu, start All Programs -> Accessories -> command prompt and you will get the Windows command line interface. Here is one of many tutorials on using the Windows command line if you are unfamiliar with it.

  • Install Python from the Python homepage. You will need to be a Windows Administrator to install packages. You want Python version 2.7+ (Evennia does not support Python3), ideally 2.7.9 or later. You should usually get the 64bit-version if your system supports it. When installing, make sure to check-mark all install options, especially the one about making Python available on the path (you may have to scroll to see it). This allows you to just write python in any console without first finding where the python program actually sits on your hard drive.
  • You need to also get GIT and install it. You can use the default install options but when you get asked to “Adjust your PATH environment”, you should select the second option “Use Git from the Windows Command Prompt”, which gives you more freedom as to where you can use the program.
  • Finally you should install the Microsoft Visual C++ compiler for Python as well as the pypiwin32 python headers.

First create a new folder for all your Evennia development (let’s call it muddev), then go to it in the console and start a virtualenv inside:

cd path\to\muddev
pip install virtualenv
# if your setup defaults to Python2.x (most likely)
virtualenv pyenv
# if your setup defaults to Python3+
virtualenv -p C:\Python27\python.exe pyenv

Using a virtualenv is a standard Python practice. A new folder pyenv will appear. This folder will hold a self-contained setup of Python packages without interfering with default Python packages on your system. Activate the virtual environment by running the script:

# If you are using a standard command prompt, you can use the following
.\pyenv\scripts\activate
# If you are using a PS Shell, Git Bash, or other, you can use the following
pyenv/scripts/activate.bat

The text (pyenv) should appear next to your prompt to show the virtual environment is active. You need to activate the virtualenv like this every time you start a new terminal to get access to the Evennia install. Next we fetch Evennia itself:

git clone https://github.com/evennia/evennia.git
pip install -e evennia

If everything went well, Evennia is installed. If the install failed with any issues, see `Windows Troubleshooting`_. Next we’ll start our new game, we’ll call it “mygame” here. This creates a new folder where you will be creating your new game:

evennia --init mygame

You can configure Evennia extensively, for example for using a different database. We’ll use the defaults here.

cd mygame
evennia migrate   (make sure to create a superuser when asked. Email is optional.)
evennia start

Your game should now be running! Open a web browser at http://localhost:8000 or point a telnet client to localhost:4000 and log in with the user you created. Check out where to go next.

Where to next

Welcome to Evennia! Your new game is, once you logged in, fully functioning but empty. To get started, follow the instructions in the Limbo room to create Evennia’s tutorial world - it’s a small solo quest to explore.

Once you get back to Limbo (if you get stuck in the tutorial quest you can do @tel #2 to jump to Limbo), a good idea is to learn how to start, stop and reload the Evennia server. After that, why not experiment with creating some new items and build some new rooms out from Limbo.

From here on, you could move on to do one of our introductory tutorials or simply dive headlong into Evennia’s comprehensive manual. If you have any questions, you can always ask in the developer chat #evennia on irc.freenode.net or by posting to the Evennia forums. Finally, if you are itching to help out or support Evennia (awesome!) have an issue to report or a feature to request, see here.

Enjoy your stay!

Troubleshooting

If you have issues with installing or starting Evennia for the first time, check the section for your operating system below. If you have an issue not covered here, please report it so it can be fixed or a workaround found!

Linux troubleshooting

  • If you get an error when installing Evennia (especially with lines mentioning failing to include Python.h) then try sudo apt-get install python-setuptools. Once installed, run pip install -e evennia again.
  • Under some not-updated Linux distributions you may run into errors with a too-old setuptools or missing functools. If so, update your environment with pip install --upgrade pip wheel setuptools. Then try pip install evennia again.
  • A common error on Ubuntu 16 and others is that you can’t start the server but get an error saying “Twisted requires zope.interface 3.6.0 or later: no module named zope.interface.”. This happens even though a much later version of zope.interface is clearly installed in the virtualenv (as verified with pip list). This appears to be due to a bug in the zope installer; it fails to install an empty __init__.py file. To fix this, issue the following command: touch pyenv/local/lib/python2.7/site-packages/zope/__init__.py. That creates the file and things should then work correctly henceforth.
  • One user reported a rare issue on Ubuntu 16 is an install error on installing Twisted; Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-build-vnIFTg/twisted/ with errors like distutils.errors.DistutilsError: Could not find suitable distribution for Requirement.parse('incremental>=16.10.1'). This appears possible to solve by simply updating Ubuntu with sudo apt-get update && sudo apt-get dist-upgrade.
  • Users of Fedora (notably Fedora 24) has reported a gcc error saying the directory /usr/lib/rpm/redhat/redhat-hardened-cc1 is missing, despite gcc itself being installed. The confirmed work-around seems to be to install the redhat-rpm-config package with e.g. sudo dnf install redhat-rpm-config.

Mac troubleshooting

  • Some mac users have reported not being able to connect to localhost (i.e. your own computer). If so, try to connect to 127.0.0.1 instead, which is the same thing. Use port 4000 from mud clients and port 8000 from the web browser as usual.

Windows troubleshooting

  • If your MUD client cannot connect to localhost:4000, try the equivalent 127.0.0.1:4000 instead. Some MUD clients on Windows does not appear to understand the alias localhost.
  • If you run virtualenv pyenv and get a 'virtualenv' is not recognized as an internal or external command, operable program or batch file. error, you can mkdir pyenv then python -m virtualenv . as a workaround.
  • If you are using an older version of Twisted than 16.x or if you are using an older version of Evennia with the latest version of Twisted you may get an error at startup. The error is due to the Twisted executable changing names on Windows from twistd.py to twistd.exe. If you don’t want to reinstall evennia anew you can instead edit evennia\evennia\server\twistd.bat. This is a file containing a single line of text. Change the single occurrence of twistd.py to instead read twistd.exe. Save. Evennia should now start correctly.
  • Some Windows users get an error installing the Twisted ‘wheel’. A wheel is a pre-compiled binary package for Python. A common reason for this error is that you are using a 32-bit version of Python, but Twisted has not yet uploaded the latest 32-bit wheel. Easiest way to fix this is to install a slightly older Twisted version. So if, say, version 16.1 failed, install 16.0 manually with pip install twisted==16.0. If that doesn’t work either, you could also try to get a 64-bit version of Python. If so, you should deactivate the virtualenv, delete the pyenv folder and recreate it anew.