What are instances?
-------------------

Instances are separate muds that run from the same Dead Souls
installation directory, but that communicate with each other.

The reason to have separate muds is to be able to test code
on a test mud, without affecting what is happening on the
other mud.

The reason to have them communicate is that the MU in MUD
stands for "Multi User" and it's nice to have more users 
communicating rather than fewer.

What instances let you do, for example, is have a "build/dev"
mud running on, say, port 8888, and a "player mud" running
on port 6666. Creators can chat with people on the player
mud while developing on the dev mud. But if they screw something
up big-time, the folks on the player mud are somewhat isolated from
catastrophe. Creators also can't mess with players on the other
mud, nor give them cheat items and such...because they're
"physically" isolated. Only communication goes back and forth.


Do I need to use instances?
---------------------------

Very very very few people will have use for this. Instances
are largely something that is useful to me, Cratylus, in my
project. If you don't immediately understand the point of
instances and go "YES! EXACTLY WHAT I NEED!" then you can
just stop reading now and forget about them.


What should I know in general?
------------------------------

- Instances use a concept of a "global" instance and client
instances. The global instance is the first instance: the mud
you installed. Instances you create must be created from the
global instance. 

- Client instances don't speak to each other, only to the global 
instance.

- Don't fiddle with ENABLE_INSTANCES in config.*. This setting
is meant to be manipulated by the instconfig command only. You
should leave that define alone in the global instance, and
leave it alone also in the client instances.


How do I get it going on Linux?
-------------------------------

To get a second instance of your mud running if the
new port is 8888 and the instance name is "Foo":

- Get the mud running the normal way. Create an admin char, etc.
- Once it's up, login as an administrator.
- Uncomment the instances line in /secure/cfg/preload.cfg
- Type: instconfig create Foo 8888
- Copy /secure/cfg/mudos.8888.cfg into bin/
- Go into bin/ and type: ./driver ./mudos.8888.cfg
- Ta-daa!


How do I get it going on Microsoft Windows?
-------------------------------------------

To get a second instance of your mud running if the
new port is 9999 and the instance name is "Bar":

- Get the mud running the normal way. Create an admin char, etc.
- Once it's up, login as an administrator.
- Uncomment the instances line in /secure/cfg/preload.cfg
- Type: instconfig create Bar 9999
- Copy lib\secure\cfg\runmud_9999.bat into your mud's top-level
  install directory (the same place you'll find runmud.bat)
- Go into your mud's top-level install directory and double-
  click on runmud_9999.bat
- Ta-daa!


Warnings
--------

- Instances are a somewhat advanced feature. If you're new to
Dead Souls, you should concentrate on basics. If you're a newbie
and have problems dealing with instances, it will be very very
difficult for me to extract from you the information I need
to help you, so you'll need to be very rigorous in reporting
problems: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

- I don't know what happens if you set up an instance with the
same port number as the global instance. If you actually do this,
please keep it to yourself. I'd rather not know.

- The instance communication protocol is quite primitive and
only allows for instances to communicate with the global instance.

- You can't create a character with the same name on another
instance. This is for security reasons. If you need to have a
character with the same name on instance foo, you'll need to
copy the user file. for example:

cp testyguy.o testyguy.8888.o

Note that whatever privileges are in effect for testyguy on the
global instance will be in effect in the client instance, since
all instances use the same groups.cfg file. You are very much
copying the same player to the new instance, not making a "new"
player.

- If you have the slightest concern that instances pose a security
risk, do not use them. In fact, *don't* use them, unless you grok
the code completely. For the most part I'm including this in the
distribution as a convenience and favor to me, because i am awesome
and I deserve it, so don't be surprised if it doesn't suit you,
and please understand what you're reporting if you do want to
report a problem.

