
                      Key is Copyright (C) 1996-1997 by
                Paul Mclachlan, Jason Crane, and George Wright
                       v0.8 alpha 20th September, 1997

This release of Key shows it in a working-stage.  It's an alpha release,
which means that I don't really think it works myself, yet. ;)  I've released
it because I'm all tied up at uni doing assignments, etc, etc, and I can see
that I won't have time to work on it at least until the end of the year.
(And maybe not then).  It seems crazy that we've gone to so much effort for
it all to be 'wasted', and so I unleash it upon the world, even in the state
it is.

Key is not for the faint of heart.  It is a _very_ powerful system, as far
as code for MUD/MOO/talkers go.  It also isn't very mature, and it doesn't
have very much documentation.  A lot of this will kind of be learn-as-you-go.

To be perfectly honest, I'm not sure it simply isn't overwhelming.  I don't
think I'd have the patience, myself, to sit down and try and work it all
out in the state it is at the moment.  I'm not trying to discourage anyone,
and I'm happy to answer any questions people have via email, but I've
taught J (snapper) and George enough to code in it, and it took them a
while to pick it up, with me standing over their shoulder to help them.

But who knows... if you like it enough... :)

The best way to learn how to use it at an 'admin' level (as opposed to at
a user level, for which there are some helpfiles, if not many), is to
get in and have a look at the setup/*.tf scripts (which create the
configuration from scratch), as well as just playing with commands like
'ref' and 'dump'.  (Which allow you to look around the system online).

if you just want to get it running:

   make sure your CLASSPATH points to key/classes
   look at and edit the bin/key script to change
     the path names you use, or whatever
   and .. run the bin/key script

If it doesn't run, check that you have at least Java version 1.1, and that
you got the classpath set up correctly.  You can always email me
(subtle@progsoc.uts.edu.au or paulm@access.com.au) if you can't get it
going.

Key isn't that easy to use, at first, and there isn't as much 'admin'
documentation as we would have liked.  (In fact, its dismal.  We don't
even have as much user documentation as we would have liked.  We're just
glad it compiles. ;)

I can give you a brief outline of how to get the initial steps up and going,
if you have any more complicated problems or issues, email me, (maybe I'll
start up a mailing list), and we can build up a list of frequently asked
questions, that might serve as documentation, at least until I finish uni
and have some time to write some. ;)

The top 'priv' is called "beyond".  If you've got beyond, you can do anything,
permissions-wise.

In order to get it, you have to be the first person online when key boots
and has to create its 'base' configuration file (config/key).  Soooo... if you
ever lose beyond, you can get it again by shutting down the program, killing
this file, booting it back up and being the first online.

Just having this priv isn't enough to let you 'do' anything, though - for that
you need to be in the appropriate ranks - you can create your own ranks
with commands in them, the information on how to do all of this is provided
in 'example' form, in the setup/ directory.  There are essentially a lot of
scripts there that set up a forest style environment.  The most basic
(and first one that you'd have to run, if you deleted all of the configuration
files) is setup/setup.tf

Initially, I've created an admin user (password 'admin'), which is linked
into all the SU levels, and so forth.  To priv yourself, boot it up, log in
as yourself as well as as admin (make sure this is the first time for you,
or you won't get beyond, see above), and, as admin, type (if your other
character were subtle):

	res subtle                     (gives them 'permission to save')
	shift #subtle /ranks/director  (the top rank on forest)
	shift #subtle /ranks/mage      (a rank which can do shutdown and sync)

As subtle, then, you could 'password' (to set your password), and 'save',
to double check that everything worked.

Not all the documentation in the doc directory is accurate, or even really
that relevant.  It's a collection of all the stuff we wrote while we were
developing the system.  A lot of it is Forest-centric, a lot of it is just
ideas that we'd like to have had time to write.  But there is some fairly
serious/interesting stuff there, and if you're even going to have a chance
at using this thing effectively, you might as well have a read.  There isn't
_that_ much. ;)

Having a look around
--------------------

There is a typescript of a quick look around Key, just so that you
can see what you're getting in for, and how to use some of the basic
'ref' (for reference, similar to cd), 'dump' (shows an object, or the
current object), and 'set'.  Take a look at 'example' in the doc directory


Compiling it
------------

Me, personally, to deal with Java, I have a classes directory off my home
directory, which I use as a kind of glorified classpath, with symlinks to
other packages where required.  I might put key in my home directory,
then, and symlink $HOME/classes/key to $HOME/key/classes/key.  To compile,
I use the 'jc' script in the key/bin directory, which will put the .class
files in the proper directory.  You can do whatever you like, but thats
how it works at the moment. 

There are some funny dependancies that you might not expect between the
different directories.  I don't have a makefile, really, but I've tried to
capture most of them in a fullcompile script.  Personally, I just "jc
*.java */*.java */*/*.java"  from the key/src directory, which does the
trick.  (If I want to compile it all, obviously) 


Shutting the damn thing down
----------------------------

There isn't a "shutdown" command as such.  Admin has a pre-created
event on him called 'shutdown' which you can use (it was created with
'instant events.Shutdown shutdown'), just like:  schedule #me/shutdown 5s 

(which will schedule a shutdown in 5 seconds).  You can also use like
'5m' for 5 minutes, '5h' for hours, and so on.  It will respond with
something like: Event 'shutdown' scheduled for Sat Sep 20, 1997 9:51:24 ( 5
seconds hence )

If you can't be bothered, type 'sync', and then 'save', and just control-C
the process. ;)

Motivations
-----------

To date, we haven't actually put key up for Forest live.  Forest is just too
large for us to do this in the state the user documentation and program is.

It probably has lots of bugs (although, none too serious, just lots of little
things), and it uses a _lot_ of memory to hold players online.  The threads
(connecting players and players) were playing up when we did try to boot it,
which, to me, means that it isn't going to stay up for a very long period
of time at the moment.

So, we're not game to use it for forest - I don't think it could really
handle 100+ people online, as we are apt to get sometimes.  That isn't to
say that it wouldn't be worth trying on a smaller talker, where you could
do cool things and a crash doesn't mean as much.  I'm certainly going to
try and boot a little 'key' talker on realm, at least to try and test it,
when I get some free time.

- Paul (subtle)

