XidusCore v0.42, by Jeremy Weatherford <xidus@xidus.net>

---------[ INSTALLATION

-------[ Quick Start (if you know what you're doing)

Compile and install Genesis, then compile the core using coldcc:
 $ bin/coldcc -c

Start genesis:
 $ bin/genesis

Connect to port 4242 locally.  To change the startup port number, run
'bin/genesis --4343' instead, for instance.

Connect and create a new character as described, and follow the
in-game instructions.

See 'Getting Started' below for more detailed installation instructions.

-------[ Introduction

XidusCore is a core for Genesis, written in ColdC.  See
http://www.cold.org for more info about either of these things.
XidusCore's homepage is at http://cold.xidus.net.  XidusCore's author
is Jeremy Weatherford, xidus@xidus.net.

XidusCore was written from scratch to be a small, usable, and
extendible core.  It's not neccessarily a minimal codebase, although
the bells and whistles will be kept to a minimum.  It's designed to be
a good place for people to start if they're interested in learning
more about ColdC, starting to write their own core, or just interested
in trying things out.  XidusCore is, at least at the present time, not
neccessarily suitable for use as an active game, at least not without
a lot of work.  The eventual goal is to produce a mature, stable
codebase which can be used as an active game server, however.

-------[ Version

This is the initial release of XidusCore, and is version 0.42.  It's
intended to be functional, but should be considered beta software.  I
haven't thought much about a license for the code, but it'll be
something free.  In the meantime, just ask me if you want to use it
for something commercial, and please let me know if you find it
useful.  :)

-------[ Security

XidusCore does provide a consistent login interface, and by disabling
character creation (which is the default, type 'enable creation' to
enable it), it should be safe from the net at large.  There is a
debug_port feature which is not currently password protected, but it's
up to you whether to enable this or not.

XidusCore does not yet have a consistent permissions system, so any
user with a character can, quite possibly, do anything with the
system.  This includes using any of the built-in natives, as almost
none of them are bound at this point.  It is recommended that you do
not allow anyone you do not trust to have a character yet.

-------[ Getting Started

First, you need to download and install Genesis, which is available
from http://www.cold.org.  There should be adequate information in
that package on installing -- if not, feel free to contact me for more
info, at xidus@xidus.net.

Once you have Genesis compiled succesfully, you can either put the
binaries coldcc and genesis in your path, or link them as shown here:

Make a 'bin' subdirectory under the XidusCore subdirectory.  Also make
a 'logs' subdirectory while you're at it.  Change to the new bin
subdirectory of the XidusCore directory and softlink the binaries
coldcc and genesis here.  The commands should be something like:
$ pwd
/home/xidus/cold/XidusCore
$ mkdir bin
$ mkdir logs
$ cd bin
$ pwd
/home/xidus/cold/XidusCore/bin
$ ln -s ~/dl/Genesis-1.1.8-STABLE/src/genesis .
$ ln -s ~/dl/Genesis-1.1.8-STABLE/src/coldcc .

Now, cd .. to go back to the XidusCore directory, and type bin/coldcc
to compile the XidusCore textdump into binary format.  You should get
a few messages, but no errors.

XidusCore uses port 4242 by default.  If you don't want to change
this, start the server now by typing 'bin/genesis'.  If you need to
change its port number, start the server by typing 'bin/genesis
--4343', for instance, substituting the desired port number, of
course.  The server should now be running on port 4242, or the port
you specified.  Note that you only need to specify the port number
once -- it will be stored in-DB after that.

Connect to it immediately and create a new character according to the
directions.  The first character created will have full admin
privileges on the system.  After that, character creation will be
disabled until you re-enable it.

If the server doesn't seem to be running, try looking at logs/db.log
for info on why.  If you're stuck, try sending all the output you can
gather to me at xidus@xidus.net.  :)

-------[ Contact and legalese

XidusCore is written by Jeremy Weatherford, xidus@xidus.net.  Feedback
of any kind is good -- this is a work in progress, and I'm basically
always poking around with new ways to approach things.

Legal stuff? There is none... use, abuse, bend, fold, mutilate, and
spindle to your heart's delight. If you find any of this stuff useful,
then good for you.  I'd love to hear about it.  :)

Do remember that this is beta software, and as such, should not be
expected to perform quite as reliably as a fully-released package.
Not yet, anyway.  :)


---------[ DOCUMENTATION

-------[ Command summaries

-----[ Introduction

The permissions system in XidusCore is basically nonexistent at this
point.  There's a little bit of structure to support one, but it's
pretty inconsistent at this point.  Basically, assume there are no
permissions.

Each user has a set of parsers that affects which commands they have
immediate access to -- that can be used to restrict permissions in a
coarse way.

-----[ Ordinary

Commands on $person_if (users and NPCS) and $user_if (users):
look, teleport, say, emote, who, quit, paste, passwd, think

look [<object>]: look around, or look at something
teleport <destination> or teleport <object> [to] [<location>]: move
  yourself magically
say <what>: Say something that those in the same room can hear
emote <what>: act/pose/emote something that those in the room can hear
who: list connected users
quit: disconnect
paste: paste a block of text to the room, end with a single period
passwd: change your password
think <what>: repeat something to yourself

-----[ Building

Commands on $builder_if:
dig, open, describe, name

dig <direction> [<name>]: open an exit leading in a given direction,
  create a room with the given name there, and create an exit back if
  the direction was a recognizable compass direction

open <direction> [to] <destination>: open an exit to the given room
open <direction> [to] last: open an exit to the room you were last in

describe <object> [as] <text>: Set a description (seen by look)

name <real object> <new name>: Set a 'real name' ($real.name, not
  objname) for an object

-----[ Exploring (of code)

Commands on $explorer_if: (read-only access to code)
methods, vars, kids, parents, tree, show, list, ex, info

methods <object>: List methods on the object, with one-line descs
vars <object>: Not implemented, will list variables and values
kids <object>: Shows children of the object
parents <object>: Shows parents of the object
tree [<object>]: Shows an ascii-art inheritance tree optionally
  starting at an object, else starting at $root
show <definer>.<variable> [on] [<object>]: Show the value of a
  variable
list <object>.<method>: List the code of a method
ex <object>: Show variables and methods on an object
info <object>.<method>: Show info about a method, including desc and
  args info

-----[ Coding

Commands on $coder_if: (write-all access to code)
editvar, edit, addmethod, eval, delmethod, addvar, addcmd,
delcmd, create, parent, setflag, copymeth, movemeth, delvar, objdesc,
descmeth, walktree

editvar <object>.<variable> [on] [<object>]: edits the contents of a
  variable using the MCP-like thing described in the Editing section
  below.
edit <object>.<method>: edits the contents of a method using the
  MCP-like thing described in the Editing section below.
addmethod <object>.<method>: creates a new method
delmethod <object>.<method>: deletes the given method
addcmd <name> [to] <cmd_if>: adds a new command to the given child of
  $cmd_ifs
delcmd <name> [from] <cmd_if>: delete a command (and its code!)
addvar <object>.<variable>: adds a variable
delvar <object>.<variable>: deletes a variable
eval [as] [<object>] <code>: evaluates code as yourself or an object
create <name> [child of] [<parent>]: creates an object parented as
  specified, or parented to $root otherwise
parent <object> [to] <newparents>: set the -complete- list of object's
  parents to the new list given
setflag <flag> [on] <object>: sets a flag ($root.flags) on an object
copymeth <from>.<method> [to] <to>[.][<newmethod>]: copy a method
movemeth <from>.<method> [to] <to>.<newmethod>: move a method's code
objdesc <obj> [as] <text>: set an obj's one-liner 'purpose' desc
descmeth <object>.<method> [as] <text>: set a method's one-liner desc
walktree [as] [<object>] [from] [<object>] [do] <code>: recursive
  evaluation helper

-----[ Admin

Commands on $admin_if: (administrators)
shutdown, nuke, allow, can, enable, disable

shutdown: shutdown the server immediately
nuke <user>: completely delete a user
allow <user> [to] <what>: not implemented, part of perms system
can <user> [do] <what>: not implemented, part of perms system
enable <what> and disable <what>: toggle flags


-------[ Subsystems in XidusCore

-----[ The Parser

I'm quite proud of the arg parser in XidusCore.  It's turned out to be
very flexible, allowing natural language commands, at least to some
degree.  The main routine is $cmd_ifs.parse_args.  New template
logic can be added in $cmd_ifs.parse_arg.  The general idea is that
a command on an interface object (ie, parented to $cmd_ifs) will
pass the string it got to parse_args, and expect a list of various
types of items, according to the template it provides.  For instance,
from $explorer_if.ex_cmd:

[obj] = (> .parse_args(user, args, "ex <object>") <);

Note the propagate expression (><) to throw any exceptions out to the
parser.  parse_args will throw things like ~usage and ~nomatch which
are handled by the parser.  You'll usually want them to wind up in the
parser.

Also note the 'scatter' expression -- the value on the left of the
equal sign is in square brackets, "[obj]", because parse_args always
returns a list, even when you only have a single variable in your
template.  Moving right along, the two arguments to every command
function, user and args, are passed to the parse_args function,
followed by a string template which I hope is self-explanatory, and
optionally, any flags for the arg parser.

The ex command requires an argument, and with the template as
specified, "ex <object>", it'll always get that argument.  If a user
types "ex" by itself, parse_args throws a ~usage exception with a
handy copy of the template.  The parser catches the ~usage exception
and displays a nice message like "Syntax: ex <object>".  If the user
types "ex nonexistentobject", on the other hand, then parse_args will
be unhappy because the argument it was given isn't an object.  You
see, the word "<object>" in the template indicates an argument
location, but also specifies its type.  parse_args will throw a
~nomatch with a useful error message, and the parser will catch that
and display a friendly "Object nonexistentobject not found."  So, you
see, most of the parsing logic for simple commands can be done in
parse_args, as long as you parent your command interface to $cmd_ifs.

There are many more complex examples using parse_args, as just about
every command in XidusCore uses parse_args for its parsing.  Here's
one to chew on, though, from $explorer_if.show_cmd, the command to
show a variable's value.

[def, v, obj] = (> .parse_args(user, args, "show <definer:object>.<variable:symbol> [on] [<object>]", ['places]) <);

We've got three possible arguments here.  This template immediately
shows off one new feature in the word "<definer:object>".  The second
word, object, defines the type of the argument.  The first word is
what the user sees when the parser is displaying the syntax message.
Thus, we get "Syntax: show <definer>.<variable> [on] [<object>]" from
the parser instead of the more cryptic "Syntax: show <object>.<symbol>
[on] [<object>]".  Be sure to notice the period between the arguments
-- it's considered a literal, and must be found in the template.

Moving on in this template, we find the word "[on]".  The square
brackets indicate an optional argument.  The word 'on' being a
literal, it's not usually included in the argument output (see 'lits
for a way to change that), so it's just optional grammatic glue.  Next
word is "[<object>]", which should make a fair amount of sense now --
it's an optional argument.  The parser is fairly smart about these
things, although it will probably still have a problem with optional
arguments followed by required arguments.  An optional argument isn't
usually included in the list returned, but you'll notice that the
'places flag was passed, which asks for placeholders.  Because of
this, if the last arg isn't found, the error ~optnf is returned (not
thrown) in the place of the third argument.  Reading down one line in
$explorer_if.show_cmd, we find the statement 'obj ?= def', which uses
the definer as the target object if no object was given.  (~optnf will
be a false value)

There are a few more interesting things about the parser -- I'll write
some more examples here eventually.


-----[ Editing

I've been able to edit code workably using TinyFugue as a client with
a simple macro to launch an editor locally.  XidusCore is currently
set up to work this way.  It uses something vaguely resembling MCP for
the messages.  I couldn't get it to play nice with tkMOO or anything
else actually using MCP, though.  The messages work like this:

(server -> client upon an edit or editvar command)
#$# edit name: $debug_port.tmp upload: edit write $debug_port.tmp
multiline
content
.
(the content terminates with the period on a line by itself)

The client just needs to allow the user to edit the content, then run
the command given in the upload: field of the initial request, follow
it by the new content, and a single period on a line by itself to
terminate.  If you get this working happily with any other client,
please let me know.  (xidus@xidus.net)  The relevant code is on
$coder_if.edit_cmd and $coder_if.editwrite_snarfer

The TinyFugue macro I use is named localedit.tfrc in the XidusCore
tarball.  Just change the neccessary directory names, then add it to
the end of your .tfrc.

-----[ .....

This is a work in progress, more documentation is forthcoming,
hopefully in some sort of in-game format.  It'll also be cleaned up, I
promise.  The rambling style above is not the best for documentation,
and I know that.  I hope it'll help you out anyway, though.