Getting Started


(This document is modified from evennia's Getting Started. We only made a few changes.)

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

Quick start

For you who are extremely impatient, here's the gist of getting a vanilla Muddery install running.
  1. Download and install Python and GIT. Start a Console/Terminal
  2. pip install virtualenv (may need to be root/admin)
  3. cd to some place to put your virtualenv
  4. virtualenv pyenv
  5. source pyenv/bin/activate (Linux, Mac), pyenv\Scripts\activate (Windows)
  6. cd to some place to put muddery
  7. git clone https://github.com/muddery/muddery.git or
    git clone git@github.com:muddery/muddery.git
  8. cd muddery
  9. pip install -e .
  10. cd to some place to put your game
  11. muddery --init mygame
  12. cd mygame
  13. muddery -i start (make sure to make a superuser when asked) Muddery should now be running and you can open a webclient by pointing your web browser to http://localhost:8000/webclient.

Prerequisites

As far as operating systems go, any system with Python support should work.
  • Linux/Unix
  • Windows (2000, XP, Vista, Win7, Win8, Win10)
  • Mac OSX (>=10.5 recommended)

Need to be installed manually (details below):
  • 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.
  • GIT - version control software for getting and updating Muddery itself

Installed automatically:
  • Twisted (v12.0+)
  • Django (v1.8+, be warned that latest dev version is usually untested with Muddery)
    • 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.

Step 1: Installing pre-requisites

Generally, you only need to "manually" download and install Python and GIT, the rest is handled by Python's installers.

Linux
Most Linux systems already have Python installed out of the box. Starting with Python 2.7.9 and later, pip, the python install manager, is packaged with Python. If your Python version is lower than 2.7.9 you need to install pip separately. In Debian-derived systems (like Ubuntu, Mint etc) this will work (as root):
apt-get install python git python-pip
If you don't have root access, these are standard packages you should easily be able to request your sysadmin to install for you. If you later get errors with a missing Python.h when installing Pillow, you should apt-get install python-dev as well. If you plan on using mysql as your database, you should apt-get install python-mysqldb as well.

If you get an error compiling twisted on a line trying to include Python.h then try apt-get install python-setuptools python-dev.

We will henceforth use pip to install the remaining python packages we need. Go to a directory where you want to do your python development:
cd /path/to/my/pythondevel/
pip install virtualenv
virtualenv pyenv
Note: If your computer has Python3 configured as default Python interpreter, you need to install Python2.7+ as well, and make sure virtualenv uses it with the -p flag; for example virtualenv -p /usr/bin/python2.7 pyenv.

This will first download and install the virtualenv program and then use it to create a folder we choose to call pyenv for this example. This folder will contain 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 (use deactivate to turn it off). We need to activate the virtual environment like this every time we start a new terminal if we want to have access to the Muddery-related environment. We don't have to be "inside" the pyenv folder though, as long as the environment is active we can do everything else without caring about the pyenv folder at all. So now go to a place where you want a folder muddery to be created and download Muddery itself:
cd <path/where/installing/muddery>
git clone https://github.com/muddery/muddery.git
If you have ssh keys set up in github you might want to use this instead:
git clone git@github.com:muddery/muddery.git

Henceforth you just stand in the muddery directory and use git pull to get the latest updates. Next we install Muddery itself:
cd muddery
pip install -e .
Note the period (.) at the end! The period means that we should install the package from the current directory. The -e flag installs Muddery via linking so that it immediately updates when you update the git repository.

Muddery and all its dependencies are now installed.

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 -e . again.

MacOSX
Users of recent MacOSX have Python 2.7 installed from the onset (this discusses how you may upgrade it). GIT can be obtained with git-osx-installeror otherwise via MacPorts as described here.

If your Python version is lower than 2.7.9 you will need to install pip manually:
sudo easy_install pip

From there on, use pip to get virtualenv and set things up the same way as described for Linux above.

Windows
Windows users should first and foremost recognize that the Muddery server is run from the command line, something which some might not be familiar with (based on the questions we have received). In the Windows launch menu, just start All Programs -> Accessories -> command prompt and you will get the Windows command line interface. There are plenty of online tutorials on using the Windows command line, one example is found here.

Install Python from the Python homepage here. You will need to be a Windows Administrator to install packages. You want Python version 2.7+ (Muddery does not support Python3), ideally 2.7.9 or later. When installing, make sure to checkmark all install options, especially the one about making Python available on the path (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.

Next cd to a place where you want to set up your Python development. If you installed Python 2.7.9 or later, the pip program will be available to you (otherwise it can be downloaded separately with easy_install pip as Administrator in a Console).
cd path\to\my\pythondev
pip install virtualenv
virtualenv pyenv
Note: If your computer has Python3 configured as default Python interpreter, you need to install Python2.7+ as well, and make sure virtualenv uses it with the -p flag; for example virtualenv -p C:\Python27\python.exe pyenv.

A new folder pyenv will be created in your current directory. This is where we will install all our Python packages. We need to activate this "virtual environment" so that Python and pip knows to install things here:
pyenv\Scripts\activate

If the prompt changes to show (pyenv) then the virtual environment is active (you can turn it off with the single command deactivate later if you want). We must activate pyenv like this every time we start a new Console in order to have access to the Python environment. Once active we don't have to care about the pyenv folder itself though - we can put our other files wherever we want. So, with the virtual environment active, cd somewhere you want to install Muddery and run:
git clone https://github.com/muddery/muddery.git
If you have ssh keys set up in github you might want to use this instead:
git clone git@github.com:muddery/muddery.git

A new folder muddery appeared. In the future, just stand in this folder and do git pull to get the latest updates. Now we will use pip to install all of Muddery's dependencies.
cd muddery
pip install -e .
Note the period (.) at the end! The period means that we should install the package from the current directory. The -e flag installs Muddery via linking so that it immediately updates when you update the git repository.

Muddery and all its dependencies are now installed. If you don't have a compiler installed (most Windows users don't) you might get a warning about "unoptimized" modules with links to installing the Visual C++ compiler. This is optional, it is currently unknown if these "unoptimized" modules have any bearing on performance.

Step 2: Setting up your game

You have now installed the Muddery library. As long as we are inside the virtual environment where Muddery is installed, you will now have access to the muddery command in the terminal. Now cd to a place where you want to create your new game folder. Avoid storing your game inside the muddery folder to keep the two separate. You can name your game whatever you want, for now we will call it "mygame".
muddery --init mygame
A new folder mygame will appear and you will get a informative text echoed to you. The mygame folder (or whatever you chose to name it) is where you will create everything unique to your game.

The server settings file is created for you as mygame/server/conf/settings.py. If you want to customize Muddery's database settings you can do this now. If you are not sure you don't need to change anything, Muddery will start with sane defaults.

If you use:
muddery --init mygame example
A simple example will be created. example is the name of a game template. Our website's demo game is created by this template too.

Step 3: Starting and Stopping the Server

To start the server, make sure you're in your mygame directory.
cd mygame
Then run
muddery -i start
The -i flag means that the server starts in interactive mode, as a foreground process. You will see debug/log messages directly in the terminal window instead of logging them to a file. This is useful to easily check everything works as it should.

You should be asked to create a superuser, make sure to do so. The superuser you register becomes your superuser (owner) account in the game. You will be asked for email address and password. The email address does not have to exist (Muddery does not check it by default).

After entering the superuser information, the server and portal will start for the first time. Muddery will quickly run some first-time configurations (notably pre-create an in-game Character with the same name as your superuser), restart once and then be running.

To stop Muddery later, do:
muddery stop

Step 4: Connecting to the server

The Muddery server is now up and running. If the defaults are not changed, Muddery will start its own Twisted-based web server on port 8000.

Point your web browser to http://localhost:8000/webclient, and you can connect directly to the game by use of our web client.

Go to http://localhost:8000/admin/worlddata/ and login as administer, you can edit the game through web. When you finish your edit, click the button Apply To Game, the server will restart and you will see your game updated according to your modifications.