MULTIPLAYER.rst

This document is mainly concerned with getting a multi-player Imaginary server up and running, to the point where you can edit the code and see things change. If you are just getting started with writing code for Imaginary, you probably want to see the far simpler getting-started guide in README.rst.

Some familiarity with Python, Twisted, Nevow, Axiom, and Mantissa are all helpful, but we will try to make sure they aren't really required just to get started.

While we have tried to make it possible to get a taste of what is possible here, if you want to make any serious progress, you will want to join the IRC channel "#imaginary" on chat.freenode.net and start asking questions. If you are curious about what needs to be done, have a look here:

https://github.com/twisted/imaginary/issues

The first step in configuring a new installation of Imaginary will normally be creating a new Mantissa database. The following instructions assume you have already set up installed Twisted, all of Imaginary's dependencies, and Imaginary itself.

First run the following command:

$ axiomatic mantissa

And answer the prompts appropriately. Please take note of the new password you enter for the "admin" user, as you will need it in a few steps.

This should create a directory called "mantissa.axiom", containing the server for a web interface that will allow you to install "offerings" (plugins for Mantissa, in this case, Imaginary), create users, and grant them privileges. You can start this webserver with the following command: (the -n option will run it in the foreground on the current terminal)

$ axiomatic start -n

You should now be able to access this server at http://localhost:8080 in your web browser.

Click the "Sign In" link in the upper right hand corner, and log in as "admin" with the password you chose previously while configuring Mantissa.

If you logged in successfully, you should now be presented with a list of "offerings" that can be installed. Click on "Imaginary" to install it.

Next, mouse over the "Admin" menu at the upper left of the screen and then click on the "Products" sub-menu.

In the "Installable Powerups" section, check the box corresponding to "Imaginary Game". Then click the "Installable Powerups" button below. You will hopefully be presented with a green confirmation dialog to confirm your success. This creates a "product" which can be given to users.

Mouse over the "Admin" menu again and click "Local Users". You should be presented with a page including a table of users - probably with only the "admin" user in it. Click the word "Endow" in the "Actions" column of that table, then select the product with "ImaginaryApp" in it (again, this is probably the only one presented) and click the "Installproducton admin@localhost" button. You should again be presented with a green confirmation dialog. Hooray!

Ideally, you will now be able to ssh into your Imaginary server. In a new terminal, ssh to localhost on the Mantissa server's SSH port (by default, this is 8022). For example:

$ ssh -p 8022 admin@localhost@localhost

Note the odd username/host specifier - "admin@localhost" is the user, and the last "localhost" specifies the host to connect to.

Log in with the same password you used to log in to the web interface. You should be presented with a screen including several options, one of which is "imaginary". Use tab to highlight that option (the highlighted option should appear red), then hit enter to select it.

At the Imaginary character prompt, choose to create a new character; enter a new username (e.g. not "admin"). You will then join the game as that new character.

Once in the game, you should see a row of dashes along the bottom of the display. To confirm your new MUDness, try typing "look" and hit enter; You should see some indication of the generic place that you are in, the available exits, and other players in the area, though initially you won't see much more than "[The Place]".

You can enter "actions" for a list of actions, and use "help" along with one of them ("help dig") for specific information on how to use them. You can even log in via other telnet windows, create additional accounts, and interact with your initial user (for example, beating them to death with "hit").

When you've tired of self-abuse, you can stop your Imaginary server by hitting control-c in the terminal where you ran "axiomatic start -n".