Engine Interfaces
Note that this interface list does not currently include all the methods declared by the defclass special form. This list is just a helpful summary of the majority of the functions available in the game engine. Examples of those not included are commands and description. These are fairly obvious though.
The global variables here often have functions that maintain them, so make sure that you understand all the functions. There might be one that can do what you need.
Variable *players* Description Holds list of all active players. Used to prevent invalid scenarios, and to gain access to all players. Variable *player-commands* Description Holds a list of commands available to all players. Variable *default-command* Description If no other command matches the input request, this is always the last command it tries. This is implemented to match up with a single symbol. Variable *initial-places* Description Holds a list of initial places where the player might end up when first created. Variable *null-place* Description The location of destroyed objects in case there are any references to that object.
Function current-time Parameters NONE Description Returns the number of seconds since the game has begun. Function insert-event Parameters (delay <number>) (thunk <function>) Description Takes a thunk, which is an argumentless function, and inserts it into the event queue such that it will be executed with the delay, in seconds. The thunk operates by effect only. Function insert-immediate-event Parameters (thunk <function>) Description Takes a thunk, and places it in the event-queue such that it will be executed immediately. Function insert-first-event Parameters (delay <number>) (thunk <function>) Description This behaves in a similar manner to the insert-event function; however, this is intended for events that should exist in every game instance. Instead of being placed directly in the event queue, the thunk here is placed in a start up data structure. When the game begins, these start up thunks are placed in the event queue. Function start-time Parameters (animate <animate>) Description When creating an <animate> object, this returns the time at which that objects first plan event should be executed. Note that this is called from the initialize method during the objects creation. Function do-something Parameters (animate <animate>) Description Used by the animate-loop, defined by the initialize method in animates. This brings the animate to life. If it is a character, it executes the character's plan. If it is a player, it requests input from the player. Any effect can be done with do-something, and really ought to be to make the game interesting. In the end, a number must be returned by do-something in order to schedule another event. The number returned is the delay until the next event. If anything but a number is returned, the animate's loop dies, and the animate is no longer active in the game. Function do-command Parameters (thing <command-able>) (listener <listener>) (input <string>) Description Gets a list of commands available to the thing being commanded, and compares the input to those commands. If a suitable command is found, the command is executed according to the input. The listener is given all the messages from the command -- useful if the player is commanding something other than the player object.
Function nick-find Parameters (nickname <symbol>) (list <list>) Description Given a nickname and a list of <game-object>s, nick-find returns the game-object with the nickname supplied, #f otherwise. Function get-exit Parameters (place1 <place>) (place2 <place>) Description Returns an <exit> object between place1 and place2 if it exists, otherwise it returns #f. The exit object should be located in the exit list of place1. Function animate? Parameters (object <top>) Description Returns #t if object is an <animate>, #f otherwise. Function player? Parameters (object <top>) Description Returns #t if object is a <player>, #f otherwise. Function inanimate? Parameters (object <top>) Description Returns #t if object is an <inanimate>, #f otherwise. Function player-exists? Parameters (player <player>) Description Returns #t if player is active and in the game, #f otherwise. Function unlock? Parameters (exit <exit>) (animate <animate>) Description Returns #t if the animate is allowed to pass through the exit, #f otherwise.
Function name+nick Parameters (object <game-object>) Description Returns a string with the object's name followed by the nickname in square braces. Function describe Parameters (player <player>) (object <game-object>) Description Given an object, displays a description of the object to the player, with possible customizations focused on the player. For instance, given a place object displays to the player information about the place, including the name, description, commands for the location, possible exits, and contents. The description is omitted if the player has already visited the location. Players also keep a history of locations, so if the current location is at the head of the list, nothing is displayed to the user since the player has only finished executing a command that does not change his or her location.
Function destroy Parameters (object <game-object>) Description Takes the necessary steps to remove the object from the game, making it possible to garbage collect the object. Garbage collection is not possible if a binding to the object still exists... a very good reason for not using define for instances unless necessary. Function logoff Parameters (player <player>) Description Calls destroy to remove the player from the game, and depending on the type of the game will perform other tasks necessary in cleaning up the player object, and possibly terminate the game.
Function transfer Parameters (object <contained>) (source <container>) (target <container>) Description Removes object from the source's contents and puts it in the target's contents. Will also update object's location to target. This is used for go operations, picking up, dropping, and giving. Function get-player-input Parameters (player <player>) (prompt <string>) Description Reads input from the player, and returns a string. Function take Parameters (object <inanimate>) (source <container>) (target <animate>) Description Using transfer, will perform the take action, telling the player the information as necessary. Function drop Parameters (object <inanimate>) (source <animate>) (target <container>) Description Using transfer, will perform the drop action, telling the player the information as necessary.. Function give Parameters (object <inanimate>) (source <animate>) (target <animate>) Description Using transfer, will perform the give action, telling the player the information as necessary. Function steal Parameters (object <inanimate>) (source <animate>) (target <animate>) Description Using transfer, will perform the steal action, telling only the information to the thief as necessary.
Function say Parameters (animate <animate>) (message <string>) Description Prints to every listener in the same room as animate that animate has said the message. Function emote Parameters (animate <animate>) (emotion <string>) Description Prints to every listener in the same room as animate that the animate has experienced the emote emotion. Emotes are typically messages like *Joe Laughs*. Function shout Parameters (animate <animate>) (message <string>) Description Prints to every listener in the same room as animate and every player in the game that animate has shouted the message. Function tell Parameters (listener <listener>) (message <string>) Description Prints message to the listener. Function greet Parameters (player <player>) Description Prints the greeting to the player at the beginning of the game. Function message Parameters (listener <listener>) (originator <animate>) (type <symbol>) (message <string>) Description Used by many of the other functions to convey different types of messages to different listeners. The listener is the one hearing the message, the originator is the one saying the message, and message is what everyone sees. The type is usually #f, meaning that the message should just be printed. Looking at the code, you can see that it can also be 'emote, 'tell, etc. This can be particularly useful if you are trying to build a plan for a listener that reacts to different messages. Function place-message Parameters (place <place>) (originator <animate>) (type <symbol>) (message <string>) Description This takes the message and sends it to every animate in the place. Good for creating messages indicating status of the surroundings. An alternative form for the originator is a list of animates. In this form, the first animate in the list is considered the originator, and no other animate in the list receives the message.
Function add-command Parameters (object <game-object>) (namespace <symbol>) specs (description <string>) (function <function>) Description Takes the specs (see command system summary for details), description (what the help command will print), and the function (which executes the command), creates a command and adds it to the object's command list. Commands are inspected in the order they are added to the object, which is described in the command system summary. The namespace is a symbol is used for narrowing the number of commands displayed in a help query. Function add-player-command Parameters (namespace <symbol>) specs (description <string>) (function <function>) Description Takes the three parameters, creates a command and adds it to the list of commands available to all players. Commands are inspected in the order they are added. The namespace is a symbol is used for narrowing the number of commands displayed in a help query. Function directed-connect Parameters (place1 <place>) (place2 <place>) Description Creates a generic exit object without any locks from place1 to place2. Alternatively, an <exit> object can be passed in for the second argument as an explicit connection. Function connect Parameters (place1 <place>) (place2 <place>) Description Creates a generic exit object without any locks in both directions.
