================================================================================ 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/contants.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] BG-specific intrinsic [SI] SI-specific intrinsic [Exult] Exult-specific intrinsic, available to both BG and SI [BG, Exult] Originally BG-only, Exult allows it in SI too [SI, Exult] Originally SI-only, Exult allows it in BG too [Exult: BG] Exult-specific intrinsic, available only to BG [Exult: SI] Exult-specific intrinsic, available only to SI (not present) Intrinsic available for BG and SI The '[Exult]', '[BG, Exult]' and '[SI, Exult]' 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) [Exult] 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) 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). ****** 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. Moreover, path_run_usecode also makes the other party members move towards the destination. **** END SI SPECIFIC **** 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. 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, [SI, Exult] 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. 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. 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) [SI, Exult] 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 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_face1(int face, int face) [SI, Exult] 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 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_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() [SI, Exult] Removes whatever face is being shown in slot 0. UI_remove_npc_face1() [SI, Exult] Removes whatever face is being shown in slot 1. UI_set_conversation_slot(int slot) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] Changes the frame of the face being displayed in slot 1. Parameters: frame The new frame to be used. UI_init_conversation() [SI] Initializes the face information for a conversation. In Exult, it is usually safe to skip it. UI_end_conversation() [SI] 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. END NOTES ABOUT ORIGINAL BG 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'. **** END SI SPECIFIC **** 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. ** END IMPORTANT NOTES ** 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. Ignored if a non-wildcard shape is given. MASK_NPC2 = 0x08 Restricts the search to 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_TRANLUCENT = 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 intrincis 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) [SI] 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 unk) 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. **** END SI SPECIFIC **** 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. unk Flag of unknown meaning. This parameter is ignored by Exult, and can be omitted. Return: Returns an array of object references for all party members that received any of the created objects. ****** 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. **** END SI SPECIFIC **** 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 'FRIENDLY' 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 FRIENDLY 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 FRIENDLY 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[]) [SI, Exult] 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. 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. ****** BG SPECIFIC ****** int UI_update_last_created(int pos[]) **** END BG SPECIFIC **** ****** SI SPECIFIC ****** object UI_update_last_created(int pos[]) **** END SI SPECIFIC **** 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); * 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: Zero if the 'last created' stack is empty and '1' if the object was deleted. Otherwise: ****** BG SPECIFIC ****** If successful, returns 1. **** END BG SPECIFIC **** ****** SI SPECIFIC ****** If successful, returns a reference to the object. **** END SI SPECIFIC **** UI_give_last_created(object obj) 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[]) obj->move_object(int pos[]) 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. 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 [SI, Exult] qual, int frame, bool unk) int obj->add_cont_items(int count, int shape, int qual, int frame, bool unk) 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. unk Flag of unknown meaning. This parameter is ignored by Exult, and can be omitted. Return: How many objects were actually added to the container. int UI_remove_cont_items(object obj, int count, int shape, [SI, Exult] 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 [SI, Exult] 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. DANCING = 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. SAILOR = 20 Object is the 'captain' of a barge. *Only set on NPCs!* 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. CONFUSED = 25 This will be set if the avatar failed copyright protection questions in SI. Only really meaningful used on the avatar. IN_MOTION = 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 'SAILOR' flag has a peculiar behavior in that it 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. 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 'SAILOR' flag, the supplied object, instead of a flag value. This stored object will be returned by future calls of the 'get_item_flag' intrinsic. 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_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 'SAILOR' flag, the object that it stores is set to zero. This will be the return of any future calls to the 'get_item_flag' intrinsic. 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. 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) [SI, Exult] 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. **** END SI SPECIFIC **** 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) [Exult] 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) [Exult] 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) [Exult] 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) [SI, Exult] 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) [SI] 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) [SI] 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) [Exult: SI] 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. 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. 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 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. **** END SI SPECIFIC **** 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. **** END SI SPECIFIC **** UI_modify_schedule(actor npc, int time, int sched, int [SI, Exult] 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 [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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. **** END BG SPECIFIC **** 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. **** END BG SPECIFIC **** 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: FRIENDLY = 0 NEUTRAL = 1 HOSTILE = 2 RANDOM_ALIGN = 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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_BACK = 0 Containers worn on the back, such as backpacks BG_BACKPACK = 0 Containers worn on the back, such as backpacks BG_WEAPON_HAND = 1 Item wielded in weapon hand BG_BOTH_HANDS = 1 Item wielded with both hands BG_OFF_HAND = 2 Item wielded in off-hand BG_SHIELD_HAND = 2 Off-hand is also called the shield hand BG_BELT = 3 Items worn around the waist such as belts, girdles BG_NECK = 4 Item worn around the neck BG_CLOAK = 4 Cloaks happen to be worn around the neck 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_GLOVES = 6 Gloves technically take up the right finger spot. 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 Usecode container, used for containing eggs 'carried' by player. **** END BG SPECIFIC **** ****** 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_BOTH_HANDS = 1 Items worn in both hands technically count as 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 **** END SI SPECIFIC **** 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) [SI, Exult] 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) [SI, Exult] 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) [SI] 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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) [SI, Exult] 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 FRIENDLY. 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() [SI, Exult] 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) [SI, Exult] 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() [BG] Causes guard to come and attack a thieving avatar. UI_attack_avatar() Causes everyone nearby to attack thieving avatar. UI_save_pos(object obj) [SI, Exult] 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) [SI, Exult] obj->teleport_to_saved_pos() 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. ================================================================================ 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_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 must 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) [Exult] 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) [SI, Exult] 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 on, false to turn it off. 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) [SI, Exult] 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. **** END BG SPECIFIC **** ****** SI SPECIFIC ****** 'flag' has no effect in the endgame. **** END SI SPECIFIC **** 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[]) [Exult] 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) [Exult] 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. Parameters: length The length, in ticks, of the fade; that is, how long it will take for the fade to happen. unk Reserved; must be zero. 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) [SI, Exult] 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 ( TH Additionally, all lowercase letters will be turned into uppercase letters, and pipes ('|') will be converted to spaces. 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. **** END SI SPECIFIC **** UI_book_mode_ex(bool is_scroll, int font) [Exult] 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. ** END IMPORTANT NOTES ** UI_close_gumps() 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. bool UI_in_gump_mode() Returns 'true' if showing gumps, 'false' otherwise. UI_display_map() [BG] Displays the main game map. Will also display the sextant crosshairs if the party has a sextant. UI_si_display_map(int num) [SI] 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) [Exult] 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 thgouth 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*. ================================================================================ 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) [Exult] 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) [Exult] 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) [SI, Exult] 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) [BG] 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) [BG] obj->recall_virtue_stone() 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. UI_set_orrery(int pos[3], int state) [BG] 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 Britania' near the specified location; it will delete the nearby planets, if any, and create new ones in the required positions. bool UI_is_water(int pos[3]) Determines if a given tile or object is a water tile. Parameters: pos Location of tile or object to be tested. 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[]) [Exult] 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[]) [SI] 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.