Seven Towers: Usecode document

GENERAL DEFINITIONS

For Usecode C purposes, the avatar is an NPC just like any other. Constants referred to below (usually in ALL CAPS) are defined in 'src/headers/constants.uc' unless otherwise stated.

Unlike Usecode C-defined functions, intrinsics do not have a 'prototype'; you can pass as many (or as few) parameters to an intrinsic as you like. The only 'hard' limits are that Exult will not like if you (1) call an intrinsic with more than 12 parameters or (2) the intrinsic expects parameters which you haven't supplied. The parameter lists in the list below is the minimum safe number of parameters.

To the right of many intrinsic 'prototypes', you can see an indicator between square brackets. This indicator is a quick way to see if that intrinsic is available for the specific game you are interested in. The possible values of these indicators are:

Indicator	Meaning
	BG-specific intrinsic
	SI-specific intrinsic
	Exult-specific intrinsic, available to both BG and SI
	Originally BG-only, Exult allows it in SI too
	Originally SI-only, Exult allows it in BG too
	Exult-specific intrinsic, available only to BG
	Exult-specific intrinsic, available only to SI
(not present)	Intrinsic available for BG and SI

The '', '' and '' indicators are essentially equivalent to no indicator at all; they are used in this document only for completeness.

The intrinsic prototypes below are in Usecode C-esque form. It is actually more like C than Usecode C. Specifically, all parameters have a type instead of the Usecode C-'var'. The parameter type indicates what Exult will be expecting; the Usecode C compiler won't care in the slightest what you pass as a parameter. The parameter types I use are as follows:

Keyword	Description
`int`	This means any integer, positive or negative.
`object`	Any object or NPC. It can be an object reference, '`item`' or a number (that must be negative, which Exult will convert to an NPC if it is in the correct range).
`actor`	Any NPC. It is evaluated the same way as '`object`' is, but Exult will reject anything that can't be converted to an NPC. Monsters are also accepted.
`bool`	A '`true`'/'`false`' parameter. Can be a number (nonzero/zero), an array (non-empty/empty) or a comparison expression (e.g., '`a == b`'.
`string`	A string (text). Strings in usecode are any set of characters surrounded by double-quotes; for example, `"This is a string."`. If you need a double-quote inside a string you can 'escape' it by prefixing them with a backslash: `"\""`; alternatively, Exult converts '`@`' into a double-quote.
`function`	A usecode function, which must be declared with either, the `shape#` or the `object#` specifiers. In Usecode C, this can be the function name or its usecode number. For example: '`extern Bolt shape#(0x2D3) ();`' can be passed as '`Bolt`' (the function name), '`0x2D3`' (its function number since '`shape#(shnum) == shnum`' if `shnum < 0x400`) or as '`&Bolt`' (using the 'address of' operator '`&`' to get the function number).

If the parameter name is followed by a '[]', it indicates an array with elements of the specified type. Example: 'actor npc[]' means an array of NPCs. If there is a number between the brackets, it means an array of that length; for example, 'int num[3]' means an array with 3 'int' elements. In some cases, an array can be of type 'mixed' to indicate that not all of the array's elements are of the same type.

Some intrinsics are 'overloaded'; i.e., they accept more than one parameter type. In those cases, all of the possibilities are listed as prototypes.

If the parameter list is simply '[special]', see the description for details.

If the intrinsic is preceded by a parameter type, it means that the intrinsic returns something of that type; the description explains the return value. In some cases, the return value can be 'mixed[]' to indicate that the intrinsic returns an array, not all of which are of the same type.

All intrinsics can be called as presented in the list. If an intrinsic has at least one parameter, it can be called in 'calle' form, with the first parameter as its 'object'. Example:

int UI_execute_usecode_array(object obj, int script[]);
int obj->execute_usecode_array(int script[]);

The first parameter and the '->' can both be omitted if 'obj' is 'item', and if you omit either of them you must omit both or the Usecode will fail to compile. For stylistic purposes, the 'calle' form should be used only when the first parameter is an object or NPC (or 'item'). For all intrinsics with 'appropriate' parameter types, I have listed both forms in the list below.

Also, you may have noticed that I did not include the parameter type of 'obj' when I gave the 'calle' form of execute_usecode_array; since I will only give the 'calle' form when the parameter type is 'object' or 'actor', I feel that it is unneeded.

RANDOM NUMBER INTRINSICS

These intrinsics are all related to random numbers and their generation.

int UI_get_random(int max)

Generates a random number, similar to rolling a dice of the given side.

Parameters

max The maximum value of the random number. Should be positive.

Return

Zero if max is zero; otherwise, a random number ranging from 1 to max.

int UI_die_roll(int min, int max)

Generates a random number in the specified range.

Parameters

`min`	The minimum value of the random number. Should be positive.
`max`	The maximum value of the random number. Should be positive.

Return

A random number ranging from min to max. If min > max, the two parameters are reversed by Exult.

bool UI_roll_to_win(int att, int def)

Performs a contest between two supplied values.

Parameters

`att`	What should be added to the die roll, improving the chances of success.
`def`	What should be subtracted from the die roll, reducing the chances of success.

Return

The contest is a roll of a 30-sided die: if the die comes up 30, the return is true; if it comes up 1, the return is false. For all other values, the attack value is added to the die roll and the defense value is subtracted from the same roll. If the result is 15 or more, the attacker wins and the return is true; otherwise, the attacker loses and the return is false.

SCRIPTING INTRINSICS

These intrinsics are used to animate characters from usecode. Some of these are deprecated by script blocks, but all others are still useful at times.

int UI_execute_usecode_array(object obj, int script[])
int obj->execute_usecode_array(int script[])

Deprecated; use Usecode C script blocks instead. Animates an object according to the supplied script.

Parameters

`obj`	The object to be animated.
`script`	The sequence of actions to be executed.

Return

Always returns '1'.

int UI_delayed_execute_usecode_array(object obj, int script[], int delay)
int obj->delayed_execute_usecode_array(int script[], int delay)

Deprecated; use Usecode C script blocks instead. Animates an object according to the supplied script after a delay. Works exactly like execute_usecode_array, but starts only after the specified delay.

Parameters

`obj`	The object to be animated.
`script`	The sequence of actions to be executed.
`delay`	The number of ticks that must elapse before the animation starts.

Return

Always returns '1'.

bool UI_in_usecode(object obj)
bool obj->in_usecode()

Checks if an object is currently executing any usecode scripts.

Parameters

obj The object to be inspected.

Return

true if there are any scripts for the specified object, false otherwise.

UI_halt_scheduled(object obj)
obj->halt_scheduled()

Terminates usecode scripts that animate the supplied object. Scripts that include the 'nohalt' command are not affected by this intrinsic.

Parameters

obj The object whose scripts should be terminated.

UI_begin_casting_mode(actor npc, int val)
npc->begin_casting_mode(int val)

Makes an NPC display casting frames until the end of its next script.

Parameters

`npc`	The NPC that should display casting frames.
`val`	The shape in 'SHAPES.VGA' to use as casting frames. If omitted, this is assumed to be shape 859.

int UI_set_to_attack(actor attacker, object target, int weapon)
int attacker->set_to_attack(object target, int weapon)
int UI_set_to_attack(actor attacker, mixed[4] target, int weapon)
int attacker->set_to_attack(mixed[4] target, int weapon)

Schedules a NPC to attack the object with a given weapon. This intrinsic does not animate the NPC in any way; the scheduled attack only emulates the actual hit with the selected weapon. The actual attack is triggered by a script; in an Usecode C script, use the 'attack' command to actually perform the attack.

Parameters

`attacker`	Who is attacking.
`target`	What is being attacked. Can be an object, NPC, or the return of a `click_on_item` intrinsic call, even if a tile has been clicked.
`weapon`	What shape in 'SHAPES.VGA' to use as the source of the weapon information in the attack. It must specify a shape that has a 'weapon' tab in Exult Studio, or nothing will happen.

If the NPC is targeting a tile, the attack will only be meaningful if the weapon causes an explosion.

Return

true if attacking a valid target with a valid weapon, false otherwise.

bool UI_path_run_usecode(int pos[], function fun, object obj, int event, int simode)

Causes the avatar to walk to a location and execute the specified usecode function when he/she arrives at the destination. If a path cannot be found for the destination, no usecode will be executed unless a call to set_path_failure intrinsic is made before returning from usecode.

The avatar can be prevented from reaching his/her destination simply by moving away from the path; this will cancel the effects of the intrinsic, and will cause the usecode function set by set_path_failure to be called. If you want the path to be uninterruptible, the avatar's DONT_MOVE flag must be set (this is flag 22 in BG and 16 in SI).

The other party members will follow the avatar towards the destination.

SI SPECIFIC

In SI, path_run_usecode finds a free spot within 3 tiles of the position specified by 'pos'; it also allows a rise/drop of 3 in the z direction.

Parameters

`pos`	The location that the avatar should walk to. Can be a (x, y) position or a (x, y, z) position. If the z coordinate is missing, or if it is negative, it is assumed to be zero.
`fun`	The usecode function to be called if the destination is reached.
`obj`	The object that should be used as `item` if the usecode function is called. If this parameter is zero, usecode will not be called at all.
`event`	The `event` that should be used if the usecode function is called.
`simode`	This optional parameter can be used to control whether or not to use the SI-specific behavior described above. It defaults to `true` in SI and to `false` in BG.

Return

If no path can be found to the destination, returns false; otherwise, returns true.

UI_si_path_run_usecode(actor npc, int pos[], int event, object obj, function fun, bool flag)
npc->si_path_run_usecode(int pos[], int event, object obj, function fun, bool flag)

Causes an NPC to walk to a location and execute the specified usecode function when he/she arrives at the destination. If a path cannot be found for the destination, no usecode will be executed unless a call to set_path_failure intrinsic is made before returning from usecode.

The avatar can be prevented from reaching his/her destination simply by moving away from the path; similarly, a scheduled event or scripted event may prevent an NPC from reaching his/her destination. In these cases, the effects of the intrinsic will be cancelled, and the usecode function set by set_path_failure will be called. If you want the path to be uninterruptible, the NPC's DONT_MOVE flag must be set (this is flag 22 in BG and 16 in SI).

Parameters

`npc`	The NPC that will be affected by this intrinsic. If this isn't a valid NPC, nothing will happen.
`pos`	The location that the NPC should walk to. Can be a (x, y) position or a (x, y, z) position. If the z coordinate is missing, or if it is negative, it is assumed to be zero.
`event`	The `event` that should be used if the usecode function is called.
`obj`	The object that should be used as `item` if the usecode function is called. If this parameter is zero, usecode will not be called at all.
`fun`	The usecode function to be called if the destination is reached.
`flag`	Flag specifying whether or not the usecode function should always be called. If `false`, it will be called only if the NPC can reach its intended destination; if `true`, the specified usecode function will be called even if the destination cannot be reached. The `set_path_failure` intrinsic will override this flag in either case. This failure usecode will use event 'SI_PATH_FAILURE'.

UI_set_path_failure(function fun, object obj, int event)

Sets usecode to be called if an NPC fails to reach its destination. This intrinsic must be used after a call to either, path_run_usecode or si_path_run_usecode intrinsics, and will affect only the NPC affected by that call. If, for any reason, the NPC in question cannot reach the destination, the usecode function assigned by this intrinsic will be run.

Parameters

`fun`	The usecode function to be called if the path fails.
`obj`	The object that should be used as `item` if the usecode function is called. If this parameter is zero, usecode will not be called at all.
`event`	The `event` that should be used if the usecode function is called.

SI SPECIFIC

In the original SI, this could never affect the failure event for si_path_run_usecode, which would always be 14. Exult does not suffer from this limitation.

bool UI_in_usecode_path(actor npc)
bool npc->in_usecode_path()

Checks whether or not the actor is traversing a path due to path_run_usecode or si_path_run_usecode intrinsics.

Parameters

npc The NPC to be checked.

Return

true if the NPC is still walking a usecode path, false otherwise.

UI_telekenesis(function fun)

Deprecated; stores a usecode function for special script behavior. The next script call to the stored function (e.g., 'script item call fun;') will have an event ID of 'DOUBLECLICK' instead of the standard 'SCRIPTED' event ID used for scripts. Since Usecode C scripts allow calling a function with an event ID of your choice (e.g., 'script item call fun, DOUBLECLICK;') it is best to simply ignore this intrinsic.

Parameters

fun The function to be stored.

CONVERSATION INTRINSICS

These intrinsics are used to display faces for conversations, storing and recalling answers, etc.

UI_show_npc_face(int face, int frnum)
UI_show_npc_face(actor face, int frnum)
face->show_npc_face(int frnum)

Displays a face onscreen for conversations. The face is a shape from 'FACES.VGA'. This intrinsic finds a free slot to display the face in or uses the second slot if there are no free slots.

Parameters

`face`	The face to be displayed. May be an integer or an NPC.
`frnum`	The frame number of the face to be displayed.

If 'face' is an integer, the shape to be displayed is the absolute value of this number. If this value is 0 or 356, the avatar's face will be displayed, using the correct face for the avatar's skin and PETRA status flag.

If 'face' is an NPC, the Exult Studio-set face for that NPC is displayed; the "default" face is equal to the NPC's number.

For the cases when 'frnum is zero, you should use Usecode C's 'npc.say()' to display the NPC's face and display any text within the parenthesis (or set with 'message') too.

UI_show_npc_face0(int face, int frnum)
UI_show_npc_face0(actor face, int frnum)
face->show_npc_face0(int frnum)

Displays a face onscreen for conversations. The face is a shape from 'FACES.VGA'. This intrinsic always uses slot 0 for the new face.

Parameters

`face`	The face to be displayed. May be an integer or an NPC.
`frnum`	The frame number of the face to be displayed.

If 'face' is an NPC, the Exult Studio-set face for that NPC is displayed; the "default" face is equal to the NPC's number.

For the cases when 'frnum is zero, you should use Usecode C's 'npc.say()' to display the NPC's face and display any text within the parenthesis (or set with 'message') too.

UI_show_npc_face1(int face, int face)
UI_show_npc_face1(actor face, int face)
npc->show_npc_face1(int face)

Displays a face onscreen for conversations. The face is a shape from 'FACES.VGA'. This intrinsic always uses slot 1 for the new face.

Parameters

`face`	The face to be displayed. May be an integer or an NPC.
`frnum`	The frame number of the face to be displayed.

If 'face' is an NPC, the Exult Studio-set face for that NPC is displayed; the "default" face is equal to the NPC's number.

For the cases when 'frnum is zero, you should use Usecode C's 'npc.say()' to display the NPC's face and display any text within the parenthesis (or set with 'message') too.

UI_remove_npc_face(int face)
UI_remove_npc_face(actor face)
face->remove_npc_face()

Deprecated; use Usecode C's 'npc.hide()' statement instead. Hides the specified face if it is being shown.

Parameters

face The face to be hidden. May be an integer or an NPC.

If 'face' is an integer, the shape to be hidden is the absolute value of this number. If this value is 0 or 356, the avatar's face will be hidden.

If 'face' is an NPC, the Exult Studio-set face for that NPC is hidden; the "default" face is equal to the NPC's number.

UI_remove_npc_face0()

Removes whatever face is being shown in slot 0.

UI_remove_npc_face1()

Removes whatever face is being shown in slot 1.

UI_init_reset_conv_face()

Changes the active conversation slot to the top slot and sets its current frame to 0.

UI_set_conversation_slot(int slot)
npc->set_conversation_slot()

Changes the active conversation slot.

Parameters

slot The new active slot. Must be zero or one.

UI_change_npc_face0(int frame)

Changes the frame of the face being displayed in slot 0.

Parameters

frame The new frame to be used.

UI_change_npc_face1(int frame)

Changes the frame of the face being displayed in slot 1.

Parameters

frame The new frame to be used.

UI_init_conversation()

Initializes the face information for a conversation. In Exult, it is usually safe to skip it.

UI_end_conversation()

Shows any pending text and removes all faces from the screen. Usually safe to skip this in Exult.

UI_add_answer(string answer)
UI_add_answer(string answer[])

Deprecated; use Usecode C's 'add(string answer)' or 'add(string answer[])' statements instead. Adds the specified strings as dialog options that the player can select.

Parameters

answer A string or array of strings containing the dialog options to be added.

UI_remove_answer(string answer)
UI_remove_answer(string answer[])

Deprecated; use Usecode C's '(remove)' construct instead. Removes the supplied strings from the dialog options available to the player.

Parameters

answer A string or array of strings containing the dialog options to be removed.

UI_push_answers()

Stores the current conversation options and clears all choices. The dialog options are stored in a LIFO stack that persists until the dialog ends; before that point, the stored options can be retrieved with a call to UI_pop_answers intrinsic.

UI_pop_answers()

Clears all current conversation options and restores the stored conversation options, if any. The restored dialog options are those stored by the last call to UI_push_answers intrinsic.

UI_clear_answers()

Clears all current dialog options.

string UI_select_from_menu()

Makes the player choose one answer from all dialog options currently being displayed.

Return

The chosen dialog option.

int UI_select_from_menu2()

Makes the player choose one answer from all dialog options currently being displayed.

Return

The index (ranging from 1 to n) of the chosen dialog option.

SOUND INTRINSICS

All intrinsics in this section relate to playing sound effects, music or speech.

UI_play_sound_effect(int sfx)

Plays a sound effect.

Parameters

sfx A numerical value indicating the sound effect that should be played.

UI_play_sound_effect2(int sfx, object obj)

Causes an object to generate a sound effect.

Parameters

`sfx`	A numerical value indicating the sound effect that should be played.
`obj`	The object generating the sound effect. The sound intensity decrease as the avatar gets farther away from this object.

UI_play_music(int track, object obj)

Plays the specified song.

Parameters

`track`	The track number to be played or 255 (0xFF) to stop any music that is playing.
`obj`	The source of the music, or zero for 'unattached' music. Positive numbers are not interpreted as NPCs!

If supplied with a valid object or NPC that is on the game world, this intrinsic will also display the sprite effect # 24 (musical notes).

int UI_get_music_track()

Gets the music being played.

Return

If music is enabled and a song is playing, returns the track number of the current song. Otherwise, return is -1.

NOTES ABOUT ORIGINAL BG

The return value in the original Black Gate was more complicated; the current song was the return value divided by 256, while the next song (the one that would be resumed after the current one ends) was the remainder of that same division. None of this behavior is true for Exult, which works as described above.

bool UI_start_speech(int track)

Plays the specified speech track.

SI SPECIFIC

In SI, speech also displays a full-screen face from 'FACES.VGA'.

Parameters

track Number indicating what speech track is to be played.

Return

Returns false if failed to play the requested speech track (for example, if speech is disabled), true otherwise.

bool UI_start_blocking_speech(int track)

Plays the specified speech track. Blocks until the speech finishes.

SI SPECIFIC

In SI, speech also displays a full-screen face from 'FACES.VGA'.

Parameters

track Number indicating what speech track is to be played.

Return

Returns false if failed to play the requested speech track (for example, if speech is disabled), true otherwise.

int UI_get_speech_track()

Determines the currently playing speech track.

Return

A number indicating what voice track is being played.

SEARCHING AND COUNTING INTRINSICS

These intrinsics allow you to find and count objects, whether they are in a container or in the game world.

object UI_find_nearest(object obj, int shape, int dist)
object obj->find_nearest(int shape, int dist)

Searches the area around a given object looking for other objects of a specified type.

Parameters

`obj`	The object around which the search will happen.
`shape`	The shape we are looking for. Can be `SHAPE_ANY = -359` to match any shape.
`dist`	The maximum distance from 'obj' that will be considered in the search.

Return

An object reference to the nearest object found given the search criteria. You cannot find eggs, barges, invisible or transparent objects with this intrinsic.

object UI_find_object(object cont, int shape, int qual, int frame)
object cont->find_object(int shape, int qual, int frame)
object UI_find_object(int cont, int shape, int qual, int frame)
object UI_find_object(int cont[3], int shape, int qual, int frame)

Finds the first object matching the search criteria.

Parameters

`cont`	The object or location to be searched. Can be a container or NPC, a (x, y, z) location, `PARTY = -357` to search the whole party or `FIND_ON_SCREEN = -359` to search a square region around the screen location with size given by the screen's height.
`shape`	The shape we are looking for.
`qual`	The quality that is being sought. Can be `QUALITY_ANY = -359` to match any quality.
`frame`	What frame is desired. Can be `FRAME_ANY = -359` to match any frame.

IMPORTANT NOTES

When 'cont' is a position, the search is made in a 1-tile-wide region centered on the given position.

Also, if the search is not being done in a container or NPC, 'shape' can be SHAPE_ANY = -359 to match any shape.

Return

An object reference to the first found object, or zero if no objects match the given criteria.

object[] UI_find_nearby(object loc, int shape, int dist, int mask)
object[] loc->find_nearby(int shape, int dist, int mask)
object[] UI_find_nearby(int loc[3], int shape, int dist, int mask)
object[] UI_find_nearby(int loc[5], int shape, int dist, int mask)
object[] UI_find_nearby(mixed loc[4], int shape, int dist, int mask)

Searches a specified area looking for objects matching a given criteria.

Parameters

`loc`	The center of the area to be searched. Can be the return of a '`UI_click_on_item`' intrinsic call, an object reference, a (x, y, z) position vector or a (x, y, z, quality, frame) vector. For the last form, quality can be `QUALITY_ANY = -359` and frame can be `FRAME_ANY = -359` (but there is little point in both being wildcards, as this is the default behavior).
`shape`	The shape we are looking for. Can be `SHAPE_ANY = -359` to match any shape.
`dist`	Radius (in tiles) of the area to be searched.
`mask`	Parameter specifying the classes of objects that can be found.

The mask value controls what can be found; using the proper mask, you can find eggs, barges, invisible or transparent objects with this intrinsic. The mask can be the combination (sum) of one or more of the following values:

MASK_NONE = 0x00	Cannot find eggs, barges, invisible or transparent objects.
MASK_NPC = 0x04	Restricts the search to NPCs, alive or dead. Ignored if a non-wildcard shape is given.
MASK_NPC2 = 0x08	Restricts the search to living NPCs.
MASK_EGG = 0x10	Allows eggs and barges to be found.
MASK_INVISIBLE = 0x20	Allows invisible objects that are not in the avatar's party to be found.
MASK_PARTY_INVISIBLE = 0x40	Allows invisible party members to be found
MASK_TRANSLUCENT = 0x80	Allows translucent objects to be found

Return

Array containing all objects of matching the given criteria that are located in the specified area. This array is sorted from right to left, closest first.

object[] UI_find_nearby_avatar(int shape)

Searches the area around the avatar looking for other objects of the specified shape.

Parameters

shape The shape we are looking for. Can be SHAPE_ANY = -359 to match any shape.

Return

Array containing all objects of the given shape that are located within 192 tiles of the avatar. This array is sorted from right to left, closest first. You cannot find eggs, barges, invisible or transparent objects with this intrinsic.

bool UI_npc_nearby(object obj)
bool obj->npc_nearby()

Finds out if the desired object is on screen and can act. An NPC is considered able to act if it is not asleep, paralyzed or dead; other objects are always considered able to act. Note that, despite the name, this intrinsic can also be used for objects.

Parameters

obj The object or NPC to be checked.

Return

true if the object is in the screen and can act, false otherwise or if the supplied parameter is not an object or NPC.

bool UI_npc_nearby2(object obj)
bool obj->npc_nearby2()

Finds out if the desired object is nearby. In this context, 'nearby' means within 40 tiles of the avatar. Note that, despite the name, this intrinsic is valid for all objects, not just NPCs.

Parameters

obj The object to be checked.

Return

true if the object is within 40 tiles of the avatar, false otherwise.

int UI_count_objects(object obj, int shape, int qual, int frame)
int obj->count_objects(int shape, int qual, int frame)

Counts all objects matching a given search criteria that are contained in the supplied object.

Parameters

`obj`	The object whose contents are to be searched. Can be a container, an NPC or `PARTY = -357` to search the whole party.
`shape`	The shape we are looking for. Can be `SHAPE_ANY = -359` to match any shape.
`qual`	The quality that is being sought. Can be `QUALITY_ANY = -359` to match any quality.
`frame`	What frame is desired. Can be `FRAME_ANY = -359` to match any frame.

Return

The number of objects that match the given criteria.

object[] UI_get_cont_items(object obj, int shape, int qual, int frame)
object[] obj->get_cont_items(int shape, int qual, int frame)

Looks for all objects matching a given search criteria that are contained in the supplied object.

Parameters

`obj`	The object whose contents are to be searched. Can be a container or an NPC.
`shape`	The shape we are looking for. Can be `SHAPE_ANY = -359` to match any shape.
`qual`	The quality that is being sought. Can be `QUALITY_ANY = -359` to match any quality.
`frame`	What frame is desired. Can be `FRAME_ANY = -359` to match any frame.

Return

Array containing object references to all objects that match the given criteria.

PLACEMENT INTRINSICS

With these intrinsics, you can create, move or delete objects or NPCs, whether they are in the game world or in a container.

bool UI_is_not_blocked(int pos[3], int shape, int frame)

Checks if there is enough room for a given shape in the specified location.

Parameters

`pos`	The location to be checked.
`shape`	The shape in 'SHAPES.VGA' that is to be checked.
`frame`	The frame of the given shape that should be checked.

Return

If there is enough room in the given location for an object of the given shape and frame, returns true; otherwise, returns false.

actor[] UI_add_party_items(int count, int shape, int qual, int frame, bool temp)

Creates a specified amount of objects matching the given parameters and gives them all to the party. Not all objects requested may be created; in particular, this intrinsic is guaranteed to create only as many of the requested objects as the party can hold.

SI SPECIFIC

If the party cannot hold all requested objects, the remaining objects are created and then placed in the ground nearby.

Parameters

`count`	The amount of objects to be created.
`shape`	The shape in 'SHAPES.VGA' that should be used for the created objects.
`qual`	The quality of the objects being created. Can be `QUALITY_ANY = -359` to create items of any quality.
`frame`	What frame will be used for the created objects. Can be `FRAME_ANY = -359` to create items of any frame.
`temp`	Flag indicating whether the created items are temporary or not.

Return

Returns an array of object references for all party members that received any of the created objects.

BG SPECIFIC

The 'temp' flag applies to all objects created by this function.

SI SPECIFIC

If any objects were added to the ground, the number of objects on the ground is appended to the end of the return array. The 'temp' flag applies only to those objects that were added to the floor.

bool UI_remove_party_items(int count, int shape, int qual, int frame)
bool UI_remove_party_items(int count, int shape, int qual, int frame, bool unk)

Looks through the party's possessions and deletes a specified amount of objects matching a given search criteria. This function is an all-or-nothing function: it will delete all requested objects or none at all if it found less objects than the amount that was requested for deletion.

Parameters

`count`	The amount of objects to be deleted. Can be `QUANTITY_ANY = -359` to delete all objects that match the criteria.
`shape`	The shape we are looking for.
`qual`	The quality that is being sought. Can be `QUALITY_ANY = -359` to match any quality.
`frame`	What frame is desired. Can be `FRAME_ANY = -359` to match any frame.
`unk`	Flag of unknown meaning. This parameter is ignored by Exult, and can be omitted.

Return

true if 'count' objects were found and deleted, false if no objects were deleted.

object UI_summon(int shape)
object UI_summon(int shape, bool unk)

Creates a monster with shape 'shape'. The created monster has equipment as defined in its equipment record, and has a 'GOOD' alignment. If the creation is successful, the return value is a reference to the monster; otherwise, the return is '0'. In the originals, there was an additional 'bool' parameter, but it is unimplemented in Exult.

Creates a monster of the supplied shape. This monster has equipment as defined in its equipment record, starts with an IN_COMBAT schedule, and will have the same alignment as item; for the cases in which item is not an NPC, the summoned monster's alignment will be GOOD instead. The monster will be placed within five tiles of the avatar.

Parameters

`shape`	The shape in 'SHAPES.VGA' to be used for the summoned monster. It must have a 'monster' tab in Exult Studio.
`unk`	A flag of unknown meaning. Exult ignores this flag, and it is safe to omit it.

Return

Zero if there is no free tile near the avatar or the specified shape is not a valid monster shape; an object reference to the summoned monster otherwise.

actor UI_clone(actor npc)
actor npc->clone()

Creates a duplicate of the supplied NPC. This duplicate is always of GOOD alignment and starts with an IN_COMBAT schedule. The clone is placed in a spot near to the original NPC.

Parameters

npc The NPC that should be cloned.

Return

An object reference to the clone, or zero if the intrinsic did not receive a valid NPC to clone or if a suitable spot for the clone could not be found.

object UI_create_new_object(int shape)

Creates a new object with the specified shape.

Parameters

shape The shape in 'SHAPES.VGA' of the new object. If this is a monster shape, the object is created without any equipment whatsoever, even if the shape has an associated equipment entry.

Return

An object reference to the newly created object. This object is pushed into the 'last created' LIFO stack, and starts out in 'limbo'; it will remain there until placed either, in the game world through the 'UI_update_last_created' intrinsic or inside a container through the 'UI_give_last_created' intrinsic.

object UI_create_new_object2(int shape, int pos[])

Creates a new object with the specified shape and places it in the game world at the supplied location.

Parameters

`shape`	The shape in 'SHAPES.VGA' of the new object. If this is a monster shape, the object is created with all equipment specified by the shape's equipment entry.
`pos`	The location where the new object is to be placed.

The location can be specified by arrays ranging from 1 to 4 components. The meaning of these components is as follows:

1 element: the object will be deleted (equivalent to 'remove_item' intrinsic);
2 elements: mean a (x, y) location. The object is placed at z = 0 in the current game map;
3 elements: mean a (x, y, z) location. The object is placed in the current game map;
4 elements: mean a (x, y, z, map) location. The object is placed in the specified map unless it is -1, in which case it will be placed in the current game map.

Return

An object reference to the newly created object. This object is placed in the game world exactly as if UI_update_last_created(pos) had been called, and hence will not be in the 'last created' stack.

UI_create_barge_object(int width, int height, int dir)

Creates a barge object with the specified width, height and direction.

Parameters

`width`	The width (x), in tiles, of the barge object.
`height`	The height (y), in tiles, of the barge object.
`dir`	This optional parameter sets the barge's initial direction. If missing, it is assumed to be north (0).

Return

An object reference to the newly created barge object. This object is pushed into the 'last created' LIFO stack, and starts out in 'limbo'; it will remain there until placed either, in the game world through the 'UI_update_last_created' intrinsic or inside a container through the 'UI_give_last_created' intrinsic.

object UI_set_last_created(object obj)
object obj->set_last_created()

Moves the object from the game map or container where it was and places it in the 'last created' stack. This intrinsic does nothing if the specified object is already in the aforementioned stack.

Parameters

obj The object to be moved to the 'last created' stack.

Return

Returns zero if the object was already in the 'last created' stack, an object reference to the object otherwise.

bool UI_update_last_created(int pos[])

Pops the last object pushed in the 'last created' stack and places it in the game map at the supplied position.

Parameters

pos The location where the new object is to be placed.

The location can be specified by arrays ranging from 1 to 4 components. The meaning of these components is as follows:

1 element: the object will be deleted (equivalent to 'remove_item' intrinsic). The original usecode generally passed '-358' for this parameter, but this is likely just by convention as any value works.
2 elements: mean a (x, y) location. In Exult, the object is placed at z = 0 in the current game map; in the original games, nothing is done and the update fails.
3 elements: mean a (x, y, z) location. The object is placed in the current game map. In Exult, this always succeeds; it could fail in the original games.
4 elements: mean a (x, y, z, map) location. Exult-only. The object is placed in the specified map unless it is -1, in which case it will be placed in the current game map.

Return

For the 1-element version, false if the 'last created' stack is empty or true if the object was deleted. Otherwise, returns true if object was successfully placed on the map, false otherwise.

NOTES ABOUT ORIGINAL GAMES

In the original games, the function could fail to place the item in the map. In this case, it would try to delete an unrelated on-screen object flagged with the TEMPORARY flag to make room for the updated object and retry. The retry could fail again, in which case the update fails; otherwise, it would succeed. This means that, on occasion, using this function could cause objects to be deleted in the original.

bool UI_give_last_created(object obj)
bool obj->give_last_created()

Gives the last item in the 'last created' stack to the specified container or NPC. This intrinsic ignores volume, and is quite likely to succeed; the given object is popped from the 'last created' stack only if the intrinsic succeeds.

Parameters

obj Container or NPC that will gain the object.

Return

true if successful, false otherwise.

int[3] UI_get_object_position(object obj)
int[3] obj->get_object_position()

Gets the current location the desired object.

Parameters

obj The object whose position is desired.

Return

An array containing the (x, y, z) position of the object.

UI_move_object(object obj, int pos[], bool flag)
obj->move_object(int pos[], bool flag)

Moves the specified object to a new location in the game world. This move is instantaneous, and is often used for teleportation in the original usecode.

Parameters

`obj`	The object to be moved. Can be `PARTY = -357` to teleport the entire party.
`pos`	The object's new location. Can be a (x, y) position, a (x, y, z) position or a (x, y, z, map) position. If no z coordinate is specified, it is assumed to be zero. If no map is specified, or if it is set to a negative number, the avatar's map will be used instead.
`flag`	This optional parameter controls controls whether or party members that are paralyzed or asleep; if `true`, these members will be teleported, otherwise, they won't defaults to `false`.

If the avatar (or the party) is being teleported, the view will center in the new location and nearby eggs will be activated normally.

int UI_get_distance(object obj1, object obj2)
int obj1->get_distance(obj2)

Gets the distance between two objects.

Parameters

`obj1`	One of the two objects.
`obj2`	The other object.

Return

The distance between the two objects, or zero if one or both of the parameters is not a valid object.

int UI_find_direction(object param1, object param2)
int param1->find_direction(object param2)
int UI_find_direction(object param1, int param2[3])
int param1->find_direction(int param2[3])
int UI_find_direction(object param1, mixed param2[4])
int param1->find_direction(mixed param2[4])
int UI_find_direction(int param1[3], object param2)
int UI_find_direction(int param1[3], int param2[3])
int UI_find_direction(int param1[3], mixed param2[4])
int UI_find_direction(mixed param1[4], object param2)
int UI_find_direction(mixed param1[4], int param2[3])
int UI_find_direction(mixed param1[4], mixed param2[4])

Get the direction from one location or object to another.

This intrinsic is aliased under the name 'direction_from'; they are both equivalent in Exult.

Parameters

`param1`	The object or location from which we want the direction.
`param2`	The object or location to which we want the direction.

Both parameters can be objects, arrays with 3 components or arrays with 4 components. Depending on what they are, Exult will treat them differently and expect them to conform to a certain format; specifically:

Type	Interpretation/Format
`object`	The parameter is an object or NPC.
`int [3]`	The parameter is a (x, y, z) position, such as the return of a `UI_get_object_position` intrinsic call.
`mixed [4]`	The parameter is of the form (object, x, y, z), such as the return of a call to `UI_click_on_item` intrinsic.

Return

The 8-cardinal-point direction of an arrow starting in the first parameter and pointing to the second parameter. It can be one of the following values:

NORTH = 0	NORTHEAST = 1	EAST = 2	SOUTHEAST = 3	SOUTH = 4
SOUTHWEST = 5	WEST = 6	NORTHWEST = 7

int UI_add_cont_items(object obj, int count, int shape, int qual, int frame, bool temp)
int obj->add_cont_items(int count, int shape, int qual, int frame, bool temp)

Create a number of objects inside a container.

Parameters

`obj`	The container or NPC that will receive the created objects.
`count`	The amount of objects to be created.
`shape`	The shape in 'SHAPES.VGA' that should be used for the created objects.
`qual`	The quality of the objects being created. Can be `QUALITY_ANY = -359` to create items of any quality.
`frame`	What frame will be used for the created objects. Can be `FRAME_ANY = -359` to create items of any frame.
`temp`	Flag indicating whether the created items are temporary or not.

Return

How many objects were actually added to the container.

int UI_remove_cont_items(object obj, int count, int shape, int qual, int frame, bool unk)
int obj->remove_cont_items(int count, int shape, int qual, int frame, bool unk)

Removes 'count' objects with shape 'shape', quality 'qual' and frame 'frame' that are contained by 'obj'. 'unk' is an unknown flag which is ignored by Exult; I think it is safe to omit it from the parameter list, but I am not sure. 'qual' and 'frame' can be wildcards:

qual	frame
QUALITY_ANY = -359	FRAME_ANY = -359

Return value is the number of objects actually removed.

Looks through the contents of a container and deletes a specified amount of objects matching a given search criteria.

Parameters

`obj`	The object whose contents are to be searched. Can be a container, an NPC or `PARTY = -357` to search the whole party.
`count`	The amount of objects to be deleted. Can be `QUANTITY_ANY = -359` to delete all objects that match the criteria.
`shape`	The shape we are looking for.
`qual`	The quality that is being sought. Can be `QUALITY_ANY = -359` to match any quality.
`frame`	What frame is desired. Can be `FRAME_ANY = -359` to match any frame.
`unk`	Flag of unknown meaning. This parameter is ignored by Exult, and can be omitted.

Return

The number of objects actually removed.

UI_remove_from_area(int shape, int frame, int ul[2], int lr[2])

Scans a rectangular area for objects matching the given criteria and deletes all found objects.

Parameters

`shape`	The shape in 'SHAPES.VGA' that is to be searched.
`frame`	The frame being sought.
`ul`	A (x, y) position specifying the upper-left corner of the region to be searched.
`lr`	A (x, y) position specifying the lower-right corner of the region to be searched

OBJECT INTRINSICS

These intrinsics are used to get or set properties of an object, such as quantity, quality or current frame.

int UI_get_item_shape(object obj)
int obj->get_item_shape()

Gets the current shape of the desired object.

Parameters

obj The object whose shape is desired.

Return

The shape in 'SHAPES.VGA' of the object in question.

UI_set_item_shape(object obj, int shape)
obj->set_item_shape(int shape)

Changes the shape of an object.

Parameters

`obj`	The object whose shape is to be changed.
`shape`	The shape in 'SHAPES.VGA' which the object will assume.

int UI_get_item_frame(object obj)
int obj->get_item_frame()

Gets the current frame of the desired object, without the rotation bit.

Parameters

obj The object whose frame is desired.

Return

The frame from 'SHAPES.VGA' of the object in question. Only the base frame is returned, without any rotation information.

UI_set_item_frame(object obj, int frame)
obj->set_item_frame(int frame)

Sets the current frame of the desired object, preserving the rotation bit.

Parameters

`obj`	The object whose frame is to be changed.
`frame`	The desired value for the frame.

int UI_get_item_frame_rot(object obj)
int obj->get_item_frame_rot()

Gets the current frame of the desired object, with the rotation bit.

Parameters

obj The object whose frame is desired.

Return

The frame from 'SHAPES.VGA' of the object in question; including the rotation bit.

UI_set_item_frame_rot(object obj, int frame)
obj->set_item_frame_rot(int frame)

Sets the current frame of the desired object; does not preserve the rotation bit.

Parameters

`obj`	The object whose frame is to be changed.
`frame`	The desired value for the frame.

int UI_get_item_quality(object obj)
int obj->get_item_quality()

Gets the quality of the desired object.

Parameters

obj The object whose quality is desired.

Return

The quality of the object if it has it, zero otherwise.

bool UI_set_item_quality(object obj, int qual)
bool obj->set_item_quality(int qual)

Sets the quality of the desired object.

Parameters

`obj`	The object whose quality is to be changed.
`qual`	The desired value for the quality. Quality is unchanged if `qual == QUALITY_ANY`.

Return

Returns true if the object has a quality or if qual == QUALITY_ANY, false otherwise.

int UI_get_item_quantity(object obj)
int obj->get_item_quantity()
int UI_get_item_quantity(object obj, int unk)
int obj->get_item_quantity(int unk)

Gets the quantity of the desired object.

Parameters

`obj`	The object whose quantity is desired.
`unk`	An unknown parameter from the original games. Can be omitted if desired, as Exult does not use it.

Return

The quantity of the object if it has it, '1' otherwise.

bool UI_set_item_quantity(object obj, int quant)
bool obj->set_item_quantity(int quant)

Sets the quantity of the desired object. The object's quantity is changed only if the object has it.

Parameters

`obj`	The object whose quantity is to be changed.
`quant`	The desired value for the quantity. If this value is zero, the object will be deleted unless it is not in the game map -- likely because it has been created by Usecode but not yet placed.

Return

Returns true if the object has a quantity, false otherwise.

int UI_get_lift(object obj)
int obj->get_lift()

Gets how far above the ground the object is.

Parameters

obj The object whose lift is desired.

Return

The object's z coordinate.

UI_set_lift(object obj, int lift)
obj->set_lift(int lift)

Moves the object on the vertical direction to a desired height off the ground.

Parameters

`obj`	The object whose lift is to be set.
`lift`	How far above the ground the object is going to be. Must be in the range 0 to 20, but heights above 15 will not be saved (as of 2009/02/26).

int UI_get_item_flag(object obj, int flag)
int obj->get_item_flag(int flag)

Inspects the chosen flag of the given object.

Parameters

`obj`	The object whose flag we wish to inspect. Not all flags are available for all objects.
`flag`	What we want to know. This is a number in the 0 to 63 range.

The flag parameter is a numeric value describing a (usually boolean) bit of information about the object in question. Valid pre-defined values for the flag are:

INVISIBLE = 0	Object is invisible (rendered with 'invisible' palette, or not at all).
ASLEEP = 1	Object is asleep. Only really useful for NPCs.
CHARMED = 2	Object is charmed (attacks allies). Only really useful for NPCs.
CURSED = 3	Object is cursed (stats malus). Only really useful for NPCs.
DEAD = 4	Object is dead. Only really useful for NPC/monster. DONT set on dead bodies, causes bugs.
IN_PARTY = 6	Object is an NPC in the party.
PARALYZED = 7	Object is paralyzed and unable to move. Normal objects will be stationary by default.
PARALYSED = 7	Canadian/British spelling.
POISONED = 8	Object is afflicted with poison. Can be set on objects, but will only do anything to NPCs.
PROTECTION = 9	Object is protected from harm. Only really useful for NPCs.
ON_MOVING_BARGE = 10	Object is on a 'barge' object that is moving.
OKAY_TO_TAKE = 11	Object will not trigger stealing usecode if you take it.
MIGHT = 12	Object has might (Stats boon). Only really useful for NPCs.
IMMUNITIES = 13	Object has several immunities. Can be inspected only.
CANT_DIE = 14	Object can't die. Used for testing purposes, and certain critical NPCs (such as L.B.). Can be inspected only.
IN_ACTION = 15	Object is executing the usecode called by the Dance spell.
DONT_MOVE = 16	SI: The NPC cannot move.
DONT_RENDER = 16	BG: The NPC cannot move, and is not rendered at all.
SI_ON_MOVING_BARGE = 17	SI: Object is on a special instance of the SI barges. (Turtle for example.)
TEMPORARY = 18	Object is temporary and will decay once the chunk it is in is un-cached.
ACTIVE_SAILOR = 20	Object is the 'captain' of a barge. When getting the flag, you will actually get the current captain.
OKAY_TO_LAND = 21	Set in usecode for flying carpet, TRUE if you can land currently.
BG_DONT_MOVE = 22	BG: BG's version of DONT_MOVE.
SI_DONT_RENDER = 22	SI: SI's version of DONT_RENDER.
IN_DUNGEON = 23	If set on PC or an NPC, they won't trigger the stealing usecode if they take food objects.
IS_SOLID = 24	Used by gangplank usecode to determine if an object is solid.
CONFUSED = 25	This will be set if the avatar failed copyright protection questions in SI. Only really meaningful used on the avatar.
ACTIVE_BARGE = 26	Object is a barge object moving, or on a barge object that is moving. Set in usecode, and mostly used for the SI 'NPC' ships such as the turtle.
MET = 28	Object has been talked to previously. Should be set in a conversation Usecode script. This determines conversation behavior, and whether the NPC's real name or shape name is displayed when they are single-clicked on. BG originally used global flags for this, which amounts to an extra 250-odd flags. What a waste of time.
SI_TOURNAMENT = 29	Literal plot immunity: the NPC can die only if the plot allows it. If enough damage is taken in a single blow, the object will call usecode (eventid = 7) on death. Used for the List Field in SI.
SI_ZOMBIE = 30	Object will not respond to normal cues. Used for sick Neyobi, insane party members/Cantra.
NO_SPELL_CASTING = 31	Object cannot cast spells. Set when the magebane strikes the object.
POLYMORPH = 32	Object is polymorphed.
TATTOOED = 33	Object has been tattooed. Set after the lady tattoos you by usecode. Causes the avatar portraits to use a different 'tattooed' shape num.
READ = 34	Object can read serpent- or rune-script text. Only really meaningful used on the avatar.
PETRA = 35	Object has switched bodies with Petra. This changes the portraits of NPCs according to a list in the 'avatar_data.txt' file. Only really meaningful for NPCs in that list.
FLIGHT = 36	Object can fly. Only really useful for NPCs.
FREEZE = 37	Object is freezing. Only really useful for NPCs.
NAKED = 38	Object is naked. On the avatar, causes him/her to use the appropriate 'naked' shape. On other NPCs there no effect. To actually make NPCs naked, use set_polymorph instead.

Return

For most flags, true if the flag is set (that is, in effect), false otherwise. There is one exception, however: The 'ACTIVE_SAILOR' and 'ACTIVE_BARGE' flags have a peculiar behavior in that they actually returns an object reference to the last object to have that flag set, or zero if no object has been set, or if the flag has been cleared with 'clear_item_flag' intrinsic for the given flag.

With the exception of the OKAY_TO_TAKE, TEMPORARY and INVISIBLE flags, these flags are valid for NPCs only. You can get, set or clear any of those values and Exult will not complain; however, it will also not save the values of the flags except for the three mentioned before. Moreover, the INVISIBLE flag will not be saved for objects unless they are of 'quality flags' class.

UI_set_item_flag(object obj, int flag)
obj->set_item_flag(int flag)

Sets the desired flag for the given object. Many flags have immediate effects when set; most do not. See the get_item_flag intrinsic for flag values.

Parameters

`obj`	The object whose flag we wish to set. Not all flags are available for all objects.
`flag`	What flag we want to set. This is a number in the 0 to 63 range; it can be any of the values for the 'flag' parameter of the `set_item_flag` intrinsic.

In the special case of the 'ACTIVE_SAILOR' and 'ACTIVE_BARGE' flags, stores the supplied object, instead of a flag value. This stored object will be returned by future calls of the 'get_item_flag' intrinsic for the given flag.

UI_clear_item_flag(object obj, int flag)
obj->clear_item_flag(int flag)

Clears the desired flag for the given object. Many flags have immediate effects when cleared; most do not. See the get_item_flag intrinsic for flag values.

Parameters

`obj`	The object whose flag we wish to clear. Not all flags are available for all objects.
`flag`	What flag we want to clear. This is a number in the 0 to 63 range; it can be any of the values for the 'flag' parameter of the `set_item_flag` intrinsic.

In the special case of the 'ACTIVE_SAILOR' and 'ACTIVE_BARGE' flags, the object that they stores is set to zero. This will be the return of any future calls to the 'get_item_flag' intrinsic for the given flag.

object UI_get_barge(object obj)
object obj->get_barge()

Checks the barge upon which the supplied object is on.

Parameters

obj The object to be inspected.

Return

Returns zero if no valid object is passed, or if the object is not lying on a barge. Otherwise, returns the object reference of the barge (shape 961) object upon which the supplied object lies.

UI_set_barge_dir(object obj, int dir)
obj->set_barge_dir(int dir)

If 'obj' is a barge object, sets its direction (along with all objects laying on 'obj') to 'dir'. 'dir' can be one of the constants defined for 'find_direction' intrinsic.

Parameters

`obj`	The object to be animated.
`dir`	The 8-cardinal-point direction that the barge should face. This can be one of the values returned by the `find_direction` intrinsic.

bool UI_on_barge()

Determines if the entire party is inside the same barge as the avatar.

SI SPECIFIC

In SI, this intrinsic also forces the barge to refresh the list of all objects lying on it.

Return

If the avatar is on a barge and all party members are on that same barge, returns true; in all other cases, returns false.

object UI_get_container(object obj)
object obj->get_container()

Gets the container of the supplied object.

Parameters

obj The object whose container is desired.

Return

Return is zero if the object is directly in the game world, or an object reference to its immediate container otherwise.

UI_remove_item(object obj)
obj->remove_item()

Removes the object from the game world and from the 'last created' stack. If the object is not an NPC, it will de deleted; NPCs will still exist.

Parameters

obj The object to be deleted.

int UI_get_usecode_fun(object obj)
int obj->get_usecode_fun()

Gets the usecode function number of an object. This takes into consideration a NPC's assigned function (if any) and the correct shape <> function mapping for shapes > 1024.

Parameters

obj The object whose usecode function we desire.

Return

The usecode function number that is assigned to the object.

UI_set_usecode_fun(actor npc, function fun)
npc->set_usecode_fun(function fun)

Assigns a new usecode function to an NPC.

Parameters

`npc`	The NPC whose usecode function will be changed.
`fun`	The new usecode function.

int UI_get_map_num(object obj)
int obj->get_map_num()

Checks which map an object is in.

Parameters

obj The object whose map is desired.

Return

The map in which the object is located, or -1 if the object is nowhere.

int UI_get_item_weight(object obj)
int obj->get_item_weight()

Checks an object's weight.

Parameters

obj The object whose weight is desired.

Return

The object's weight.

bool UI_is_on_keyring(int qual)

Checks if a key is in the keyring. Note that the keyring is a global object; multiple keyrings will share the same list of keys.

Parameters

qual The quality of the key to be checked.

Return

true if the key is on the keyring, false otherwise.

UI_add_to_keyring(int qual)

Adds a key to the keyring. Note that the keyring is a global object; multiple keyrings will share the same list of keys.

Parameters

qual The quality of the key to be added.

bool UI_remove_from_keyring(int qual)

Removes a key from the keyring. Note that the keyring is a global object; multiple keyrings will share the same list of keys.

Parameters

qual The quality of the key to be removed.

Return

If the key was on the keyring, returns true; otherwise, returns false.

int UI_apply_damage(int base, int hits, int type, object obj)

Causes random damage of a given type to the desired object, subject to armor.

Parameters

`base`	The 'strength' of the attack; only one third of this value (rounded down) is used to deal damage. This parameter is ignored depending on damage type; specifically, damage of `LIGHTNING_DAMAGE` type ignores this parameter.
`hits`	The 'weapon points' of the attack. If this parameter is equal to 127 or more, this intrinsic will ignore all armor and deal a fixed 127 points of damage of the specified type, ignoring the 'base' parameter.
`type`	The type of the damage. If the target is immune to this damage type, he will take no damage from this intrinsic; conversely, a monster vulnerable to this type of damage takes doubled damage. Armor-granted immunities also protect the target from the effects of this intrinsic. If the damage type is `LIGHTNING_DAMAGE`, `ETHEREAL_DAMAGE` or `SONIC_DAMAGE`, this intrinsic will ignore armor.
`obj`	The object to be damaged.

The type of the damage is a numerical value that describes what kind of damage should be caused. It can be one of the following values:

NORMAL_DAMAGE = 0	Normal damage.
FIRE_DAMAGE = 1	Damage from heat sources.
MAGIC_DAMAGE = 2	Damage from a magical source.
LIGHTNING_DAMAGE = 3	Damage from electrical sources such as lightning. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
POISON_DAMAGE = 3	Damage from poison. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
STARVATION_DAMAGE = 3	Damage from starvation. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
FREEZING_DAMAGE = 3	Damage from frostbite. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
ETHEREAL_DAMAGE = 4	Special magical damage, basically magic damage not blocked by normal magic resistance or armor.
SONIC_DAMAGE = 5	Sound-based damage. This damage type ignores armor.

The damage is calculated from a series of generated random numbers. It proceeds along the following steps:

If the target is wearing any armor that makes him/her immune to the specified damage type, he takes no damage from this intrinsic.
If hits is 127 or more, 127 points of damage are caused to the target. This case ignores all armor.
If base/3 (rounded down) is zero, it does not affect damage; likewise, if hits is zero, it does not affect damage. A random number will be generated for each of them that are nonzero, ranging from 1 to base/3 or from 1 to hits, as appropriate. These two random numbers are added together.
If the damage type does not ignore armor, the armor value of everything worn by the target is computed. Monster-specified armor values are also added to this value. If the total armor is at least zero, a random number in the range 1 to (total armor) is generated and subtracted from the damage total above.
If the target has immunities granted by his monster data, he will take no damage; if he has any vulnerabilities, the remaining damage, if positive, will be doubled.

Return

Returns true if any damage is caused on a valid target, false otherwise.

UI_reduce_health(object obj, int hits, int type)
obj->reduce_health(int hits, int type)

Causes a fixed amount of damage of the specified type to a target. This intrinsic ignores armor and armor-granted immunities.

Parameters

`obj`	The object to be damaged.
`hits`	How much damage is to be caused.
`type`	The type of the damage. If the target is immune to this damage type, he will take no damage from this intrinsic; conversely, a monster vulnerable to this type of damage takes doubled damage. Armor-granted immunities are ignored.

The type of the damage is a numerical value that describes what kind of damage should be caused. It can be one of the following values:

NORMAL_DAMAGE = 0	Normal damage.
FIRE_DAMAGE = 1	Damage from heat sources.
MAGIC_DAMAGE = 2	Damage from a magical source.
LIGHTNING_DAMAGE = 3	Damage from electrical sources such as lightning. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
POISON_DAMAGE = 3	Damage from poison. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
STARVATION_DAMAGE = 3	Damage from starvation. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
FREEZING_DAMAGE = 3	Damage from frostbite. Extremely painful, even a single point of damage causes the screen to flash a red color. This damage ignores all armor and does not depend on the attacker's strength.
ETHEREAL_DAMAGE = 4	Special magical damage, basically magic damage not blocked by normal magic resistance or armor.
SONIC_DAMAGE = 5	Sound-based damage. This damage type ignores armor.

int UI_attack_object(object attacker, object target, int weapon)
int attacker->attack_object(object target, int weapon)

Causes a NPC to attack the object with a given weapon. This intrinsic does not animate the NPC in any way; it only emulates a hit with the selected weapon.

Parameters

`attacker`	Who is attacking.
`target`	What is being attacked. Must be an object or NPC.
`weapon`	What shape in 'SHAPES.VGA' to use as the source of the weapon information in the attack, or -1 for an unarmed attack. If this is a missile or thrown weapon, it will consume the appropriate ammunition (if any) and fire the correct projectile.

If the NPC is targeting a tile, the attack will only be meaningful if the weapon causes an explosion.

Return

true if a melee attack hits or if a ranged attack fires its projectile; returns false if the melee attack missed or if the attack could not be realized for any reason (including an invalid attacker, an invalid target, being out of range, lack of adequate ammunition for the given weapon) if attacking a valid target with a valid weapon, false otherwise.

UI_fire_projectile(object obj, int dir, int proj, int attpts, int weapon, int ammo)
obj->fire_projectile(int dir, int proj, int attpts, int weapon, int ammo)

Causes the given object to fire a high-speed missile in the supplied direction.

Parameters

`obj`	The object that will fire the projectile.
`dir`	Numeric value indicating the direction in which the projectile will be fired.
`proj`	The shape in 'SHAPES.VGA' of the projectile to be fired.
`attpts`	Numeric value determining the likelihood that the missile will hit. Works like the 'att' parameter in the `roll_to_win` intrinsic in a contest against the target's `COMBAT` property.
`weapon`	The shape in 'SHAPES.VGA' whose weapon information will be used when the missile hits.
`ammo`	The shape in 'SHAPES.VGA' whose ammunition information will be used when the missile hits.

The direction into which the projectile is filed is the 8-cardinal-point direction in which the projectile will travel. It can be one of the following values:

NORTH = 0	NORTHEAST = 1	EAST = 2	SOUTHEAST = 3	SOUTH = 4
SOUTHWEST = 5	WEST = 6	NORTHWEST = 7

NPC INTRINSICS

These intrinsics allow you to get or set NPC-specific properties of a NPC, such as schedules, alignment or stats.

int UI_get_npc_object(int npc)
int npc->get_npc_object()
int[] UI_get_npc_object(int npc[])

Gets the NPC object references of one or more NPC numbers.

Parameters

npc The NPC number, or array of NPC numbers, whose object references are desired.

Return

If the input is an array of NPC numbers, the return is an array of NPC object references. The output array places the NPC references in the same order they are in the input array.

Otherwise, the return is the object reference of the given NPC number.

int UI_get_schedule_type(actor npc)
int npc->get_schedule_type()

Gets the current schedule of an NPC.

Parameters

npc The NPC whose schedule is desired.

Return

Zero if 'npc' is not a valid NPC; otherwise, an integer associated to the NPC's current schedule. This is the same value that is reported in the cheat screen, and can be one of the following values:

IN_COMBAT = 0	PACE_HORIZONTAL = 1	PACE_VERTICAL = 2	TALK = 3
DANCE = 4	EAT = 5	FARM = 6	TEND_SHOP = 7
MINE = 8	MINER = 8	HOUND = 9	STANDTHERE = 10
LOITER = 11	WANDER = 12	BLACKSMITH = 13	SLEEP = 14
WAIT = 15	MAJOR_SIT = 16	GRAZE = 17	BAKE = 18
SEW = 19	SHY = 20	LAB = 21	THIEF = 22
WAITER = 23	SPECIAL = 24	KID_GAMES = 25	TAG = 25
EAT_AT_INN = 26	DUEL = 27	SPAR = 27	PREACH = 28
PATROL = 29	DESK_WORK = 30	FOLLOW_AVATAR = 31

SI SPECIFIC

If the NPC is traversing a path created by a call to either, UI_path_run_usecode or UI_si_path_run_usecode intrinsics, this intrinsic will return the value WALK_TO_SCHEDULE = 32 instead of the values above.

UI_set_schedule_type(actor npc, int sched)
npc->set_schedule_type(int sched)

Gets the current schedule of an NPC.

Parameters

`npc`	The NPC whose schedule we wish to change.
`sched`	The new schedule type. Can be any of the values listed as the return of a `get_schedule_type` intrinsic call.

SI SPECIFIC

The SI-specific value WALK_TO_SCHEDULE = 32 cannot be set with this intrinsic; only a call to either, UI_path_run_usecode or UI_si_path_run_usecode intrinsics can do that.

UI_modify_schedule(actor npc, int time, int sched, int pos[2])
npc->modify_schedule(int time, int sched, int pos[2])

Changes the schedule table of an NPC for the desired time period. This new schedule is persistent across save games. The NPC will execute his/her new schedule in the map he/she currently resides when the time comes.

Parameters

`npc`	The NPC whose schedule table is to be changed.
`time`	An integer specifying the time period of the new schedule. Must be an integer in the 0-7 range, such as those returned by the `part_of_day` intrinsic.
`sched`	An integer specifying the new schedule. Must be an integer in the 0-31 range, such as those returned by the `get_schedule_type` intrinsic.
`loc`	A (x, y) location, specifying the location of the new schedule.

UI_set_new_schedules(actor npc, int time, int sched, int loc[2])
UI_set_new_schedules(actor npc, int time[n], int sched[n], int loc[2n])
npc->set_new_schedules(int time, int sched, int loc[2])
npc->set_new_schedules(int time[n], int sched[n], int loc[2n])

Changes the schedule table of an NPC. This new schedule table is persistent across save games. The NPC will execute his/her new schedules in the map he/she currently resides.

Parameters

`npc`	The NPC whose schedule table is to be changed.
`time`	An integer, or array of integers, specifying the time periods of the new schedules. Each element of the array is an integer in the 0-7 range, such as those returned by the `part_of_day` intrinsic.
`sched`	An integer, or array of schedules, specifying the new schedules. There must be one such schedule for each time period supplied in the 'time' parameter. Each element of this array is an integer in the 0-31 range, such as those returned by the `get_schedule_type` intrinsic.
`loc`	An array of (x, y) positions, specifying the new schedule locations. This array must have a (x, y) location for each time period supplied in the 'time' parameter.

UI_run_schedule(actor npc)
npc->run_schedule()

Forces an NPC to return to his/her regularly scheduled activities.

Parameters

npc The NPC that should be minding his own business.

UI_revert_schedule(actor npc)
npc->revert_schedule()

Reverts the schedules of a NPC to those stored in 'STATIC/schedule.dat'. Can be risky for NPCs not in the original games.

Parameters

npc The NPC whose schedule is to be reset.

int UI_get_npc_prop(object obj, int prop)
int UI_get_npc_prop(object obj, string prop)
int obj->get_npc_prop(int prop)
int obj->get_npc_prop(string prop)

Gets the current value of an object's or NPC's property. Despite the name, this intrinsic can also be called for any object, although most properties will be unavailable for anything but NPCs.

Parameters

`obj`	The object or NPC whose property is desired.
`prop`	String or integer specifying the property to be inspected.

If the desired property has been specified as an integer, it must be in the range from 0 to 11. It can be one of the following values:

STRENGTH = 0	DEXTERITY = 1	INTELLIGENCE = 2	HEALTH = 3
COMBAT = 4	MANA = 5	MAX_MANA = 6	TRAINING = 7
EXPERIENCE = 8	FOODLEVEL = 9	SEX_FLAG = 10	MISSILE_WEAPON = 11

Return

Returns the current value of the specified property. The following properties are special cases:

`HEALTH`	This is the only meaningful property for non-NPC objects. Returns the current remaining hit points of the object or NPC.
`SEX_FLAG`	The return is `true` if the NPC is female, `false` otherwise.
`MISSILE_WEAPON`	The return is `true` if the NPC is using a missile weapon or a good thrown weapon (such as a spear), `false` otherwise.

This intrinsic returns zero for any property which is not meaningful for the supplied object; this includes string properties that have not been previously set with a UI_set_npc_prop intrinsic call.

BG SPECIFIC

Standard BG does not have sex data for anyone but the avatar, so the return is almost always 'false'. This is not a limitation of the engine or of Exult, just a statement about the game data.

UI_set_npc_prop(object obj, int prop, int delta)
UI_set_npc_prop(object obj, string prop, int delta)
obj->set_npc_prop(int prop, int delta)
obj->set_npc_prop(string prop, int delta)

Changes an object's or NPC's property by the specified value. Despite the name, this intrinsic can also be called for any object, although most properties will be unavailable for anything but NPCs.

Parameters

`obj`	The object or NPC whose property is to be changed.
`prop`	String or integer specifying the property to be changed.
`delta`	The desired numeric change in the specified property.

If the desired property has been specified as an integer, it must be one of the values listed in the UI_get_npc_prop intrinsic description. The following values are special cases:

`HEALTH`	This is the only meaningful property for non-NPC objects. Changes the remaining hit points of the object or NPC. If the remaining hit points become zero, an object will become indestructible.
`EXPERIENCE`	This property is changed by half of the specified value.
`SEX_FLAG`	A nonzero 'delta' sets the NPC to female, while a zero 'delta' sets the NPC to male.
`MISSILE_WEAPON`	Nothing happens when this property value is supplied.

BG SPECIFIC

In the original BG, you could not set the sex flag except by hex-editing the game data. Exult does not suffer from this limitation.

If the desired property has been specified as a string, it will be created if it does not exist; its initial value is assumed to be zero in this case. Only NPCs can have such properties, and they will be displayed in the NPC's stats window.

Return

Always returns '0'.

string UI_get_npc_name(object obj)
string obj->get_npc_name()
string[] UI_get_npc_name(object obj[])

Gets the name of one or more objects. Despite the name, this intrinsic can be called for any object, not just NPCs; for non-NPCs, the return is the text displayed when you click the object.

Parameters

obj The object, or array of objects, whose names are desired.

Return

If the input is an array of objects, the return is an array with the names of these objects. The output array places the object names in the same order as the objects are in the input array.

Otherwise, the return is the name of the given object.

UI_set_npc_name(actor npc, string name)
npc->set_npc_name(string name)

Changes the name of an NPC.

Parameters

`npc`	The NPC whose name is to be changed.
`name`	The new name.

UI_is_npc(mixed obj)
obj->is_npc()

Determines if a given object is an NPC.

Parameters

obj The object to be checked.

Return

true if the object is an NPC, false otherwise.

bool UI_is_dead(actor npc)
bool npc->is_dead()

Checks if the NPC is dead or alive. This is equivalent to checking if the 'DEAD' flag is set.

Parameters

npc Who we want to check.

Return

Returns true if the NPC is dead, false otherwise.

int UI_get_npc_number(actor npc)
int npc->get_npc_number()

Parameters

npc The NPC whose number is desired. This is intended to receive an object reference, but accepts integers as normal.

Return

The NPC's number. This is a negative number for all 'true' NPCs, -356 for the avatar, 1 for monsters or zero for anything that is not a valid NPC.

int UI_get_alignment(actor npc)
int npc->get_alignment()

Gets the NPC's attitude towards the avatar.

Parameters

npc The NPC whose alignment is desired.

Return

Returns a number describing the NPC's attitude towards the avatar. Can be one of the following values:

NEUTRAL = 0

GOOD = 1

EVIL = 2

CHAOTIC = 3

UI_set_alignment(actor npc, int align)
npc->set_alignment(int align)

Sets an NPC's attitude towards the avatar. This change forces the NPC to reevaluate his targets, and may stop the NPC from fleeing.

Parameters

`npc`	The NPC to be adjusted.
`align`	The new attitude towards the avatar. Can be any of the return values of `get_alignment` intrinsic.

UI_remove_npc(actor npc)
npc->remove_npc()

Removes the NPC from the game world. The NPC is effectively placed in 'limbo', and has its schedule set to 'WAIT'.

Parameters

npc The NPC to be removed.

UI_kill_npc(actor npc)
npc->kill_npc()

Kills the specified victim.

Parameters

npc The soon-to-be-dead NPC.

int UI_get_attack_mode(actor npc)
int npc->get_attack_mode()

Gets the NPC's attack mode.

Parameters

npc The NPC whose attack mode is desired.

Return

A numeric value specifying how the NPC behaves in combat. Possible values are:

NEAREST = 0	WEAKEST = 1	STRONGEST = 2	BERSERK = 3	PROTECT = 4
DEFEND = 5	FLANK = 6	FLEE = 7	RANDOM = 8	MANUAL = 9

UI_set_attack_mode(actor npc, int mode)
npc->set_attack_mode(int mode)

Changes the NPC's attack mode to the desired value.

Parameters

`npc`	The NPC whose attack mode is to be changed.
`mode`	Numeric value determining how the NPC should behave in combat. Can be one of the return values of `get_attack_mode` intrinsic.

int UI_get_npc_id(actor npc)
int npc->get_npc_id()

Retrieves a NPC's identity. This identity has no real effect other than that given to it by usecode.

Parameters

npc The NPC whose identity is sought.

Return

If given a valid NPC, this intrinsic returns that NPC's identity; otherwise it returns zero.

UI_set_npc_id(actor npc, int id)
npc->set_npc_id(int id)

Changes an NPC's identity. This identity has no real effect other than that given to it by usecode.

Parameters

`npc`	The NPC whose identity is to be changed.
`id`	The new identity value. Must be an integer in the 0-31 range; values outside this range are accepted but incorrectly saved.

actor UI_get_oppressor(actor npc)
actor npc->get_oppressor()

Gets whoever is attacking the supplied NPC. This oppressor can be set through usecode, but it is also automatically set to whomever has last attacked (caused damage to) the supplied NPC. It is also set whenever an NPC acquires a new target -- this NPC will be set as its target's oppressor.

Parameters

npc The NPC whose oppressor is desired.

Return

Returns the NPC number of the supplied NPC's oppressor, or zero if no valid NPC was supplied. The return value has the opposite sign from what you get from a get_npc_number intrinsic call.

UI_set_oppressor(actor npc, actor opp)
npc->set_oppressor(opp)

Sets the supplied NPCs oppressor to another NPC.

Parameters

`npc`	The NPC whose oppressor is to be changed.
`opp`	The NPC that is to be the new oppressor, which must be distinct from the NPC we are altering. Must be a true NPC; an egg- or usecode- spawned monster has no real NPC number in Exult, and cannot be an oppressor.

object UI_get_readied(actor npc, int spot)
object npc->get_readied(int spot)

Inspects the given equipment slot in an NPC.

Parameters

`npc`	The NPC we wish to inspect.
`spot`	What equipment slot we wish to inspect. Can be any of the values of 'spot' for `is_readied` intrinsic.

Return

Returns zero for an invalid spot or if the spot is empty, otherwise returns an object reference to the object that resides in the desired spot.

bool UI_is_readied(actor npc, int spot, int shape, int frame)
npc->is_readied(int spot, int shape, int frame)

Returns 'true' if an object with shape 'shape' and frame 'frame' is readied in ready spot 'spot' of 'npc', 'false' otherwise. 'frame' can be the wildcard 'FRAME_ANY'. Valid values for 'spot' are:

For SI, it is better to use 'get_readied' intrinsic instead.

Checks to see if the given NPC is wearing a piece of equipment on a specified location.

Parameters

`npc`	The NPC whose equipment is to be inspected.
`spot`	The spot we are checking.
`shape`	The shape we are looking for.
`frame`	The frame we are looking for. Can be `FRAME_ANY = -359` to match any frame.

BG SPECIFIC

In BG, the 'spot' parameter is limited to the 0-12 range. It can take any of the following values:

BG_BACKPACK = 0	Containers worn on the back, such as backpacks
BG_WEAPON_HAND = 1	Item wielded in weapon hand
BG_SHIELD_HAND = 2	Off-hand is also called the shield hand
BG_OFF_HAND = 2	Item wielded in off-hand
BG_BELT = 3	Items worn around the waist such as belts, and girdles
BG_NECK = 4	Items worn around the neck such as amulets, and necklaces
BG_TORSO = 5	Worn on the torso, such as armor
BG_LEFT_RING = 6	Item worn on left finger (ring)
BG_RIGHT_RING = 7	Item worn on right finger (ring)
BG_QUIVER = 8	Arrows held in quiver
BG_HEAD = 9	Items worn on the head such as headbands, helms, etc
BG_LEGS = 10	Worn on legs, such as greaves
BG_FEET = 11	Worn on feet, such as boots
BG_USECODE = 12	Exult-only. Usecode container, used for containing eggs 'carried' by player
BG_CLOAK = 13	Exult-only. Items worn around the neck and back such as cloaks and capes
BG_GLOVES = 14	Exult-only. Items worn on both hands, such as gloves
BG_TRIPLE_BOLTS = 15	Special slot used by triple crossbow bolts
BG_EARS = 16	Exult-only. Earrings, such as the serpent earrings
BG_BACK_SHIELD = 17	Exult-only. Shield slung across the back
BG_BACK_2H = 19	Exult-only. Weapon slung across the back
BG_BOTH_HANDS = 20	Special slot for item wielded with both hands
BG_LRGLOVES = 21	Special slot for item wielded with both ring slots
BG_AMULET = 22	Exult-only. Items worn on the neck such as a collar

SI SPECIFIC

In SI, the 'spot' parameter is limited to the 0-17 range. It can take any of the following values:

SI_OFF_HAND = 0	Items wielded in the off-hand
SI_SHIELD_HAND = 0	Off-hand is also called shield hand
SI_WEAPON_HAND = 1	Items wielded in the weapon hand
SI_CLOAK = 2	Items worn around the neck and back such as cloaks and capes
SI_AMULET = 3	Items worn on the neck such as a collar
SI_HEAD = 4	Items worn on the head such as a helm
SI_GLOVES = 5	Items worn on both hands, such as gloves
SI_USECODE = 6	Usecode container, used for containing eggs 'carried' by player
SI_RIGHT_RING = 7	Ring or item worn on right hand
SI_LEFT_RING = 8	Ring or item worn on left hand
SI_EARS = 9	Earrings, such as the serpent earrings
SI_QUIVER = 10	Arrows held in quiver
SI_BELT = 11	Worn across the waist, such as belts and girdles
SI_TORSO = 12	Worn on the torso, such as armor
SI_FEET = 13	Worn on feet, such as boots
SI_LEGS = 14	Worn on legs, such as greaves
SI_BACKPACK = 15	Containers worn on the back, such as backpacks
SI_BACK_SHIELD = 16	Shield slung across the back
SI_BACK_2H = 17	Weapon slung across the back
SI_TRIPLE_BOLTS = 18	Exult-only. Special slot used by triple crossbow bolts
SI_BOTH_HANDS = 20	Special slot for item wielded with both hands
SI_LRGLOVES = 21	Exult-only. Special slot for item wielded with both ring slots

Return

Returns true if the NPC is wearing an object of the specified shape and frame on the inspected slot, false if not.

int UI_get_weapon(actor npc)
int npc->get_weapon()

Inspect what type of weapon an NPC is using.

Parameters

npc The NPC whose weapon is to be inspected.

Return

Zero if no weapon, one- or two-handed, is wielded by the NPC. Otherwise, the shape in 'SHAPES.VGA' of the weapon being used.

UI_set_opponent(actor npc, object obj)
npc->set_opponent(object obj)

Makes the supplied NPC target the desired object. This does not make the NPC attack unless his schedule is IN_COMBAT. This intrinsic will reevaluate if the NPC's oppressor is actually attacking him, and will invalidate the oppressor if not.

Parameters

`npc`	The NPC whose opponent we wish to set.
`obj`	What the target should be set to. If the target is an NPC, his/her oppressor will be set to the attacking NPC.

UI_sit_down(actor npc, object obj)
npc->sit_down(object obj)

Causes the specified NPC to sit on the given chair. 'npc' sit on 'obj'. 'obj' must be a chair/seat shape (currently, hardcoded to 873/292). For barge seats, also runs the barge usecode when everyone in the party is seated.

Parameters

`npc`	The NPC that is going to sit down.
`obj`	The chair that should be sat upon.

If the chair is shape 292 (a barge seat), if there is a barge containing the chair and if all party members are sitting, then Exult will run the barge's usecode (function 0x634).

UI_get_body_npc(object obj)
obj->get_body_npc()

Inspects what NPC (is associated with the given dead body.

Parameters

obj The object to be inspected.

Return

If the supplied object is the dead body of an NPC, returns the NPC's number, as reported by get_npc_num intrinsic call; otherwise, returns zero.

actor UI_resurrect(object obj)
actor obj->resurrect()

Brings a dead body back to life. If 'obj' is the body of an NPC, resurrects the NPC and returns a reference to the NPC; otherwise, returns a null ('0') reference.

Parameters

obj The body that is to be resurrected. Monsters cannot be brought back to life in this manner, so it must be the body of a true NPC. This body will be deleted after the usecode ends, and all of its contents will be transferred to the resurrected NPC.

Return

Zero if the supplied object was not the body of an NPC, otherwise an object reference to the resurrected NPC.

UI_resurrect_npc(actor npc)
npc->resurrect_npc()

Brings the desired NPC back to life. If the NPC has a body, this body will be completely ignored; moreover, the NPC will be back without any equipment that was left on his body when he died.

Parameters

npc Who is to be resurrected.

UI_set_polymorph(actor npc, int shape)
npc->set_polymorph(int shape)

Makes an NPC take a different, temporary shape. The polymorphed shape is persistent across save games. The NPC can be returned to its normal shape by unsetting the NPC's POLYMORPH flag with a call to clear_item_flag intrinsic.

Parameters

`npc`	The NPC to be polymorphed.
`shape`	The shape in 'SHAPES.VGA' that the NPC will take.

int UI_get_temperature(actor npc)
int npc->get_temperature()

Inspects a NPC's temperature. The NPC's temperature changes over time depending on whether or not his FREEZE flag is set.

Parameters

npc The NPC whose temperature is sought.

Return

A numeric value in the 0-63 range specifying how cold the NPC is; 0 being normal temperature and 63 being freezing cold.

UI_set_temperature(actor npc, int temp)
npc->set_temperature(int temp)

Changes a NPC's temperature. The NPC's temperature changes over time depending on whether or not his FREEZE flag is set.

Parameters

`npc`	The NPC whose temperature is to be changed.
`temp`	The new value for the temperature. This is value in the 0-63 range specifying how cold the NPC is; 0 being normal temperature and 63 being freezing cold.

int UI_get_temperature_zone(object obj)
int obj->get_temperature_zone()

Inspects a NPC's temperature zone. The temperature zone is a grouping of temperature ranges that determine how the NPC is affected by the cold. Like the NPC's temperature, it changes over time depending on whether or not his FREEZE flag is set.

Parameters

obj The NPC whose temperature zone is sought.

Return

Zero if anything but an NPC is supplied; otherwise, a number in the 1-5 range, equal to the frame of the stats gump that should be displayed.

int UI_get_npc_warmth(object obj)
int obj->get_npc_warmth()

Inspects the warmth given by a NPC's equipment.

Parameters

obj The object to be checked.

Return

The combined warmth given by all objects worn by the NPC, or -75 if supplied with anything but a valid NPC.

PARTY INTRINSICS

These intrinsics relate to obtaining or modifying the list of party members.

actor[] UI_get_party_list()
actor[] UI_get_party_list2()

Gets a list of all party members.

Return

An array containing object references to all of the party's members, including the avatar.

UI_add_to_party(actor npc)
npc->add_to_party()

Makes the specified NPC join the avatar's party, if there is enough room. The NPC's schedule is changed to FOLLOW_AVATAR, and his/her alignment is changed to GOOD.

Parameters

npc Who should be added to the party.

UI_remove_from_party(actor npc)
npc->remove_from_party()

Removes the specified NPC from the avatar's party. The NPC's alignment is changed to NEUTRAL.

Parameters

npc Who should be removed from the party.

object[] UI_get_dead_party(object obj)
object[] obj->get_dead_party()

Gets a list of all dead party members near a given object.

Parameters

obj The object around which dead bodies will be searched.

Return

An array containing object references to the bodies of all dead party members within 50 tiles of the given object, or zero if no party members were found.

AVATAR INTRINSICS

All intrinsics in this section are about obtaining or modifying properties specific to the Avatar.

actor UI_get_avatar_ref()

Gets an object reference to the avatar.

Return

The Avatar's object reference.

bool UI_in_combat()

Checks if the avatar is in combat.

Return

true if the avatar is in combat mode, false otherwise.

bool UI_is_pc_female()

Determines the avatar's gender.

Return

true if the avatar is a woman, false otherwise.

int UI_get_skin_colour()

Obtains the avatar's skin color.

Return

A numeric value describing the avatar's skin color. The return values are determined by a table in 'avatar_data.txt'.

bool UI_is_pc_inside()

Determines if the avatar has a roof over his head.

Return

Returns true if there is a roof above the avatar's head, false otherwise.

bool UI_wearing_fellowship()

Determines if the avatar is wearing a fellowship amulet.

Return

Returns 'true' if the avatar is wearing a fellowship amulet (shape 955, frame 1), 'false' otherwise.

bool UI_approach_avatar(actor npc)
bool npc->approach_avatar()
bool UI_approach_avatar(actor npc, int unk1, int unk2)
bool npc->approach_avatar(int unk1, int unk2)

Makes a NPC approach the avatar at fairly high speed.

Warning: If the NPC is initially at more than 10 tiles from the avatar, Exult will let him/her walk for about 1/5 seconds before returning, effectively halting the game in the mean time.

NOTICE: In the original, this intrinsic seems: to create the NPC off-screen, while it approaches the avatar due to si_path_run_usecode or the 'TALK' schedule. This requires further investigation; this means that this intrinsic is subject to change.

Parameters

`npc`	Who should approach the avatar.
`unk1`	Unknown parameter from the original. Exult does not use this parameter, but this is subject to change. Ignore this parameter at your own peril.
`unk2`	Unknown parameter from the original. Exult does not use this parameter, but this is subject to change. Ignore this parameter at your own peril.

Return

false if the NPC is dead or cannot reach the avatar, true otherwise.

UI_call_guards()

Causes guard to come and attack a thieving avatar.

UI_attack_avatar()

Causes everyone nearby to attack thieving avatar.

UI_stop_arresting()

Any guards approaching the avatar to arrest will stop what they are doing and will start to wander instead.

UI_save_pos(object obj)
obj->save_pos()

Saves the current position/map of an object. This persists across save games, but there is only one 'slot' in which the position is saved. Therefore, only the last stored position is available.

Parameters

obj The object whose position we want.

UI_teleport_to_saved_pos(object obj, bool flag)
obj->teleport_to_saved_pos(bool flag)

Teleports the avatar and party to the last saved position. Note that only the last position stored by the UI_save_pos intrinsic is available.

Parameters

`obj`	If this is not the avatar, nothing happens. Otherwise, the party is teleported to the stored position.
`flag`	This optional parameter controls whether avatar or party members that are paralyzed or asleep are teleported; if `true`, these members will be teleported, otherwise, they won't; defaults to `false`.

WEATHER/TIME INTRINSICS

These intrinsics allow you to check or alter the weather, the game clock and usecode timers.

int UI_get_timer(int timer)

Gets how many hours elapsed since the timer was set.

Parameters

timer Numeric value indicating the timer to be inspected.

Return

If the specified timer has been initialized by a previous call to 'UI_set_timer' intrinsic, the return is the number of hours since the initialization (or reinitialization) of the timer. Uninitialized timers return a random number in the 0-12 hour range.

UI_set_timer(int timer)

Resets a timer to the current game time.

Parameters

timer Numeric value indicating the timer to be initialized.

int UI_game_day()

Gets the game day.

Return

The current game day, starting with day 0.

int UI_game_hour()

Gets the game hour.

Return

The current game hour in 24-hour format.

int UI_game_minute()

Gets the game minutes.

Return

The current game minute (0-59).

int UI_part_of_day()

Gets the number of 3-hour periods that have elapsed in full since midnight.

Return

Returns an integer in the 0-7 range corresponding to the number of 3-hour periods that have elapsed in full since midnight. More specifically, the return value is equal to 'UI_game_hour()%3'. The following constants are defined for convenience:

MIDNIGHT = 0	EARLY = 1	DAWN = 2	MORNING = 3	NOON = 4
AFTERNOON = 5	EVENING = 6	NIGHT = 7

UI_nap_time(object obj)
obj->nap_time()

Makes the avatar lay down to sleep in the specified bed. What constitutes a bed is currently hard-coded (as of 2009/02/27). Once the avatar reaches the bed, Exult will call usecode function 0x622. If the bed is occupied, causes one of the party members to pop up and say so.

Parameters

obj The bed where the avatar should sleep. This bed should be unoccupied.

UI_advance_time(int amount)

Advances the game time forward.

Parameters

amount Number of game ticks that should be advanced; 25 ticks are equal to one game minute, and 1500 ticks are equal to one game hour.

UI_stop_time(int length)

Stops time for all but the avatar and party.

Parameters

length How long the effect should last. The actual duration, in seconds, is equal to one fourth of this value.

int UI_get_weather()

Returns the current weather state. Return values are:

Return

A numeric value indicating what the current weather is. Possible values are:

CLEAR_WEATHER = 0	No clouds, no precipitation.
SNOWING = 1	Snowing.
RAIN = 2	Raining
SPARKLE = 3	Magical storm, causes magic to fail.
FOG = 4	Nothing happens.
OVERCAST = 5	Light cloud cover.
CLOUDY = 6	Heavy cloud cover.

UI_set_weather(int type)

Modifies the current weather to the desired type. The new weather lasts for 15 game minutes.

Parameters

type Numeric value indicating what the weather should be. Can be any of the values returned by UI_get_weather intrinsic.

USER INTERFACE INTRINSICS

With these intrinsics, you can ask the user for input or display feedback for his actions.

mixed[4] UI_click_on_item()

Displays the targeting square and waits for the player to click on something.

Return

An array with 4 elements. The first element is the object clicked, or zero if the player clicked a tile; the remaining 3 elements make up the (x, y, z) location of the object or tile clicked.

If used after a 'set_intercept_item' intrinsic call, the preassigned object or tile is returned in the same manner as if the player had clicked it.

This intrinsic has a special case: when event == WEAPON (weapon hit), and if item is a valid object, the return will be overridden to be it (although a 'set_intercept_item' intrinsic call takes precedence over this special case).

UI_set_intercept_item(object obj)
obj->set_intercept_item()
UI_set_intercept_item(int obj[2])
UI_set_intercept_item(int obj[3])
UI_set_intercept_item(mixed obj[4])

Preassigns the return of the next 'UI_click_on_item' intrinsic' call.

Parameters

obj What we want to set the return of the next the next 'UI_click_on_item' intrinsic' call to. Can be an object reference, a location (2 or 3 coordinates) or even the return of another 'UI_click_on_item' intrinsic' call.

int UI_input_numeric_value(int min, int max, int step, int default)

Prompts the player for numerical input with the bar slider.

Parameters

`min`	The lowest number allowed.
`max`	The highest number allowed.
`step`	The distance between any two consecutive numbers that can be chosen.
`default`	The initial value selected; this value is forced to conform to the boundaries specified above.

Return

The number chosen by the player.

bool UI_mouse_exists()

Determines if a mouse exists.

Return

Exult always returns true; the original games will return true if a mouse if present, false otherwise.

UI_flash_mouse(int cursor)

Momentarily changes the mouse cursor to another shape.

Parameters

cursor Numeric parameter indicating what the new shape will be. Valid values are:

CURSOR_X = 1	CURSOR_OUT_OF_RANGE = 2	CURSOR_OUT_OF_AMMO = 3
CURSOR_TOO_HEAVY = 4	CURSOR_WONT_FIT = 5

UI_ambient_light(bool onoff)

Toggles on or off a permanent version of the light spell.

Parameters

onoff Flag specifying whether we want to turn the light on or off: true to turn it off, false to turn it on.

UI_cause_light(int length)

Creates a light which illuminates the screen.

Parameters

length How long the created light will last. The duration is in game minutes.

UI_infravision(actor npc, bool onoff)
npc->infravision(bool onoff)

Toggles infravision for the given NPC.

Parameters

`npc`	The NPC that should have infravision toggled. This intrinsic has effect only for party members.
`onoff`	Flag specifying whether we want infravision or not: `true` to turn it on, `false` to turn it off.

UI_set_light(object obj, bool onoff)
obj->set_light(bool onoff)

Marks the given light source as being added to or removed from its containing NPC.

Parameters

`obj`	The light source that is being added or removed.
`onoff`	Flag specifying whether we want to add or remove the light source: `true` to add it to its containing NPC, `false` to remove it.

UI_earthquake(int length)

Causes the screen to shake. Also plays the earthquake SFX at the start of the effect.

Parameters

length The earthquake's duration, in ticks.

UI_armageddon()

Ends the world and kills everyone in it. This is the Armageddon spell from BG; use with care :-). This intrinsic also exists in the original SI, though unlike what happens in BG, it seems to leave no survivors.

Who survives armageddon seems to be hard-coded in the original games; in Exult, you can control who survives this intrinsic by setting the 'Survives Armageddon' flag in the 'NPC Flags' tab in Exult Studio.

Those 'killed' by this intrinsic cannot be resurrected, and they do not leave lootable corpses.

Monster eggs are disabled, as are intrinsics that call guards to attack a thieving avatar.

UI_restart_game()

Stops the music and restarts the game from the last save. The original games started from the beginning of the game; Exult does it differently to preserve the last quicksave.

UI_run_endgame(bool flag)

Runs the endgame.

Parameters

flag Boolean value specifying the manner in which the game was finished. If it is true, will set the game-completion flag that allows the endgame to be viewed from the title screen.

BG SPECIFIC

If 'flag' is 'false', the avatar stepped through the Black Gate; if 'true', the avatar destroyed the Black Gate.

SI SPECIFIC

'flag' has no effect in the endgame.

UI_error_message([special])

Prints the input variables to 'stdout'.

Parameters

One to twelve parameters of any type, whether or not they are arrays. Please note that the original games only one parameter was accepted.

string UI_printf(string out[])

Prints formatted text to 'stdout'.

Parameters

out An array of strings. The first element is the 'format' string. The format string gives the basic text, and has a placeholder for each of the other elements of the array; each element past the first writes its text at the next available placeholder. Placeholders are the '%s' sequence, without the single quotes, embedded in the format string.

Return

An empty string.

DISPLAY INTRINSICS

All intrinsics in this section are related to showing things to the player, be they other portions of the game map or objects from 'SPRITES.VGA'.

UI_center_view(object obj)
obj->center_view()

Centers the screen on a given object.

Parameters

obj The object that the screen should be centered on.

UI_display_area(int pos[])

Displays the specified location on-screen. Overlays sprite shape 10 over the screen.

Parameters

pos The location about which the screen is to be centered. Can be a 3-element (x, y, z) location or a 4-element (x, y, z, map) location. If map is omitted or is -1, the current map is used.

UI_set_camera(object obj)
obj->set_camera()

Centers the screen on a given object.

Parameters

obj The object that the screen should be centered on. If it is an NPC, the camera will follow that NPC.

UI_view_tile(int[2] pos)

Centers screen around a given tile. It is usually better to use UI_display_area instead.

Parameters

pos The (x, y) location to be displayed.

UI_wizard_eye(int length)

Lets the player move the screen around, keeping the avatar in its present location. Overlays sprite shape 10 over the screen.

Parameters

length The duration of the effect, in ticks. Actual duration is increased by 50% in Exult.

UI_fade_palette(int length, int unk, bool type)

Causes the screen to fade to/from black and plays music.

Parameters

`length`	The length, in ticks, of the fade; that is, how long it will take for the fade to happen.
`unk`	Reserved; unknown. This is an unknown parameter from the original games; it is unimplemented in Exult. It cannot be left out, however.
`type`	The type of fade. If `true`, fades from black; if `false`, fades to black.

UI_fade_palette_sleep(int length, int unk, bool type)

Causes the screen to fade to/from black.

When fading to black, plays music 24; otherwise, plays music 22.

Parameters

`length`	The length, in ticks, of the fade; that is, how long it will take for the fade to happen.
`unk`	Reserved; unknown. This is an unknown parameter from the original games; it is unimplemented in Exult. It cannot be left out, however.
`type`	The type of fade. If `true`, fades from black; if `false`, fades to black.

UI_set_time_palette()

Resets palette to default palette, based on time of day and number of lights.

UI_item_say(object obj, string bark)
obj->item_say(string bark)

Causes text to be displayed near the object.

Parameters

`obj`	The object which is to display the text.
`bark`	Text to be displayed.

UI_clear_item_say(object obj)
obj->clear_item_say()

Deletes the string (if any) being displayed near the desired object.

Parameters

obj The object in question.

UI_display_runes(int gump, string runes)

Displays the selected gump on screen and prints lines of runic text on-screen. What font is used to draw the text depends on the gump shown, and is currently hard-coded (as of 2009/02/26).

Parameters

`gump`	The shape in 'GUMPS.VGA' that will be used.
`runes`	An array containing one element per line of runes to display.

If the avatar's READ flag is set, some symbols are converted into pairs of letters. Specifically:

(	TH
)	EE
*	NG
+	EA
,	ST

Additionally, all lowercase letters will be turned into uppercase letters, and pipes ('|') will be converted to spaces.

When compiling code, UCC accepts some escape sequences to make these strings easier to read:

(	\{th}
)	\{ee}
*	\{ng}
+	\{ea}
,	\{st}
\|	\{dot}

UI_book_mode(object obj)
obj->book_mode()

Displays a book or scroll on screen. Text in the book or scroll is supplied through normal conversation methods.

Parameters

obj The object whose shape is to be used to determine what shape from 'GUMPS.VGA' is to be shown. This association is currently hard-coded (as of 2009/02/27): if the shape of the supplied object is equal to 797, a scroll gump will be displayed; otherwise, a book gump will be displayed.

SI SPECIFIC

There is one additional shape which displays a scroll gump: shape 707. This shape, and shape 705 (serpentine book), will both display text using serpentine characters; if the avatar's 'READ' flag is set, any serpentine runes will be translated into normal runes.

UI_book_mode_ex(bool is_scroll, int font)
UI_book_mode_ex(bool is_scroll, int font, int gump)

Displays a book or scroll on screen. Text in the book or scroll is supplied through normal conversation methods.

Parameters

`is_scroll`	Flag determining whether to display a scroll (`true`) or a book gump (`false`). This determines the area occupied by the text, and will determine what shape from 'GUMPS.VGA' to display if none is specified.
`font`	Integer that determines what shape from 'FONTS.VGA' will be used to render the text.
`gump`	Numerical value determining what shape from 'GUMPS.VGA' will be used. The text area is not affected by this parameter.

IMPORTANT NOTES

Unlike the 'UI_book_mode' intrinsic, this intrinsic performs no translation of any kind if the avatar's 'READ' flag is set. This is an intentional design feature -- for example, text written in Gargish and being displayed in a Gargish font should be translated by more than a mere font substitution. Also, the gump shapes should be 'compatible' with the standard book/scroll shapes as Exult will write the text in the same region of the screen as it does for standard books/scrolls.

UI_close_gumps()

Closes all gumps.

IMPORTANT NOTES

This intrinsic does nothing if called when event == READIED or event == UNREADIED. See 'UI_close_gumps2' if you need it to work in these cases.

UI_close_gumps2()

Closes all gumps.

UI_close_gump(object obj)
obj->close_gump()

Closes an object's gump.

Parameters

obj The object whose gump is to be closed.

IMPORTANT NOTES

This intrinsic does nothing if called when event == READIED or event == UNREADIED. See 'UI_close_gump2' if you need it to work in these cases.

UI_close_gump2(object obj)
obj->close_gump2()

Closes an object's gump.

Parameters

obj The object whose gump is to be closed.

bool UI_in_gump_mode()

Returns 'true' if showing gumps, 'false' otherwise.

UI_display_map()

Displays the main game map. Will also display the sextant crosshairs if the party has a sextant.

UI_si_display_map(int num)

Displays the specified map on screen.

Parameters

num Index of the map to be displayed. This is converted into a shape in 'SPRITES.VGA' in a hard-coded manner.

UI_display_map_ex(int mapshp, bool show_loc)

Displays the given map centered in the screen.

Parameters

`mapshp`	The shape in 'SPRITES.VGA' to be displayed as a map.
`show_loc`	`true` to show the sextant crosshairs, `false` otherwise. Showing the crosshairs does not depend on being underground or actually having sextants.

UI_lightning()

Causes a lightning effect. The screen flashes, and the corresponding sound effect is played.

UI_sprite_effect(int sprite, int x, int y, int vel_x, int vel_y, int frame, int reps)

Displays a graphical effect at the given location.

Parameters

`sprite`	The shape in 'SPRITES.VGA' to be displayed.
`x`	The initial horizontal location at which the sprite will be displayed.
`y`	The initial vertical location at which the sprite will be displayed.
`vel_x`	The horizontal speed at which the sprite will move. This is added to the location at every tick.
`vel_y`	The vertical speed at which the sprite will move. This is added to the location at every tick.
`frame`	The initial frame in 'SPRITES.VGA' of the sprite. This is increased by one every tick, and may loop back to zero when it reaches the last frame (depending on the value of the 'reps' parameter).
`reps`	Number of repetitions to execute. If zero, the sprite will be displayed for a tick and then go away. If positive, how many times the sprite frame will go through all of its frames. If negative, the sprite will go through all of its frames once.

UI_obj_sprite_effect(object obj, int sprite, int rel_x, int rel_y, int vel_x, int vel_y, int frnum, int reps)
obj->obj_sprite_effect(int sprite, int rel_x, int rel_y, int vel_x, int vel_y, int frnum, int reps)

Creates a sprite effect from 'SPRITES.VGA'. This sprite effect is tied to 'obj'; if 'obj' moves, the sprite will move along. 'sprite' is the sprite's shape number, ('rel_x', 'rel_y') is the relative (x, y) offset of the sprite relative to the position of 'obj', ('vel_x', 'vel_y') is the (x, y) speed (i.e., change in coordinates at every tick, and in addition to any motion of 'obj'). 'frnum' is the initial frame of the sprite effect. If 'reps' < 0, the sprite effect goes through all frames (at the rate of one frame per tick) and deletes itself; otherwise, 'reps' is the total number of ticks the animation will last before deleting itself, looping the sprite's frames if it is needed.

Displays a graphical effect around a given object. This sprite effect is linked to the object, and will move with it.

Parameters

`obj`	The object about which the effect will happen.
`sprite`	The shape in 'SPRITES.VGA' to be displayed.
`rel_x`	The initial horizontal offset from the object at which the sprite will be displayed.
`rel_y`	The initial vertical offset from the object at which the sprite will be displayed.
`vel_x`	The horizontal speed at which the sprite will move. This is added to the horizontal offset at every tick.
`vel_y`	The vertical speed at which the sprite will move. This is added to the vertical offset at every tick.
`frame`	The initial frame in 'SPRITES.VGA' of the sprite. This is increased by one every tick, and may loop back to zero when it reaches the last frame (depending on the value of the 'reps' parameter).
`reps`	Number of repetitions to execute. If zero, the sprite will be displayed for a tick and then go away. If positive, how many times the sprite frame will go through all of its frames. If negative, the sprite will go through all of its frames once.

UI_play_scene(string text, bool fade_out, bool fade_in)

Plays scripted animated and/or text cutscene after checking whether the files text_info.txt and text.flx exist in the patch folder.

Parameters

`text`	The base name of the cutscene files.
`fade_out`	This optional parameter controls whether the game fades out to the scene; defaults to `true`.
`fade_in`	This optional parameter controls whether the the scene fades in to the game; defaults to `true`.

OTHER INTRINSICS

All intrinsics that did not fit in the previous categories.

bool UI_add_spell(int index, int unk, object obj)

Adds a spell to a spellbook.

Parameters

`index`	The spell to be added. This index starts at zero, and must be in the 0-71 range.
`unk`	Reserved, must be zero. This is an unknown parameter from the original games; it doesn't seem to have any effects there, and is unused in Exult. You must still pass it to calls to this intrinsic, though.
`obj`	What spellbook the spell should be added to.

Return

false if the supplied object is not a spellbook or if it already has the spell; true otherwise.

bool UI_has_spell(object obj, int index)

Checks if a spellbook has one particular spell.

Parameters

`obj`	The spellbook to be inspected.
`index`	The spell to be checked. This index starts at zero, and must be in the 0-71 range.

Return

true if the supplied object is a spellbook and contains the spell; false otherwise.

bool UI_remove_spell(object obj, int index)

Removes the specified spell from the desired spellbook.

Parameters

`obj`	The spellbook that will be modified.
`index`	The spell to be removed. This index starts at zero, and must be in the 0-71 range.

Return

true if the supplied object is a spellbook and had the spell; false otherwise.

UI_remove_all_spells(object obj)
obj->remove_all_spells()

Removes all spells from the desired spellbook.

Parameters

obj The spellbook to be cleared. This intrinsic has no effect if this is not a valid spellbook.

int UI_get_array_size([special])

Gets how many elements an array has.

Parameters

[special] A single array of any type or size.

Return

If supplied with a valid array, returns the number of elements in the array; otherwise, returns 1.

UI_mark_virtue_stone(object obj)
obj->mark_virtue_stone()

Imprints a virtue stone with its current location. Any subsequent calls to recall_virtue_stone that target that same stone will teleport the avatar's party to this stored location. The stored location includes the map where the stone is.

Parameters

obj The virtue stone to be marked.

UI_recall_virtue_stone(object obj, bool flag)
obj->recall_virtue_stone(bool flag)

Teleports the party to the virtue stone's stored location. The stone is forcibly given to the avatar if needed.

Parameters

`obj`	The virtue stone that contains the destination.
`flag`	This optional parameter controls controls whether or party members that are paralyzed or asleep; if `true`, these members will be teleported, otherwise, they won't defaults to `false`.

UI_set_orrery(int pos[3], int state)

Sets the position of the planets in the orrery at Moonglow.

Parameters

`pos`	The location of the orrery.
`state`	Numeric value in the 0 to 9 range determining the relative positions of the planets.

The intrinsic tries to find 'Planet Britannia' near the specified location; it will delete the nearby planets, if any, and create new ones in the required positions.

int UI_is_water(object param)
int param->is_water()
int UI_is_water(int param[2])
int UI_is_water(int param[3])
int UI_is_water(mixed param[4])

Determines if a given tile or object is a water tile.

Parameters

param The object or location to be tested.

The parameter can be an object, an array with 2 components, an array with 3 components, or an array with 4 components. The interpretation of the parameter is as follows:

Type	Interpretation/Format
`object`	Exult specific: The parameter is an object or NPC, whose shape is tested for the water flag.
`int [2]`	The parameter is a (x, y) position specifying a tile to be tested.
`int [3]`	The parameter is a (x, y, z) position, such as the return of a `UI_get_object_position` intrinsic call. Of this position, (x, y) specifies a tile to be tested.
`mixed [4]`	Exult specific: The parameter is of the form (object, x, y, z), such as the return of a call to `UI_click_on_item` intrinsic. If object is not null, it's shape is tested for the water flag. Otherwise, (x, y) is used to find and test the corresponding tile.

Return

true if the specified tile or object is a water tile, false otherwise.

string UI_a_or_an(string text)

Checks whether a bit of text starts with a vowel or not.

Parameters

text The string being inspected.

Return

If the first letter of the supplied string is in the "aeiouyAEIOUY" set, returns 'an'; otherwise, returns 'a'.

bool UI_is_dest_reachable(actor npc, int pos[])
bool npc->is_dest_reachable(int pos[])

Checks if a NPC can walk from its present location to a specified position.

Parameters

`npc`	The NPC we wish to check.
`pos`	Where we want check if the NPC can go.

Return

true if the NPC can walk to the supplied destination, false otherwise.

bool UI_can_avatar_reach_pos(int pos[])

Checks if the avatar can walk from its present location to a specified position. This is similar to, but more limited than, the is_dest_reachable Exult intrinsic.

Parameters

pos Where we want check if the avatar can go. Must have at least two elements; if it has exactly two elements, Exult will assume the z coordinate of the destination to be zero.

Return

false if the supplied position is invalid or if the avatar cannot reach the supplied destination, true otherwise.