XidusCore v0.42, by Jeremy Weatherford ---------[ 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 []: look around, or look at something teleport or teleport [to] []: move yourself magically say : Say something that those in the same room can hear emote : 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 : repeat something to yourself -----[ Building Commands on $builder_if: dig, open, describe, name dig []: 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 [to] : open an exit to the given room open [to] last: open an exit to the room you were last in describe [as] : Set a description (seen by look) 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 : List methods on the object, with one-line descs vars : Not implemented, will list variables and values kids : Shows children of the object parents : Shows parents of the object tree []: Shows an ascii-art inheritance tree optionally starting at an object, else starting at $root show . [on] []: Show the value of a variable list .: List the code of a method ex : Show variables and methods on an object info .: 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 . [on] []: edits the contents of a variable using the MCP-like thing described in the Editing section below. edit .: edits the contents of a method using the MCP-like thing described in the Editing section below. addmethod .: creates a new method delmethod .: deletes the given method addcmd [to] : adds a new command to the given child of $cmd_ifs delcmd [from] : delete a command (and its code!) addvar .: adds a variable delvar .: deletes a variable eval [as] [] : evaluates code as yourself or an object create [child of] []: creates an object parented as specified, or parented to $root otherwise parent [to] : set the -complete- list of object's parents to the new list given setflag [on] : sets a flag ($root.flags) on an object copymeth . [to] [.][]: copy a method movemeth . [to] .: move a method's code objdesc [as] : set an obj's one-liner 'purpose' desc descmeth . [as] : set a method's one-liner desc walktree [as] [] [from] [] [do] : recursive evaluation helper -----[ Admin Commands on $admin_if: (administrators) shutdown, nuke, allow, can, enable, disable shutdown: shutdown the server immediately nuke : completely delete a user allow [to] : not implemented, part of perms system can [do] : not implemented, part of perms system enable and disable : 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 ") <); 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 ", 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 ". 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 "" 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 . [on] []", ['places]) <); We've got three possible arguments here. This template immediately shows off one new feature in the word "". 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 . [on] []" from the parser instead of the more cryptic "Syntax: show . [on] []". 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 "[]", 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.