UCC Reference

intrinsic_reference

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.

Full intrinsic reference | Reference definitions