CAOS Documentation - Creatures Engine 2.144

Agents Brain Camera Compounds Creatures Debug Files Flow Genetics History Input Map Motion Ports Resources Scripts Sounds Time Variables Vehicles World

Attribute Flags Creature Permissions Debug Keys Emitter Locus Numbers Game Variables Message Numbers Receptor Locus Numbers Script Numbers Stimulus Numbers


Agents

ALPH (command) on_off (integer) alpha_value (integer)
Tell the agent to draw the current sprite with alpha channeling (send 1 as first parameter) or normally (send 0 as first parameter). The second parameter is the intensity 0 being no blending and 255 being maximum blending. For a compound agent remember to set the PART number.

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.

BMPS (command) pose (integer) filename (string)
Saves an image from the TARG agent's sprite file as a bitmap. The file will be saved using the specified name to the My Pictures folder.

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

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. 39 (or "unclassified") is always returned if none match.

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

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.

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 (agent)
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.

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.

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.

HEDX (float) attachment_index (integer)
This returns the X position of the TARG creature's specified attachment point in absolute (map) coordinates. Attachments go in this order: 0 - neck 1- mouth 2 - left ear 3- right ear 4 - hair (top of head)

HEDY (float) attachment_index (integer)
This returns the Y position of the TARG creature's specified attachment point in absolute (map) coordinates. Attachments go in this order: 0 - neck 1- mouth 2 - left ear 3- right ear 4 - hair (top of head)

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_.

IMGE (command) file_name (string)
The agent will save its current sprite file to a file with the given name. The file is saved to the images folder within the local world directory.This doesn't work for creatures

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.

ONTV (integer) agent (agent) checkAllCameras (integer)
Checks if the given 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

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.

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.

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.

SCLE (command) pose (integer) scaleBy (float)
Scales an image from the TARG agent's sprite file by the given percentage. The scale factor always refers to the original size of the image. If the pose number is -1 then the whole sprite file will be cloned and scaled. Note that this takes up lots of memory.

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.

SHOW (integer)
Returns true if the TARG is currently on visible, false otherwise.

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.

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.

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.

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)
Returns true if the given x y position coincides with a non transparent pixel on the TARG agent. 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.

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

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.


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.

MIRR (command) scene_on_off (integer) agents_on_off (integer)
Tell the agent to draw the whole scene mirrored (send 1 as a parameter) or normally (send 0 as a parameter), the second paramater mirrors just the agents.

PRNT (command) pose (integer)
Prints an image from the TARG agent's sprite file. The pose is taken to be from the current base image.

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

SCRL (command) toggle_on_off (integer)
This turns off all scrolling capabilities these are the automatic scrolling with the mouse and cursor keys.

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 <= 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.

TNTO (command) world_tint (integer) body_part_index (integer) set_number (integer) fileIndex (integer)
This tints the given set of clothing (overlay) for the TARG norn. The file index cannot be zero since that set of clothing is not tintable.

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.


Compounds

CHAR (string)
Returns the last character received by the currently selected character translator.

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 (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.

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: CHAR (command) part_id (integer)
Creates a part that will recieve keyboard input and translate key codes.

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: 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 tab or return are pressed - a good place to use PTXT to get the text out, and to set the focus elsewhere.

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.

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

TRAN (string) key_code (integer)
The currently selected character code translator will translates the given key code to a character.


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. This only works for the non tintable overlay file

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

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

BRED (integer) body_part_index (integer)
Returns the variant number for the appearance of the specified body part of the TARG creature

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.

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.

DYED (command) body_id (integer) overlay_file (integer) set_number (integer) layer (integer)
Sets a layer of clothing on part of the creature. The overlay_file is the index of the overlay gallery. Currently there is also one tintable gallery available which is index 1. 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.

EXPR (command) animated_expression_index (integer) ticks (integer)
This sets the animated expression for a creatures, these are facial expressions requiring more than one frame and lasting a specified number of ticks, for example laughing or eating. Animated expression indexes are as follows: 0 - laugh 1 - cry 2 - eat

EXPR (integer)
Returns the current facial expression index for the creature. Expressions are as follows: EXPR_NORMAL = 0, EXPR_HAPPY =1, EXPR_SAD = 2, EXPR_ANGRY= 3, EXPR_SURPRISE = 4, EXPR_SLEEPY = 5, EXPR_VERY_SLEEPY = 6, EXPR_VERY_HAPPY = 7, EXPR_MISCHEVIOUS = 8, EXPR_SCARED = 9, EXPR_ILL = 10, EXPR_HUNGRY = 11

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.

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.

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.

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

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 is executed on that creature, to inform them that they've been selected.

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.

RSET (command)
This clothes the TARG creature with the last stored clothing set - see STRE command.

SAYN (command)
Creature expresses need, by speaking.

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.

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.

STRE (command)
This stores the current clothing set for the TARG creature. If the creature is not wearing clothes this will be recorded.

SWAP (command) variant (integer) bodypart_id (integer) commit_changes (integer)
Swap the specified part of the body with the equivalent body part of the given variant.

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.

TNTC (command) world_tint_index (integer) bodypart_id (integer) commit_changes (integer)
Tint the specified part of the body with the given world tint. Use WTNT to create the world tint.

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.

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

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. Variables can use SETA to store agent r-values directly for internal use.

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

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 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)
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. Variables can use SETA to store agent r-values directly for internal use.


Files

FILE EXEC (command) directory (integer) filename (string)
Launches an executable.

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, or 1 for the main 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, or 1 for the main 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, jornal 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


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 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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.


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 (command) 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 (command) 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 (command)
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 (command) 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 (command)
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

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 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_name (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 name should be used to find the creature again to import it. In Creatures 3, most exported creatures have a chunk name EXPC, and the starter family uses SFAM.

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 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 (string) actually_do_it (integer) keep_file (integer)
This function imports the creature with the requested moniker. 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 - related genome files could not be loaded

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).

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 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. 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.

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. 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.

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. This forces a PRAY GARB to happen automatically

PRAY SIZE (integer) resource_name (string)
The return value for this is the size of the chunk. This can be used to determine chunk information for decisions on time criteria. E.g. a large compressed chunk will take a short while to decompress.

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.

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) volume (integer) which_module (integer)
Set overall the volume of the MIDI and the sound effects. Send 0 as the second parameter to affect just the MIDI, 1 to affect just the sound effects and anything else to affect both modules.


Time

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 0.05 secs.
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. 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)
Set a variable to 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.

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

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.

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 undefined contents). Agents, integers, floats and strings can be stored in game variables. Variable names are case sensitive.

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.

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.

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

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.

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.

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

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.

LANG (string)
Returns preferred language id eg fr - french german - de.

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.

NWLD (integer)
Returns the number of world directories.

PSWD (command) world_name (string)
Sets the password of the current world.

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 Swallow Mouse Clicks When set on an agent, it will receive mouse clicks as if activatable but will not fire off a message.
2048 No Activate1 Pointer Animation When set on an agent, the mouse pointer will not fire its default activate1 animation allowing you to create your own.
4096 No Walking Inside Cabin When set on a vehicle, the passenger norn will not walk inside the cabin.


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


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+Shift+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.
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_volume Integer 0 This sets the normal volume for the game.
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.
9 Timer Called at a regular time interval, as set by TICK.
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 build 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.
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  

581 documented commands