Login

Play Now:
* Browser Client
* Download Client

LPmud A Programmable Multi-User Domain by Lars Pensj| [ Edited from TeX into Ascii by Adam Beeman ] 1 General 1.1 Idea of the game LPmud is a multi user adventure game. That means that several players can be playing the game at the same time, using the same object database. It also means that the players will meet each other, and affect the game for other players. 1.2 History of LPmud In the beginning, I played a lot of Abermud and some Tinymud, and wanted to do something better, combining the two systems. I made the first version of LPmud as some kind of argument, to show that my ideas were possible. Luckily, I didn't know at that time how that would impact my near future. 1.3 Objects, files and programs The programs defining the behaviour of objects are stored in files. Every object has exactly one file defining the program, but every file may be used for more than one object. When an object that is not loaded is referenced, it will automatically be compiled and loaded. More than one instance of an object can be created using the function clone_object(). [See clone_object in the LPC reference manual]. clone_object() should not be used if only one instance of an object is wanted. Cloned objects may be configured differently after creation, hence enabling different behaviour. Chapter 2: Installation and Setup This chapter describes how to get LPmud running from scratch. It works for SUN SparcStation running SunOS 4.1.1. If you are using any other platform you may have some trouble getting the game up. We don't have time or equipment needed for porting the game to other systems. 2.1 Getting LPmud Sources [ Editor's note: Currently, the source for a full 3.0 mudlib is not available. You can choose one of two options: get the old 2.4.5 mudlib and run in compatibility mode, or begin from scratch with the mudlib.n. You could also just wait until someone decides to release a functional 3.0 mudlib. This may be a while. ] LPmud can be retrieved with anonymous FTP from host alcazar.cd.chalmers.se, IP-number 129.16.48.100. Log on as ftp, and give your email address as password. The archive holding the source can be found in `/pub/lpmud/3.0', and is called `3.0.50.tar.Z'. It is a binary file, which means that you have to set FTP in binary mode. This is how a ftp session might look: % ftp alcazar.cd.chalmers.se Connected to alcazar. 220 alcazar FTP server (Version 5.53 Sun May 27 01:43:44 MET DST 1990) ready. Name (alcazar.cd.chalmers.se:arne): ftp 331 Guest login ok, send ident as password. Password: arne@cd.stanford.edu 230 Guest login ok, access restrictions apply. ftp> cd pub/lpmud 250 CWD command successful. ftp> bin 200 Type set to I. ftp> get 3.0.50.tar.Z 200 PORT command successful. 150 Opening BINARY mode data connection for 3.0.50.tar.Z (510193 bytes). 226 Transfer complete. local: 3.0.50.tar.Z remote: 3.0.50.tar.Z 510193 bytes received in 1e-06 seconds (1.4e+06 Kbytes/s) ftp> bye 221 Goodbye. % 2.2 Contents of the Archive The archive contains all you need to set up an LPmud on your host. However you need a mudlib. You can write one yourself or get one by ftp. The software you got in this archive contains the preprocessor, communication stuff, efuns and lots of other functions needed in the game. The other major part is what we call `mudlib'. Everything accessible from within the game is in `mudlib', such as save files, log files and LPC source code. The LPC source code is the code defining what your LPmud will be like. It is the game itself, while the `game driver' is a tool for running the game. There are also some other things included in the archive, among them documentation and some useful utilities. This is what the directory structure in the archive looks like: mud | ---------------------------------------------------------- | | | | | | README bin doc lib src swap | util [ Editor's note: this is what it WILL look like, one day. Currently the source code just spills out into the current directory, making the util directory. So when you unpack 3.0.50.tar.Z, be sure to move the file into a directory called 'src' before unpacking it. The structure I use looks more like this: mud ________|__________ / | | \ mudlib bin src swap | | several subdirs util including doc You have to make these directories yourself... the main differences are the position of the doc directory, which tends to be needed from inside the mudlib. You could just use symbolic links, of course. ] This is a description of what some of the direcories are. [See File Hierarchy for information on the contents of the `lib' directory.] README A file describing where to find the documentation. bin Directory that will contain all the executables after installation. doc All the documentation as a text file, a texinfo file and a PostScript file. lib The `mudlib' directory. src The source code for the `game driver'. util Source code for some utility programs and shell scripts. swap When the game is running it creates a swap file here. 2.3 Unpacking the Source Archive When you unpack the source archive, a directory called `mud' will be created in your current directory. All the files in the archive will be put in the `mud' directory. Before unpacking the archive you should decide where in the filesystem you want to have the game and change directory to that location. [ Editor's note: As of 11/26/91, this was not true. You must create the 'mud' directory and the 'src' directory. Then, change into the 'src' directory before unpacking the source. ] The archive is a compressed tar archive. To unpack it you need one of the commands uncompress or zcat and the program tar. Here is an example of how the archive can be unpacked: [ edited for accuracy ] % cd /usr/src/games % mkdir mud % cd mud % mkdir src % mkdir bin % mkdir swap % cd src % zcat 3.0.50.tar.Z | tar xf - 2.4 Compiling the Game Driver The first thing you have to do is to configure LPmud to suit your system. Change directory to `mud/src'. Edit `config.h' and change any defines needed. They are well commented in the file, but those that it is likely that you want to change are explained here. TIME_TO_SWAP Tells how long the game driver should wait before swapping out an unused object. The time should be high if you have much memory, and low if disk space is more abundant than memory. TIME_TO_RESET Sets the intervall between calls to reset() in objects. PORTNO This is the port number that the games uses. Before setting it, you should ask your system manager what number to use. DOMAINS If this is defined you enable domains, i.e. groups of wizards can work together, with a special domain directory for each group. SWAP_FILE Should be a full path to a file used for swapping objects. It is typically set to `mud/swap' as mentioned previously. LOG_SHOUT If LOG_SHOUT is defined all shouting in the game is logged in a file, `mud/syslog/SHOUTS'. MAX_PLAYERS The maximum number of simultaneous players in the game. The more powerful system you have, the higher it should be. Next, you should edit the `Makefile' and make changes suitable for your system. These are some of the parameters that you might want to change. MALLOC There are three different versions of malloc to choose from. The `Makefile' tells the difference between them. CC What C compiler to use. BINDIR Where to put all the executables. Typically set to `mud/bin'. MUD_LIB The path to mudlib. Usually set to `mud/lib'. After editing `config.h' and `Makefile' you are ready to compile the game driver. Type: make If the compilation is completed without errors, an executable file `driver' should have been created. 2.5 Installing the Game After compiling the game driver, several files have to be installed in their proper places. If you have changed the path for MUD_LIB in the `Makefile' to something other than `mud/lib' in the directory where you extracted the software, you have to move the contents of `mud/lib' to the new location. If you have changed BINDIR in the `Makefile' or SWAP_FILE in `config.h' to be other than those that were extracted, you must make those directories in the new location. After doing that, give the command: make install Now the game driver should be installed in BINDIR. We provide a shell script that restarts the game every time it crashes or is shut down. It restarts the game at most 50 times. After that the script has to be rerun. The script is called `restart_mud' and is located in `mud/src/util'. To install it in BINDIR type: make install.restart_mud If you want the game to be restarted every time your computer is rebooted, ask your system manager to run `restart_mud' from `/etc/rc.local'. Here is an example of what to put in `/etc/rc.local'. if [ -f /usr/games/mud/bin/restart_mud ]; then /bin/su arne -c /usr/games/mud/bin/restart_mud 2>&/dev/null echo 'Starting LPmud' fi [ Editor's note: This assumes the game is run by account 'arne'. ] 2.6 Starting the Game The simplest way of starting the game is to issue the command driver that after a successfull installation resides in `bin'. That command will start the game in 3.0 mode, accepting connections on the port configured in `src/config.h'. These are the command line options that are available: -c Print a message to stdout every time a file is compiled. -d Print debug information. -e Start the game without loading any wizard or domain files. [ Editor's note: This command will start the game, but unless you redirect the output of it, it will also send error messages to the tty that the game was booted from, rather than logging the errors. I recommend you either use restart_mud, or issue the command in this form: driver >& ../mudlib/log/lpmud.log & This will send the output of the game driver (run time errors, etc.) to a log file you can check from inside the game, and background the process. ] Chapter 3: Commands Tied to Functions in Objects All commands except a very few special cases are defined by the objects. All commands have a simple basic way to be recognized. The first word of the sentence is supposed to be the verb. Every command defined is tied to a special function in an object. Commands are defined with the function add_action(), which specifies the verb to be recognised, and the name of the local function to be called [See add_action, in the LPC Reference Manual]. When a living object gives a command which matches a verb with a command defined by an object, then the corresponding function will be called in the specified object. If this function returns 0, then next command with the same verb is tried. If the function returns 1, then he search is terminated. This enables several objects to define commands with the same verbs, but still behave different if the rest of the sentence differs. For example, there might be two armours. One is named leather jacket, and one is named plate mail. Both objects will have defined a command with the verb wear. If the player now gives the command `wear jacket', then we can't know which defined command is called first. Suppose that the wear function in the plate mail is called first. It will then detect that the argument to wear is jacket, not plate mail. It would then return 0, which would enable the game driver to call the command in the leather jacket that defines the wear verb. This function would accept the command, and execute some appropriate code, followed by a return of 1. Every time an object O comes in contact with a living object L then O will be asked to define commands. 3.1 Call of clean_up() The function clean_up() is automatically called now and then. When an object is loaded, it is checked for existence of a function clean_up(). If found, a flag O_WILL_CLEAN_UP is set. If an object hasn't been used (any function called) for a certain time and O_WILL_CLEAN_UP is set, then clean_up() is called. If this function returns a non-zero value, then O_WILL_CLEAN_UP is set again (which means that clean_up() can be called again). The idea of clean_up() is that objects can self-destruct, which is much more space effective than being swapped out. It will also work for cloned objects. It can be a good idea to define a default clean_up() in the much used room.c, which will destruct the room when it is empty. If a wizard wants to save important rooms, (s)he will have to redefine clean_up(). It is of course possible to do other types of cleaning than destruction. The administrator has to define time until clean up() is called in config.h. The time should be much longer than the time to reset(). [ Editor's note: I have no idea why this is. I tend to use a fairly short clean_up( time myself, to keep memory use down. ] 4 LPC reference manual The language used to program objects is called LPC. It is syntactically modelled after C. As it is important that objects be loadable "on the fly" in a game, I chose to make it an interpreted language. If it would be compiled for real, there would be big problems of portability when moving to different machines. The security of the program is also very important. Under no circumstances should an LPC programmer crash the game by doing a mistake. That rules out standard C. Several ideas has been borrowed from object oriented languages, like inheritance. However, as performance is very important, I have not hesitated to use "impure" language constructs when needed, which will conflict with the concepts of object oriented languages. An LPC programs consists several building blocks: - inheritance specifications - preprocessor - variables - functions 4.1 Types Declaration Types can be used at four places: 1. Declaring type of global variables. 2. Declaring type of functions. 3. Declaring type of arguments to functions. 4. Declaring type of local variables to functions. Normally, the type information is completely ignored, and can be regarded purely as documentation. However, when the basic type of a function is declared, then a more strict type checking will be enforced. That means that the type of all arguments must be defined. And, the variables can only be used to store values of the declared type. The function call_other is defined to return an unkown type, as the compiler can't know the type. This value must always be casted (when strict type checking is enabled). Casting a type is done by putting the type name inside a pair of parentheses. Note that casting in LPC is not the same as casting in C. It is only used as information for the compiler, and can only be used to cast values of type unknown. This type is only returned from call_other. An example when querying the short description of an object: (string)call_other(ob, "short"); When a function is compiled with strict type testing, it can only call other functions that are defined. If they are not yet defined, prototypes can be defined. string func(int arg); Note the ';' instead of a body to the function. All arguments must be given names, but do not have to have the same names as in the real definition. All types must of course be the same. [ Editor's note: this means you can do: string func(int arg); and then later string func(int x) { /* begin actual function */ be sure to keep the number of arguements and their types consistent. ] There is currently a bug (3.0.36) that recursive calls can not be done if the function is not also defined by a prototype. That is because a function is not really defined until the whole function has been compiled. Don't rely on this behaviour, which will hopefully soon be fixed. A dangerous effect is that it is possible to redefine efun's, and let the new definition call the old before it is replaced. Such code will break sooner or later. If an efun is to be redefined to get some new enhancements, always define the new one with a new name. There are two kinds of types. Basic types, and special types. There can be at most one basic type, but any number of special types. The strict type checking is only used by the compiler, not by the runtime. Hence, it is actually possible to store a number in a string variable even when strict type checking is enabled. Why use strict type checking? It is really recommended, because the compiler will find many errors at compile time, which will save a lot of hard work. It is in general much harder to trace an error occuring at run time. I recommend, that when a wizard is having problem with an object and wants help, that he first must make all functions have declared types. The basic types can be divided in to groups. Those that are referenced by value, and those that are referenced by address. The types int and string are always representing different entities. But the type object is a pointer to an object. If a value of this type is assigned to a variable or passed as argument, they will all point to the same object. The same goes for arrays. That means that if the value of an element in an array is changed, then it can modify all other variables pointing to the same array. Changing the size of the array will always allocate a new one, though. The comparation operator, ==, will compare the actual value for the group of types above. But for arrays and objects, it will simply check if it is the same object (or array). That has the very important implication that the expression `() == ()' will always evaluate to false becaus the array construction operator-pair, ( ) always generates a new array. [ Editor's note: not sure if this bit about arrays is still true. ] 4.1.1 Basic Types int An integer 32 bit number. object Pointer to an object. An object pointer can mainly be used for two things. Either giving as argument to functions, or used for calling functions defined by that object with its specific instance of variables. string An unlimited string of characters. A lot of operators are allowed for strings, like + and [] etc. mixed This type is special, in that it is valid to use in any context. Thus, if everything was declared mixed, then the compiler would never complain. This is of course not the idea. It is really only supposed to be used when a variable really is going to contain different types of values. This should be avoided if possible. It is not good coding practice, to allow a function for example to return different types. void This type is only usable for functions. It means that the function will not return any value. The compiler will complain (when type checking is enabled) if the return value is used. 4.1.2 Arrays Arrays are declared using a '*' with a basic type. For example, declaring an array of numbers: int *arr; Use the type mixed if you want an array of arrays, or a mixed combination of types. 4.1.3 Special Types There are some special types, which can be given before the basic type. These special types can also be combined. When using special type T before an inherit statement, all symbols defined by inheritance will also get the special type T. The only special case is public-defined symbols, which can not be redefined as private in a private inheritance statement. varargs A function of this type can be called with a variable number of arguments. Otherwise, the number of arguments is checked, and can generate an error. private Can be given for both functions and variables. Functions that are private in object A can not be called through call_other from another object. And, they are not accessible to any object that inherits A. static This special type behaves different for variables and functions. It is similar to private for functions, in that they can not be called from other objects. static variables will be neither saved nor restored when calling save_object() or restore_object(). public A function defined as public will always be accessible from other objects, even if private inheritance is used. nomask All symbols defined as nomask can not be redefined by inheritance. They can still be used and accessed as usual. 4.2 Access of data and programs in other objects There is a function call_other(), that can be used to call functions in other objects. All functions can be called except those declared static or private. See Section 4.7 [Predefined Functions] for more information. There is another syntax that will do the same thing: ob->func(args); This will call function func in object ob. It is a much better looking way to do it. There has been a lot of questions why this syntax hasn't been used to allow for accessing variables in other objects. There are some good reasons for that. - It conflicts with the idea of programming in an object-oriented way. - It makes the programming less structured, as there are more dependencies. - If a variable name is changed, code can be broken. - Sometimes, you don't even want to keep the variable at all any longer. 4.3 Statements 4.3.1 If 4.3.2 Block 4.3.3 While 4.3.4 Do - While 4.3.6 Return 4.4 Expressions 4.5 Saving and Restoring Objects 4.6 Inheritance [ As yet, this is undocumented. ] 4.7 Predefined Functions There are two kinds of predefined functions: efun The functions hard coded , which are defined by the game driver. They can be redefined by a local function of the same name, which will then be used instead. lfun Functions that optionally can be defined by the objects. These functions will be called by other lfuns, and sometimes by the game driver. They will control how the object will behave in special situations. An example is get(), which if defined and returning 1, will enable the object to be picked up by players. If returning 0, then the player will get a message that says that the object can't be picked up. 4.7.1 Efuns [ What follows is a listing of most or all of the efuns. I have removed the section numbering on them, because when new functions are added, it is easier for me to put them in if I don't have to redo the numbering. ] ---- add_action void add_action(string fun, string cmd, int flag) Set up a local function fun to be called when user input matches the command cmd. Functions called by a player command will get the arguments as a string. It must then return 0 if it was the wrong command, otherwise 1. If it was the wrong command, the parser will continue searching for another command, until one returns true or give error message to player. For example, there can be a wand and a rod. Both of these objects defines add_verb("wave"). One of them will be randomly called first, and it must look at the argument, and match against "wand" or "rod" respectively. If second argument, cmd, is not given, it must be given by add_verb(). Support of add_verb() is of historical reasons. Always have add_action() called only from an init() routine. The object that defines commands must be present to the player, either being the player, being carried by the player, being the room around the player, or being an object in the same room as the player. If argument flag is 1, then only the leading characters of the command has to match the verb cmd. Never define an action that will call the function exit(), because it is a special function. [ Editor's note: I believe this is called when leaving a room. ] See also: query_verb, add_verb, lfun/init, lfun/exit. ----- add_verb void add_verb(string str) This function is connected to the add_action() function. It will set up the command str to trigger a call to the function set up by the previous call to add_action(). This function is now obsolete as the verb can be given directly with add_action(). add_verb() remains for compatibility. See also: add_action, query_verb. ----- all_inventory object *all_inventory(object ob) Returns an array of the objects contained in the inventory of ob. See also: first_inventory, next_inventory. ----- allocate allocate(int size) Allocate an array of size elements. The number of elements must be >= 0 and not bigger than a system maximum (usually 1000). See also: sizeof. ----- call_other unknown call_other(object ob, string str, mixed arg) Call function in another object with an argument. The return value is returned from the other object. See also: present, find_living. ----- call_out void call_out(string fun, int delay, mixed arg) Set up a call of function fun in this_object(). The call will take place in delay seconds, with the argument arg provided. arg can be of any type. Please note that you can't rely on `write' or `say' in the fun called since this_player() is set to 0. Use tell_object() instead. [ Editor's note: This has now been fixed. "this_player()" now carries through the call_out(). ] See also: remove_call_out, call_out_info. ----- call_out_info mixed *call_out_info() Get information about all pending call outs. An array is returned, where every item in the array consists 4 elements: 1. The object 2. The function 3. The delay to go 4. The optional argument See also: call_out, remove_call_out. ----- capitalize string capitalize(string str) Convert the first character in str to upper case, and return the new string. ----- cat int cat(string path, int start, int num) List the file found at path. It is not legal to have '..' or spaces in the path. This function is normally connected to the `cat' command that wizards have. It is also used by the `help' command. The optional arguments start and num makes is start line number, and number of lines. If they are not given, the whole file is printed from the beginning. The total number lines will not exceed a system limit, which normally is 40 lines. cat() returns number of lines read and printed if success, 0 if no such file or no lines to read. See also: ls, file_size. ----- catch mixed catch(string expr) Evaluate expr. If there is no error, 0 is returned. If there is a standard error, a string (with a leading '*') will be returned. The function throw(value) can also be used to immediately return any value, except 0. The catch() is somewhat costly, and should not be used anywhere. Rather, use it at places where an error would destroy consistency. ----- clear_bit string clear_bit(string str, int n) Return the new string where bit n is cleared in string str. Note that the old string str is not modified. See also: set_bit, test_bit. ----- clone_object object clone_object(string name) Load a new object from definition name, and give it a new unique name. Return the new object. The original used for cloning, should not be used in the game, only used for cloning. [ Editor's note: if the original copy has a locatio, you will get an error, *cloning bad object. ] See also: destruct, move_object. ----- command int command(string str) Execute str as a command given directly by the player. Any effects of the command will apply to the current object. There was a second argument, which is not supported any longer. Return value is 1 or 0, for success or failure. Return value is 0 for failure. Otherwise, a numeric value is returned, which tells the evaluation cost. Bigger number means higher cost. The evaluation cost is approximately the number of of machine code instructions executed. See also: enable_commands. ----- create_wizard string create_wizard(string name) string create_wizard(string name, string domain) In the first form, with only name given as argument, create_wizard() makes a directory for the wizard with the name name. It also creates the files `castle.c' and `workroom.c' in the new directory. The new directory is called `PLAYER_DIR/name', where PLAYER_DIR is a define in the game driver and name is the name of the wizard. The second form is used for adding a wizard to a domain, and expects the argument domain to contain the name of the domain that the wizard name is joining. The difference from the first form is that the directory is placed in `DOMAIN_DIR/domain/name', where DOMAIN_DIR is a define in the game driver, domain is the name of the domain and name is the name of the wizard. Also, a symbolic link is created in PLAYER_DIR pointing at the new directory. It returns the name of the new castle. In case of error, false is returned. ----- creator string creator(object ob) Return as a string the name of the wizard that created object ob. If the object was not created by a wizard, 0 is returned. This function is no longer supported (except in -o mode). ----- crypt string crypt(string str, string seed); Crypt the string str using two characters from seed as a seed. If seed is 0, then random seed is used. The result has the first two characters as the seed. ----- ctime string ctime(int clock) Give a nice string with current date and time, with the argument clock that is the number of seconds since 1970. See also: time. ----- destruct void destruct(object ob) Completely destroy and remove object ob. The argument can also be a string. After the call to destruct(), no global variables will exist any longer, only local, and arguments. If an object self-destructs, it will immediately terminate execution and return 0. There is one exception: If the destruct-statement is followed by a `return 1;' immediately after, then this return statement will be executed. This should NOT be used on normal objects in the game, instead use the lfun remove() in the object you want removed: `ob->remove();'. This will ensure correct update of weights, volumes etc. See also: clone_object. ----- ed void ed(string file); void ed(string file, string func); This is a funny function. It will start a local editor on an optional file. This editor is almost ed compatible. If a second argument is given, then a function with that name will be called when the user exits the editor. ----- enable_commands void enable_commands(); Enable this object to use commands normally accessible to players. This also marks the current object as living. Commands defined by `player.c' will not be accessible, of course. This function must be called if the object is supposed to interact with other players. Avoid calling this function from other places then reset(), because the command_giver will be set to the this_object(). See also: command, living. ----- environment object environment(object obj) Return the surrounding object to obj. If no argument is giving, it returns the surrounding to the current object. The object will dissapear silently without any sign. See also: find_first_inventory, this_player, this_object. ----- explode string *explode(string str, string del) Return an array of strings, created when the string str is splitted into substrings as divided by del. The str must end with del if the last part is wanted too. Example: explode(str, " ") will split the string str into an array of words as separated by spaces in the original string. The array is returned. See also: sscanf, extract. ----- export_uid int export_uid(object ob) Set the uid of object ob to this_object's effective uid. It is only possible when object ob has an effective uid of 0. See also: seteuid, getuid. ----- extract string extract(string str, int from, int to) Extract a substring from a string. Character 0 is first character. `extract(str, n)' will return a substring from characer number n to the end. `extract(str, i, j)' will return a string from character i to character j. See also: sscanf, explode. ----- file_name string file_name(object ob) Get the file name of an object. If the object is a cloned object, then it will not have any corresponding file name, but rather a new name based on the original file name. Example: `find_object(file_name(ob)) == ob' is guaranteed to be true for all objects ob. [ Editor's note: the new name, when it is a cloned object, will be the file name of the object, a #, and the object number... so, a player might be "/obj/player#38". ] ----- file_size int file_size(string file) Give the size of a file. Size -1 indicates that the file either does not exist, or that it is not readable by you. Size -2 indicates that it is a directory. See also: save_object, load_object, write_file, cat. ----- filter_objects mixed *filter_objects(mixed *arr, string fun, object ob, mixed extra) Returns an array holding the items of arr filtered through `ob->fun()'. The function fun in ob is called for each element in arr with that element as parameter. A second parameter extra is sent in each call if given. If `ob->fun(arr[.index.], extra)' returns 1 the element is included in the returned array. If arr is not an array, then 0 will be returned. ----- find_call_out int find_call_out(string func) Find the first call out due to be executed for function func, and return the time left. If it is not found, then return -1. See also: efun/call_out, efun/remove_call_out. ----- find_living object find_living(string str) Find first `living' object that answers to the id str (by calling local id()). A living object is an object that has done enable_commands(). The object must have set a name with set_living_name(). There is a special hash table that speeds up the search for living objects. See also: find_player, enable_commands, set_living_name. [ Editor's note: it seems actually to find the name set with set_living_name() rather than the id. These are usually set to the same string though. ] ----- find_object object find_object(string str) Find an object with the file name str. If the file isn't loaded, it will not be found. ----- find_player object find_player(string str) Find a player with the name str. The string must be lowercase. Players are found even if they are invisible or link dead. Monsters are not found. This function uses the name that was set by set_living_name(). This is done automatically in the player object. See also: find_living, set_living_name. ----- first_inventory object first_inventory(mixed ob) Get the first object in the inventory of ob, where ob is either an object or the file name of an object. See also: next_inventory, all_inventory. ----- function_exists string function_exists(string str, object ob) Return the file name of the object that defines the function str in object ob. The returned value can be other than `file_name(ob)' if the function is defined by an inherited object. 0 is returned if the function was not defined. ----- getuid string getuid(object ob) Get the name of the wizard that is set to the user of this object. That name is also the name used in the wizlist. See also: geteuid, seteuid, and export_euid. ----- geteuid string geteuid(object ob) Get the effective user identification of the object ob. The effective user id is often used to determine permissions. See also: getuid, seteuid, and export_euid. ----- implode string implode(mixed *arr, string del) Concatenate all strings found in array arr, with the string del between each element. Only strings are used from the array. See also: explode. ----- input_to void input_to(string fun, int flag) Enable next line of user input to be sent to the local function fun as an argument. The input line will not be parsed. Note that fun is not called immediately. It will not be called until the current execution has terminated, and the player has given a new command. If input_to() is called more than once in the same execution, only the first call has any effect. If optional argument flag is non-zero, the line given by the player will not be echoed, and is not seen if snooped. See also: call_other, sscanf. ----- interactive int interactive(object ob) Return non-zero if ob is an interactive player. 0 will be returned if he is link dead. See also: query_ip_number, query_ip_name. ----- intp int intp(mixed arg) Return 1 if arg is an integer number. See also: stringp, pointerp, objectp. ----- living int living(object ob) Return true if ob is a living object (that is, enable_commands() has been called by ob). ----- log_file void log_file(string file, string message) Append a message to a log file. All log files are in the directory `lib/log'. `/log' is automatically prepended to the file name. See also: write_file. ----- lower_case string lower_case(string str) Convert the all characters in str to lower case, and return the new string. See also: capitalize. ----- ls void ls(string path) List files in an optional path. It is not allowed to use '.' or space in the path. This function is normally connected to the `ls' command. This function is also obsolete in native mode. See also: cat, get_dir. ----- map_array mixed *map_array(mixed *arr, string fun, object ob, mixed extra) Returns an array holding the items of arr mapped through `ob->fun()'. The function fun in ob is called for each element in arr with that element as parameter. A second parameter extra is sent in each call if given. Principal function: `foreach (index) arr[index] = ob->fun(arr[index],extra);' The value returned by `ob->fun(arr[.index.], extra)' replaces the existing element in the array. If arr is not an array, then 0 will be returned. ----- member_array int member_array(mixed item, mixed *arr) Returns the index of the first occurence of item in array arr. If not found, then -1 is returned. ----- mkdir int mkdir(string path) Make a directory named path. Return 1 for success and 0 for failure. See also: rmdir, rm ----- move_object void move_object(mixed item, mixed dest) Move the object item to the object dest. Currently, both arguments can be strings. Usually, transfer() should be used instead of move_object(). In native mode, move_object() can only be called from the object being moved. See also: transfer, first_inventory, this_object, this_player. ----- next_inventory object next_inventory(object ob) Get next object in the same inventory as ob. Warning: If the object ob is moved by move_object(), then next_inventory() will return an object from the new inventory. See also: first_inventory, all_inventory. ----- notify_fail void notify_fail(string str) Store str as the error message given instead of the default message `What ?'. If notify_fail() is called more than once, only the last call of will be used. The idea of this function is to give better error messages instead of simply `What ?'. ----- objectp int objectp(mixed arg) Return 1 if arg is an object. See also: intp, stringp, pointerp. ----- parse_command int parse_command(string str, object source, string pattern, var1, var2 ...) Parses commands given in str against the pattern in pattern and returns 1 if it matches. source is either an object or an array of objects. This is essentially a 'hotted' sscanf and it has a similar syntax, although parse_command works on word basis where sscanf works on character basis. str Given command. source source is either an object or an array of objects. array array holding the accessible objects object object from which to recurse and create the list of accessible objects, normally ob = environment(this_player()) pattern Parse pattern as list of words and formats: word obligatory text (One word) [word] optional text (One word) / Alternative marker %o Single item, object %l Single living object %s Any text (multiple words) %w Any word %p Preposition %i Any items %d Number 0- or tx(0-99) Example string: " 'get' / 'take' %i " Items as in %o and %i be can on many forms. Some examples: apple, two apples, twentyfirst apple apples, all apples, all green apples, all green ones varN This is the list of result variables as in sscanf. One variable is needed for each %_ The return types of different %_ are: %o Returns an object %l Returns an object %s Returns a string of words %w Returns a string of one word %p Can on entry hold a list of word in array or an empty variable Returns: if empty variable: a string if array: array[0]=matched word %i Returns a special array on the form: [0] = (int) given numeric prefix =0: all or a pluralform given >0: numeral given: two, three, four... <0: order given: second, third ... [1..n] (object) Objectpointers A list of the POSSIBLE objects that can match the given %i. No choosing of third or such. %d Returns a number Example: a=parse_command("take apple",environment(this_player()), " 'get' / 'take' %i ", items); [ Editor's note: That example didn't help much, did it? ] ----- people void people() A function that will list all interactive players, and some info about them. This function is normally connected to the people command, that wizards have. THIS FUNCTION IS OBSOLETE. LOOK AT users() INSTEAD. ----- pointerp int pointerp(mixed arg) Return 1 if arg is a string. See also: intp, stringp, objectp. ----- present object present(mixed str, object ob) If an object that identifies to the name str is present, then return it. str can also be an object, in which case the test is much faster and easier. The object is searched for in the inventory of the current object, and in the inventory of the environment of the current object. A second optional argument ob is the enviroment where the search for the str is done. Normally this_player() is a good environment. See also: move_object, environment. ----- previous_object object previous_object() Returns an object pointer to the object that did a call_other() to the current object, if any. There is one exception, and that is doing call_other() to this_object(), which will not change the value of previous_object(). See also: call_other. ----- query_idle int query_idle(object ob) Query how many seconds idle a player object has been. This will generate an error if called on a non-interactive object. ----- query_ip_name string query_ip_name(object ob) Give the ip-name for player ob. An asynchronous process `hname' is used to find out this name in parallell. If there are any failures to find the ip-name, then the ip-number is returned instead. See also: query_ip_number. ----- query_ip_number string query_ip_number(object ob) Give the ip-number for player ob. See also: query_ip_name. ----- query_verb string query_verb() Give the name of the current command, or 0 if not executing from a command. This enables add_action() of several commands to the same function. See also: add_action. ----- random int random(int n) Return a number in the random range [0 .. n-1]. ----- regexp string *regexp(string *list, string pattern); Match the pattern pattern against all strings in list, and return a new array with all strings that matched. ----- remove_call_out int remove_call_out(string fun) Remove next pending call out for function fun in this object. The time left is returned. -1 is returned if there were no call out pending to this function. See also: call_out, call_out_info. ----- rename int rename(string from, string to) The efun rename will move `from' to the new name `to'. If `from' is a file, then `to' may be either a file or a directory. If `from' is a directory, then `to' has to be a directory. If `to' exists and is a directory, then `from' will be placed in that directory and keep its original name. It is only possible to change name of a directory within a directory on machines running System V, i.e it is not possible to move it to another directory. It is not possible to move a directory across filesystems on any system. On successful completion rename will return 0. If any error occurs 1 is returned. ----- restore_object int restore_object(string name) Restore values of variables for current object from file name. It is illegal to have '.' or spaces in the name. Return true if success. Variables that has the type modifer `static' will not be saved. Example: `static int xxx;'. If inheritance is used, then it might be possible that a variable will exist with the same name in more than one place. When restoring, only one of these variables will be restored if encountered in the save file. A good practice is to have verbose and unique names on non-static variables, which also will make it easier to read or patch the save file manually. See also: save_object. ----- rm int rm(string file) Remove file file. Returns 0 for failure and 1 for success. See also: mkdir, rmdir. ----- rmdir void rmdir(string dir) Remove directory dir. See also: rm, mkdir. ----- save_object void save_object(string name) Save values of variables of this object in the file name. It is illegal to have '.' or space in the field name. Wizards that call this function can only save to files in their own directories. Object pointers are stored as the number '0'. Variables that has the type modifier 'static' will not be saved. Example: `static int xxx;'. See also: restore_object. ----- say void say(string str) void say(string str, object obj) Send a message str to all players in the same object (room). This function is also used by the `say' command. If the message depends on the reciever an array of two messages or a message containing words intended for 'value by function call' can be used. If a second argument obj is specified, messages is sent to all except obj. If obj is not an object, but an array of objects, all those objects are excluded, they do not get the message. This commands behaves differently if called from a heart_beat(), or otherwise. When called from a heart_beat(), the message will reach all players in the same environment of the object that calls say(). See also: write, shout, tell. ----- set_bit string set_bit(string str, int n) Return the new string where bit n is set in string str. Note that the old string str is not modified. The max value of n is limited. Ask the administrator if you want to know the maximum value. The new string will automatically be extended if needed. Bits are packed 6 per byte in printable strings. See also: clear_bit, test_bit. ----- set_heart_beat int set_heart_beat(int flag) Enable or disable heart beat. If the heart beat is not needed for the moment, then done disable it. This will reduce system overhead. Return true for success, and false for failure. Specifically, it will fail if the heart beat function has been disabled, which it will be if there is a run time error in it. See also: lfun/heart_beat. ----- set_light int set_light(int n) An object is by default dark. It can be set to not dark by calling `set_light(1)'. The environment will the also get this light. The returned value is the total number of lights in this room. Note that the value of the argument is added to the light of the current argument! ----- set_living_name void set_living_name(string name) Set a living name on an object that must be living. When this is done, the object can be found with find_living(). An object can only have one name that can be searched for with find_living(). See also: find_living, find_player. ----- seteuid int seteuid(string str) Set effective uid to str. It is not possible to set it to any string. It can always be set to getuid(), the creator of the file for this object or 0. When this value is 0, then current objects uid can be changed by export_uid(), and only then. But, when the value is 0, no objects can be loaded or cloned by this object. See also: export_uid, getuid. ----- shout void shout(string str) Send a string str to all players. This function is also used by the sampshout command. [ Editor's note: This function is not to be used lightly, as many find it highly annoying. ] See also: write, tell_object, say. ----- sizeof int sizeof(mixed arr) Return the number of arguments of an array arr. If arr is not an array, then '0' is returned. See also: allocate. ----- slice_array mixed *slice_array(mixed *arr, int from, int to) Returns an array that is a slice of the array arr from the index from to the index to. Indexes are numbered beginning with 0. If arr is not an array or indexes are outside the limits of arr, then 0 will be returned. Note also that you can use the operator `+' on arrays. THIS IS NOW OBSOLETE. YOU CAN NOW RETURN RANGES OF AN ARRAY. ----- sscanf int sscanf(string str, string fmt, mixed var1, mixed var2 ...) Parse a string str using the format fmt. fmt can contain strings separated by "%d" and "%s". Every "%d" and "%s" corresponds to one of var1, var2... "%d" will give a number, and "%s" will give a string. The number of matched "%d" and "%s" is returned. See also: extract, explode. ----- stringp int stringp(mixed arg) Return 1 if arg is a string. See also: intp, pointerp, objectp. ----- tell_object void tell_object(object ob, string str) Send a message str to object ob. If it is an interactive object (a player), then the message will go to him, otherwise it will go to the local function catch_tell(). See also: write, shout, say. ----- tell_room void tell_room(mixed ob, string str) Send a message str to object all objects in the room ob. ob can also be the name of the room (string). If the message depends on the reciever an array of two messages or a message containing words intended for 'value by function call' can be used. See also: write, shout, say, tell_object. ----- test_bit int test_bit(string str, int n) Return 0 or 1 of bit n was set in string str. See also: set_bit, clear_bit. ----- this_object object this_object() Return the object pointer of this object. This is not to be confused with the internal name of an object, which is used by the id() function. See also: this_player. ----- this_player object this_player() Return the object representing the current player. See also: this_object. ----- time int time() Return number of seconds since 1970. See also: ctime. ----- trace int trace(int traceflags) Sets the trace flags and returns the old trace flags. When tracing is on a lot of information is printed during execution. The trace bits are: 1 Trace all function calls to lfuns. 2 Trace all calls to call_other. 4 Trace all function returns. 8 Print arguments at function calls and return values. 16 Print all executed stack machine instructions (produces a lot of output!). 32 Enable trace in heart beat functions. 64 Trace calls to apply. 128 Show object name in tracing. ----- traceprefix string traceprefix(string prefix) If the the traceprefix is set (i.e. not 0) tracing will only occur in objects having a name with the set prefix. ----- unique_array mixed unique_array(object *obarr, string separator) Groups objects together for which the separator function returns the same value. obarr should be an array of objects, other types are ignored. The separator function is called only once in each object in obarr. The return value is an array of arrays of objects on the form: ({ (-Same1:1, Same1:2, Same1:3, .... Same1:N "), (-Same2:1, Same2:2, Same2:3, .... Same2:N "), (-Same3:1, Same3:2, Same3:3, .... Same3:N "), .... .... (-SameM:1, SameM:2, SameM:3, .... SameM:N "), }) ----- users object *users() Return an array of objects, containing all interactive players. ----- write void write(mixed str) Write a message str to current player. str can also be a number, which will be translated to a string. See also: say, tell_object, shout. ----- write_file int write_file(string file, string str) Append the string str into the file file. Returns 0 or 1 for failure or success. See also: file_size, cat, log_file. ----- 4.7.2 Lfuns ----- move int move(object dest) Move the object to the object dest. All kinds of tests are done, and a number is returned specifying the result: 0: Success. 1: To heavy for destination. 2: Can't be dropped. 3: Can't take it out of it's container. 4: The object can't be inserted into bags etc. 5: The destination doesn't allow insertions of objects. 6: The object can't be picked up. If an object is transfered to a newly created object, make sure that the new object first is moved to it's destination. ----- Shadow object shadow(object ob, int flag) If flag is 1, then current object will shadow ob. If flag is 0, then either 0 will be returned, or the object that is the shadow for ob. An object that defines the funtion query_prevent_shadow() to return 1 can't be shadowed, and the shadow() function will return 0 instead of ob. If an object A shadows an object B, then all call_other() to B will be redirected to A. If object A has not defined the function, then the call will be passed on to B. There is only one object that can call functions in B with ncall_other(), and that is A. Not even object B can call_other() itself. All normal (internal) function calls inside B will however remain internal to B. There are two ways to remove the shadow. Either destruct it, or the object that was shadowed. In the latter case, the shadow will also be destructed automatically. The result is that it is possible to hide an object behind another one, but everything can be totally transparent. ----- 4.8 Compilation Errors [ Editors's note: he didn't do anything here. ] ----- 4.9 Simulated efuns There is a mechanism to simulate efuns. All simulated efuns have to be defined in a special file (which can be anywhere). The function 'string get_simul_efun()' has to be defined in master.c to return the name of this file, as well as loading it. If this function returns 0 or is non-existing, then no automatic simulation of efuns will take place. When compiling an object and a function call is found that has not been defined locally, then it is either an efun or an undefined function. If this function is defined in the file of simulated efuns, then there will be a call_other set up to this function. That means that the function will behave as if it was an efun. The type result of the call_other does not have to be casted, but will automatically be set by the compiler. This file of simulated efuns are examined by the game driver at startup of the game. All functions and the types of them are stored then to speed up later references. This means that it is possible to modify this file and reload it. But, changing the number of functions or the type definitions of them will not affect the compiler. The idea of these simulated efuns are several. One is that it is now possible to do major changes (and even removals) of efuns, to be replaced by a simulated efun. A function declared as static will never be called automatically. Chapter 5: The LPC Implementation The language is defined by two files. `lex.c' defines the lexical elemements and takes care of preprocessor directives. `lang.y' defines the grammar. [ note: unfinised. ] 5.1 The Virtual Stack Machine [ note: also unfinished ] 5.2 How to Add Your Own Functions All predefined functions callable by the object must return exactly one result on the stack, even if they are defined as void functions. The compiler assumes that there always is one resulting value. The functions that returns the void value, might as well return anything, as it won't be used (or at least is undefined). That means that I usually return the first argument, which speeds things up as I don't have to pop and push unnecessarily. Many 'stack instructions' exists only to be called by the compiler. Like 'pop', which obviously must not return a value on the stack. But, all those instructions are only generated explicitely by the compiler, which knows what it does. If you want to add a new function of you own, you will have to change: - lang.y: Define a new name 'F_XXX'. Add it last in the list of '%token', because the Makefile has not been instructed to recompile every file depending on the order of the F_ definitions. - lex.c: Add a line to 'predefs', with information about the instruction. Functions that only allow a constant number of arguments are best, as the compiler always knows how many arguments there is, and won't generated code information about that. - interpret.c: Add a case statement in eval_instruction(). If the types of the arguments were specified, and only one type allowed, then you will not have to check the types, but can assume they are correct. If different types are allowed, then they will have to be checked. Also, if the number of arguments are constant, then you can assume they are correct. Otherwise, the variable num_var will tell you the actual number of arguments. [ Well, that's all for today, kids... I realize that there's still a lot to be done as far as writing documentation here... I can only hope that more will be written and shared. If you should write anything that fills in the empty spaces, please send me a copy, at adam@dogstar.colorado.edu --Adam / Buddha ]