Usecode C

Download Markdown | Natural Docs source

General Definitions

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

Unlike Usecode C-defined functions, intrinsics do not have compiler-enforced prototypes. The signatures below describe the values expected by the engine, rather than declarations to copy into your source. Supply the documented parameters and use the named intrinsic so UCC selects the correct game-specific ID.

There is no fixed 12-argument buffer limit in the current engine. This does not make arbitrary argument lists meaningful: the implementation determines which values it reads, how it interprets them, and whether omitted arguments have defaults. Omit an argument only when the intrinsic description explicitly makes it optional. The runtime checks each intrinsic's declared minimum argument count before calling its implementation; calls with too few arguments print a diagnostic and are skipped. Optional-argument defaults are handled by the implementation, which receives exactly the arguments supplied by the caller.

The descriptions and ID table have been checked against usecode/intrinsics.cc, usecode/bgintrinsics.h, usecode/siintrinsics.h, and usecode/sibetaintrinsics.h. UCC portrait statements are also checked against tools/compiler/ucparse.yy.

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

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

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

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

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.

Usecode arrays are one-based: the first element is array[1]. Array sizes in signatures describe the number of elements, not the last zero-based index. Flat coordinate lists such as [x1, y1, x2, y2] are single arrays, not arrays of arrays.

Intrinsic IDs and game availability

The following IDs come from Exult's usecode/bgintrinsics.h, usecode/siintrinsics.h, and usecode/sibetaintrinsics.h. Select the appropriate table with #game "blackgate", #game "serpentisle", or #game "serpentbeta"; use the named intrinsic in source rather than copying an ID from another game. Multiple IDs in a cell are aliases for the same intrinsic. An em dash means that the intrinsic is absent from that table. UNKNOWN and NOP entries are omitted.

The badges on individual descriptions distinguish original game support from Exult extensions for BG and SI. This table also records SI beta availability, which those badges do not cover. In particular, SI beta has sib_path_run_usecode and sib_is_dest_reachable with different signatures from their counterparts, supports the virtue-stone intrinsics, and lacks save_pos and teleport_to_saved_pos.

Random Number Intrinsics

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

UI_get_random

int UI_get_random(int max)

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

Parameters

Return

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

UI_die_roll

int UI_die_roll(int min, int max)

Generates a random number in the specified range.

Parameters

Return

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

UI_roll_to_win

bool UI_roll_to_win(int att, int def)

Performs a contest between two supplied values.

Parameters

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.

UI_execute_usecode_array

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

Return

Always returns '1'.

UI_delayed_execute_usecode_array

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

Return

Always returns '1'.

UI_in_usecode

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

Checks if an object is currently executing any usecode scripts.

Parameters

Return

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

UI_halt_scheduled

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

UI_begin_casting_mode

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

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

Parameters

UI_set_to_attack

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

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

Return

true if the attacker, weapon, and object or tile target were accepted and stored, false otherwise. This does not mean that an attack has already occurred or hit the target.

UI_path_run_usecode

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

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

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

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

When simode is true, Exult looks for a free spot within 3 tiles of pos and allows a rise/drop of 3 in the z direction. If no spot is found, it tries again at the NPC's current height.

Parameters

Return

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

A successful return means a path has been started, not that the destination has been reached. Use the arrival or failure callback to detect the outcome. UI_sib_path_run_usecode is a separate SI beta variant that takes an explicit NPC before pos.

UI_si_path_run_usecode

UI_si_path_run_usecode(actor npc, int pos[], int event, object obj, function fun)
UI_si_path_run_usecode(actor npc, int pos[], int event, object obj, function fun, bool flag)
npc->si_path_run_usecode(int pos[], int event, object obj, function fun)
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

This intrinsic uses the nearby-free-spot search described for UI_path_run_usecode with simode = true. An NPC on the WAIT schedule has its ASLEEP and PARALYZED flags cleared before pathfinding. The call has no meaningful return value.

For SI beta, UI_sib_path_run_usecode(npc, pos, fun, obj, event) is a different intrinsic: it has five parameters, places fun before obj and event, and returns a success boolean. UI_si_path_run_usecode, with its optional sixth argument, remains available in that table as well.

UI_set_path_failure

UI_set_path_failure(function fun, object obj, int event)

Sets usecode to be called if an NPC fails to reach its destination. This intrinsic must be used after UI_path_run_usecode, UI_si_path_run_usecode, or UI_sib_path_run_usecode, and affects the NPC from the most recent path call. If, for any reason, the NPC in question cannot reach the destination, the usecode function assigned by this intrinsic will be run.

Parameters

SI SPECIFIC

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

The NPC must still have a usecode path action for the callback to be installed. A path requested with no callback object may use a plain walking action, in which case this intrinsic has no effect.

UI_in_usecode_path

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

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

Parameters

Return

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

UI_telekenesis

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

UI_sib_path_run_usecode

bool UI_sib_path_run_usecode(actor npc, int pos[], function fun, object obj, int event)
bool npc->sib_path_run_usecode(int pos[], function fun, object obj, int event)

Causes an NPC to walk to a location and execute a usecode function on arrival. This SI beta intrinsic uses the same argument order as UI_path_run_usecode, rather than the order used by UI_si_path_run_usecode.

Parameters

Return

true if a path was successfully started, false otherwise. Starting a path does not guarantee that the NPC will reach its destination.

This intrinsic is available only with #game "serpentbeta". It does not take the flag argument of UI_si_path_run_usecode and does not request that the callback run when the destination cannot be reached. Use UI_set_path_failure to supply a failure callback.

Conversation Intrinsics

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

UI_show_npc_face

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

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

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.

Use Usecode C's face.show(frnum) statement in place of this intrinsic. The frame argument is optional: face.show() is equivalent to face.show(0). The receiver may be either a face number or an NPC.

When frnum is zero, npc.say("@Text.@") displays the NPC's face and the supplied text. Use npc.say() to display text previously set with message.

UI_show_npc_face0

UI_show_npc_face0(int face, int frnum)
UI_show_npc_face0(actor face, int frnum)
face->show_npc_face0(int frnum)
face.show@0(frnum)
face.show@0()

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

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.

Use Usecode C's face.show@0(frnum) statement in place of this intrinsic. The frame argument is optional: face.show@0() is equivalent to face.show@0(0). The receiver may be either a face number or an NPC.

When frnum is zero, npc.say@0("@Text.@") displays the NPC's face in slot 0 and the supplied text. Use npc.say@0() to display text previously set with message.

UI_show_npc_face1

UI_show_npc_face1(int face, int frnum)
UI_show_npc_face1(actor face, int frnum)
face->show_npc_face1(int frnum)
face.show@1(frnum)
face.show@1()

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

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.

Use Usecode C's face.show@1(frnum) statement in place of this intrinsic. The frame argument is optional: face.show@1() is equivalent to face.show@1(0). The receiver may be either a face number or an NPC.

When frnum is zero, npc.say@1("@Text.@") displays the NPC's face in slot 1 and the supplied text. Use npc.say@1() to display text previously set with message.

UI_remove_npc_face

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

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

UI_remove_npc_face0()
hide@0()

Removes whatever face is being shown in slot 0. Use Usecode C's hide@0() statement in place of this intrinsic.

UI_remove_npc_face1

UI_remove_npc_face1()
hide@1()

Removes whatever face is being shown in slot 1. Use Usecode C's hide@1() statement in place of this intrinsic.

UI_reset_conv_face

UI_reset_conv_face()

Resets the portrait frame in conversation slot 0 to frame 0 after displaying any pending text. This does not change the active conversation slot; use UI_set_conversation_slot(0) to select that slot for subsequent speech.

UI_set_conversation_slot

UI_set_conversation_slot(int slot)
npc->set_conversation_slot()

Changes the active conversation slot.

Parameters

UI_change_npc_face0

UI_change_npc_face0(int frame)

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

Parameters

UI_change_npc_face1

UI_change_npc_face1(int frame)

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

Parameters

UI_init_conversation

UI_init_conversation()

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

UI_end_conversation

UI_end_conversation()

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

UI_add_answer

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

UI_remove_answer

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

UI_push_answers

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

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

UI_clear_answers()

Clears all current dialog options.

UI_select_from_menu

string UI_select_from_menu()

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

Return

The chosen dialog option.

UI_select_from_menu2

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

UI_play_sound_effect(int sfx)

Plays a sound effect.

Parameters

UI_play_sound_effect2

UI_play_sound_effect2(int sfx, object obj)

Causes an object to generate a sound effect.

Parameters

UI_play_music

UI_play_music(int track, object obj)

Plays the specified song.

Parameters

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

UI_get_music_track

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.

UI_start_speech

bool UI_start_speech(int track)

Plays the specified speech track.

SI SPECIFIC

In SI, tracks 0-20 show the Balance Serpent's portrait (solid when wearing the serpent ring, translucent otherwise), tracks 21-22 show the Guardian, tracks 23-24 show Arcadion, and tracks 25-26 show the Chaos and Order Serpents respectively. These portraits wait for a click before being removed; other tracks do not select a portrait here.

Parameters

Return

Returns true for a non-negative track number and false for a negative track number. This does not report whether audio was actually available or played. The requested number is stored for UI_get_speech_track; a negative number also reinitializes the conversation.

UI_start_blocking_speech

bool UI_start_blocking_speech(int track)

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

SI SPECIFIC

In SI, tracks 0-20 show the Balance Serpent's portrait (solid when wearing the serpent ring, translucent otherwise), tracks 21-22 show the Guardian, tracks 23-24 show Arcadion, and tracks 25-26 show the Chaos and Order Serpents respectively. These portraits wait for a click before being removed; other tracks do not select a portrait here.

Parameters

Return

Returns true for a non-negative track number and false for a negative track number. This does not report whether audio was actually available or played. The requested number is stored for UI_get_speech_track; a negative number also reinitializes the conversation.

UI_get_speech_track

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.

UI_find_nearest

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

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.

UI_find_object

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

IMPORTANT NOTES

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

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

Return

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

UI_find_nearby

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

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:

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.

UI_find_nearby_avatar

object[] UI_find_nearby_avatar(int shape)

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

Parameters

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.

UI_npc_nearby

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

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

Parameters

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.

UI_npc_nearby2

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

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

Parameters

Return

true if the object is valid and fewer than 40 tiles from the avatar, false otherwise. Sleeping, paralysis, or death do not affect this test.

UI_count_objects

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

Return

The number of objects that match the given criteria.

UI_get_cont_items

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

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.

UI_is_not_blocked

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

Return

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

UI_add_party_items

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

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

SI SPECIFIC

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

Parameters

Return

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

BG SPECIFIC

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

SI SPECIFIC

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

UI_remove_party_items

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

Return

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

UI_summon

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

Creates a monster of the supplied shape. This monster has equipment as defined in its equipment record, starts with an IN_COMBAT schedule, and inherits item's effective alignment when item is an NPC outside the party. If item is a party member or is not an NPC, the summoned monster's alignment is GOOD. The monster will be placed within five tiles of the avatar.

Parameters

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.

UI_clone

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

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

Parameters

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.

UI_create_new_object

object UI_create_new_object(int shape)

Creates a new object with the specified shape.

Parameters

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.

UI_create_new_object2

object UI_create_new_object2(int shape, int pos[])
object UI_create_new_object2(int shape, int pos[], [int frame])

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

Parameters

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

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

Return

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

UI_create_barge_object

UI_create_barge_object(int width, int height)
UI_create_barge_object(int width, int height, int dir)

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

Parameters

Return

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

UI_set_last_created

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

Return

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

UI_update_last_created

bool UI_update_last_created(int pos[])

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

Parameters

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

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

Return

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

NOTES ABOUT ORIGINAL GAMES

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

UI_give_last_created

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

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

Parameters