CAOS Documentation - Creatures Engine 2.286 (netbabel 148)


Agents

ABBA (integer)
Returns the absolute base for the current agent/part. Returns -1 if an invalid part. The absolute base is the value passed into NEW: SIMP and so on, it is different from the BASE.

ALPH (command) alpha_value (integer) yesOrNo (integer)
The agent will be drawn alpha blended against the background by the given value - from 256 for invisible to 0 for completely solid. For compound agents set the PART to affect a particular part or to -1 to affect all parts. The second parameter switches alpha blending on (1) or off (0). Alpha graphics are drawn much slower, so use sparingly and turn it off completely rather than using an intensity value of 0 or 256. At the moment alpha channels only work on compressed, non-mirrored, non-zoomed sprites.

ANIM (command) pose_list (byte-string)
Specify a list of POSEs such as [1 2 3] to animate the current agent/part. Put 255 at the end to continually loop. The first number after the 255 is an index into the animation string where the looping restarts from - this defaults to 0 if not specified. e.g. [0 1 2 10 11 12 255 3] would loop just the 10, 11, 12 section.

ANMS (command) anim_string (string)
This is like ANIM, only it reads the poses from a string such as "3 4 5 255". Use this when you need to dynamically construct animations. Use ANIM in general as it is quicker to execute, although they are the same speed once the animation is underway.

ATTR (command) attributes (integer)
Set attributes of target. Sum the values in the Attribute Flags table to get the attribute value to pass into this command.

ATTR (integer)
Return attributes of target.

BASE (command) index (integer)
Set the base image for this agent or part. The index is relative to the first_image specified in the NEW: command. Future POSE/ANIM commands and any ANIM in progress are relative to this new base.

BASE (integer)
Returns the BASE image for the current agent/part. Returns -1 if an invalid part.

BHVR (command) permissions (integer)
Sets the creature permissions for target. Sum the entries in the Creature Permissions table to get the value to use.

BHVR (integer)
Returns the creature permissions for the target agent.

CALL (command) event_no (integer) param_1 (anything) param_2 (anything)
Calls a subroutine script on the owner with the specified event number. When that script finishes the current script is resumed. No variables are shared between the two scripts so any return values must go through OVs. The called script starts in the same INST state as the calling script, however, it may use SLOW or INST to override this initial state. In addition, when the script returns to the calling script, the INST state is reset to what it was before the CALL command, so CALL preserves INSTness in the calling script. So if the caller script is in an INST then the called script will inherit that, any change in the called script to cancel this (such as OVER, WAIT, SLOW etc) will only affect the called script... when execution returns to the caller script it will still be in whatever state it was in before.

CARR (agent)
Returns the the agent currently holding the target, or NULL if there is none.

CATA (integer)
Returns the target's category. This either depends on its classifier as described in CATI, or is its own individual override set with CATO.

CATI (integer) family (integer) genus (integer) species (integer)
Return the category id for the given classifier. The catalogue tag "Agent Classifiers" specifies these, and you can have more than 40. They are tested in order until the first match is found. -1 is always returned if none match. Agents can override their classifier category with CATO.

CATO (command) category (integer)
Change the target's category to the one specified. The default is -1 which means the category is based on classifier and the catalogue as described in CATI. See also CATX and CATA.

CATX (string) category_id (integer)
Returns the name of the given category. For example, "toy" or "bad bug". The catalogue tag "Agent Categories" stores these. If the id is out of range, CATX returns an empty string.

CLAC (integer)
This returns the CLAC action of the TARG object. If the TARG is in CLIK mode, then the return value is -2. Otherwise it is the CLAC action.

CLIK (integer) which_value (integer)
This returns the CLIK action of the TARG object. If the object is in CLAC mode, then it returns -2, else the return values are as follows:
0 -> Current click action number (1,2,3)
1 -> First CLIK action.
2 -> Second CLIK action.
3 -> Third CLIK action

CORE (command) topY (float) bottomY (float) leftX (float) rightX (float)
Sets the bounding box of the physical core of the object TARG. May be set to smaller (or larger) than the sprite's rectangle.

DCOR (command) core_on (integer)
Debug command to show the physical core of the TARG agent graphically.

DISQ (float) other (agent)
Returns the square of the distance between the centre points of the target agent, and the other agent. It is quicker to compare this square against a squared constant directly, or if you need the actual distance use SQRT.

DROP (command)
Force the TARG to drop what it is carrying. this will try to find a safe place for the agent to fall.

DSEE (command) can_see_on (integer)
Debug command to show all the agents which can be seen by any creature.

ENUM (command) family (integer) genus (integer) species (integer)
Iterate through each agent which conforms to the given classification, setting TARG to point to each valid agent in turn. family, genus and/or species can be zero to act as wildcards. NEXT terminates the block of code which is executed with each TARG. After an ENUM, TARG is set to OWNR.

ESEE (command) family (integer) genus (integer) species (integer)
As ENUM, except only enumerates through agents which OWNR can see. An agent can see another if it is within RNGE, its PERM allows it to see through all intervening walls, and for creatures ATTR Invisible isn't set. See also STAR and SEEE. In install scripts, when there is no OWNR, TARG is used instead.

ETCH (command) family (integer) genus (integer) species (integer)
As ENUM, except only enumerates through agents which OWNR is touching. Agents are said to be touching if their bounding rectangles overlap. See also TTAR. In install scripts, when there is no OWNR, TARG is used instead.

FLTX (float)
This returns the X position of the TARG object's floating vector.

FLTY (float)
This returns the Y position of the TARG object's floating vector.

FMLY (integer)
Returns family of target. See also GNUS, SPCS.

FRAT (command) FrameRate (integer)
This command sets the frame rate on the TARG agent. If it is a compound agent, then the part affected can be set with the PART command. Valid rates are from 1 to 255. 1 is Normal rate, 2 is half speed etc...

FROM (variable)
If we're processing a message, this is the OWNR who sent the message. NULL if the message was sent from an injected script or an install script. If the message was sent over the network using NET: WRIT, then this contains the user id of the sender, as a string.

GAIT (command) gait_number (integer)
Specifies the current gait for a creature. The gaits are genetically defined. It sets the gait of the creature agent stored in TARG.

GALL (command) sprite_file (string) first_image (integer)
Changes the gallery (sprite file) used by an agent. This works for simple and compound agents (using the current PART). The current POSE is kept the same in both galleries.

GALL (string)
Returns the gallery (sprite file) used by an agent. This works for simple and compound agents (using the current PART).

GNUS (integer)
Returns genus of target. See also FMLY, SPCS.

HAND (command) name_for_the_hand (string)
Sets the name of the hand. Bt default this is 'hand'.

HAND (string)
This returns the name of the hand.

HELD (agent)
Returns the item currently held by the target. For vehicles this returns a random carried agent if carrying more than one. Consider using EPAS instead.

HGHT (integer)
Returns the height of target.

IITT (agent)
Returns the target creature's current agent of attention. Compare _IT_.

IMSK (integer)
Returns the input event mask.

KILL (command) agent (agent)
Destroys an agent. The pointer won't be destroyed. For creatures, you probably want to use DEAD first.

MESG WRIT (command) agent (agent) message_id (integer)
Send a message to another agent. The message_id is from the table of Message Numbers; remember that early Message Numbers differ slightly from Script Numbers. If used from an install script, then FROM for the message to NULL rather than OWNR.

MESG WRT+ (command) agent (agent) message_id (integer) param_1 (anything) param_2 (anything) delay (integer)
Send a message with parameters to another agent. Waits delay ticks before sending the message. The message_id is from the table of Message Numbers.

MIRA (command) on_off (integer)
Tell the agent to draw the current sprite mirrored (send 1 as a parameter) or normally (send 0 as a parameter)

MIRA (integer)
Is the current sprite for this agent mirrored (returns 1) or not (returns 0)

MOWS (integer)
Returns whether the lawn was cut last Sunday or not.

MTHX (float)
This returns the X position of the TARG creature's mouth attachment point in absolute (map) coordinates.

MTHY (float)
This returns the Y position of the TARG creature's mouth attachment point in absolute (map) coordinates.

NCLS (agent) previous (agent) family (integer) genus (integer) species (integer)
Finds the next agent in the agent list which also matches the given classifier. If the previous agent doesn't exist or doesn't match the classifier then the first agent matching it is returned. If none match the classifier, then NULL is returned.

NEW: SIMP (command) family (integer) genus (integer) species (integer) sprite_file (string) image_count (integer) first_image (integer) plane (integer)
Create a new simple agent, using the specified sprite file. The agent will have image_count sprites available, starting at first_image in the file. The plane is the screen depth to show the agent at - the higher the number, the nearer the camera.

NEXT (command)
Closes an enumeration loop. The loop can begin with ENUM, ESEE, ETCH or EPAS.

NOHH (command)
Tell the creature to immediately stop holding hands with the pointer. Useful when you are about to teleport a norn, it prevents the pointer from continuosly changing his position back to where it was.

NULL (agent)
Returns a null agent pointer.

OVER (command)
Wait until the current agent/part's ANIMation is over before continuing. Looping anims stop this command terminating until the animation is changed to a non-looping one.

OWNR (agent)
Returns the agent who's virtual machine the script is running on. Returns NULL for injected or install scripts.

PAUS (command) paused (integer)
Stops the target agent from running - it'll freeze completely, scripts and physics. Set to 1 to pause, 0 to run. You might want to use WPAU with this to implement a pause game option.

PAUS (integer)
Returns 1 if the target agent is paused, or 0 otherwise.

PCLS (agent) next (agent) family (integer) genus (integer) species (integer)
Same as NCLS, only cycles the other way.

PLNE (command) plane (integer)
Sets the target agent's principal drawing plane. The higher the value, the nearer the camera. For compound agents, the principal plane is the one for the automatically made first part. The plane of other parts is relative to this one.

PLNE (integer)
Returns the screen depth plane of the principal part.

PNTR (agent)
Returns the mouse pointer, which is also known as the hand.

POSB (float)
Returns bottom position of target's bounding box.

POSE (command) pose (integer)
Specify a frame in the sprite file for the target agent/part. Relative to any index specified by BASE.

POSE (integer)
Return the current POSE of the target agent/part, or -1 if invalid part.

POSL (float)
Returns left position of target's bounding box.

POSR (float)
Returns right position of target's bounding box.

POST (float)
Returns top position of target's bounding box.

POSX (float)
Returns X position of centre of target.

POSY (float)
Returns Y position of centre of target.

PUHL (command) pose (integer) x (integer) y (integer)
Set the relative x and y coordinate of the handle that target is picked up by, for the given pose. This pose is measured from the absolute base specified in the NEW: command, rather than the relative base specified by the BASE command. Pose -1 sets the same point for all poses.

PUHL (integer) pose (integer) x_or_y (integer)
Returns the x or y coordinate of the handle that target is picked up by for the given pose. x_or_y is 1 for x, 2 for y. The pose is measured from the absolute base specified in the NEW: command, rather than the relative base specified by the BASE command.

PUPT (command) pose (integer) x (integer) y (integer)
Set the relative x and y coordinate of the place where target picks agents up, for the given pose. This pose is measured from the absolute base specified in the NEW: command, rather than the relative base specified by the BASE command. Pose -1 sets the same point for all poses. For vehicles use the CABN command.

PUPT (integer) pose (integer) x_or_y (integer)
Returns the x or y coordinate of the place where target picks agents up for the given pose. x_or_y is 1 for x, 2 for y. The pose is measured from the absolute base specified in the NEW: command, rather than the relative base specified by the BASE command.

RNGE (command) distance (float)
Sets the distance that the target can see and hear, and the distance used to test for potential collisions. See also ESEE, OBST.

RNGE (float)
Returns the target's range. See ESEE, OBST.

RTAR (command) family (integer) genus (integer) species (integer)
Randomly chooses an agent which matches the given classifier, and targets it.

SEEE (integer) first (agent) second (agent)
Returns 1 if the first agent can see the second, or 0 if it can't. See ESEE.

SHOW (command) visibility (integer)
Set the parameter to 0 to hide the agent and to 1 to show the agent on camera. This removes or adds the agent to the main camera and any remote cameras. A non-shown agent can still be visible to creatures, and can still be clicked on or picked up. It just doesn't appear on the cameras.

SPCS (integer)
Returns species of target. See also FMLY, GNUS.

STAR (command) family (integer) genus (integer) species (integer)
Randomly chooses an agent which matches the given classifier and can be seen by the owner of the script. It then sets TARG to that agent. See ESEE for an explanation of seeing.

TARG (agent)
Returns current target, on whom many commands act.

TCOR (integer) topY (float) bottomY (float) leftX (float) rightX (float)
Tests setting the bounding box of the physical core of the object TARG. May be set to smaller (or larger) than the sprite's rectangle. Returns 1 if OK to set (using CORE), 0 if not.

TICK (command) tick_rate (integer)
Start agent timer, calling Timer script every tick_rate ticks. Set to 0 to turn off the timer.

TICK (integer)
Returns the current timer rate set by the command TICK.

TINO (command) red_tint (integer) green_tint (integer) blue_tint (integer) rotation (integer) swap (integer)
Like TINT but only tints the current frame. The other frames are no longer available in the gallery, it becomes a one frame sprite file. Original display engine only.

TINT (command) red_tint (integer) green_tint (integer) blue_tint (integer) rotation (integer) swap (integer)
This tints the TARG agent with the r,g,b tint and applies the colour rotation and swap as per pigment bleed genes. Specify the PART first for compound agents. The tinted agent or part now uses a cloned gallery, which means it takes up more memory, and the save world files are larger. However it also no longer needs the sprite file. Also, tinting resets camera shy and other properties of the gallery. See TINO for a quicker version that tints only one frame.

TINT (integer) attribute (integer)
Returns a tint value for an agent - currently it works only on Skeletal Creatures. Attribute can be:
1 - Red
2 - Green
3 - Blue
4 - Rotation
5 - Swap

TOTL (integer) family (integer) genus (integer) species (integer)
Counts the number of agents in the world matching the classifier.

TOUC (integer) first (agent) second (agent)
Returns 1 if the two specified agents are touching, or 0 if they are not. Agents are said to be touching if their bounding rectangles overlap.

TRAN (integer) xpos (integer) ypos (integer)
Test for a transparent pixel, returns 1 if the given x y position coincides with a transparent pixel on the TARG agent, otherwise it will return 0. This does not work for creatures.

TTAR (command) family (integer) genus (integer) species (integer)
Randomly chooses an agent which matches the given classifier and is touching the owner of the script. It then sets TARG to that agent. See ETCH.

TWIN (agent) original (agent) agent_null (integer)
Clones an agent, and returns the replica. If agent_null is set to 1 the agents that this agent points to (in OVxx, or VAxx in its running script) are set to NULL in the clone. If agent_null is 0, then the clone points to the same agents as the original. When using agent_null 1, you might want to call STPT first so variables being used mid-script aren't cleared under the agent's nose.

UCLN (command)
Make sure that an agent isn't cloned anymore, this releases the memory taken up by TINTing it. Agents are usually cloned for purposes such as tinting. Don't forget to set the relevant PART number for compound agents.

VISI (integer) checkAllCameras (integer)
Checks if the agent, or any of its parts, is on screen and returns 1 if it is or 0 if it is not. Set to 0 to check if the agent is on the main camera. Set to 1 to check if the agent is on the main camera or any remote cameras

WDTH (integer)
Returns the width of target.

WILD (string) family (integer) genus (integer) species (integer) tag_stub (string) offset (integer)
Searches for a catalogue tag based on the given classifier, and returns the string at the given offset. See also READ. As an example, with a tag_stub of "Agent Help" and a classifier 3 7 11 it would first look for the tag "Agent Help 3 7 11". If that wasn't present, it would go through the wildcards, eventually trying "Agent Help 0 0 0", and throwing an error if even that isn't there.

_IT_ (agent)
Returns the agent OWNR's attention was on when the current script was entered. This is only valid if OWNR is a creature. Compare IITT.


Brain

ADIN (command) verb (integer) noun (integer) qualifier (float) drive (integer)
Add an instinct to the creature's brain queue. (The instinct is not processed immediately). Example: ADIN 3 4 0.5 7 encourages (by a factor of 0.5) the creature to do action 3 on category 4 when drive 7 is high.

BRN: DMPB (command)
Dumps the sizes of the binary data dumps for current lobes and tracts.

BRN: DMPD (command) tract_number (integer) dendrite_number (integer)
Dumps a dendrite as binary data.

BRN: DMPL (command) lobe_number (integer)
Dumps a lobe as binary data.

BRN: DMPN (command) lobe_number (integer) neuron_number (integer)
Dumps a neuron as binary data.

BRN: DMPT (command) tract_number (integer)
Dumps a tract as binary data.

BRN: SETD (command) tract_number (integer) dendrite_number (integer) weight_number (integer) new_value (float)
Sets a dendrite weight.

BRN: SETL (command) lobe_number (integer) line_number (integer) new_value (float)
Sets a lobe's SV rule float value.

BRN: SETN (command) lobe_number (integer) neuron_number (integer) state_number (integer) new_value (float)
Sets a neuron weight.

BRN: SETT (command) tract_number (integer) line_number (integer) new_value (float)
Sets a tract's SV rule float value.

DOIN (command) no_of_instincts_to_process (integer)
Make the creature TARG process N instincts.


Camera

BKGD (command) metaroom_id (integer) background (string) transition (integer)
Change the current background displayed for the selected camera (with SCAM). Transition is as for META. The background must have been specified with the ADDM or ADDB command first.

BKGD (string) metaroom_id (integer)
Returns the name of the background file currently shown by the given camera.

BRMI (command) metaroom_base, (integer) room_base (integer)
Sets the Map's Metaroom and Room index bases for adding new rooms/metarooms.

CMRA (command) x (integer) y (integer) pan (integer)
Move current camera so top left corner of view is at world coordinate x y. Set pan 0 to jump straight to location, pan 1 to smoothly scroll there (unless in a different meta room).

CMRP (command) x (integer) y (integer) pan (integer)
Centre current camera on world coordinate x y. Set pan 0 to jump straight to location, pan 1 to smoothly scroll there (unless in different meta room), and pan 2 to smoothly scroll only if the destination is already visible.

CMRT (command) pan (integer)
Centre current camera on target. Set pan 0 to jump straight to location, pan 1 to smoothly scroll there (unless in different meta room), and pan 2 to smoothly scroll only if the destination is already visible.

CMRX (integer)
Returns the x coordinate of the centre of the current camera.

CMRY (integer)
Returns the y coordinate of the centre of the current camera.

FRSH (command)
Refreshes the main view port.

LINE (command) x1 (integer) y1 (integer) x2 (integer) y2 (integer) r (integer) g (integer) b (integer) stipple_on (integer) stipple_off (integer)
Adds a line to target's drawing list. The line goes between the start and end points (world coordinates) in the specified colour. Set stipple_on and stipple_off to 0 to draw a solid line, or to the number of pixels to alternate for a stippled line. To clear all the lines for an agent, call LINE with the start and end points the same.

LOFT (integer) filename (string)
Declares that you have finished with a photograph image file taken by SNAP. If the file is in use in a gallery, this function fails and returns 1. Otherwise it returns 0. The file will be marked for the attic, and moved there later.

META (command) metaroom_id (integer) camera_x (integer) camera_y (integer) transition (integer)
Change the current camera (set with SCAM) to a new meta room. Moves the top left coordinate of the camera to the given coordinates.

Transition can be:
0 - no transition effect
1 - flip horizontally
2 - burst

META (integer)
Returns the metaroom id that the current camera is looking at.

SCAM (command) compoundagent (agent) partNumber (integer)
Sets the current camera to be used in subsequent camera macro commands. This uses the given TARG and the given PART number. If you set this to NULL then the Main Camera will be used. This is the default setting

SNAP (command) filename (string) x_centre (integer) y_centre (integer) width (integer) height (integer) zoom_factor (integer)
This takes a photograph of the world at a particular place. The zoom parameter should be between 0 and 100. 100 means at original size, 50 means half size etc. It makes a new image file in the world images directory - you can use it to make agents and parts as with any image file. Call SNAX first to check your filename isn't already in use in any images directory. When you have finished with the file, call LOFT.

SNAX (integer) filename (string)
Returns 1 if the specified image file exists, or 0 if it doesn't. Use with SNAP to find a unique filename to use.

TRCK (command) agent (agent) x% (integer) y% (integer) style (integer) transition (integer)
Camera follows the given agent. Set to NULL to stop tracking. x% and y% are percentages (0-100) of the screen size. They describe a rectangle centred on the screen which the target stays within.
Style 0 is brittle - if you move the camera so the target is out of the rectangle, then the tracking is broken.
Style 1 is flexible - you can move the camera away from the target. If you move it back, then tracking resumes.
Style 2 is hard - you can't move the camera so the target is out of the rectangle.
The transition is the sort of fade to use if the tracking causes a change in meta room. The values are the same as for the transition in the META command.

TRCK (agent)
Returns the agent being tracked by the camera, if any.

WDOW (command)
Toggle full screen mode.

WDOW (integer)
Returns 1 if in full screen mode, or 0 if in windowed mode.

WNDB (integer)
Returns world coordinates of bottom of current camera window.

WNDH (integer)
Returns height of current camera window.

WNDL (integer)
Returns world coordinates of left of current camera window.

WNDR (integer)
Returns world coordinates of right of current camera window.

WNDT (integer)
Returns world coordinates of top of current camera window.

WNDW (integer)
Returns width of current camera window.

ZOOM (command) pixels (integer) x (integer) y (integer)
Zoom in on the specified position by a negative amount of pixels or out by positive amount of pixels. If you send -1 as the x and y coordinates then the camera zooms in on the exising view port centre. This only applies to remote cameras.


CD Player

_CD_ EJCT (command)
Open the CD tray.

_CD_ FRQH (integer)
Returns the average value for the highest frequencies detected in the CD player for the current tick.

_CD_ FRQL (integer)
Returns the average value for the lowest frequencies detected in the CD player for the current tick.

_CD_ FRQM (integer)
Returns the average value for the medium frequencies detected in the CD player for the current tick.

_CD_ INIT (command)
Let the game know that you wish to use the cd player. This will shut down all in game sounds and music as the mixer is needed to gauge the frequency spectrum.

_CD_ PAWS (command) on_off (integer)
Pause the CD player if the parameter is greater than zero, to continue playing a previous paused track set the parameter to 1.

_CD_ PLAY (command) first_track (integer) last_track (integer)
Tell the CD Player to play the given track.

_CD_ SHUT (command)
Tell the game that you have finished with the cd player. This will reinstate the in game sounds and music.

_CD_ STOP (command)
Stop the cd player.


Compounds

FCUS (command)
Set keyboard focus to the current PART of the targetted agent. The part should be a PAT: TEXT. If you TARG NULL first, then no part will have the focus.

FRMT (command) left_margin (integer) top_margin (integer) right_margin (integer) bottom_margin (integer) line_spacing (integer) character_spacing (integer) justification (integer)
Use this command to alter the appearance of the current text part. The line and character spacing values are expressed in number of extra pixels to insert between characters. Values for justification are 0 - Left, 1 - Right, 2 - Center, 4 - Bottom, 8 - Middle, 16 - Last Page Scroll (if you add extra text to the part and show the last page, it will scroll upwards). You may add mutually compatible numbers. The default format values are 8 8 8 8 0 0 0.

GRPL (command) red (integer) green (integer) blue (integer) min_y (float) max_y (float)
Add a line to a graph (previously created with PAT: GRPH). The first line you add will be line 0.

GRPV (command) line_index (integer) value (float)
Add a value to a line on a graph. after you have added a value to each line on the graph, it will be updated by scrolling the current values to the left

NEW: COMP (command) family (integer) genus (integer) species (integer) sprite_file (string) image_count (integer) first_image (integer) plane (integer)
Create a new compound agent. The sprite file is for the first part, which is made automatically. Similarly, image_count and first_image are for that first part. The plane is the absolute plane of part 1 - the planes of other parts are relative to the first part.

NPGS (integer)
Returns the number of available pages for current text part.

PAGE (command) page (integer)
Sets current page for text part. The page number should be equal or greater than zero and less than the number returned by NPGS. Use PAT: TEXT or PAT: FIXD to make a text part, and PART to set the current part.

PAGE (integer)
Returns the current page for current text part. See the PAGE command for more information.

PART (command) part_id (integer)
Sets the working part number. Future command such as POSE and ANIM, amongst others, act on that part of a compound agent. To find what parts there are on an agent use PNXT.

PART (integer) part_id (integer)
Returns 1 if the given part number exists on the TARG agent and 0 if it does not.

PAT: BUTT (command) part_id (integer) sprite_file (string) first_image (integer) image_count (integer) rel_x (decimal) rel_y (decimal) rel_plane (integer) anim_hover (byte-string) message_id (integer) option (integer)
Create a button on a compound agent. anim_hover is an animation, as in the ANIM command, to use when the mouse is over the button - when the mouse is moved off, it returns to any previous animation that was going. message_id is sent when the button is clicked. option is 0 for the mouse to hit anywhere in the bounding box, 1 to hit only non-transparent pixels.
_P1_ of the message is set to the part number of the buttons allowing you to overload your messages by button group and then switch on input value in the script.

PAT: CMRA (command) part_id (integer) overlay_sprite (string) baseimage (integer) relx (decimal) rely (decimal) relplane (integer) viewWidth (integer) viewHeight (integer) cameraWidth (integer) cameraHeight (integer)
Create a camera with possible overlay sprite whose name may be blank. Use SCAM to change the camera's view.

PAT: DULL (command) part_id (integer) sprite_file (string) first_image (integer) rel_x (decimal) rel_y (decimal) rel_plane (integer)
Create a dull part for a compound agent. A dull part does nothing except show an image from the given sprite file. You should number part ids starting at 1, as part 0 is automatically made when the agent is made. The dull part's position is relative to part 0, as is its plane. Use PART to select it before you change POSE or ANIM, or use various other commands.

PAT: FIXD (command) part_id (integer) sprite_file (string) first_image (integer) rel_x (decimal) rel_y (decimal) rel_plane (integer) font_sprite (string)
Create a fixed text part. The text is wrapped on top of the supplied gallery image. new-line characters may be used. Use PTXT to set the text.

PAT: GRPH (command) part_id (integer) overlay_sprite (string) baseimage (integer) relx (decimal) rely (decimal) relplane (integer) numValues (integer)
Creates a graph part on a compound agent. Use GRPL to add a line to the graph and GRPV to add a value to a graph line.

PAT: KILL (command) part_id (integer)
Destroys the specified part of a compound agent. You can't destroy part 0.

PAT: MOVE (command) part_id (integer) rel_x (decimal) rely (decimal)
Moves a compound part to the new relative position specified.

PAT: TEXT (command) part_id (integer) sprite_file (string) first_image (integer) rel_x (decimal) rel_y (decimal) rel_plane (integer) message_id (integer) font_sprite (string)
Creates a text entry part. Gains the focus when you click on it, or with the FCUS command. Sends the message_id when return is pressed - a good place to use PTXT to get the text out, and to set the focus elsewhere. Set message_id to 0 to not call any script, or to -1 to not send any message and instead insert a carriage return.

PNXT (integer) previous_part (integer)
Returns the next compound PART on an agent. Start by calling it with -1 to get the first part, and it finishes by returning -1 when it reaches the end.

PTXT (command) text (string)
Set string of current text part. Use PAT: TEXT or PAT: FIXD to make a text part, and PART to set the current part.

In the original display engine, you can use special tags to set TINT colours for characters. Use something like <tint 255 255 0> to begin colouring, and <tint> to end. The tint tag takes up to five parameters as the TINT command, they all default to 128 if not specified. Less than and greater than symbols are still printed if not within a tint tag. The tags also apply to text entry parts, but only when the text is initially set with PTXT; they are obeyed in a character count fashion during editing, but not updated.

PTXT (string)
Returns the string of the current text part. See the PTXT command for more information.


Creatures

AGES (command) times (integer)
Forces a creature to age the given number of times. See also CAGE.

APPR (command)
Creature approaches the IT agent. If there is no IT agent, the creature follows the CA smell to find an agent of that category. The script resumes when it gets there, or if it can't get any further.

ASLP (command) asleep (integer)
Make the creature asleep or awake. 1 for asleep, 0 for awake.

ASLP (integer)
Returns 1 if the creature is asleep, 0 otherwise.

ATTN (integer)
Returns the current focus of attention id.

BODY (command) set_number (integer) layer (integer)
Similar to WEAR, only puts the given set of clothes on every body part.

BODY (integer) bodyPart (integer)
Return the set number of the outfit the norn is wearing on the outer most layer or -1 if it is not wearing anything

BOOT (command) subboot_number (integer) folder_number_sum (integer) clear_world (integer)
Loads in a list of numbered bootstrap folders contained within a folder called subboot. Bootstraps folders numbers are powers of 2, sum the folder numbers to load those folders. There is provision for more than one subboot folder, these should be uniquely numbered.

BORN (command)
Signals the target creature as having been born - this sends a birth event, and sets the TAGE ticking.

BVAR (integer)
Returns the variant number for target creature.

BYIT (integer)
Returns 1 if the creature is within reach of the IT agent, or 0 if it isn't.

CAGE (integer)
Returns life stage of target creature. See also AGES.

CALG (command) category_id (integer) category_representative_algorithm_id (integer)
Choose how a creature (TARG) decides which particular object in a category to look at. PICK_NEAREST_IN_X_DIRECTION=0, PICK_A_RANDOM_ONE=1, PICK_NEAREST_IN_CURRENT_ROOM=2, PICK_NEAREST_TO_GROUND=3, PICK_RANDOM_NEAREST_IN_X_DIRECTION=4.

CALG (integer) category_id (integer)
Find out which algorithm is currently being used for the creature TARG to decide which particular object in a category to look at.

CHEM (command) chemical (integer) adjustment (float)
Adjusts chemical (0 to 255) by concentration -1.0 to +1.0 in the target creature's bloodstream.

CHEM (float) chemical (integer)
Returns concentration (0.0 to 1.0) of chemical (1 to 255) in the target creature's bloodstream.

CREA (integer) agent (agent)
Returns 1 if the agent is a creature, 0 if not.

DEAD (command)
Makes the target creature die, triggering Die script and history events, closing its eyes, and stopping brain and biochemistry updates. Not to be confused with KILL, which you will have to use later to remove the actual body.

DEAD (integer)
Returns 1 if target creature is dead, or 0 if alive.

DECN (integer)
Returns the current focus of decision id.

DFTX (float)
Returns X coordinate of creature's down foot.

DFTY (float)
Returns Y coordinate of creature's down foot.

DIRN (command) direction (integer)
Change creature to face a different direction. North 0, South 1, East 2, West 3.

DIRN (integer)
Returns the direction that target creature is facing. North 0, South 1, East 2, West 3.

DONE (command)
Stops the targetted creature doing any involuntary actions.

DREA (command) dream (integer)
Set to 1 to make the creature fall asleep and dream, 0 to stop the creature dreaming. When dreaming, a creature's instincts are processed. See also ASLP.

DREA (integer)
Returns 1 if the creature is asleep and dreaming, 0 otherwise.

DRIV (command) drive (integer) adjustment (float)
Adjusts the level of the given drive by the specified amount - can be positive or negative.

DRIV (float) drive (integer)
Returns the value (0.0 to 1.0) of the specified drive.

DRV! (integer)
Returns the id of the highest drive for the target creature.

EXPR (integer)
Returns the current facial expression index for the creature.

FACE (command) set_number (integer)
Sets a facial expression on target creature.

FACE (integer)
Returns the front facing pose for the current facial expression. See the FACE string rvalue.

FACE (string)
Returns the name of the sprite file for the target creature's face. Currently automatically gives you the youngest age version of the gallery but soon will work in the following way: If you set the parameter to -1 you will get the name of the file the creature is currently using. Note that when the creature ages, this file name will change (the GALL command could be useful here). If you set the parameter to a particular age then the filename returned will be the gallery that best matches that age. Use the FACE integer rvalue to get the pose number for facing forwards. See also LIMB.

FORF (command) creature_to_learn_about (agent)
Set the friends or foe lobe to learn from the creature.

HAIR (command) stage (integer)
Tidies or ruffles hair. Positive means tidy, negative untidy. There can be multiple stages of tidiness or untidiness; the more extreme the value the tidier or untidier.

HHLD (agent)
Returns the creature currently holding hands with the pointer agent. NULL if no agent is holding hands.

INJR (command) organ (integer) amount (integer)
Injures an organ, -1 to randomly choose the organ, 0 for the body organ.

INS# (integer)
Number of instincts still queued to be processed.

LIKE (command) creature_state_opinion_about (agent)
State a personal opinion about a creature.

LIMB (string) body_part (integer) genus (integer) gender (integer) age (integer) variant (integer)
Returns the filename for the specified part of a creature. If the exact part isn't present, a 'nearby' file which is on the disk is returned.

LOCI (command) type (integer) organ (integer) tissue (integer) id (integer) new_value (float)
Sets a biochemical locus value. See Receptor Locus Numbers and Emitter Locus Numbers

LOCI (float) type (integer) organ (integer) tissue (integer) id (integer)
Reads a biochemical locus value.

LTCY (command) action (integer) min (integer) max (integer)
Sets latency time on involuntary actions to a random value between min and max. After an involuntary action occurs, the same action will not be able to kick in again until after that many ticks. Min and max must range between 0 and 255.

MATE (command)
Male creature mates with the IT agent - if IT is a female of the same genus! The female doesn't need to be in reach. If successful, the sperm is transmitted to the female and there is a chance of conception. If pregnancy occurs, gene slot 1 of the mother contains the genome of the child.

MIND (command) state (integer)
Enable (1) or disable (0) the creature's brain (unlike ZOMB# in that the brain actually stops processing and it's output is frozen onto the one noun and verb).

MIND (integer)
Returns whether the creature TARG's brain is being processed or not.

MOTR (command) state (integer)
Enable (1) or disable (0) the creature's motor faculty, i.e. whether it sets the IT object and fires off scripts.

MOTR (integer)
Returns whether the creature TARG's motor faculty is being processed or not.

MVFT (command) x (float) y (float)
Move creature's down foot to position x,y. Use this instead of MVTO for creatures.

NEW: CRAG (command) family (integer) gene_agent (agent) gene_slot (integer) sex (integer) variant (integer) sprite_file (string) image_count (integer) first_image (integer) plane (integer)
Makes a non-skeletal creature. The first five arguments are the same as NEW: CREA. The last four, starting from the sprite file, are exactly as in NEW: COMP.

NEW: CREA (command) family (integer) gene_agent (agent) gene_slot (integer) sex (integer) variant (integer)
Makes a creature using the genome from the given gene slot in another agent. You'll want to use GENE CROS or GENE LOAD to fill that slot in first. The gene slot is cleared, as control of that genome is moved to the special slot 0 of the new creature, where it is expressed. Sex is 1 for male, 2 for female or 0 for random. The variant can also be 0 for a random value between 1 and 8. See also NEWC.

NEWC (command) family (integer) gene_agent (agent) gene_slot (integer) sex (integer) variant (integer)
This version of NEW: CREA executes over a series of ticks, helping to prevent the pause caused by the creation of a creature with the NEW: CREA command. However, it cannot be used in install scripts (e.g. the bootstrap) and so NEW: CREA should be used for that.

NORN (command) creature (agent)
Chooses the active creature. Script 120 (Selected Creature Changed) is then executed on all agents which have it.

NORN (agent)
Returns the creature currently selected by the user.

NUDE (command)
Removes all clothes from a creature. Any changed layer 0 will revert to drawing the body part again. See WEAR.

ORDR SHOU (command) speech (string)
Sends a spoken command from target to all creatures that can hear it.

ORDR SIGN (command) speech (string)
Sends a spoken command from target to all creatures that can see it.

ORDR TACT (command) speech (string)
Sends a spoken command from target to all creatures that are touching it.

ORDR WRIT (command) creature (agent) speech (string)
Sends a spoken command from target to the specified creature.

ORGF (float) organ_number (integer) data (integer)
Returns floating point data about the specified organ. The organ number is from 0 to ORGN - 1. The data parameter specifies what information is returned:

0 - Clock rate in updates per tick (as locus)
1 - Short term life force as a proportion of intial (as locus)
2 - Factor to modulate rate of repair (as locus)
3 - Injury to apply (as locus)
4 - Initial life force, a million is the largest initial value
5 - Short term life force, temporary damage
6 - Long term life force, permanent damage
7 - Long term rate damage during repair
8 - Energy cost to run this organ, calculated from the number of receptors, emitters and reactions
9 - Damage done to the organ if no energy is available

ORGI (integer) organ_number (integer) data (integer)
Returns integer data about the specified organ. The organ number is from 0 to ORGN - 1. The data parameter specifies what information is returned:

0 - receptor count
1 - emitter count
2 - reaction count.

ORGN (integer)
Returns the number of organs in target creature.

PLMD (command) tract_index, (integer) filename (string)
Dumps out all the dendrite learned information of the specified tract to a file (will be changed to sync with Palm).

PLMU (command) tract_index, (integer) filename (string)
Configures the dendrites in the specified tract with the data in the file (will be changed to sync with Palm).

SAYN (command)
Creature expresses need, by speaking.

SEEN (agent) category (integer)
Returns the agent which the creature TARG has currently in mind for the category specified.

SOUL (command) facultyId (integer) on (integer)
Enable (1) or disable (0) the update on the creature's faculty as given by type id as follows: Sensory Faculty (0), Brain (1), Motor Faculty (2), Linguistic Faculty (3), Biochemistry (4), Reproductive Faculty (5), Expressive Faculty (6), Music Faculty (7), Life Faculty (8)

SOUL (integer) facultyId (integer)
Returns whether the creature faculty of the type specified is being processed or not.

SPNL (command) lobe_moniker (string) neuron_id (integer) value (float)
This sets the input of the neuron in the lobe specified to be the value given.

STEP (command) facultyId (integer)
Does one update of the specified faculty (for faculty id see SOUL#).

STIM SHOU (command) stimulus (integer) strength (float)
Shout a stimulus to all creatures who can hear OWNR. The strength is a multiplier for the stimulus. Set to 1 for a default stimulation, 2 for a stronger stimulation and so on. It is important you use this, rather than send several stims, as it affects learning. Set strength to 0 to prevent learning altogether, and send a strength 1 chemical change. See the table of Stimulus Numbers.

STIM SIGN (command) stimulus (integer) strength (float)
Send a stimulus to all creatures who can see OWNR.

STIM TACT (command) stimulus (integer) strength (float)
Send a stimulus to all creatures who are touching OWNR.

STIM WRIT (command) creature (agent) stimulus (integer) strength (float)
Send stimulus to a specific creature. Can be used from an install script, but the stimulus will be from NULL, so the creature will react but not learn.

SWAY SHOU (command) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float)
Stimulate all creatures that can hear OWNR to adjust four drives by the given amounts.

SWAY SIGN (command) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float)
Stimulate all creatures that can see OWNR to adjust four drives by the given amounts.

SWAY TACT (command) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float)
Stimulate all creatures that are touching OWNR to adjust four drives by the given amounts.

SWAY WRIT (command) creature (agent) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float) drive (integer) adjust (float)
Stimulate a specific creature to adjust four drives by the given amounts.

TAGE (integer)
Returns the age in ticks since the target creature was BORN. Ticking stops when the creature dies - see DEAD.

TOUC (command)
Make creature reach out to touch the IT agent. Blocks the script until the creature either reaches the agent, or it's fully stretched and still can't.

UFTX (float)
Returns X coordinate of creature's up foot.

UFTY (float)
Returns Y coordinate of creature's up foot.

UNCS (command) unconscious (integer)
Make the creature conscious or unconscious. 0 for conscious, 1 for unconscious.

UNCS (integer)
Returns 1 if the creature is unconscious, 0 otherwise.

URGE SHOU (command) noun_stim (float) verb_id (integer) verb_stim (float)
Urge all creatures who can hear OWNR to perform the verb_id action on OWNR. Stimuli can range from -1 to 1, ranging from discourage to encourage.

URGE SIGN (command) noun_stim (float) verb_id (integer) verb_stim (float)
Urge all creatures who can see OWNR to perform an action on OWNR.

URGE TACT (command) noun_stim (float) verb_id (integer) verb_stim (float)
Urge all creatures who are touching OWNR to perform an action on OWNR.

URGE WRIT (command) creature (agent) noun_id (integer) noun_stim (float) verb_id (integer) verb_stim (float)
Urge a specific creature to perform a specific action on a specific noun. A stimulus greater than 1 will force the Creature to perform an action, or to set its attention (mind control!). Use an id -1 and stim greater than 1 to unforce it.

VOCB (command)
Learn all vocabulary instantly.

WALK (command)
Sets creature walking indefinitely. Chooses a walking gait according to chemo-receptors. Always means ignore IT and walk in the current direction set by DIRN.

WEAR (command) body_id (integer) set_number (integer) layer (integer)
Sets a layer of clothing on part of the creature. The set_number is the type of clothing to put on from the overlay file - think of it as an outfit number. layer 0 is the actual body of the creature, so unless you want to replace the body part itself use a higher layer. Higher layers are on top of lower ones. e.g. 0 for a face, 1 for measels spots, 2 for a fencing mask. See also BODY and NUDE.

ZOMB (command) zombie (integer)
Make or undo the creature's zombification factor. 1 makes creatures zombies: in a zombie state creatures won't process any decision scripts but they will respond to ANIMs and POSEs. 0 umzombifies.

ZOMB (integer)
Returns 1 if the creature is zombified (has its brain to motor link severed), 0 otherwise.


Debug

AGNT (agent) unique_id (integer)
Given a unique identifier, returns the corresponding agent. Returns NULL if the agent no longer exists. UNID extracts the unique id. NOTE: This should only be used for external programs to persistently refer to an agent during a session. Variables can use SETA to store agent r-values directly for internal use. Unique identifiers can change across saved sessions.

APRO (command) search_text (string)
Lists all command names whose help contains the text.

BANG (command)
Causes a division by zero exception in the processor, to test the engine's error handling routines.

CODE (integer)
Returns event script number currently being run by target. Returns -1 if not running anything.

CODF (integer)
Returns family of script currently being run by target. Returns -1 if not running anything.

CODG (integer)
Returns genus of script currently being run by target. Returns -1 if not running anything.

CODP (integer)
Returns the offset into the source code of the next instruction to be executed by the target. Use SORC to get the source code. Returns -1 if not running anything.

CODS (integer)
Returns species of script currently being run by target. Returns -1 if not running anything.

DBG# (string) variable (integer)
Dumps debug information for the virtual machine of target. Whatever the type of the variable, a string is output.

Variable can be:
-1 : Whether in INST or not
-2 : Whether in LOCK or not
-3 : Current TARG of virtual machine
-4 : OWNR - should be the same as our outer TARG
-5 : FROM - who sent the message which is being run
-6 : IT - if a Creature, where their attention was
-7 : PART - part number being worked on for compound agents
-8 : _P1_ - first parameter of message, if in a message
-9 : _P2_ - second parameter of message, if in a mesesage
0 to 99 : Local variables VA00 to VA99

DBG: ASRT (command) condition (condition)
Confirms that a condition is true. If it isn't, it displays a runtime error dialog.

DBG: CPRO (command)
Clears agent profiling information. Measurements output with DBG: PROF start here.

DBG: FLSH (command)
This flushes the system's input buffers - usually only useful if DBG: PAWSed.

DBG: HTML (command) sort_order (integer)
Sends CAOS documentation to the output stream. Sort order is 0 for alphabetical, 1 for categorical.

DBG: OUTS (command) value (string)
Send a string to the debug log - use DBG: POLL to retrieve.

DBG: OUTV (command) value (decimal)
Send a number to the debug log - use DBG: POLL to retrieve.

DBG: PAWS (command)
This pauses everything in the game. No game driven ticks will occur until a DBG: PLAY command is issued, so this command is only useful for debugging. Use PAUS for pausing of specific agents, which you can use to implement a pause button.

DBG: PLAY (command)
This command undoes a previously given DBG: PAWS and allows game time to flow as normal.

DBG: POLL (command)
This takes all of the DBG: OUTV and DBG: OUTS output to date and writes it to the output stream.

DBG: PROF (command)
Sends agent profile information to the output stream. This gives you data about the time the engine spends running the update and message handling code for each classifier. The data is measured from engine startup, or the point marked with DBG: CPRO. It's output in comma separated value (CSV) format, so you can load it into a spreadsheet (e.g. Gnumeric or Excel) for sorting and summing.

DBG: TACK (command) follow (agent)
Pauses the game when the given agent next executes a single line of CAOS code. This pause is mid-tick, and awaits incoming requests, or the pause key. Either another DBG: TACK or a DBG: PLAY command will make the engine carry on. Any other incoming requests will be processed as normal. However, the virtual machine of the tacking agent is effectively in mid-processing, so some CAOS commands may cause unpredictable results, and even crash the engine. In particular, you shouldn't KILL the tacking agent. You can see which agent is being tracked with TACK.

DBG: TOCK (command)
This command forces a tick to occur. It is useful in external apps to drive the game according to a different clock instead of the game clock.

DBG: WTIK (command) new_world_tick (integer)
Changes the world tick WTIK to the given value. This should only be used for debugging, as it will potentially leave confusing information in the creature history, and change the time when delayed messages are processed. Its main use is to jump to different seasons and times of day.

DBGA (string) variable (integer)
Dumps debug information for target. Whatever the type of the variable, a string is output.

Variable can be:
0 to 99 : agent variables OV00 to OV99
-1 : Counter for timer tick

HEAP (integer) index (integer)
Returns heap and garbage collection information.
0 - current allocated heap memory (development builds only)
1 - total agents, including ones waiting to be garbage collected
2 - similar, but just for creatures

HELP (command)
Lists all command names to the output stream.

MANN (command) command (string)
Outputs help on the given command to the output stream.

MEMX (command)
Windows only. Sends information about the memory allocated to the output stream. In order, these are the Memory Load (unknown), Total Physical (size in bytes of physical memory), Available Physical (free physical space), Total Page File (maximum possible size of page file), Available Page File (size in bytes of space available in paging file), Total Virtual (size of user mode portion of the virtual address space of the engine), Available Virtual (size of unreserved and uncommitted memory in the user mode portion of the virtual address space of the engine).

PAWS (integer)
Returns 1 for debug pawsed, 0 for playing. See DBG: PAWS.

TACK (agent)
Returns the agent currently being DBG: TACKed.

UNID (integer)
Returns unique identifier for target agent. AGNT goes the opposite way. NOTE: This should only be used for external programs to persistently refer to an agent for a session. Variables can use SETA to store agent r-values directly for internal use. The unique identifier of an agent can change if you save a world and load it in again.


Files

FILE GLOB (command) directory (integer) filespec (string)
This globs a journal directory (0 for world one, 1 for main one) for the filespec provided. As all this can do is list files, it does not worry about where you look relative to the journal directory in question. Use this with care.

Having globbed a directory, the listing is available on the input stream as a number, followed by the names of each file. To read - ise INOK, INNI and INNL. Once you have finished, remember to do a FILE ICLO to remove the glob output from the VM.

FILE ICLO (command)
Disconnects anything which is attached to the input stream. If this is a file, then the file is closed.

FILE IOPE (command) directory (integer) filename (string)
Sets the file for the input stream of the current virtual machine - there is a virtual machine for each agent, so this is much the same as setting it for OWNR. Use INNL, INNI and INNF to get data from the stream, and INOK to check validity of the stream. The filename should include any file extension.

You should use FILE ICLO to close the file, although this happens automatically if you set a new file, if the virtual machine is destroyed, or if the engine exits.

Directory is 0 for the current world's journal directory, 1 for the main journal directory, or 2 for the GAME engine_other_world world's journal directory.

FILE JDEL (command) directory (integer) filename (string)
This deletes the file (filename) specified from the journal directory specified. If directory is zero, this is the current world's journal directory, otherwise it is the main journal directory. It deletes the file immediately, rather than marking it for the attic.

FILE OCLO (command)
Disconnects anything which is attached to the output stream. If this is a file, then the file is closed.

FILE OFLU (command)
Flush output stream. If it is attached to a disk file, this will force any data in the buffer to be written to disk.

FILE OOPE (command) directory (integer) filename (string) append (integer)
Sets the file for the output stream of the current virtual machine - there is a virtual machine for each agent, so this is much the same as setting it for OWNR. Use OUTV and OUTS or various other commands to send text data to the stream. The filename should include any file extension.

You should use FILE OCLO to close the file, although this happens automatically if you set a new file, if the virtual machine is destroyed, or if the engine exits.

Directory is 0 for the current world's journal directory, 1 for the main journal directory, or 2 for the GAME engine_other_world world's journal directory. Set append to 1 to add to the end of the file, or 0 to replace any existing file.

FVWM (string) name (string)
This returns a guaranteed-safe filename for use in world names, journal file names, etc.

INNF (float)
Retrieves a float from the input stream, delimited by white space. Defaults to 0.0 if no valid data.

INNI (integer)
Retrieves an integer from the input stream, delimited by white space. Defaults to 0 if no valid data.

INNL (string)
Retrieves a line of text from the input stream.

INOK (integer)
Returns 1 if the input stream is good, or 0 if it is bad. A bad stream could be a non existent file, or the end of file reached. If the stream has never been opened at all, an error is displayed.

OUTS (command) text (string)
Sends a string to the output stream. When running a script, the stream is null and this command does nothing. For an externally injected command, the data from the stream is returned to the calling process. For the CAOS command, the text is returned as a string. You can use FILE OOPE to set the stream to a journal file.

OUTV (command) value (decimal)
Similar to OUTS only outputs a float or integer as a decimal string.

OUTX (command) text (string)
This sends the string text to the output stream. However it first transforms any escapes into quoted escapes, and it also quotes the entire string for you.

e.g.:

outx "Moooose\n"

Would produce:

"Moooose\n"

on the output stream instead of:

Moooose

WEBB (command) http_url (string)
Launches an external URL in the user's browser. The game engine adds http:// at the beginning to prevent malicious launching of programs, so you just need to specify the domain name and path.


Flow

DOIF (command) condition (condition)
Execute a block of code if the condition is true. The code block ends at the next ELSE, ELIF or ENDI. A condition is composed of one or more comparisons joined by AND or OR. A comparison compares two values with EQ, NE, GT, GE, LT, LE, or alternatively =, <>, >, >=, <, <=.

DOIF ov00 GE 5 AND ov00 LT 10
--- code block 1 ---
ELIF ov00 GE 10 OR ov00 LT 100
--- code block 2 ---
ELSE
--- code block 3 ---
ENDI

Conditions are evaluated simply from left to right, so "a AND b OR c" is the same as "(a AND b) OR c", not "a AND ( b OR c )".

Conditional statements may not work correctly with commands overloaded by rvalue.

ELIF (command) condition (condition)
ELseIF command to follow a DOIF. If the condition in a DOIF is false, each following ELIF command will be evaluated in turn. Only the first true condition will have its code block executed.

ELSE (command)
ELSE clause to follow DOIF and ELIF(s). If nothing else matches, the ELSE block will be executed.

ENDI (command)
Closes a DOIF...ELIF...ELSE... set.

EVER (command)
Forms the end of a LOOP..EVER loop, which just loops forever.

GOTO (command) destination (label)
Don't use this command. It jumps directly to a label defined by SUBR. This command is only here because it is used implicitly by DOIF blocks. This is a really dangerous command to use manually, because if you jump out of a block of code (eg a LOOP...EVER block), the stack frame will no longer be correct, and the script will most likely crash. Don't use it! See SUBR.

GSUB (command) destination (label)
Jumps to a subroutine defined by SUBR. Execution will continue at the instruction after the GSUB when the subroutine hits a RETN command.

LOOP (command)
Begin a LOOP..UNTL or LOOP..EVER loop.

REPE (command)
Closes a REPS loop.

REPS (command) count (integer)
Loop through a block of code a number of times. Must have a matching REPE command to close the block.

RETN (command)
Return from subroutine. Do not use this instruction from inside a block of code (eg a LOOP#..EVER or ENUM...NEXT etc...)! See SUBR and GSUB.

SUBR (command)
Defines the start of a subroutine. Specify a label after the SUBR command - the label is case sensitive, and should start with a letter. If this instruction is hit during normal program flow, it works as a STOP instruction. See GSUB and RETN.

UNTL (command) condition (condition)
Forms the end of a LOOP..UNTL loop. The loop will execute until the condition is met. See DOIF for information on the form of the condition.


Genetics

GENE CLON (command) dest_agent (agent) dest_slot (integer) source_agent (agent) source_slot (integer)
Clones a genome, creating a new moniker and copying the genetics file.

GENE CROS (command) child_agent (agent) child_slot (integer) mum_agent (agent) mum_slot (integer) dad_agent (agent) dad_slot (integer) mum_chance_of_mutation (integer) mum_degree_of_mutation (integer) dad_chance_of_mutation (integer) dad_degree_of_mutation. (integer)
Crosses two genomes with mutation, and fills in a child geneme slot. Mutation variables may be in the range of 0 to 255.

GENE KILL (command) agent (agent) slot (integer)
Clears a genome slot.

GENE LOAD (command) agent (agent) slot (integer) gene_file (string)
Loads an engineered gene file into a slot. Slot 0 is a special slot used only for creatures, and contains the moniker they express. Only the NEW: CREA command fills it in. Other slot numbers are used in pregnant creatures, in eggs, or to temporarily store a genome before expressing it with NEW: CREA. You can use them as general purpose genome stores.

The gene file can have any name, and is loaded from the main genetics file. A new moniker is generated, and a copy of the gene file put in the world directory. You can use * and ? wildcards in the name, and a random matching file will be used.

You can also load monikered files from the world genetics directory with this command. If so, the file is copied and a new moniker generated. Wildcards are matched first in the main genetics directory, and only if none match is the world genetics directory searched.

GENE MOVE (command) dest_agent (agent) dest_slot (integer) source_agent (agent) source_slot (integer)
Moves a genome from one slot to another.

GTOS (string) slot (integer)
Returns the target's moniker in the given gene variable slot. This universally unique identifier is the name of a genetics file. Slot 0 is a creature's actual genome. Other slots are used in pregnant creatures, eggs and other places.

MTOA (agent) moniker (string)
Returns the agent which references the given moniker. The moniker could be stored in any of the gene slots for that agent, including the special slot 0 for a creature. If the moniker is not currently used in the game, then returns NULL. This command can be slow - use MTOC if possible.

MTOC (agent) moniker (string)
Returns the creature with the given moniker. If there is no agent alive with that moniker, then returns NULL. See also MTOA.


History

HIST CAGE (integer) moniker (string) event_no (integer)
Returns the life stage of the creature when the given life event happened.

HIST COUN (integer) moniker (string)
Returns the number of life events that there are for the given moniker. Returns 0 of there are no events, or the moniker doesn't exist.

HIST CROS (integer) moniker (string)
Returns the number of crossover points when the genome was made by splicing its parents genomes.

HIST EVNT (command) moniker (string) event_type (integer) related_moniker_1 (string) related_moniker_2 (string)
Triggers a life event of the given type. Some events are triggered automatically by the engine, some events need triggering from CAOS, others are custom events that you can use for your own purposes. See HIST TYPE for details of the event numbers. All new events made call the Life Event script.

HIST FIND (integer) moniker (string) event_type (integer) from_index (integer)
Searches for a life event of a certain HIST TYPE for the given moniker. The search begins at the life event after the from index. Specify -1 to find the first event. Returns the event number, or -1 if there is no matching event.

HIST FINR (integer) moniker (string) event_type (integer) from_index (integer)
Reverse searches for a life event of a certain HIST TYPE for the given moniker. The search begins at the life event before the from index. Specify -1 to find the last event. Returns the event number, or -1 if there is no matching event.

HIST FOTO (string) moniker (string) event_no (integer)
For the given life event, returns the filename of the associated photograph, or an empty string if there is no photo.

HIST FOTO (command) moniker (string) event_no (integer) new_value (string)
For the given life event, sets the associated photograph. Use SNAP to take the photograph first.

If there was already a photograph for the event, then it is automatically marked for the attic as in LOFT, and overwritten with the new photo. Hence you can use an empty string to clear a photo. If HIST WIPE is used to clear the event, the photo is similarly stored in the attic.

It is considered an error to send a photograph that is in use (unless cloned with TINT) to the attic. If this happens, you will get a runtime error. You should either be confident that no agents are using the photo, or call LOFT first to test if they are.

HIST GEND (integer) moniker (string)
Returns the sex that the creature with the given moniker has or had. 1 for male, 2 for female. If the creature hasn't been born yet, returns -1.

HIST GNUS (integer) moniker (string)
Returns the genus of the moniker. This is 1 for Norn, 2 for Grendel, 3 for Ettin by convention.

HIST MON1 (string) moniker (string) event_no (integer)
For the given life event, returns the first associated moniker.

HIST MON2 (string) moniker (string) event_no (integer)
For the given life event, returns the second associated moniker.

HIST MUTE (integer) moniker (string)
Returns the number of point mutations the genome received during crossover from its parents.

HIST NAME (string) moniker (string)
Returns the name of the creature with the given moniker.

HIST NAME (command) moniker (string) new_name (string)
Renames the creature with the given moniker.

HIST NETU (string) moniker (string) event_no (integer)
Returns the network identifier of the user when the given life event happened.

HIST NEXT (string) moniker (string)
Returns the next moniker which has a history, or an empty string if we're at the end already. If the specified moniker is an empty string or doesn't have a history, then the first moniker with a history entry is returned, or an empty string if there isn't one.

HIST PREV (string) moniker (string)
Returns the previous moniker which has a history. If the specified moniker is an empty string or doesn't have a history, then the last moniker with a history entry is returned, or an empty string if there isn't one.

HIST RTIM (integer) moniker (string) event_no (integer)
Returns the real world time when the given life event happened. This is measured in seconds since midnight, 1 January 1970 in UTC. To display, use RTIF.

HIST TAGE (integer) moniker (string) event_no (integer)
Returns the age in ticks of the creature when the given life event happened to it. If the creature was not in the world, wasn't born yet, or was fully dead, then -1 is returned. If the creature was dead, but its body still in the world, then its age on death is returned. See also TAGE.

HIST TYPE (integer) moniker (string) event_no (integer)
For the given life event, returns its type.

All histories begin with one of the following four events. You can read the associated monikers with HIST MON1 and HIST MON2.
0 Conceived - a natural start to life, associated monikers are the mother's and father's
1 Spliced - created using GENE CROS to crossover the two associated monikers
2 Engineered - from a human made genome with GENE LOAD, the first associated moniker is blank, and the second is the filename
14 Cloned - such as when importing a creature that already exists in the world and reallocating the new moniker, when TWINing or GENE CLONing; associated moniker is who we were cloned from

The following events happen during a creature's life:
3 Born - triggered by the BORN command, associated monikers are the parents.
4 Aged - reached the next life stage, either naturally from the ageing loci or with AGES
5 Exported - emmigrated to another world
6 Imported - immigrated back again
7 Died - triggered naturally with the death trigger locus, or by the DEAD command
8 Became pregnant - the first associated moniker is the child, and the second the father
9 Impregnated - first associated moniker is the child, second the mother
10 Child born - first moniker is the child, second the other parent
15 Clone source - someone was cloned from you, first moniker is whom
16 Warped out - exported through a worm hole with NET: EXPO
17 Warped in - imported through a worm hole

These events aren't triggered by the engine, but reserved for CAOS to use with these numbers:
11 Laid by mother
12 Laid an egg
13 Photographed

Other numbers can also be used for custom life events. Start with numbers 100 and above, as events below that are reserved for the engine. You send your own events using HIST EVNT.

HIST UTXT (command) moniker (string) event_no (integer) new_value (string)
For the given life event, sets the user text.

HIST UTXT (string) moniker (string) event_no (integer)
For the given life event, returns the user text.

HIST VARI (integer) moniker (string)
Returns the variant that the creature with the given moniker has or had. If the creature hasn't been born yet, returns -1.

HIST WIPE (command) moniker (string)
Purge the creature history for the given moniker. Only applies if the genome isn't referenced by any slot, and the creature is fully dead or exported. Use OOWW to test this first.

HIST WNAM (string) moniker (string) event_no (integer)
Returns the name of the world the given life event happened in.

HIST WTIK (integer) moniker (string) event_no (integer)
Returns the world tick when the life event happened, for the world that the event happened in.

HIST WUID (string) moniker (string) event_no (integer)
Returns the unique identifier of the world the given life event happened in.

HIST WVET (integer) moniker (string)
Returns 1 if the Creature is a warp hole veteran, 0 otherwise. The creature is a veteran if they have ever been exported with NET: EXPO. They must have been the main exported creature - warping as an embryo doesn't make you a veteran.

OOWW (integer) moniker (string)
Returns the status of the moniker.

0 - never existed, or history purged
1 - genome referenced by a slot, for example an egg
2 - creature made with NEW: CREA
3 - creature properly BORN
4 - out of world, exported
5 - dead, body still exists
6 - dead, body KILLed
7 - unreferenced genome


Input

CLAC (command) message (integer)
Set the click action, which is the identifier of the message sent to the agent when it is clicked on, provided attribute Activateable is set. Default is activate 1. Use -1 to prevent it sending a message. Also overriden by CLIK. Remember that the early Message Numbers differ slightly from Script Numbers.

CLIK (command) message_1 (integer) message_2 (integer) message_3 (integer)
Sets a chain of three message ids to cycle through as the agent is clicked on. Entries of -1 are ignored. Overriden by CLAC.

HOTP (integer)
Returns the number of the compound part under the pointer. Returns -1 if no agent is under the pointer, and 0 if the agent is simple or a skeletal creature. Transparency of the parts is ignored, so each part is a rectangle. Transparency of the agent as a whole is, however, obeyed. Planes are also ignored, except later part numbers are treated as above earlier ones. See also HOTS to find the agent under the pointer.

HOTS (agent)
Returns the agent nearest the screen under the hotspot of the pointer. For each agent, TRAN decides whether this allows for transparent pixels. See also HOTP, which does the same for compound parts.

IMSK (command) mask (integer)
Set the input event mask. Indicates which types of global input events the agent is interested in, if any. For example, if the flag for "key up" events is set here, the agents "key up" script will be run every time a key is released.

Input event bit flags are
1 Raw Key Down
2 Raw Key Up
4 Raw Mouse Move
8 Raw Mouse Down
16 Raw Mouse Up
32 Raw Mouse Wheel
64 Raw Translated Char

You can find the script numbers executed by following the links above.

KEYD (integer) keycode (integer)
Returns 1 if the specified key is currently pressed down, 0 if not.

MOPX (integer)
Returns x position of mouse in world coordinates.

MOPY (integer)
Returns y position of mouse in world coordinates.

MOUS (command) behaviour (integer)
Defines the behaviour of the mouse button for the default pointer behaviour - see PURE.
0 is normal
1 means the right button does what the left button does
2 means the left button does what the right button does

MOVX (float)
Returns horizontal mouse velocity.

MOVY (float)
Returns vertical mouse velocity.

PURE (command) value (integer)
Enables or disables the default clicking and moving behaviour of the pointer. This default behaviour is to implement CLAC and CLIK, and to operate ports. Set to 1 to enable, 0 to disable. When disabled, use IMSK to hook mouse events.

PURE (integer)
Returns whether default pointer behaviour is disabled or enabled. 1 if enabled, 0 if disabled.

TRAN (command) transparency (integer) part_no (integer)
Sets pixel transparency awareness. 1 for pixel perfect, so transparent parts of the agent can't be clicked. 0 to allow anywhere on the agent rectangle to be clicked. See also the option parameter on PAT: BUTT which overrides this.


Map

ADDB (command) metaroom_id (integer) background_file (string)
Add a new background to the given metaroom. Use BKGD to change the current displayed background.

ADDM (integer) x (integer) y (integer) width (integer) height (integer) background (string)
Creates a new metaroom with the given coordinates. Specifies the starting background file. Returns the id of the new metaroom.

ADDR (integer) metaroom_id (integer) x_left (integer) x_right (integer) y_left_ceiling (integer) y_right_ceiling (integer) y_left_floor (integer) y_right_floor (integer)
Creates a new room within a metaroom. Rooms have vertical left and right walls, but potentially sloped floors and ceilings. The coordinates specify the exact shape. Returns the id of the new room.

ALTR (command) room_id (integer) ca_index (integer) ca_delta (float)
Directly adjusts the level of a CA in a room. Specify an identifier of -1 to use the room of the midpoint of the target agent.

BKDS (string) metaroom_id (integer)
Returns a string containing all the background names for the specified metaroom in a comma seperated list.

CACL (command) family (integer) genus (integer) species (integer) ca_index (integer)
This associates the classification specified with the CA specified. This allows the linking of CA's to classifiers within creatures' brains.

CALC (command)
Recalculates all the navigational CAs (warning: slow).

DELM (command) metaroom_id (integer)
Deletes the specified metaroom from the map.

DELR (command) room_id (integer)
Deletes the specified room from the map.

DMAP (command) debug_map (integer)
Set to 1 to turn the debug map image on, 0 to turn it off. The debug map includes vehicle cabin lines.

DOCA (command) no_of_updates (integer)
Updates all CAs the specified number of times.

DOOR (command) room_id1 (integer) room_id2 (integer) permiability (integer)
Sets the permiability of the door between two rooms. This is used for both CAs and physical motion. See also PERM.

DOOR (integer) room_id1 (integer) room_id2 (integer)
Returns the door permiability between two rooms.

DOWN (integer)
Returns the value of the down constant.

EMID (string)
Returns a string containing all the metaroom ids in the world seperated by spaces.

EMIT (command) ca_index (integer) amount (float)
Target now constantly emits an amount of a CA into the room it is in.

ERID (string) metaroom_id (integer)
Returns a string containing all the room ids in the specified metaroom separated by spaces. Returns all rooms in the world if metaroom_id is -1.

GMAP (integer) x (float) y (float)
Returns the metaroom id at point x,y on the map. If the point is outside the room system, it returns -1.

GRAP (integer) x (float) y (float)
Returns the room id at point x,y on the map. If the point is outside the room system, it returns -1.

GRID (integer) agent (agent) direction (integer)
Returns the ID of a room adjacent to the agent in the given direction. A straight line is drawn from the centre of the agent until it hits a room. Directions are LEFT, RGHT, _UP_, or DOWN. A value of -1 is returned if no room can be found.

HIRP (integer) room_id (integer) ca_index (integer) directions (integer)
Returns id of the room adjacent to this one with the highest concentration of the given CA. direction is 0 for left/right, 1 for any direction.

LEFT (integer)
Returns the value of the left constant.

LINK (command) room1 (integer) room2 (integer) permiability (integer)
Sets the permiability of the link between the rooms specified, creating the link if none exists before. Set to 0 to close (destroy) the link. This is used for CAs. See also DOOR.

LINK (integer) room1 (integer) room2 (integer)
Returns the permiability of the link between the rooms specified or 0 if no link exists.

LORP (integer) room_id (integer) ca_index (integer) directions (integer)
Returns id of the room adjacent to this one with the lowest concentration of the given CA. direction is 0 for left/right, 1 for any direction.

MAPD (command) width (integer) height (integer)
Sets the dimensions of the map. These are the maximum world coordinates. Metarooms are rectangles within this area.

MAPH (integer)
Returns the total height of the map.

MAPK (command)
Resets the map to be empty.

MAPW (integer)
Returns the total width of the map.

MLOC (string) metaroom_id (integer)
Returns the location of the specified metaroom as a string formated as follows: x y width height.

PERM (command) permiability (integer)
Value from 1 to 100. Sets which room boundaries the agent can pass through. The smaller the PERM the more it can go through. DOOR sets the corresponding room boundary permiability. Also used for ESEE, to decide what it can see through.

PERM (integer)
Returns the target's map permiability.

PROP (command) room_id (integer) ca_index (integer) ca_value (float)
Sets the level of a CA (cellular automata) in a particular room. There are 16 CAs, and their meaning depends on the game. The level is between 0 and 1.

PROP (float) room_id (integer) ca_index (integer)
Returns the value of a CA in a room.

RATE (command) room_type (integer) ca_index (integer) gain (float) loss (float) diffusion (float)
Sets various rates for a CA (cellular automata) in a particular type of room. The values can be from 0 to 1. Gain is the susceptibility to absorb from agents in the room, and loss is the amount lost to the atmosphere. The diffusion is the amount it spreads to adjacent rooms.

RATE (string) room_type (integer) ca_index (integer)
Returns a string containing gain, loss and diffusion rates for that combination of room type and CA.

RGHT (integer)
Returns the value of the right constant.

RLOC (string) room_id (integer)
Returns the location of the specified room as a string formated as follows: xLeft xRight yLeftCeiling yRightCeiling yLeftFloor yRightFloor.

ROOM (integer) agent (agent)
Returns the id of the room containing the midpoint of the specified agent.

RTYP (command) room_id (integer) room_type (integer)
Sets the type of a room. The meaning of the types depends on the game. RATE also uses the room type.

RTYP (integer) room_id (integer)
Returns the type of a room, or -1 if not a valid room id.

TORX (float) room_id (integer)
Returns relative X position of the centre of the given room from target's top left corner.

TORY (float) room_id (integer)
Returns relative Y position of the centre of the given room from target's top left corner.

_UP_ (integer)
Returns the value of the up constant.


Motion

ACCG (command) acceleration (float)
Set acceleration due to gravity in pixels per tick squared.

ACCG (float)
Returns target's acceleration due to gravity in pixels per tick squared.

ADMP (command) damping_factor (float)
Damp angular velocity by this much each tick. The value is from 0.0 to 1.0 where 0.0 means no damping, 1.0 maximum.

ADMP (float)
Get current angular damping. The value is from 0.0 to 1.0 where 0.0 means no damping, 1.0 maximum.

AERO (command) aerodynamics (integer)
Set aerodynamic factor as a percentage. The velocity is reduced by this factor each tick.

AERO (integer)
Returns aerodynamic factor as a percentage.

ANGL (float) x (float) y (float)
Gets the angle (as a fraction of a circle) from TARG's position to the position specified.

AVEL (command) amount_in_fraction_of_whole_circle (float)
Set angular velocity.

AVEL (float)
Get current angular velocity.

ELAS (command) elasticity (integer)
Set the elasticity percentage. An agent with elasticity 100 will bounce perfectly, one with elasticity 0 won't bounce at all.

ELAS (integer)
Return the elasticity percentage.

FALL (integer)
Returns 1 if target is moving under the influence of gravity, or 0 if it is at rest.

FDMP (command) damping_factor (float)
Damp forward velocity by this much each tick. The value is from 0.0 to 1.0 where 0.0 means no damping, 1.0 maximum.

FDMP (float)
Get current forwards damping. The value is from 0.0 to 1.0 where 0.0 means no damping, 1.0 maximum.

FLTO (command) screen_x (float) screen_y (float)
Move the top left corner of target to either the given screen coordinates, or the given coordinates relative to the agent it is FREL to. Useful for floating agents.

FREL (command) relative (agent)
Sets an agent for target to float relative to. To make target actually float, you need to set attribute Floatable as well. Set FREL to NULL to make the target float relative to the main camera - this is the default. Use FLTO to set the relative position of the top left corner of the floating agent to the top left corner of the agent it is floating relative to.

FRIC (command) friction (integer)
Set physics friction percentage, normally from 0 to 100. Speed is lost by this amount when an agent slides along the floor.

FRIC (integer)
Return physics friction percentage.

FVEL (command) amount_in_pixels (float)
Set forwards velocity.

FVEL (float)
Get current forwards velocity.

MOVS (integer)
Returns the movement status of the target.
0 Autonomous
1 Mouse driven
2 Floating
3 In vehicle
4 Carried

MVBY (command) delta_x (float) delta_y (float)
Move the target agent by relative distances, which can be negative or positive.

MVSF (command) x (float) y (float)
Move the target agent into a safe map location somewhere in the vicinity of x, y. Only works on autonomous agents - see MOVS. Works like a safe MVFT for creatures.

MVTO (command) x (float) y (float)
Move the top left corner of the target agent to the given world coordinates. Use MVFT instead to move creatures.

OBST (float) direction (integer)
Returns the distance from the agent to the nearest wall that it might collide with in the given direction. Directions are LEFT, RGHT, _UP_, or DOWN. If the distance to the collsion is greater than RNGE then a very large number is returned.

RELX (float) first (agent) second (agent)
Returns the relative X distance of the centre point of the second agent from the centre point of the first.

RELY (float) first (agent) second (agent)
Returns the relative Y distance of the centre point of the second agent from the centre point of the first.

ROTN (command) no_of_sprites_for_each_rotation (float) no_of_rotations (float)
For automatic change of sprite when the agent rotates the engine assumes that the sprite file is stored with all the sprites for one rotation together starting with pointing north.

SDMP (command) damping_factor (float)
Damp sideways velocity by this much each tick. The value is from 0.0 to 1.0 where 0.0 means no damping, 1.0 maximum.

SDMP (float)
Get current sideways damping. The value is from 0.0 to 1.0 where 0.0 means no damping, 1.0 maximum.

SPIN (command) amount_in_fraction_of_whole_circle (float)
Rotate to a particular facing.

SPIN (float)
Get current facing angle.

SVEL (command) amount_in_pixels (float)
Set sideways velocity.

SVEL (float)
Get current sideways velocity.

TMVB (integer) delta_x (float) delta_y (float)
Similar to TMVT only tests a MVBY.

TMVF (integer) x (float) y (float)
Test if a creature could move it's down foot to position x,y.

TMVT (integer) x (float) y (float)
Test if target can move to the given location and still lie validly within the room system. Returns 1 if it can, 0 if it can't.

VARC (command) view_arc_size (float)
[not implemented yet]

VARC (float)
[not implemented yet]

VECX (float) angle (float)
Returns a normalised vector for the given angle (X coordinate).

VECY (float) angle (float)
Returns a normalised vector for the given angle (Y coordinate).

VELO (command) x_velocity (float) y_velocity (float)
Set velocity, measured in pixels per tick.

VELX (variable)
Horizontal velocity in pixels per tick - floating point.

VELY (variable)
Vertical velocity in pixels per tick - floating point.

WALL (integer)
Returns the direction of the last wall the agent collided with. Directions are LEFT, RGHT, _UP_, or DOWN.


Net

NET: ERRA (integer)
Returns an error code from the last command. Currently NET: LINE is the only command to set it.

Error codes are:
0 - Unknown
1 - Connection OK
2 - Connection failed, you or the server are offline
3 - Connection failed, invalid user name/password
4 - Connection failed, you are already logged in elsewhere
5 - Connection failed, too many users for server
6 - Connection failed, internal error
7 - Connection failed, new client version required.

Try NET: RAWE for more detailed diagnostic codes.

NET: EXPO (integer) chunk_type (string) dest_user_id (string)
Transwarp the target creature to the given user. The Creature is exported to the warp out directory; this command is very similar to PRAY EXPO. Return value is one of the following:
0 for success
1 if the creature, or if pregnant any of its offspring, are already on disk in some form. This case won't happen much, if you use a special chunk name like WARP.
2 if the user hasn't been online in this world yet / since the user name changed, so we don't know who they are.

When receiving a creature, use NET: FROM to find out who sent it.

NET: FROM (string) resource_name (string)
The user who sent the PRAY file which contains the specified resource. If the resource did not arrive as a message over the network via NET: MAKE or NET: EXPO, then this returns an empty string. The user returned by this command is guaranteed in a way that looking at the content of the PRAY file would not be. For example, the "Last Network User" attribute in an exported Creature made with NET: EXPO could be faked.

NET: HEAD (command)
Dump debugging informatino about who is NET: HEARing on what channels.

NET: HEAR (command) channel (string)
The target agent will now accept CAOS messages over the network on the specified channel, and execute their script as appropriate. Use NET: WRIT to send the message.

NET: HOST (string)
Returns the hostname, port, id and friendly name on that host that we are currently connected to, or empty string if offline. The fields are space separated, although the last field (friendly name) may contain spaces.

NET: LINE (command) state (integer)
Goes on or offline, connecting or disconnecting from the Babel server. Set to 1 to connect, 0 to disconnect. A NET: USER must be set first. NET: ERRA is set to any error code. While the connection is being made, this command can block for several ticks. This command never runs in an INST.

NET: LINE (integer)
Returns 1 if you are connected to the Babel server, or 0 if you aren't.

NET: PASS (string)
Returns the currently set username, as selected with PASS.

NET: PASS (command) nick_name (string) password (string)
Set nickname and password - do this before connecting with NET: LINE. If you set GAME "engine_netbabel_save_passwords" to 1 then the password for each nickname is saved in user.cfg, so you can specify an empty string for the password after the first time. The nickname is saved with the serialised world, so is cleared when you start a new world. You can use NET: PASS to retrieve the user later.

NET: RAWE (integer)
Returns an internal error code from Babel. Only use this for display and diagnostic purpose, use NET: ERRA for documented error codes which you can rely on.

NET: RUSO (command) store_result (variable)
Returns (into store_result) a random user who is currently online. Returns an empty string if you're offline, or if you aren't using the Docking Station Babel server module. Since you're online, it can return yourself (especially if you're the only person online!). The user is also only likely to be online - they could have gone offline since the server replied to you.

This is a command rather than an integer r-value because it is blocking. This means that it might take several ticks before the server returns the result. In this sense it is similar to a command like OVER, so it does not run in an INST. You should use LOCK if you don't want your script interrupting.

NET: STAT (command) time_online (variable) users_online (variable) bytes_received (variable) bytes_sent (variable)
Returns statistics for the current Babel connection, or -1 if offline. This command can block (doesn't execute in an INST). The statistics are:
time_online - Time online in milliseconds
users_online - Number of users currently connected to the server
bytes_received - Bytes received by the client
bytes_sent - Bytes sent from the client

NET: ULIN (integer) user_id (string)
Returns 1 if the specified user is online, or 0 if they are offline. This is slow (i.e. has to call the server) unless the user is in the whose wanted register of any agent. Use NET: WHON to add a user to the register.

NET: UNIK (command) user_id (string) store_result (variable)
Returns the specified user's screen or nick name. Returns empty string if offline, or no such user. This command can take many ticks to execute while the server is quizzed, like NET: RUSO.

NET: USER (string)
Returns the user's numeric Babel id, or an empty string if they have never logged in with this world since they last changed user name.

NET: WHAT (string)
For debugging only. Returns a string describing what the upload/query network thread is currently doing. For example, it may be fetching a random online user, or uploading some creature history. Returns an emptry string if it is doing nothing.

NET: WHOD (command)
Dump debugging information about the whose wanted register.

NET: WHOF (command) user (string)
Removes a user from the whose wanted list for the target agent. See NET: WHON.

NET: WHON (command) user (string)
Add a user to the whose wanted register for the target agent. Scripts User Online and User Offline are now called on this agent when that user goes on or offline, or indeed when the local user goes offline. Use NET: WHOF to remove them from the register. This command is blocking, it can take several ticks to return.

NET: WHOZ (command)
Zap the target agent's whose wanted register, removing all entries.

NET: WRIT (command) user_id (string) channel (string) message_id (integer) param_1 (anything) param_2 (anything)
Send a message to a remote machine, as specified by the user identifier. All agents which are NET: HEARing on the given channel will receive the message, and run the appropriate script. If the specified user is offline, then the message is discarded. The FROM variable of the receiving script contains the user id of the sender, as a string. See also MESG WRIT.


Ports

ECON (command) agent (agent)
Starts an enumeration across all the agents in a connective system, where agent is any agent within the connective system.

PRT: BANG (command) bang_strength (integer)
Breaks connections randomly with other machines (as if the machine had been 'banged'. Use a bang_strength of 100 to disconnect all ports, 50 to disconnect about half etc.

PRT: FRMA (agent) inputport (integer)
Returns the agent from which the input port is fed. Returns NULLHANDLE if that port does not exist, or is not connected.

PRT: FROM (integer) inputport (integer)
Returns the output port index on the source agent, feeding that input port on the TARG agent.
Return values are -ve for error.

PRT: INEW (command) id (integer) name (string) description (string) x (integer) y (integer) message_num (integer)
Create a new input port on target. You should number input port ids starting at 0. The message_num is the message that will be sent to the agent when a signal comes in through the input port. _P1_ of that message will contain the data value of the signal. The position of the port, relative to the agent, is given by x, y.

PRT: ITOT (integer)
Returns the number of input ports, assuming they are indexed sequentially.

PRT: IZAP (command) id (integer)
Remove the specified input port.

PRT: JOIN (command) source_agent (agent) output_id (integer) dest_agent (agent) input_id (integer)
Connect an output port on the source agent to an input port on the destination. An input may only be connected to one output at at time, but an output may feed any number of inputs.

PRT: KRAK (command) agent (agent) in_or_out (integer) port_index (integer)
Breaks a specific connection on a machine. If in_or_out is zero, it is an input port whose connection is broken, if it is an output port, then all inputs are disconnected.

PRT: NAME (string) agent (agent) in_or_out (integer) port_index (integer)
Returns the name of the indexed port (input port if in_or_out is zero, output port if non-zero) on the specified agent. Returns "" in error.

PRT: ONEW (command) id (integer) name (string) description (string) x (integer) y (integer)
Create a new output port on target. You should number input port ids starting at 0. The port's relative position is given by x, y.

PRT: OTOT (integer)
Returns the number of output ports, assuming they are indexed sequentially.

PRT: OZAP (command) id (integer)
Remove the specified output port.

PRT: SEND (command) id (integer) data (anything)
Send a signal from the specified output port to all connected inputs. The data can be any integer.


Resources

NET: MAKE (integer) which_journal_spot (integer) journal_name (string) user (string) report_destination (variable)
Like PRAY MAKE, only sends the made pray file to the specified user. This will arrive in their inbox, where it can be read with normal PRAY commands and deleted with PRAY KILL.

PRAY AGTI (integer) resource_name (string) integer_tag (string) default_value (integer)
This returns the value of the integer tag associated with the named resource. If the resource does not contain such a tag, then the default value specified is returned. This call pairs with PRAY AGTS.

PRAY AGTS (string) resource_name (string) string_tag (string) default_value (string)
This returns the value of the string tag associated with the named resource. If the resource does not contain such a tag, then the default value specified is returned. This call pairs with PRAY AGTI.

PRAY BACK (string) resource_type (string) last_known (string)
Like PRAY PREV, only doesn't loop at the end. If you go beyond the first entry then it returns an empty string.

PRAY COUN (integer) resource_type (string)
This returns the number of resource chunks which are tagged with the resource type passed in. Resource types are four characters only. Anything over that length will be silently truncated.

PRAY DEPS (integer) resource_name (string) do_install (integer)
This performs a scan of the specified resource, and checks out the dependency data. The primary use for this would be in the preparation for injection of agents. If you pass zero in the do_install parameter, then the dependencies are only checked. If do_install is non-zero, then they are installed also. The return values are as follows:
0 = Success
-1 = Agent Type not found
-2 = Dependency Count not found
-3 to -(2 + count) is the dependency string missing
-(3+count) to -(2+2*count) is the dependency type missing
2*count to 3*count is the category ID for that dependency being invalid
1 to count is the dependency failing

PRAY EXPO (integer) chunk_type (string)
This function exports the target creature. If the creature is exported successfully then it has been removed from the world. Returns value is one of the following:
0 for success
1 if the creature, or if pregnant any of its offspring, are already on disk in some form.

The chunk type should be used to find the creature again to import it. In Creatures 3, most exported creatures have a chunk type EXPC, and the starter family uses SFAM.

For new games, you should not use SFAM, as its data would get confused with that of an EXPC with the same moniker. This is for backwards compatibility with Creatures 3's use of SFAM, which works because the CAOS code guarantees different monikers.

For other chunk names, creatures exported with a different type are kept entirely separately, and will not get confused with each other. The chunk type is added to the end of the moniker to form the chunk name.

The exported creature has some fields associated with it, that can be read by PRAY AGTI or PRAY AGTS before importing:
"Exported At World Time" integer
"Creature Age In Ticks" integer
"Exported At Real Time" integer
"Creature Life Stage" integer
"Exported From World Name" string
"Exported From World UID" string
"Native Network User" string
"Last Network User" (could be faked, NET: FROM is safer) string
"Creature Name" string
"Gender" integer
"Genus" integer
"Variant" integer
"Head Gallery" string (this is calculated on the sending computer, so the file may be missing on the receiving one - try LIMB instead)
"Pregnancy Status" integer

In addition you can add custom fields by setting NAME variables on the Creature before export. Any strings or integers whose name begin "Pray Extra " are added as entries to the export file.

PRAY FILE (integer) resource_name (string) resource_type (integer) do_install (integer)
This performs the "installation" of one file from the resource files. The resource_type is defined in the agent resource guide. If do_install is zero, the command simply checks if the file install should succeed. Return value is 0 for success, 1 for error.

PRAY FORE (string) resource_type (string) last_known (string)
Like PRAY NEXT, only doesn't loop at the end. If you go beyond the last entry then it returns an empty string.

PRAY GARB (command) force (integer)
This command clears the manager's cached resource data. Execute this after a lot of resource accesses (E.g. installing an agent) to clean up the memory used during the process. If you don't do this, excess memory can be held for a while, If the parameter is zero (the most usual) then the manager will only forget resources which are not in use at the moment. If force is non-zero, then the manager will forget all the previously loaded resources. As the resources currently in use go out of scope, they are automatically garbage collected.

PRAY IMPO (integer) moniker_chunk (string) actually_do_it (integer) keep_file (integer)
This function imports the creature with the requested moniker and chunk type. Returns one of the following codes:
0 - success
1 - couldn't reconcile histories so creature was cloned
2 - moniker not found in PRAY system
3 - unused error code
4 - internal / file format error

Set actually_do_it to 1 to try and perform the import, or 0 to perform a query giving just the return value. You can use the query to test if the creature is available, and if the creature would have to be cloned upon importing, and warn the user. The new creature is TARGetted after import. If you set keep file to 1, then the exported file won't be deleted (moved to the porch). The creature will appear in the same place that it was exported, but as with NEW: CREA, it will be in limbo, and won't function until moved to a valid place.

PRAY INJT (integer) resource_name (string) do_install (integer) report_var (variable)
This command injects an agent. The agent must be in the chunk named. If do_install is zero, the command simply checks for the presence of the required scripts and dependencies. If non-zero, it attempts to inject the agent. The report var is a string variable, and is set to the name of the offending script if the injection/check fails.
Return is 0 for success, -1 for "Script not found" and if injecting, -2 for "Injection failed".
Return value -3 indicates that a dependency evaluation failed, and in this case, the report var is the return code from PRAY DEPS

PRAY KILL (integer) resource_name (string)
Deletes the resource file which contains the specified chunk. This is permanent and irreversible. Returns 1 if there was such a chunk and file, or 0 if there wasn't.

PRAY MAKE (integer) which_journal_spot (integer) journal_name (string) which_pray_spot (integer) pray_name (string) report_destination (variable)
Please see the documentation accompanying the praybuilder on CDN

Suffice it to say: return value is zero for success, otherwise non-zero, and report is set to the praybuilder output for you

Also, the which_journal_spot is zero for world journal, 1 for global journal. Also the which_pray_spot is zero for "My Agents" and 1 for "My Creatures"

PRAY NEXT (string) resource_type (string) last_known (string)
This returns the name of the resource chunk directly after the named one, given that they are of the same type. It loops when it reaches the end. If the named resource cannot be found in the list of resources of the type specified, then the last resource of that type is returned. This call pairs with PRAY PREV. Compare PRAY FORE.

PRAY PREV (string) resource_type (string) last_known (string)
This returns the name of the resource chunk directly before the named one, given that they are of the same type. It loops when it reaches the end. If the named resource cannot be found in the list of resources of the type specified, then the first resource of that type is returned. This call pairs with PRAY NEXT. Compare PRAY BACK.

PRAY REFR (command)
This command refreshes the engine's view of the Resource directory. Execute this if you have reason to believe that the files in the directory may have changed. It only detects changes if there is a new file or a deleted file - if a file has only changed it won't notice. This is awkward during development, you can use PRAY KILL to kill the old file before copying the new one over. PRAY REFR forces a PRAY GARB to happen automatically.

PRAY TEST (integer) resource_name (string)
This checks for the existence of a chunk, returning zero if it is not found, and a value from 1-3 indicating the cost to load if it is.
Return values are currently defined as:
0 - Chunk not available at this time
1 - Chunk Available, Cached and ready for use
2 - Chunk available, on disk uncompressed and fine for loading
3 - Chunk available, on disk compressed and ready for loading.

Thus the return value could be thought of as the cost of loading, where 1 is no cost, and 3 is high cost.


Scripts

CAOS (string) inline (integer) state_trans (integer) p1 (anything) p2 (anything) commands (string) throws (integer) catches (integer) report (variable)
Executes the specified CAOS commands instantly. The local environment (_IT_ VAxx TARG OWNR etc.) will be promoted to the script's environment if inline is non-zero. If state_trans is non-zero, then FROM and OWNR are propogated, if zero, then the script is run orphaned. CAOS returns the output of the script. As you can put multiple scripts through in one call, the output is potentially concatenated. Note that all sets of scripts are executed in the same virtual machine if inline is non-zero, otherwise the virtual machine is reset before each script is passed. The params _p0_ and _p1_ are passed in as the parameters to the script, even when inline. You can execute "outv 7 endm scrp 3 7 11 6 outv 3 endm outv 9", which will make a script 3 7 11 6 and return "79".

If throws is non-zero then the system will throw exceptions, otherwise it will return "***" with report set to the exception sid in the CAOS catalogue TAG. If catches is non-zero then the system will catch any run errors encountered and return them in report, having set the return value to "###" first.

GIDS FMLY (command) family (integer)
Output the genus numbers for which there are scripts in the scriptorium for the given family. List is space delimited.

GIDS GNUS (command) family (integer) genus (integer)
Output the species numbers for which there are scripts in the scriptorium for the given family and genus. List is space delimited.

GIDS ROOT (command)
Output the family numbers for which there are scripts in the scriptorium. List is space delimited.

GIDS SPCS (command) family (integer) genus (integer) species (integer)
Output the event numbers of scripts in the scriptorium for the given classifier. List is space delimited.

INST (command)
This command indicates that the following commands should execute in a single tick - ie the script cannot be interrupted by the script 'scheduler'. This can be important for certain tasks which might leave an agent in an undefined (and dangerous) state if interrupted. The INST state is broken either manually, using a SLOW command, or implictly, if a blocking instruction is encountered (eg WAIT). Blocking instructions force the remainder of the script's timeslice to be discarded.

JECT (command) cos_file (string) flags (integer)
Injects a COS file from the bootstrap directory. The file is searched for (case insensitively) in all bootstrap subdirectories. You must specify the file extension (it doesn't have to be .cos). Flags is a combination of what you want to inject:

1 - Remove sctipt
2 - Event scripts
4 - Install script

The scripts (if present) are injected in that order. So, setting flags to 7 will fully uninstall and reinstall the cos file. Error messages and output are written to the current output stream.

LOCK (command)
Prevent the current script being interrupted until UNLK. Normally, events other than timer scripts interrupt (abort) currently running scripts. You can also use INST for similar, stronger protection.

SCRX (command) family (integer) genus (integer) species (integer) event (integer)
Remove specified script from the scriptorium.

SLOW (command)
Turn off INST state.

SORC (string) family (integer) genus (integer) species (integer) event (integer)
Returns the source code for the specified script. Use the GIDS commands to find available scripts.

SORQ (integer) family (integer) genus (integer) species (integer) event (integer)
Returns 1 if the script is in the scriptorium, or if there is a general event script for the entire genus, or family. Returns 0 if there is no matching script.

STOP (command)
Stops running the current script. Compare STPT.

STPT (command)
Stops any currently running script in the target agent. See also STOP.

UNLK (command)
End the LOCK section.

WAIT (command) ticks (integer)
Block the script for the specified number of ticks. This command does an implicit SLOW.


Sounds

FADE (command)
Fade out a controlled sound.

MCLR (command) x (integer) y (integer)
Clear the music for the metaroom at the given location.

MIDI (command) midi_file (string)
Plays a MIDI file. Set to an empty string to stop the MIDI player.

MMSC (command) x (integer) y (integer) track_name (string)
Associates a music track with the meta room at the specified coordinates.

MMSC (string) x (integer) y (integer)
Returns the name of the music track played at the metaroom in the given location.

MUTE (integer) andMask (integer) eorMask (integer)
This returns (and potentially sets) the mute values for the sound managers in the game. Sensible settings for the parameters are as follows:

andMaskeorMaskreturns
033 - Mutes both sound and music
300 for no mute
1 for sound muted
2 for music muted
3 for both muted
Sets nothing
12Returns 2 for music muted, or 3 for both muted
Only sets mute on music, leaves sound alone

RCLR (command) x (integer) y (integer)
Clear the music for the room at the given location.

RMSC (command) x (integer) y (integer) track_name (string)
Associates a music track with the room at the specified coordinates. This overrides any track specified for the metaroom that the room is in.

RMSC (string) x (integer) y (integer)
Returns the name of the music track played at the room in the given location.

SEZZ (command) text (string)
Makes the TARG agent speak the specified text with voice as set by VOIS or VOIC. If TARG is a creature then it will be spoken properly (speech bubble et al).

SNDC (command) sound_file (string)
Plays a controlled sound effect emitted from the target. Updates volume and panning as the agent moves.

SNDE (command) sound_file (string)
Play a sound effect audible as if emitted from target's current location.

SNDL (command) sound_file (string)
Play a sound effect as in SNDC, only the sound is looped.

SNDQ (command) sound_file (string) delay (integer)
As SNDE, only with a delay before playing.

STPC (command)
Stops a controlled sound.

STRK (command) latency (integer) track (string)
This triggers the music track specified. The track will play for at least latency seconds before being overridden by room or metaroom music.

VOIC (command) genus (integer) gender (integer) age (integer)
This sets the TARG agent's voice to the specified creature voice, using standard cascade techniques to select the nearest match. On failure, "DefaultVoice" will be reloaded. Use SEZZ to actually say something.

VOIS (command) voice_name (string)
Sets the TARG agent's voice to the specified value. The voice name must be valid in the catalogue. If it fails, then "DefaultVoice" will be reloaded. Use SEZZ to actually say something.

VOIS (string)
This returns the voice name for the TARG agent. (Unless it has been serialised in :( In which case it returns "Lozenged" if the agent had a voice before the save, or "" as normal if the agent can't speak.)

VOLM (command) channel (integer) volume (integer)
Set overall the volume of the sound effects (channel 0), the MIDI (channel 1) or the generated music (channel 2). Values range from -10000 (silent) to 0 (loudest).

VOLM (integer) channel (integer)
Returns the overall the volume of the sound effects (channel 0), the MIDI (channel 1) or the generated music (channel 2). Values range from -10000 (silent) to 0 (loudest). Currently not supported for MIDI.


Time

BUZZ (command) interval (integer)
Sets the ideal interval in milliseconds between each tick. However fast the machine, it won't tick quicker than this, but it might tick slower. You can find the actual time taken with RACE. Changing this from the default value of 50 midgame will damage profiling and seasons. Things such as creature brains are designed for the default 50 millisecond update interval. Change this with caution!

BUZZ (integer)
Returns the ideal interval in milliseconds between each tick. You can find the actual interval with RACE.

DATE (integer)
Returns the day within the current season, from 0 to GAME "engine_LengthOfSeasonInDays" - 1. See also HIST DATE.

DAYT (integer)
Returns the current day of the month

ETIK (integer)
Returns the number of ticks since the engine was loaded in.

HIST DATE (integer) world_tick (integer)
Returns the day within the current season. This is the same as DATE. See also WTIK and HIST WTIK.

HIST SEAN (integer) world_tick (integer)
Returns the current season for a given world tick. This is the same as SEAN. See also WTIK and HIST WTIK.

HIST TIME (integer) world_tick (integer)
Returns the time of day for a given world tick. This is the same as TIME. See also WTIK and HIST WTIK.

HIST YEAR (integer) world_tick (integer)
Returns the number of game years elapsed for a given world tick. This is the same as YEAR. See also WTIK and HIST WTIK.

MONT (integer)
Returns the month of the year

MSEC (integer)
Returns a time stamp measured in milliseconds. It is not specified when the time is measured from; the stamp is only guaranteed to be consistent during one session.

PACE (float)
Returns the tick rate satisfaction factor.
Factor 1 - ticks are taking the time we would expect them to, which is set by BUZZ.
Factor more than 1 - the engine is running too slowly.
Factor less than 1 - the engine is leaving spare processing time.
This is averaged over the last 10 ticks.

Agents can look at this to adjust the resources they use according to current spare processing time. For example, if you have a random snowflake generator in winter, you could increase the chance of generation if PACE is low, and decrease the chance if PACE is high. When you do this remember that computers will be arbitarily faster in the future, so you should place an extra upper limit on the number of snowflakes to stop them filling the whole screen.

Note that PACE only measures the time the engine takes for tick processing, not for handling requests from external applications, or adding Windows events to its internal queue. Because of this, you should aim for a value which is a bit less than 1.

Compare RACE.

RACE (integer)
Returns the time in milliseconds which the last tick took overall. This differs from PACE in that on fast machines it will have a minimum of 50 milliseconds, or the value set by BUZZ. It accounts for all the time in the tick, including event handling and window processing.

RTIF (string) real_time (integer) format (string)
Takes a real world time, as returned by RTIM or HIST RTIM and converts it to a localised string for display. The format string is made up of any text, with the following special codes:

%a - Abbreviated weekday name
%A - Full weekday name
%b - Abbreviated month name
%B - Full month name
%c - Date and time representation appropriate for locale
%d - Day of month as decimal number (01 - 31)
%H - Hour in 24-hour format (00 - 23)
%I - Hour in 12-hour format (01 - 12)
%j - Day of year as decimal number (001 - 366)
%m - Month as decimal number (01 - 12)
%M - Minute as decimal number (00 - 59)
%p - Current locale�s AM/PM indicator for 12-hour clock
%S - Second as decimal number (00 - 59)
%U - Week of year as decimal number, with Sunday as first day of week (00 - 53)
%w - Weekday as decimal number (0 - 6; Sunday is 0)
%W - Week of year as decimal number, with Monday as first day of week (00 - 53)
%x - Date representation for current locale
%X - Time representation for current locale
%y - Year without century, as decimal number (00 - 99)
%Y - Year with century, as decimal number
%z, %Z - Time-zone name or abbreviation; no characters if time zone is unknown
%% - Percent sign

The # flag may prefix any formatting code, having the following meanings:
%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#% # flag is ignored.
%#c Long date and time representation, appropriate for current locale. For example: Tuesday, March 14, 1995, 12:41:29.
%#x Long date representation, appropriate to current locale. For example: Tuesday, March 14, 1995.
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y Remove leading zeros (if any).

You probably want to READ any formatted string you use from a catalogue file.

RTIM (integer)
Returns the current real world time. This is measured in seconds since midnight, 1 January 1970 in UTC. To display, use RTIF.

SCOL (integer) and_mask (integer) eor_mask (integer) up_speeds (byte-string) down_speeds (byte-string)
Set an AND and an EOR mask, to control the following scrolling functions:

1 - Screen edge nudgy scrolling
2 - Keyboard scrolling
4 - Middle mouse button screen dragging
8 - Mouse wheel screen scrolling

The byte strings is used for nudgy and keyboard scrolling. The defaults are [1 2 4 8 16 32 64] and [0 1 2 4 8 16 32]. They represent the number of pixels scrolled each consecutive tick, as the scrolling gets slower and faster.

If you use [] for a byte string, then the string won't be changed at all.

SEAN (integer)
Returns the current season. This can be
0 - spring
1 - summer
2 - autumn
3 - winter

The GAME variable engine_LengthOfSeasonInDays sets the season length. See also HIST SEAN.

TIME (integer)
Returns the time of day. This can be
0 - dawn
1 - morning
2 - afternoon
3 - evening
4 - night

The GAME variable engine_LengthOfDayInMinutes sets the day length. See also HIST TIME.

WOLF (integer) kanga_mask (integer) eeyore_mask (integer)
Provides various functions to distort space-time and otherwise help with wolfing runs. Set an AND and an EOR mask, to control the following bits:

1 - Display rendering. Turning it off speeds the game up.
2 - Fastest ticks. The game usually runs at a maximum of 20 frames per second. If this is set, it instead runs as fast as it can.
4 - Refresh display at end of tick. If set, then the display is updated at the end of the tick, and the flag is cleared.
8 - Autokill. If set, agents which generate run errors are automatically killed, as the command line option.

WPAU (command) paused (integer)
Stops world ticks from running. Days, seasons and years won't change and any delayed messages are paused, as are CAs and some sound effects. Set to 1 to pause, 0 to run. Use along with PAUS.

WPAU (integer)
Returns 1 if world ticks are paused, or 0 otherwise.

WTIK (integer)
Returns the number of ticks since the world was first made. For debugging purposes only you can change this value with DBG: WTIK.

YEAR (integer)
Returns the number of game years elapsed. The GAME variable engine_NumberOfSeasons sets the year length. See also HIST YEAR.


Variables

ABSV (command) var (variable)
Makes a variable positive (its absolute value), so if var is negative var = 0 - var, otherwise var is left alone.

ACOS (float) x (float)
Returns arccosine of x in degrees.

ADDS (command) var (variable) append (string)
Concatenates two strings, so var = var + append.

ADDV (command) var (variable) sum (decimal)
Adds two integers or floats, so var = var + sum.

ANDV (command) var (variable) value (integer)
Peform a bitwise AND on an integer variable, so var = var & value.

ASIN (float) x (float)
Returns arcsine of x in degrees.

ATAN (float) x (float)
Returns arctangent of x in degrees.

AVAR (variable) agent (agent) index (integer)
This is the OVnn variable of the agent passed in. It is equivalent to target agent, OVnn, but means that you don't need to target it first :) You can also use them to implement primitive arrays.

CHAR (command) string (variable) index (integer) character (integer)
Sets a character in a string. String indices begin at 1.

CHAR (integer) string (string) index (integer)
Returns a character from a string. String indicies begin at 1.

COS_ (float) theta (float)
Returns cosine of theta. Theta should be in degrees.

DELE (command) variable_name (string)
Deletes the specified EAME variable.

DELG (command) variable_name (string)
Deletes the specified GAME variable.

DELN (command) variable_name (anything)
Deletes the specified NAME variable on TARG.

DIVV (command) var (variable) div (decimal)
Divides a variable by an integer or float, so var = var / div. Uses integer division if both numbers are integers, or floating point division otherwise.

EAME (variable) variable_name (string)
Very similar to GAME variables only they aren't saved or loaded with the world; they keep their value between worlds for one session of the engine. The E in EAME stands for for Engine. See the table of engine Eame Variables.

EAMN (string) previous (string)
Enumerates through EAME variable names, roughly as GAMN does through GAME variables. Start and end with an empty string.

FTOI (integer) number_to_convert (float)
Converts a floating-point value into its integer equivalent.

GAME (variable) variable_name (string)
A game variable is a global variable which can be referenced by name.
eg: SETV GAME "pi" 3.142
Game variables are stored as part of the world and so will be saved out in the world file. If a script uses a non-existant game variable, that variable will be created automatically (with value integer zero). Agents, integers, floats and strings can be stored in game variables. Variable names are case sensitive. When a new world is loaded, all the game variables are cleared.

There are some conventions for the variable names:
engine_ for Creatures Engine
cav_ for Creatures Adventures
c3_ for Creatures 3

It's important to follow these, as 3rd party developers will just use whatever names they fancy. DELG deletes a game variable. See also the table of engine Game Variables.

GAMN (string) previous (string)
Enumerates through game variable names. Pass in an empty string to find the first one, and then the previous one to find the next. Empty string is returned at the end.

GNAM (string)
Returns the game name. For example "Creatures 3".

ITOF (float) number_to_convert (integer)
Converts an integer value into its floating-point equivalent.

LOWA (string) any_old (string)
Converts the given string into all lower case letters.

MAME (variable) variable_name (anything)
Machine variable version of NAME. Accesses the same variables, only via OWNR rather than TARG. This is the same difference as between MVxx and OVxx.

MODU (string)
Returns a string listed the loaded modules, and the display engine type. You can use SINS to parse this for particular values.

MODV (command) var (variable) mod (integer)
Gives the remainder (or modulus) when a variable is divided by an integer, so var = var % mod. Both values should to be integers.

MULV (command) var (variable) mul (decimal)
Multiplies a variable by an integer or float, so var = var * mul.

MVxx (variable)
MV00 to MV99 are variables specific to an agent. They are read from OWNR, the owner agent of the current script. These are the exact same variables as OVxx, except read from owner not targ. If owner and targ are the same, then OV23 is MV23, for example.

NAME (variable) variable_name (anything)
This is a named variable, similar to a GAME variable, only local to the target agent. See also MAME. The "name" of the variable is not limited to strings, but can be anything stored in a variable. i.e. integer, float, string, even an agent.

NAMN (command) previous (variable)
Enumerates through NAME variable names, roughly as GAMN does through GAME variables. Start and end with an empty string.

NEGV (command) var (variable)
Reverse the sign of the given integer or float variable, so var = 0 - var.

NOTV (command) var (variable)
Peform a bitwise NOT on an integer variable.

ORRV (command) var (variable) value (integer)
Peform a bitwise OR on an integer variable, so var = var | value.

OVxx (variable)
OV00 to OV99 are variables specific to an agent. They are read from TARG, the target agent. You can also access these same variables via owner using MVxx.

RAND (integer) value1 (integer) value2 (integer)
Returns a random integer between value1 and value2 inclusive of both values. You can use negative values, and have them either way round.

READ (string) catalogue_tag (string) offset (integer)
Returns a string from the catalogue. This is used for localisation. offset 0 is the first string after the TAG command in the catalogue file. See also REAN and WILD.

REAF (command)
Refreshes the catalogue from files on disk, from the main catalogue directory and the world catalogue directory. These are normally read in at startup, when a new world is read in, or when the PRAY resources system installs a catalogue file. Use while developing CAOS programs to refresh the catalogue as you add entries.

REAN (integer) catalogue_tag (string)
Returns the number of entries in the catalogue for the given tag. For the same tag, you can READ values from 0 to one less than REAN returns.

REAQ (integer) catalogue_tag (string)
Returns 1 if the catalogue tag is present, 0 if not.

SETA (command) var (variable) value (agent)
Stores a reference to an agent in a variable.

SETS (command) var (variable) value (string)
Sets a variable to a string value.

SETV (command) var (variable) value (decimal)
Stores an integer or float in a variable.

SINS (integer) main (string) index_to_search_from (integer) search (string)
Looks for the search string as an exact substring of the main string (string in string). Starts searching at the given index into the main string - to find the first occurence, set this to 1. String indices begin at 1. Returns the index of the position of the substring, if found, or -1 otherwise. The search is case sensitive - use UPPA and LOWA to convert all strings first, for a case insensitive search.

SIN_ (float) theta (float)
Returns sine of theta. Theta should be in degrees.

SQRT (float) value (float)
Calculates a square root.

STOF (float) value (string)
Converts a string in decimal to a floating point number. Characters in the string after an initial number are quietly ignored. If there is no obvious number then zero is returned.

STOI (integer) value (string)
Converts a string in decimal to an integer. Characters in the string after an initial number are quietly ignored. If there is no obvious number then zero is returned.

STRL (integer) string (string)
Returns the length of a string.

SUBS (string) value (string) start (integer) count (integer)
Slices up a string, returning the substring starting at position start, with length count. String indices begin at 1.

SUBV (command) var (variable) sub (decimal)
Subtracts an integer or float from a variable, so var = var - sub.

TAN_ (float) theta (float)
Returns tangent of theta. Theta should be in degrees. Watch out for those nasty discontinuities at 90 and 270.

TARG (command) agent (agent)
This sets the TARG variable to the agent specified.

TYPE (integer) something (anything)
Determines the type of a variable. The type is one of the following:
0 - integer
1 - floating-point
2 - string
3 - simple agent
4 - pointer agent
5 - compound agent
6 - vehicle
7 - creature
ERROR codes for agents:
-1 - NULL agent handle
-2 - Unknown agent - you should never get this

UFOS (string)
This returns the equivalent of "uname -a" on compatible systems, or a description of your operating system on others. This is a descriptive string and should not be taken as fixed format, or parseable.

UPPA (string) any_old (string)
Converts the given string into all upper case letters.

VAxx (variable)
VA00 to VA99 are local variables, whose values are lost when the current script ends.

VMJR (integer)
Returns the major version number of the engine.

VMNR (integer)
Returns the minor version number of the engine.

VTOS (string) value (decimal)
Converts an integer or float into a string in decimal.

_P1_ (variable)
Returns the first parameter sent to a script.

_P2_ (variable)
Returns the second parameter sent to a script.


Vehicles

CABB (integer)
Returns relative position of bottom side of cabin.

CABL (integer)
Returns relative position of left side of cabin.

CABN (command) left (integer) top (integer) right (integer) bottom (integer)
Set a vehicles cabin rectangle. The cabin is the area in which agents inside the vehicle are kept. The rectangle is relative to the position of the vehicle. Default cabin is the bounding rectangle of part 0. You might want to use ATTR to set attribute Greedy Cabin, on the vehicle. This will make it automatically pick up items which are dropped in the cabin.

CABP (command) plane (integer)
Set the plane that vehicle passengers are at. This is relative to the vehicle's plane.

CABP (integer)
Returns the plane that passengers of the vehicle are at.

CABR (integer)
Returns relative position of right side of cabin.

CABT (integer)
Returns relative position of topside of cabin.

CABV (command) cabin_room_id (integer)
Sets the room number which things in the cabin think they are in. By default, the value is -1, and the room is the one underneath wherever the agent happens to be. Make sure you set this if the vehicle ever remotely leaves the room system. This command effects values returned from ROOM and GRID. It won't apply to some aspects of Creatures in the vehicle.

CABV (integer)
Returns the cabin room number.

CABW (command) cabin_capacity (integer)
Set the capacity or width of the cabin. This will determine how many passengers the cabin can hold, each passenger will be on a separate plane within the cabin. Use CABP to set the plane of the first agent relative to the cabin. The default width is zero, this means that the cabin will accept any number of passengers and will place them all on the same plane.

DPAS (command) family (integer) genus (integer) species (integer)
Drop all passengers matching classifier.

EPAS (command) family (integer) genus (integer) species (integer)
Enumerate over owner vehicle's passengers which match the given classifier. Similar to ENUM.

GPAS (command) family (integer) genus (integer) species (integer) rect_to_use (integer)
Collect all nearby agents matching the classifier as passengers.
rect_to_use 0 : Nearby means touching bounding rectangle of agent
rect_to_use 1 : Nearby means touching cabin rectangle

NEW: VHCL (command) family (integer) genus (integer) species (integer) sprite_file (string) image_count (integer) first_image (integer) plane (integer)
Create a new vehicle. Parameters are the same as NEW: COMP.

RPAS (command) vehicle (agent) passenger (agent)
Specified vehicle drops the specified passenger.

SPAS (command) vehicle (agent) new_passenger (agent)
Specified vehicle picks up the specified passenger.


World

DELW (command) world_name (string)
Deletes the specified world directory.

LOAD (command) world_name (string)
Loads the specified world at the start of the next tick. See also QUIT for important information about using INST. See BOOT and engine_no_auxiliary_bootstrap_nnn for extra information about bootstrapping a world.

NWLD (integer)
Returns the number of world directories.

PSWD (command) password (string)
Sets the password for the next world loaded. The world must be loaded (and saved) before it is actually set.

PSWD (string) worldIndex (integer)
Returns the password for the specified world. If the world is not password protected the return value will be an empty string.

QUIT (command)
Quits the engine at the start of the next tick, without saving any changes. Call SAVE first to make it save the current world. If doing a sequence like "SAVE QUIT" or "SAVE LOAD menu", do it in an INST section. Otherwise it will sometimes save between the two instructions, meaning it quits (or loads menu) immediately upon reloading.

RGAM (command)
Refresh all settings that are always read from game variables at start up e.g. the length of a day. This allows you to change such setting on the fly.

SAVE (command)
Saves the current world at the start of the next tick. See also QUIT for important information about using INST.

TNTW (command) index (integer)
This tints the TARG agent with the global tint manager at index. Specify the PART first for compound agents. See also TINT.

WNAM (string)
Returns the name of the currently loaded world.

WNTI (integer) world (string)
This returns the index of the world. If you pass in a world name which is not within the system, -1 is returned.

WRLD (command) world_name (string)
Creates a new world directory for the specified world.

WRLD (string) world_index (integer)
Returns the name of the world specified by world_index which must be in the range 0 to (NWLD-1).

WTNT (command) index (integer) red_tint (integer) green_tint (integer) blue_tint (integer) rotation (integer) swap (integer)
This sets up the world (global) tint table. The index is the number associated with the tint table - (keep it small please) and the r,g,b is the tint level. Rotation and Swap work as for pigment bleed genes.

WUID (string)
Returns the unique identifier of the currently loaded world.


Attribute Flags

Number (for ATTR) Name Description
1 Carryable Can be picked up by things other than creatures, vehicles and the pointer.
2 Mouseable Can be picked up by the mouse.
4 Activateable Can be activated using the mouse - otherwise CLAC and CLIK style events don't get sent when you click on the agent.
8 Greedy Cabin When set on a vehicle, it will automatically pick up things dropped in its cabin.
16 Invisible Creatures don't see you - applies to ESEE and STAR on creatures, as well as internal creature code.
32 Floatable Agent floats relative to the screen. Move it with FLTO. If you call FREL, the agent will float relative to another agent instead of the screen.
64 Suffer Collisions Will collide with room boundaries, according to its PERM.
128 Suffer Physics Agent falls with proper physics, including gravity, air resistance and friction. Otherwise, it simply moves with velocity.
256 Camera Shy Agent can't be seen on a remote camera (PAT: CMRA) or photograph (SNAP). For vehicles, the contents is shy as well.
512 Open Air Cabin When set on a vehicle, it allows creatures to see and activate its passengers. The default behaviour is that they can't.
1024 Rotatable When set on an agent the various rotation commands (SPIN, ROTN, AVEL etc.) can be used.
2048 Presence An agent with this attribute set has a circular physical presence in the world and receives Impact script callbacks.


Creature Permissions

Number (for BHVR) Name Description
1 Activate 1 Creature can activate 1 this agent.
2 Activate 2 Creature can activate 2 this agent.
4 Deactivate Creature can deactivate this agent.
8 Hit Creature can hit this agent.
16 Eat Creature can eat this agent.
32 Pick Up Creature can pick up this agent.


Debug Keys

Key Action
Pause Performs a DEBUG pause on the game (no more ticking messages are sent)
Space Even when debug paused, this causes a tick to execute - allowing single stepping of the world
Key Action
Insert Turns the mapline display on or off
Page Up Moves to the previous Metaroom
Page Down Moves to the next Metaroom
Home Cycles through the resolutions available to the display engine
Delete Toggles the highlight box around agents which a creature is paying attention to
End Toggles the skeleton update speed between normal and double speed
Key Action
Numpad 0 Sets creature permission highlights to CanActivate1
Numpad 1 Sets creature permission highlights to CanActivate2
Numpad 2 Sets creature permission highlights to CanDeactivate
Numpad 3 Sets creature permission highlights to CanHit
Numpad 4 Sets creature permission highlights to CanEat
Numpad 5 Sets creature permission highlights to CanPickUp
Numpad 6 Turns creature permission highlights off


Eame Variables

Variable (for EAME) Expected Type Default Description
engine_no_auxiliary_bootstrap_nnn Integer 0 Set to non-zero to prevent LOAD using that auxiliary Bootstrap directory for new worlds. nnn can be 0 for the main Bootstrap directory, or the number of an auxiliary one. The setting is stored for each world in files in the world's directory.
engine_clone_upon_import Integer 0 Set to 1 to force PRAY IMPO to clone all creatures.
engine_screensaver Integer 0 or 1 Returns 1 if the engine is in screen saver mode, 0 otherwise. This should treated as a read only game variable
engine_scrpreview Integer 0 or 1 Returns 1 if the engine is in screen saver preview mode, 0 otherwise. This should treated as a read only game variable
engine_scrconfig Integer 0 or 1 Returns 1 if the engine is in screen saver configuration mode, 0 otherwise. This should treated as a read only game variable


Emitter Locus Numbers

'Organ' Tissue Locus ID Name Description
0 Brain Lobe tissue ID defined in genome 0-3 Neuron 0 states 0 to 3.  
    4-7 Neuron 1 states 0 to 3.  
    ... ...  
    252-255 Neuron 63 states 0 to 3.  
'Organ' Tissue Locus ID Name Description
1 Creature        
  0 Somatic      
    0 Muscles How much energy has been expended on movement this tick.
'Organ' Tissue Locus ID Name Description
  1 Circulatory 0-31 Floating  
'Organ' Tissue Locus ID Name Description
  2 Reproductive 0 Fertile If male has a sperm or female has an egg available
    1 Pregnant If female has both egg and sperm & so is pregnant
    2 Ovulate If low, remove any egg/sperm from .Gamete; if high, add one
    3 Receptive If >0, female is receptive to incoming sperm & will conceive
    4 Chance of Mutation  
    5 Degree of Mutation  
'Organ' Tissue Locus ID Name Description
  3 Immune 0 Dead >0 if creature is dead (allows post-mortem chemistry)
'Organ' Tissue Locus ID Name Description
  4 Sensorimotor 0 Constant Always 1.0 (for regular emitters).
    1 Asleep 1.0 if asleep, 0.0 otherwise.
    2 Coldness (DEPRECATED)
    3 Hotness (DEPRECATED)
    4 Lightlevel (DEPRECATED)
    5 Crowdedness How many and how close others of your kind are
    6 Radiation (DEPRECATED)
    7 Timeofday (DEPRECATED)
    8 Season (DEPRECATED)
    9 Air Quality How breathable is the air (0.0 for air, 1.0 for water).
    10 Upslope How steep is the slope I'm facing
    11 Downslope How steep is the slope I'm facing
    12 Headwind (DEPRECATED)
    13 Tailwind (DEPRECATED)
'Organ' Tissue Locus ID Name Description
  5 Drives 0 Drive 0  
    1 Drive 1  
    2 Drive 2  
    3 Drive 3  
    4 Drive 4  
    5 Drive 5  
    6 Drive 6  
    7 Drive 7  
    8 Drive 8  
    9 Drive 9  
    10 Drive 10  
    11 Drive 11  
    12 Drive 12  
    13 Drive 13  
    14 Drive 14  
    15 Drive 15  
    16 Drive 16  
    17 Drive 17  
    18 Drive 18  
    19 Drive 19  
'Organ' Tissue Locus ID Name Description


Game Variables

Variable (for GAME) Expected Type Default Description
engine_debug_keys Integer 1 This determines if the debug keys are operative. If the value is 1 then the keys described in the Debug Keys table are functional. For non-numeric keypad keys, you must hold Shift down with the key.
engine_full_screen_toggle Integer 1 Alt+Enter usually toggles full screen mode. Set to 0 to disable this.
engine_SkeletonUpdateDoubleSpeed Integer 0 If non-zero, skeleton updates happen each tick. If Zero, they happen every other tick (default)
engine_creature_pickup_status Integer 0 If zero, right click on a creature is pickup. If one, right click is holding hands. If two, hold shift to pickup, don't hold shift to hold hands. If three, as two but creature must be a selectable one as according to the Grettin game variable.
engine_dumb_creatures Integer 0 If non-zero, creatures do not burble.
engine_pointerCanCarryObjectsBetweenMetaRooms Integer 0 If zero, the pointer drops objects when a metaroom change occurs. If non-zero, then it continues to carry them allowing objects to be moved between metarooms by the pointer.
engine_password String <NONE> If set, this allows the determining of the password for the world. This does not set anything other than the pswd returned - enabling world-switchers to correctly deal with the passwords.
engine_creature_template_size_in_mb Integer 1 This is the amount of data space allocated to the creature gallery sprite files. If a single life stage image set exceeds this value - problems will ensue
engine_near_death_track_name String <NONE> This sets the track (and optionally MNG file) for the track which the engine will play when a creature gets near death within the game.
engine_plane_for_lines Integer 9998 This sets the plane for lines drawn on entity images. This includes Connective agent lines and the debug cabins
engine_synchronous_learning Integer 0 By default learning is asynchronous, so the creature learns from all STIMs. Set to 1 to make the creatures learn only from STIMs caused by the action they are thinking about carried out by the agent their attention is on.
engine_zlib_compression Integer 6 Saved worlds and other archives are compressed using zlib. This sets the compression level. The value ranges between: 0 - No compression, 1 - Best speed, 9 - Best compression.
engine_other_world String <NONE> Used by FILE OOPE to allow saving to other world's journal directories.
engine_netbabel_save_passwords Integer 0 Set to 1 to tell the netbabel module to save passwords in user.cfg, 0 for it to forget them.
Variable (for GAME) Expected Type Default Description
engine_multiple_birth_first_chance Float 0.0 This sets the chance (from 0 to 1) that a mate event will result in multiple pregnancies
engine_multiple_birth_subsequent_chance Float 0.0 This sets the subsequent chance (from 0 to 1) that more than two children are conceived
engine_multiple_birth_maximum Integer 1 This sets the maximum number of births allowed by the engine
engine_multiple_birth_identical_chance Float 0.5 This sets the chance that the children will be genetically identical
Variable (for GAME) Expected Type Default Description
engine_LengthOfDayInMinutes Integer 0 This sets the number of minutes in a day. (Game time)
engine_LengthOfSeasonInDays Integer 0 This sets the number of days in a season. (Game time)
engine_NumberOfSeasons Integer 0 This sets the number of seasons in a year. (Game Time)
Variable (for GAME) Expected Type Default Description
engine_mute Integer 0 This sets whether (non zero) or not (zero) to mute the MIDI player
engine_playAllSoundsAtMaximumLevel Integer 0 If non-zero, all sounds played by agents are set to full volume and center pan.
engine_usemidimusicsystem Integer 0 If non-zero, this tells the engine to use MIDI music instead of the MUNGED data usually used.
Variable (for GAME) Expected Type Default Description
cav_birthdate String <NONE> If set, the engine uses this to inform the birthday agent when it is the player's birthday.
cav_quittime String <NONE> If set, the engine uses this to inform the countdown clock agent to show its countdown, and also to quit the game at the specified time.
cav_gamelengthIsPerDay String <NONE> If set, the engine uses this to inform the countdown clock agent when the maximum play time for the day is up.
cav_useparentmenu Integer 0 If non-zero, this causes the engine to deal with extra information such as the countdown clock and birthday agents. These are activated by registry settings.
cav_CountdownClockAgent Agent NULL If not null, countdown messages are sent to this agent.
cav_BirthdayBannerAgent Agent NULL If not null, birthday messages are sent to this agent.
Variable (for GAME) Expected Type Default Description
engine_distance_before_port_line_warns Float 600.0 At this distance, port lines will pulse red not blue to indicate that they are nearning their maximum length before they snap
engine_distance_before_port_line_snaps Float 800.0 At this distance, port lines will simply snap.


Message Numbers

Number Name Description
0 Activate 1 Calls the Activate 1 script. If the message is from a creature, and the permissions set with BHVR disallow it, then the script is not executed.
1 Activate 2 Calls the Activate 2 script. The permissions set with BHVR are checked first.
2 Deactivate Calls the Deactivate script. The permissions set with BHVR are checked first.
3 Hit Calls the Hit script. If the message is from a creature, and the permissions set with BHVR disallow it, then the message is not sent.
4 Pickup The agent is picked up by the agent that the message was FROM. The permissions set with BHVR are checked first.
5 Drop If the agent is being carried, then it is dropped.
12 Eat Calls the Eat script. The permissions set with BHVR are checked first.
13 Hold Hands Causes a creature to hold hands with the pointer.
14 Stop Holding Hands Causes a creature to stop holding hands with the pointer. Since messages take a tick to be procesed, calling NOHH is quicker than using this message.


Receptor Locus Numbers

'Organ' Tissue Locus ID Name Description
0 Brain Lobe tissue ID defined in genome 0-3 Neuron 0 states 0 to 3.  
    4-7 Neuron 1 states 0 to 3.  
    ... ...  
    252-255 Neuron 63 states 0 to 3.  
'Organ' Tissue Locus ID Name Description
1 Creature 0 Somatic 0 Age 0 If on and currently BABY, become CHILD.
    1 Age 1 If on and currently CHILD, become ADOLESCENT.
    2 Age 2 If on and currently ADOLESCENT, become YOUTH.
    3 Age 3 If on and currently YOUTH, become ADULT.
    4 Age 4 If on and currently ADULT, become OLD.
    5 Age 5 If on and currently OLD, become SENILE.
    6 Age 6 If on DIE IMMEDIATELY of old age
'Organ' Tissue Locus ID Name Description
  1 Circulatory 0-31 Floating  
'Organ' Tissue Locus ID Name Description
  2 Reproductive 0 Ovulate If low, remove any egg/sperm from .Gamete; if high, add one
    1 Receptive If >0, female is receptive to incoming sperm & will conceive
    2 Chanceofmutation  
    3 Degreeofmutation  
'Organ' Tissue Locus ID Name Description
  3 Immune 0 Die If on, creature dies (ill health, poison, starvation...)
'Organ' Tissue Locus ID Name Description
  4 Sensorimotor 0 Involuntary 0 Trigger flinching.
    1 Involuntary 1 Lay egg.
    2 Involuntary 2 Sneeze.
    3 Involuntary 3 Cough.
    4 Involuntary 4 Shiver.
    5 Involuntary 5 Sleep
    6 Involuntary 6 Fainting
    7 Involuntary 7 Drowning
'Organ' Tissue Locus ID Name Description
    8 Gait 0 Trigger various walking gaits (0=default).
    9 Gait 1  
    10 Gait 2  
    11 Gait 3  
    12 Gait 4  
    13 Gait 5  
    14 Gait 6  
    15 Gait 7  
    16 Gait 8  
    17 Gait 9  
    18 Gait 10  
    19 Gait 11  
    20 Gait 12  
    21 Gait 13  
    22 Gait 14  
    23 Gait 15  
    24 Gait 16  
'Organ' Tissue Locus ID Name Description
  5 Drives 0 Drive 0  
    1 Drive 1  
    2 Drive 2  
    3 Drive 3  
    4 Drive 4  
    5 Drive 5  
    6 Drive 6  
    7 Drive 7  
    8 Drive 8  
    9 Drive 9  
    10 Drive 10  
    11 Drive 11  
    12 Drive 12  
    13 Drive 13  
    14 Drive 14  
    15 Drive 15  
    16 Drive 16  
    17 Drive 17  
    18 Drive 18  
    19 Drive 19  
'Organ' Tissue Locus ID Name Description


Script Numbers

Number Name Description
0 Deactivate Called when the agent receives a deactivate message.
1 Activate 1 Called when the agent receives an activate 1 message.
2 Activate 2 Called when the agent receives an activate 2 message.
3 Hit Called when the agent receives a hit message.
4 Pickup Called when the agent has been picked up by something other than a vehicle.
5 Drop Called when the agent has been dropped by something other than a vehicle.
6 Collision Called when the agent collides with an obstacle. _P1_ and _P2_ are the x and y components of the collision velocity.
7 Bump Called when a creature walks into a wall.
8 Impact Called when an agent's presence impacts with another agent's presence (this is assuming both agents have their presence switched on).
9 Timer Called at a regular time interval, as set by TICK.
10 Constructor Called on creation.
12 Eat Called when the creature eats something.
13 Start Hold Hands Called when a creature starts holding hands with the pointer.
14 Stop Hold Hands Called when a creature stops holding hands with the pointer.
Number Name Description
16 Quiescent on Agents Scripts 16 - 30 are executed on a creature when it decides to do something with its attention on an ordinary agent (rather than a creature). The script should perform this action. Quiescent means stand and watch it. The catalogue entry "Action Script To Neuron Mappings" maps the brain to these scripts, although which scripts require an it object are hard-wired.
17 Activate 1 on Agents Activate 1 it.
18 Activate 2 on Agents Activate 2 it.
19 Deactivate on Agents Deactivate it.
20 Approach on Agents Go up and look at it.
21 Retreat on Agents Walk or run away from it.
22 Pickup on Agents Pick it up.
23 Drop on Agents Drop anything you're carrying.
24 Need on Agents Say what's bothering you.
25 Rest on Agents Becoming sleepy.
26 West on Agents Walk idly to west.
27 East on Agents Walk idly to east.
28 Eat on Agents Eat it.
29 Hit on Agents Hit it.
30 Undefined on Agents For future expansion.
31 Undefined on Agents For future expansion.
Number Name Description
32 Quiescent on Creatures Scripts 32 - 47 are executed on a creature when it decides to do something with its attention on another creature. Quiescent means stand and twiddle your thumbs.
33 Activate 1 on Creatures Mating script.
34 Activate 2 on Creatures Mating script.
35 Deactivate on Creatures Deactivate it.
36 Approach on Creatures Go up and look at it.
37 Retreat on Creatures Walk or run away from it.
38 Pickup on Creatures Pick it up.
39 Drop on Creatures Drop anything you're carrying.
40 Need on Creatures Say what's bothering you.
41 Rest on Creatures Rest or sleep.
42 West on Creatures Walk idly to west.
43 East on Creatures Walk idly to east.
44 Eat on Creatures Eat it.
45 Hit on Creatures Hit it.
46 Undefined on Creatures For future expansion.
47 Undefined on Creatures For future expansion.
Number Name Description
64 Flinch Involuntary action called when the creature flinches.
65 Lay Egg Involuntary action called when the creature lays an egg.
66 Sneeze Involuntary action called when the creature sneezes.
67 Cough Involuntary action called when the creature coughs.
68 Shiver Involuntary action called when the creature shivers.
69 Sleep Involuntary action called when the creature sleeps.
70 Fainting Involuntary action called when the creature faints.
71 Unassigned Involuntary action for future expansion.
72 Die Special involuntary action called when a creature dies. Any death animations go here.
Number Name Description
73 Raw Key Down Called when a key is pressed and IMSK is set. The key code is sent in _P1_.
74 Raw Key Up Called when a key is released and IMSK is set. The key code is sent in _P1_.
75 Raw Mouse Move Called when the mouse moves and IMSK is set. The new x and y position is sent in _P1_ and _P2_
76 Raw Mouse Down Called when a mouse button is pressed and IMSK is set. The button is sent in _P1_ - 1 left, 2 right, 4 middle.
77 Raw Mouse Up Called when a mouse button is released and IMSK is set. The button is sent in _P1_ - 1 left, 2 right, 4 middle.
78 Raw Mouse Wheel Called when the mouse wheel is moved and IMSK is set. The delta value is sent in _P1_ - 120 units per 'click'.
79 Raw Translated Char Called when a translated character is received and IMSK is set. For example, on Japanese systems the raw key down and up codes can be in Roman characters, but the Input Method Editor converts them to Japanese characters, which are sent to the game with this message. The translated key code is sent in _P1_. You can use this for character input, but it is easier to use PAT: TEXT.
Number Name Description
92 UI Mouse Down Called when the mouse clicks on an agent.
Number Name Description
101 Pointer Activate 1 Called on the pointer when an agent is activated 1. The script has the same classifier as the agent being activated.
102 Pointer Activate 2 Called on the pointer when an agent is activated 2. The script has the same classifier as the agent being activated.
103 Pointer Deactivate Called on the pointer when an agent is deactivated. The script has the same classifier as the agent being deactivated.
104 Pointer Pickup Called on the pointer when an agent is activated 1. The script has the same classifier as the agent being activated.
105 Pointer Drop Called on the pointer when an agent is dropped. The script has the same classifier as the agent being dropped.
110 Pointer Port Select Called on the pointer when you manipulate a port.
111 Pointer Port Connect Called on the pointer when you complete the connection between two ports.
112 Pointer Port Disconnect Called on the pointer when you complete the disconnection of two previously connected ports.
113 Pointer Port Cancel Called on the pointer if you cancel a port change part way through.
114 Pointer Port Error Called on the pointer if there is some error with the configuration of ports the user is trying to make.
116 Pointer Clicked Background Called when the pointer is clicked but there aren't any agents under it.
117 Pointer Action Dispatch Called on the pointer to tell it what action clicking would take on the creature under it. _P1_ says what will happen: 0 means no action or not above a creature, 1 means deactivate (slap), 2 means activate 1 (tickle).
118 Connection Break Called on an agent when any of its ports are broken as a result of exceeding the maximum connection distance.
Number Name Description
120 Selected Creature Changed Called on all agents with this script when the selected creature is changed by NORN. _P1_ is the new creature, _P2_ is the previously selected creature.
121 Vehicle Pickup Called when an agent has been picked up by a vehicle.
122 Vehicle Drop Called when an agent has been dropped by a vehicle.
123 Window Resized Called on all agents with this script whenever the main view is resized.
124 Got Carried Agent Tells an agent that they have just picked something up.
125 Lost Carried Agent Tells an agent that they have just dropped something.
126 Make Speech Bubble Called when a creature speaks, so scripts can display a speech bubble. Every agent which has this script is called. _P1_ is the text being spoken, _P2_ is the creature who is speaking.
127 Life Event Called whenever there is a new life event, whether an event built into the engine, or a custom event sent with HIST EVNT. _P1_ is the moniker that the event happened to, _P2_ is the event number as an index into the events for that moniker.
128 World Loaded Called when the world had just been loaded, whether from bootstrap or from a saved file.
Number Name Description
135 Net Online Connection to the Babel server has been made.
136 Net Offline Connection to the Babel server is broken.
137 User Online User chosen with NET: WHON has gone online. _P1_ contains the user's id.
138 User Offline User chosen with NET: WHON has gone offline. _P1_ contains the user's id.
150 Creature Navigation Callback Valid It Called by the approach command with _P1_ and _P2_ set to the IT object's X and Y coordinates respectively.
151 Creature Navigation Callback Outside Room System Called by the approach command when you are unable to use the CA because you're outside the room system.
152 Creature Navigation Callback Neighbour Called by the approach command if there is no IT object. _P1_ and _P2_ are set to the X and Y coordinates of the room's centre with the highest (or lowest if retreating) smell of IT nearby.
153 Creature Navigation Callback Link As for 152 but called when the best room is a link.
154 Creature Navigation Callback Current Room Best As for 152 but called when the room you're in is already the best one.
160 Creature Ageing Callback Called when the creature is about to age. _P1_ contains the value of the next age stage.
200 Mate Reserved for use in the mating scripts, but not directly used by the engine. Tells a male to mate.
255 Agent Exception This script specifies the behaviour when an agent tries to do something to an invalid agent. For example, if you try and access an OVxx with a NULL target. If this script isn't present for OWNR, you get a run time error. If it is present, that script is called and you can reset variables as necessary.


Stimulus Numbers

Number Name Description
0 Disappoint Issue to disappoint (punish) a creature for a pointless action (eg. failed to activate)
1 Pointerpat User has patted creature
2 Creaturepat Another creature has patted you
3 Pointerslap User has slapped creature
4 Creatureslap Another creature has slapped you
5 Approaching deprecated Object is approaching
6 Retreating deprecated Object is retreating
7 Bump Creature has hit a wall
8 Newobj deprecated New object has come into view
9 Gobbledygook Heard unrecognised speech
10 Pointerword Heard user speak
11 Creatureword Heard creature speak
12 Quiescent Emit PERIODICALLY while quiescent
13 Activate1 Emit AFTER activation
14 Activate2  
15 Deactivate  
16 Approach Emit PERIODICALLY while watching (after approach phase over)
17 Retreat Emit AFTER retreat
18 Get Emit AFTER get
19 Drop  
20 Expressneed Emit AFTER say need
21 Rest Emit after resting but before falling asleep
22 Sleep Emit PERIODICALLY while sleeping (later in REST action)
23 Travwesteast Emit PERIODICALLY while walking west OR east
24 Push Emit AFTER being pushed
25 Hit Emit AFTER being hit
26 Eat Emit AFTER eating
27 Ac6  
28 Invol0  
29 Invol1  
30 Invol2  
31 Invol3  
32 Invol4  
33 Invol5  
34 Invol6  
35 Invol7  
36 Approaching edge deprecated Emit AFTER moving towards an edge object
37 Retreating edge deprecated Emit AFTER moving away from an edge object
38 Falling deprecated Emit whilst falling under gravity
39 Impact Emit after a collision
40 Pointeryes Emit after user spoken verb YES
41 Creatureyes Emit after creature spoken verb YES
42 Pointerno Emit after user spoken verb NO
43 Creatureno Emit after creature spoken verb NO
44 Aggression Emit after performing a HIT
45 Mate Emit after mating
46 Oppsex tickle  
47 Samesex tickle  
48 Go nowhere  
49 Go in  
50 Go out  
51 Go up  
52 Go down  
53 Go left  
54 Go right  
55 Reached peak of smell0  
56 Reached peak of smell1  
57 Reached peak of smell2  
58 Reached peak of smell3  
59 Reached peak of smell4  
60 Reached peak of smell5  
61 Reached peak of smell6  
62 Reached peak of smell7  
63 Reached peak of smell8  
64 Reached peak of smell9  
65 Reached peak of smell10  
66 Reached peak of smell11  
67 Reached peak of smell12  
68 Reached peak of smell13  
69 Reached peak of smell14  
70 Reached peak of smell15  
71 Reached peak of smell16  
72 Reached peak of smell17  
73 Reached peak of smell18  
74 Reached peak of smell19  
75 Wait  
76 Discomfort  
77 Eaten plant  
78 Eaten fruit  
79 Eaten food  
80 Eaten animal  
81 Eaten detritus  
82 Consume alchohol  
83 Danger plant  
84 Friendly plant  
85 Play bug  
86 Play critter  
87 Hit critter  
88 Play danger animal  
89 Activate button  
90 Activate machine  
91 Got machine  
92 Hit machine  
93 Got creature egg  
94 Travelled in lift  
95 Travelled through meta door  
96 Travelled through internal door  
97 Played with toy  

666 documented commands