Skip to content

Effect scripts: <effect.h>

Natives for effect scripts (dungeon/eff_script, dungeon/articles, dungeon/sphida).

Natives are built-in engine functions declared with NATIVE(...). A native with one result returns a value. A native with multiple results writes to pointer arguments. OPTIONAL(...) marks arguments that a call can omit. Natives return immediately and do not yield frames; use WAIT(); to pause a script for one frame (25 FPS on PAL).

Declared in sdk/effect.h and sdk/helpers/effect.h. See C Language, SDK, and Patches for SDK syntax and API Reference for all headers. Generated by dc2tk api-docs from the SDK's headers; change the headers, not this page.

Natives

Native Number What it does
clear_vector 0 Writes 0.0 to all three out variables.
normalize_vector 1 Scales the vector held in the three variables to length 1 in place.
copy_vector 2 Copies src_x, src_y, src_z into the three out variables.
add_vector 3 Adds dx, dy, dz to the vector held in the three variables, in place.
subtract_vector 4 Subtracts dx, dy, dz from the vector held in the three variables, in place.
scale_vector 5 Multiplies the vector held in the three variables by factor, in place.
divide_vector 6 Divides the vector held in the three variables by divisor, in place.
get_vector_length 7 Returns the length of the vector (x, y, z).
get_distance 8 Returns the distance between point (x1, y1, z1) and point (x2, y2, z2).
get_square_root 9 Returns the square root of value.
get_atan2 10 Returns atan2(y, x) in radians.
compare_angles 11 Compares two angles in radians after wrapping their difference into -pi..pi.
wrap_angle 12 Wraps the angle held in the variable into the range -pi..pi radians, in place.
VM_ARGS 13 Writes a random number from 0 up to but not including range into value.
get_rot_toward 14 Computes the rotation in radians that faces from point (from_x, from_y, from_z) toward point (to_x, to_y, to_z).
get_dir_from_rot 15 Turns a rotation in radians into a unit direction: the +Z axis rotated by rot_x (pitch) and rot_y (yaw).
set_effect_origin 50 Sets the origin of this effect.
get_effect_origin 51 Writes the origin of this effect into the three out variables.
set_origin_follow 52 With on = 1 the effect's drawing origin also follows its target scene character (see get_target_id), or that character's frame named frame_name when given.
get_work_vector1 53 Writes the first work vector that the effect's starter passed in (for example a start position) into the three out variables.
get_work_vector2 54 Writes the second work vector that the effect's starter passed in into the three out variables.
get_target_id 55 Returns the scene character slot that this effect aims at or follows, or -1 when none was set.
get_owner_id 56 Returns the owner of this effect: the scene character slot that started it, whose sound bank and attack identity the effect uses.
get_effect_value 57 Reads shared value slot index (0 to 7) of this effect into value, as an int or a float according to the type of the variable passed.
VM_ARGS 58 Stores value, int or float, in value slot index (0 to 7) of this effect.
set_model_visible 100 Shows (1) or hides (0) the effect's model.
get_model_visible 101 Writes whether the effect's model is shown into visible, and its fade setting into fade when given.
set_model_pos 102 Sets the position of the effect's model, relative to the effect origin.
get_model_pos 103 Writes the position of the effect's model into the three out variables.
set_model_rot 104 Turns the effect's model toward rotation (x, y, z) in radians.
get_model_rot 105 Writes the rotation of the effect's model in radians into the three out variables.
set_model_scale 106 Sets the x, y and z scale of the effect's model.
get_model_scale 107 Writes the scale of the effect's model into the three out variables.
play_model_motion 108 Starts the named motion on the effect's model.
set_model_motion_speed 109 Sets the frames the effect model's motion advances each step.
get_model_dir 110 Writes the unit direction the effect's model faces, from its pitch and yaw, into the three out variables.
get_model_rot_toward 111 Computes the rotation in radians that faces from the effect's model toward point (x, y, z).
move_model_by 112 Adds (dx, dy, dz) to the position of the effect's model.
rotate_model_by 113 Adds (dx, dy, dz) radians to the rotation of the effect's model and wraps each angle into -pi..pi.
scale_model_by 114 Meant to add to the scale of the effect's model, but the engine discards the result, so it has no effect.
create_model_copies 125 Creates count extra copies (at most 4) of the effect's model, numbered 0 to count - 1, for the *_model_copy natives.
set_model_copy_pos 126 Sets the position of model copy number copy, relative to the effect origin.
set_model_copy_rot 127 Sets the rotation in radians of model copy number copy.
set_model_copy_scale 128 Sets the scale of model copy number copy.
play_model_copy_motion 129 Starts the named motion on model copy number copy, with speed (negative keeps the current speed) and flags as in play_model_motion.
move_model_copy_by 130 Adds (dx, dy, dz) to the position of model copy number copy.
rotate_model_copy_by 131 Adds (dx, dy, dz) radians to the rotation of model copy number copy, wrapping each angle into -pi..pi.
scale_model_copy_by 132 Adds (dx, dy, dz) to the scale of model copy number copy.
get_model_motion_progress 133 Returns how far the effect model's current motion has played, from 0.0 to 1.0.
set_model_copy_visible 134 Shows (1) or hides (0) model copy number copy, fading at a fixed 0.1 alpha per frame when fade = 1.
get_model_frame_pos 135 Writes the world position of the frame (bone) named frame_name in the effect's model into the three out variables.
set_model_light_color 136 Sets the colour attribute (red, green, blue, alpha) on every frame of the effect's model.
allocate_sprites 150 Allocates count billboard sprites for this effect, numbered 0 to count - 1.
free_sprites 151 Frees this effect's sprites so allocate_sprites can be called again.
set_sprite_texture 152 Sets the texture, by name in the effect's texture block, that all of this effect's sprites are drawn with.
set_sprite_blend 153 Sets the blend mode of sprites: 1 translucent, 2 additive, 3 subtractive, 4 opaque, 5 additive ignoring alpha; 0 keeps the screen's current mode.
reset_sprites 154 Resets sprites to defaults: hidden, translucent blend, at (0, 0, 0), colour 128 on all channels, scale 1, zero size and UV, and every velocity, acceleration, easing and blink cleared.
set_sprite_visible 155 Shows (nonzero) or hides (0) sprites.
get_sprite_visible 156 Returns the visibility flag of sprite index.
set_sprite_uv 157 Sets the texture rectangle drawn on sprites: left u, top v, width and height in texture pixels.
set_sprite_size 158 Sets the drawn width and height of sprites in world units, before their scale is applied.
set_sprite_pos 159 Sets the position of sprites, relative to the effect origin.
get_sprite_pos 160 Writes the position of sprite index into the three out variables.
set_sprite_angle 161 Sets the screen-plane rotation of sprites in radians.
get_sprite_angle 162 Returns the screen-plane rotation in radians of sprite index.
set_sprite_scale 163 Sets the horizontal and vertical scale of sprites; the drawn size is size times scale.
get_sprite_scale 164 Writes the horizontal and vertical scale of sprite index into scale_x and scale_y.
set_sprite_color 165 Sets the colour of sprites, each channel 0 to 255 with 128 as normal brightness and full alpha.
get_sprite_color 166 Writes the colour channels of sprite index into the four out variables.
spread_sprite_pos 167 Places a run of sprites along a curve: the first gets (x, y, z), and each next one is offset by a step vector that starts at (vx, vy, vz) and grows by (ax, ay, az) per sprite.
spread_sprite_angle 168 Sets screen-plane angles across a run of sprites: the first gets angle, and each next one adds a step that starts at velocity and grows by accel per sprite, all in radians.
move_sprite_by 169 Adds (dx, dy, dz) to the position of sprites.
rotate_sprite_by 170 Adds angle radians to the screen-plane rotation of sprites, wrapping into -pi..pi.
add_sprite_color 171 Adds to the colour channels of sprites and clamps each to 0..255.
rotate_sprites_around_y 172 Rotates the positions of sprites by angle radians around the Y axis through the effect origin.
set_sprite_life 173 Unsupported: always fails and does nothing.
set_sprite_velocity 174 Sets the per-frame movement of sprites; the engine adds it to their position every frame.
set_sprite_accel 175 Sets the per-frame change of sprite velocity; the engine adds it to their velocity every frame.
set_sprite_spin 176 Sets the radians per frame that sprites turn in the screen plane.
VM_ARGS 177 Sets the per-frame change of sprite spin, in radians; spin is capped at 2 pi per frame.
set_sprite_color_velocity 178 Sets the amount added to each sprite colour channel every frame.
set_sprite_color_accel 179 Sets the per-frame change of the sprite colour velocity.
set_sprite_blink 180 Makes sprites pulse: each drawn frame adds SIN(phase) times the given amplitude to each colour channel, and phase advances by speed radians.
spread_sprite_color 181 Sets colours across a run of sprites: the first gets (red, green, blue, alpha), and each next one adds a step that starts at the velocity colour and grows by the accel colour per sprite.
VM_ARGS 182 Sets the amount added to the horizontal and vertical scale of sprites every frame.
set_sprite_scale_accel 183 Sets the per-frame change of the sprite scale velocity.
spread_sprite_scale 184 Sets scales across a run of sprites: the first gets (scale_x, scale_y), and each next one adds a step that starts at (vx, vy) and grows by (ax, ay) per sprite.
ease_sprite_scale 185 Eases the scale of sprites toward (scale_x, scale_y): every frame they move 1/divisor of the remaining distance.
ease_sprite_color 186 Eases the colour of sprites toward (red, green, blue, alpha): every frame each channel moves 1/divisor of the remaining distance.
get_scene_chara_pos 200 Writes the position of the scene character in slot chara (for example the owner or target id) into the three out variables.
get_scene_chara_rot 201 Writes the rotation in radians of the scene character in slot chara.
get_chara_frame_pos 202 Writes the world position of the frame (bone) named frame_name on the scene character in slot chara into the three out variables.
get_line_hit 203 Tests the line from start to end against the scene's collision polygons, skipping polygons whose ignore bits match ignore_mask, and writes the nearest hit.
create_damage 204 Disabled in this build: prints an error and fails without creating anything or writing the result.
delete_damage 205 Disabled in this build: does nothing and fails.
set_damage_pos 206 Disabled in this build: does nothing and fails.
set_damage_dir 207 Disabled in this build: does nothing and fails.
set_damage_amount 208 Disabled in this build: prints an error and fails.
create_attack 210 Gives this effect an attack shape set up from the damage table row named damage_name, replacing any attack it had.
VM_ARGS 211 Places this effect's attack.
delete_attack 212 Removes this effect's attack.
get_attack_hit_count 213 Returns how many hits this effect's attack has dealt.
set_attack_damage 214 Sets the damage each hit of this effect's attack deals, overriding the damage table value.
get_attack_hit_pos 215 Writes the position of the last hit of this effect's attack into the three out variables.
set_attack_gift 216 Marks this effect's attack as carrying a gift of three item numbers.
get_attack_knockback 217 Writes nonzero into knocked_back when another attack has knocked this effect's attack back, and the knockback direction into dir_x, dir_y, dir_z when given.
play_owner_se 220 Plays sound effect se from the owner character's sound bank.
stop_owner_se 221 Stops sound effect se in the owner character's sound bank.
play_battle_se 222 Plays sound effect se from the scene's battle sound bank.
stop_battle_se 223 Stops sound effect se in the scene's battle sound bank.
play_base_se 224 Plays sound effect se from the scene's base sound bank.
stop_base_se 225 Stops sound effect se in the scene's base sound bank.
play_chara_se 226 Plays sound effect se from the sound bank of the scene character in slot chara.
stop_chara_se 227 Stops sound effect se in the sound bank of the scene character in slot chara.
set_sprite_lighting 230 With on = 1 this effect's sprites take their red, green and blue from the scene light and ambient colour instead of their own; alpha is kept.
get_chara_entry_pos 231 Writes the world position of entry point index (an attachment frame such as a weapon mount) on the scene character in slot chara, or the character's own position when it has none.
get_chara_frame_dir 232 Writes the world direction of the +Z axis of the frame named frame_name on the scene character in slot chara into the three out variables.
get_chara_frame_rot 233 Writes the pitch, yaw and 0, in radians, that face along the +Z axis of the frame named frame_name on the scene character in slot chara.
get_entry_object_pos 234 Same as get_chara_entry_pos, but index must be 0 or 1.
start_child_effect 240 Starts the effect named effect_name, owned by this effect's owner; it runs its program 200.
VM_ARGS 241 Sets the first work vector of a child effect, read there with get_work_vector1.
VM_ARGS 242 Sets the second work vector of a child effect, read there with get_work_vector2.
set_child_target 243 Sets the target scene character slot of a child effect, read there with get_target_id.
share_attack_with_child 244 Gives the most recently started child effect a pointer to this effect's attack.
VM_ARGS 245 Stores an int or float in value slot index (0 to 7) of a child effect, read there with get_effect_value.
get_event_object_pos 251 Writes the position of whatever event object handle number handle refers to into the three out variables.
set_model_frame_visible 252 Shows (1) or hides (0) the frame named frame_name in the effect's model.
check_model_motion_end 253 Returns 1 when the effect model's motion reaches its last frame within the next two steps or no motion plays, else 0.
VM_ARGS 250 Numbers the disc calls that this table never registers.

clear_vector

extern void clear_vector(float *x, float *y, float *z) NATIVE(0);

Writes 0.0 to all three out variables. Fails unless given three arguments.

Original name: _ZERO_VECTOR.

normalize_vector

extern void normalize_vector(float *x, float *y, float *z) NATIVE(1);

Scales the vector held in the three variables to length 1 in place. Pass the variables as &x, &y, &z; they are read and written back.

Original name: _NORMAL_VECTOR.

copy_vector

extern void copy_vector(float *x, float *y, float *z, float src_x, float src_y, float src_z) NATIVE(2);

Copies src_x, src_y, src_z into the three out variables.

Original name: _COPY_VECTOR.

add_vector

extern void add_vector(float *x, float *y, float *z, float dx, float dy, float dz) NATIVE(3);

Adds dx, dy, dz to the vector held in the three variables, in place.

Original name: _ADD_VECTOR.

subtract_vector

extern void subtract_vector(float *x, float *y, float *z, float dx, float dy, float dz) NATIVE(4);

Subtracts dx, dy, dz from the vector held in the three variables, in place.

Original name: _SUB_VECTOR.

scale_vector

extern void scale_vector(float *x, float *y, float *z, float factor) NATIVE(5);

Multiplies the vector held in the three variables by factor, in place.

Original name: _SCALE_VECTOR.

divide_vector

extern void divide_vector(float *x, float *y, float *z, float divisor) NATIVE(6);

Divides the vector held in the three variables by divisor, in place. Fails and leaves the vector unchanged when divisor is 0.

Original name: _DIV_VECTOR.

get_vector_length

extern float get_vector_length(float x, float y, float z) NATIVE(7);

Returns the length of the vector (x, y, z).

Original name: _DIST_VECTOR.

get_distance

extern float get_distance(float x1, float y1, float z1, float x2, float y2, float z2) NATIVE(8);

Returns the distance between point (x1, y1, z1) and point (x2, y2, z2).

Original name: _DIST_VECTOR2.

get_square_root

extern float get_square_root(float value) NATIVE(9);

Returns the square root of value.

Original name: _SQRT.

get_atan2

extern float get_atan2(float y, float x) NATIVE(10);

Returns atan2(y, x) in radians. Scripts pass (dx, dz) to get a yaw angle.

Original name: _ATAN2F.

compare_angles

extern int compare_angles(float a, float b, float tolerance) NATIVE(11);

Compares two angles in radians after wrapping their difference into -pi..pi. Returns 0 when a and b differ by no more than tolerance, 1 when a is larger, -1 when it is smaller.

Original name: _ANGLE_CMP.

wrap_angle

extern void wrap_angle(float *angle) NATIVE(12);

Wraps the angle held in the variable into the range -pi..pi radians, in place.

Original name: _ANGLE_LIMIT.

VM_ARGS

extern void get_random VM_ARGS(any range, void *value) NATIVE(13);

Writes a random number from 0 up to but not including range into value. A float range gives a float; an int range gives an int.

Original name: _GET_RAND.

get_rot_toward

extern void get_rot_toward(float from_x, float from_y, float from_z, float to_x, float to_y, float to_z, float *rot_x, OPTIONAL(float *rot_y, float *rot_z)) NATIVE(14);

Computes the rotation in radians that faces from point (from_x, from_y, from_z) toward point (to_x, to_y, to_z). With three out parameters it writes pitch, yaw and 0; with only one it writes the yaw.

Original name: _GET_REF_ROT.

get_dir_from_rot

extern void get_dir_from_rot(float rot_x, float rot_y, float rot_z, float *dir_x, float *dir_y, float *dir_z) NATIVE(15);

Turns a rotation in radians into a unit direction: the +Z axis rotated by rot_x (pitch) and rot_y (yaw). rot_z is ignored.

Original name: _GET_DIR_VECTOR.

set_effect_origin

extern void set_effect_origin(float x, float y, float z) NATIVE(50);

Sets the origin of this effect. The effect's model, its copies and its sprites are drawn at their positions plus this origin.

Original name: _SET_ORIGIN.

get_effect_origin

extern void get_effect_origin(float *x, float *y, float *z) NATIVE(51);

Writes the origin of this effect into the three out variables.

Original name: _GET_ORIGIN.

set_origin_follow

extern void set_origin_follow(int on, OPTIONAL(string frame_name)) NATIVE(52);

With on = 1 the effect's drawing origin also follows its target scene character (see get_target_id), or that character's frame named frame_name when given. With on = 0 it stops following.

Original name: _AUTO_SET_OFFSET.

get_work_vector1

extern void get_work_vector1(float *x, float *y, float *z) NATIVE(53);

Writes the first work vector that the effect's starter passed in (for example a start position) into the three out variables. It is (0, 0, 0) when none was set.

Original name: _GET_WORK_VECT1.

get_work_vector2

extern void get_work_vector2(float *x, float *y, float *z) NATIVE(54);

Writes the second work vector that the effect's starter passed in into the three out variables. It is (0, 0, 0) when none was set.

Original name: _GET_WORK_VECT2.

get_target_id

extern int get_target_id(void) NATIVE(55);

Returns the scene character slot that this effect aims at or follows, or -1 when none was set.

Original name: _GET_TARGET_ID.

get_owner_id

extern int get_owner_id(void) NATIVE(56);

Returns the owner of this effect: the scene character slot that started it, whose sound bank and attack identity the effect uses.

Original name: _GET_USER_ID.

get_effect_value

extern void get_effect_value(int index, void *value) NATIVE(57);

Reads shared value slot index (0 to 7) of this effect into value, as an int or a float according to the type of the variable passed. The starter fills these slots with set_child_value.

Original name: _GET_VALUE.

VM_ARGS

extern void set_effect_value VM_ARGS(int index, any value) NATIVE(58);

Stores value, int or float, in value slot index (0 to 7) of this effect.

Original name: _SET_VALUE.

set_model_visible

extern void set_model_visible(int visible, OPTIONAL(int fade, float fade_speed)) NATIVE(100);

Shows (1) or hides (0) the effect's model. With fade = 1 it fades in from transparent or out from opaque at a fixed 0.1 alpha per frame; fade_speed is read and ignored. Fails when the effect has no model.

Original name: _CHR_SET_SHOW.

get_model_visible

extern void get_model_visible(int *visible, OPTIONAL(int *fade)) NATIVE(101);

Writes whether the effect's model is shown into visible, and its fade setting into fade when given.

Original name: _CHR_GET_SHOW.

set_model_pos

extern void set_model_pos(float x, float y, float z) NATIVE(102);

Sets the position of the effect's model, relative to the effect origin. New effects place it at (0, -10000, 0).

Original name: _CHR_SET_POS.

get_model_pos

extern void get_model_pos(float *x, float *y, float *z) NATIVE(103);

Writes the position of the effect's model into the three out variables.

Original name: _CHR_GET_POS.

set_model_rot

extern void set_model_rot(float x, float y, float z, OPTIONAL(int steps)) NATIVE(104);

Turns the effect's model toward rotation (x, y, z) in radians. With steps it moves only 1/steps of the remaining shortest angle on each call, so calling it every frame turns the model smoothly; without it the rotation is set at once.

Original name: _CHR_SET_ROT.

get_model_rot

extern void get_model_rot(float *x, float *y, float *z) NATIVE(105);

Writes the rotation of the effect's model in radians into the three out variables.

Original name: _CHR_GET_ROT.

set_model_scale

extern void set_model_scale(float x, float y, float z) NATIVE(106);

Sets the x, y and z scale of the effect's model.

Original name: _CHR_SET_SCALE.

get_model_scale

extern void get_model_scale(float *x, float *y, float *z) NATIVE(107);

Writes the scale of the effect's model into the three out variables.

Original name: _CHR_GET_SCALE.

play_model_motion

extern void play_model_motion(string motion_name, OPTIONAL(float speed, enum motion_flags flags)) NATIVE(108);

Starts the named motion on the effect's model. speed sets the frames advanced per step; a negative value (the default) keeps the current speed. flags: 1 pauses, 2 holds the last frame instead of looping, 4 restarts from the first frame without blending.

Original name: _CHR_SET_MOTION.

set_model_motion_speed

extern void set_model_motion_speed(float speed) NATIVE(109);

Sets the frames the effect model's motion advances each step.

Original name: _CHR_SET_MOT_STEP.

get_model_dir

extern void get_model_dir(float *x, float *y, float *z) NATIVE(110);

Writes the unit direction the effect's model faces, from its pitch and yaw, into the three out variables.

Original name: _CHR_GET_DIR_VECTOR.

get_model_rot_toward

extern void get_model_rot_toward(float x, float y, float z, float *rot_x, OPTIONAL(float *rot_y, float *rot_z)) NATIVE(111);

Computes the rotation in radians that faces from the effect's model toward point (x, y, z). With three out parameters it writes pitch, yaw and 0; with only one it writes the yaw.

Original name: _CHR_GET_REF_ROT.

move_model_by

extern void move_model_by(float dx, float dy, float dz) NATIVE(112);

Adds (dx, dy, dz) to the position of the effect's model.

Original name: _CHR_ADD_POS.

rotate_model_by

extern void rotate_model_by(float dx, float dy, float dz) NATIVE(113);

Adds (dx, dy, dz) radians to the rotation of the effect's model and wraps each angle into -pi..pi.

Original name: _CHR_ADD_ROT.

scale_model_by

extern void scale_model_by(float dx, float dy, float dz) NATIVE(114);

Meant to add to the scale of the effect's model, but the engine discards the result, so it has no effect.

Original name: _CHR_ADD_SCALE.

create_model_copies

extern void create_model_copies(int count) NATIVE(125);

Creates count extra copies (at most 4) of the effect's model, numbered 0 to count - 1, for the *_model_copy natives. They are drawn with the same origin as the model.

Original name: _CHR_COPY_CHARA.

set_model_copy_pos

extern void set_model_copy_pos(int copy, float x, float y, float z) NATIVE(126);

Sets the position of model copy number copy, relative to the effect origin.

Original name: _CHR_SET_POS2.

set_model_copy_rot

extern void set_model_copy_rot(int copy, float x, float y, float z) NATIVE(127);

Sets the rotation in radians of model copy number copy.

Original name: _CHR_SET_ROT2.

set_model_copy_scale

extern void set_model_copy_scale(int copy, float x, float y, float z) NATIVE(128);

Sets the scale of model copy number copy.

Original name: _CHR_SET_SCALE2.

play_model_copy_motion

extern void play_model_copy_motion(int copy, string motion_name, float speed, enum motion_flags flags) NATIVE(129);

Starts the named motion on model copy number copy, with speed (negative keeps the current speed) and flags as in play_model_motion. The engine checks the argument count without counting copy, so always pass all four arguments.

Original name: _CHR_SET_MOTION2.

move_model_copy_by

extern void move_model_copy_by(int copy, float dx, float dy, float dz) NATIVE(130);

Adds (dx, dy, dz) to the position of model copy number copy.

Original name: _CHR_ADD_POS2.

rotate_model_copy_by

extern void rotate_model_copy_by(int copy, float dx, float dy, float dz) NATIVE(131);

Adds (dx, dy, dz) radians to the rotation of model copy number copy, wrapping each angle into -pi..pi.

Original name: _CHR_ADD_ROT2.

scale_model_copy_by

extern void scale_model_copy_by(int copy, float dx, float dy, float dz) NATIVE(132);

Adds (dx, dy, dz) to the scale of model copy number copy.

Original name: _CHR_ADD_SCALE2.

get_model_motion_progress

extern float get_model_motion_progress(void) NATIVE(133);

Returns how far the effect model's current motion has played, from 0.0 to 1.0.

Original name: _CHR_GET_MOT_WAIT.

set_model_copy_visible

extern void set_model_copy_visible(int copy, int visible, OPTIONAL(int fade, float fade_speed)) NATIVE(134);

Shows (1) or hides (0) model copy number copy, fading at a fixed 0.1 alpha per frame when fade = 1. fade_speed is read and ignored.

Original name: _CHR_SET_SHOW2.

get_model_frame_pos

extern void get_model_frame_pos(string frame_name, float *x, float *y, float *z) NATIVE(135);

Writes the world position of the frame (bone) named frame_name in the effect's model into the three out variables. Fails when there is no such frame.

Original name: _CHR_GET_FRAME_POS.

set_model_light_color

extern void set_model_light_color(float red, float green, float blue, float alpha, OPTIONAL(int no_light)) NATIVE(136);

Sets the colour attribute (red, green, blue, alpha) on every frame of the effect's model. When no_light is given it also sets whether the model ignores scene lighting (nonzero) or not (0).

Original name: _CHR_SET_LIGHT_COLOR.

allocate_sprites

extern void allocate_sprites(int count, OPTIONAL(int *ok)) NATIVE(150);

Allocates count billboard sprites for this effect, numbered 0 to count - 1. Fails when the effect already has sprites. ok, when given, receives 1 on success and 0 when memory ran out.

Original name: _SPT_ASSIGN_SPRITE.

free_sprites

extern void free_sprites(void) NATIVE(151);

Frees this effect's sprites so allocate_sprites can be called again.

Original name: _SPT_DELETE_SPRITE.

set_sprite_texture

extern void set_sprite_texture(string texture_name) NATIVE(152);

Sets the texture, by name in the effect's texture block, that all of this effect's sprites are drawn with.

Original name: _SPT_SET_TEXNAME.

set_sprite_blend

extern void set_sprite_blend(int first, OPTIONAL(enum blend_mode blend_mode, int count)) NATIVE(153);

Sets the blend mode of sprites: 1 translucent, 2 additive, 3 subtractive, 4 opaque, 5 additive ignoring alpha; 0 keeps the screen's current mode. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count. The disc once calls it with only first, which leaves the mode unspecified.

Original name: _SPT_SET_ALPHAB.

reset_sprites

extern void reset_sprites(int first, OPTIONAL(int count)) NATIVE(154);

Resets sprites to defaults: hidden, translucent blend, at (0, 0, 0), colour 128 on all channels, scale 1, zero size and UV, and every velocity, acceleration, easing and blink cleared. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_INIT_SPRITE.

set_sprite_visible

extern void set_sprite_visible(int first, int visible, OPTIONAL(int count)) NATIVE(155);

Shows (nonzero) or hides (0) sprites. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_DRAW_FLAG.

get_sprite_visible

extern int get_sprite_visible(int index) NATIVE(156);

Returns the visibility flag of sprite index.

Original name: _SPT_GET_DRAW_FLAG.

set_sprite_uv

extern void set_sprite_uv(int first, float u, float v, float width, float height, OPTIONAL(int count)) NATIVE(157);

Sets the texture rectangle drawn on sprites: left u, top v, width and height in texture pixels. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_UV_SIZE.

set_sprite_size

extern void set_sprite_size(int first, float width, float height, OPTIONAL(int count)) NATIVE(158);

Sets the drawn width and height of sprites in world units, before their scale is applied. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_PUT_SIZE.

set_sprite_pos

extern void set_sprite_pos(int first, float x, float y, float z, OPTIONAL(int count)) NATIVE(159);

Sets the position of sprites, relative to the effect origin. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_POS.

get_sprite_pos

extern void get_sprite_pos(int index, float *x, float *y, float *z) NATIVE(160);

Writes the position of sprite index into the three out variables.

Original name: _SPT_GET_POS.

set_sprite_angle

extern void set_sprite_angle(int first, float angle, OPTIONAL(int count)) NATIVE(161);

Sets the screen-plane rotation of sprites in radians. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_ROTZ.

get_sprite_angle

extern float get_sprite_angle(int index) NATIVE(162);

Returns the screen-plane rotation in radians of sprite index.

Original name: _SPT_GET_ROTZ.

set_sprite_scale

extern void set_sprite_scale(int first, float scale_x, float scale_y, OPTIONAL(int count)) NATIVE(163);

Sets the horizontal and vertical scale of sprites; the drawn size is size times scale. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_SCALE.

get_sprite_scale

extern void get_sprite_scale(int index, float *scale_x, float *scale_y) NATIVE(164);

Writes the horizontal and vertical scale of sprite index into scale_x and scale_y.

Original name: _SPT_GET_SCALE.

set_sprite_color

extern void set_sprite_color(int first, float red, float green, float blue, float alpha, OPTIONAL(int count)) NATIVE(165);

Sets the colour of sprites, each channel 0 to 255 with 128 as normal brightness and full alpha. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_COLOR.

get_sprite_color

extern void get_sprite_color(int index, float *red, float *green, float *blue, float *alpha) NATIVE(166);

Writes the colour channels of sprite index into the four out variables.

Original name: _SPT_GET_COLOR.

spread_sprite_pos

extern void spread_sprite_pos(int first, float x, float y, float z, float vx, float vy, float vz, float ax, float ay, float az, OPTIONAL(int count)) NATIVE(167);

Places a run of sprites along a curve: the first gets (x, y, z), and each next one is offset by a step vector that starts at (vx, vy, vz) and grows by (ax, ay, az) per sprite. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_VAN_SET_POS.

spread_sprite_angle

extern void spread_sprite_angle(int first, float angle, float velocity, float accel, OPTIONAL(int count)) NATIVE(168);

Sets screen-plane angles across a run of sprites: the first gets angle, and each next one adds a step that starts at velocity and grows by accel per sprite, all in radians. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_VAN_SET_ROT.

move_sprite_by

extern void move_sprite_by(int first, float dx, float dy, float dz, OPTIONAL(int count)) NATIVE(169);

Adds (dx, dy, dz) to the position of sprites. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_ADD_POS.

rotate_sprite_by

extern void rotate_sprite_by(int first, float angle, OPTIONAL(int count)) NATIVE(170);

Adds angle radians to the screen-plane rotation of sprites, wrapping into -pi..pi. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_ADD_ROTZ.

add_sprite_color

extern void add_sprite_color(int first, float red, float green, float blue, float alpha, OPTIONAL(int count)) NATIVE(171);

Adds to the colour channels of sprites and clamps each to 0..255. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_ADD_COLOR.

rotate_sprites_around_y

extern void rotate_sprites_around_y(int first, float angle, OPTIONAL(int count)) NATIVE(172);

Rotates the positions of sprites by angle radians around the Y axis through the effect origin. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_WORLD_ROT.

set_sprite_life

extern void set_sprite_life(void) NATIVE(173);

Unsupported: always fails and does nothing.

Original name: _SPT_SET_LIFE.

set_sprite_velocity

extern void set_sprite_velocity(int first, float vx, float vy, float vz, OPTIONAL(int count)) NATIVE(174);

Sets the per-frame movement of sprites; the engine adds it to their position every frame. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_VELO_POS.

set_sprite_accel

extern void set_sprite_accel(int first, float ax, float ay, float az, OPTIONAL(int count)) NATIVE(175);

Sets the per-frame change of sprite velocity; the engine adds it to their velocity every frame. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_ACC_POS.

set_sprite_spin

extern void set_sprite_spin(int first, float velocity, OPTIONAL(int count)) NATIVE(176);

Sets the radians per frame that sprites turn in the screen plane. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_VELO_ROTZ.

VM_ARGS

extern void set_sprite_spin_accel VM_ARGS(int first, float accel, OPTIONAL(int count, any unused)) NATIVE(177);

Sets the per-frame change of sprite spin, in radians; spin is capped at 2 pi per frame. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count. A fourth argument seen on the disc is ignored.

Original name: _SPT_SET_ACC_ROTZ.

set_sprite_color_velocity

extern void set_sprite_color_velocity(int first, float red, float green, float blue, float alpha, OPTIONAL(int count)) NATIVE(178);

Sets the amount added to each sprite colour channel every frame. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_VELO_COL.

set_sprite_color_accel

extern void set_sprite_color_accel(int first, float red, float green, float blue, float alpha, OPTIONAL(int count)) NATIVE(179);

Sets the per-frame change of the sprite colour velocity. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_ACC_COL.

extern void set_sprite_blink(int first, float red, float green, float blue, float alpha, float speed, OPTIONAL(int count)) NATIVE(180);

Makes sprites pulse: each drawn frame adds SIN(phase) times the given amplitude to each colour channel, and phase advances by speed radians. speed = 0 turns blinking off. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_BLINKING.

spread_sprite_color

extern void spread_sprite_color(int first, float red, float green, float blue, float alpha, float velocity_red, float velocity_green, float velocity_blue, float velocity_alpha, float accel_red, float accel_green, float accel_blue, float accel_alpha, int count) NATIVE(181);

Sets colours across a run of sprites: the first gets (red, green, blue, alpha), and each next one adds a step that starts at the velocity colour and grows by the accel colour per sprite. Starts at sprite first; pass count, since the engine reads it whenever there are 11 or more arguments.

Original name: _SPT_VAN_SET_COL.

VM_ARGS

extern void set_sprite_scale_velocity VM_ARGS(int first, float scale_x, float scale_y, OPTIONAL(int count, any unused)) NATIVE(182);

Sets the amount added to the horizontal and vertical scale of sprites every frame. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count. A fifth argument seen on the disc is ignored.

Original name: _SPT_SET_VELO_SCL.

set_sprite_scale_accel

extern void set_sprite_scale_accel(int first, float scale_x, float scale_y, OPTIONAL(int count)) NATIVE(183);

Sets the per-frame change of the sprite scale velocity. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SET_ACC_SCL.

spread_sprite_scale

extern void spread_sprite_scale(int first, float scale_x, float scale_y, float vx, float vy, float ax, float ay, OPTIONAL(int count)) NATIVE(184);

Sets scales across a run of sprites: the first gets (scale_x, scale_y), and each next one adds a step that starts at (vx, vy) and grows by (ax, ay) per sprite. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_VAN_SET_SCL.

ease_sprite_scale

extern void ease_sprite_scale(int first, float scale_x, float scale_y, float divisor, OPTIONAL(int count)) NATIVE(185);

Eases the scale of sprites toward (scale_x, scale_y): every frame they move 1/divisor of the remaining distance. A divisor of 0 or less stops easing. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_SCALE_CONV.

ease_sprite_color

extern void ease_sprite_color(int first, float red, float green, float blue, float alpha, float divisor, OPTIONAL(int count)) NATIVE(186);

Eases the colour of sprites toward (red, green, blue, alpha): every frame each channel moves 1/divisor of the remaining distance. A divisor of 0 or less stops easing. Affects count sprites starting at first (count defaults to 1); it stops and fails at the first index past the effect's sprite count.

Original name: _SPT_COLOR_CONV.

get_scene_chara_pos

extern void get_scene_chara_pos(int chara, float *x, float *y, float *z) NATIVE(200);

Writes the position of the scene character in slot chara (for example the owner or target id) into the three out variables. Fails when the slot is empty.

Original name: _SCN_GET_CHR_POS.

get_scene_chara_rot

extern void get_scene_chara_rot(int chara, float *rot_x, OPTIONAL(float *rot_y, float *rot_z)) NATIVE(201);

Writes the rotation in radians of the scene character in slot chara. With three out parameters it writes x, y and z; with only one it writes the yaw (y).

Original name: _SCN_GET_CHR_ROT.

get_chara_frame_pos

extern void get_chara_frame_pos(int chara, string frame_name, float *x, float *y, float *z) NATIVE(202);

Writes the world position of the frame (bone) named frame_name on the scene character in slot chara into the three out variables.

Original name: _SCN_GET_CHR_FRM_POS.

get_line_hit

extern void get_line_hit(enum coll_query ignore_mask, float start_x, float start_y, float start_z, float end_x, float end_y, float end_z, void *hit_x, OPTIONAL(void *hit_y, void *hit_z, void *reflect_x, void *reflect_y, void *reflect_z, void *hit_index, void *area_kind, int *foot_sound)) NATIVE(203);

Tests the line from start to end against the scene's collision polygons, skipping polygons whose ignore bits match ignore_mask, and writes the nearest hit. The outputs depend on how many follow the 7 inputs: 1-3 outs get hit_index (polygon index or -1), area_kind, foot_sound; 4-6 outs get hit x, y, z, then those three; 7-9 outs get hit x, y, z, the unit reflection direction x, y, z, then those three. Other outputs are only valid when hit_index is 0 or more.

Original name: _INTERSECTION_POINT.

create_damage

extern int create_damage(string damage_name, float radius, int owner) NATIVE(204);

Disabled in this build: prints an error and fails without creating anything or writing the result. Use create_attack instead.

Original name: _CREATE_DAMAGE.

delete_damage

extern void delete_damage(int handle) NATIVE(205);

Disabled in this build: does nothing and fails.

Original name: _DELETE_DAMAGE.

set_damage_pos

extern void set_damage_pos(int handle, float x, float y, float z) NATIVE(206);

Disabled in this build: does nothing and fails.

Original name: _DMG_SET_POS.

set_damage_dir

extern void set_damage_dir(int handle, float x, float y, float z) NATIVE(207);

Disabled in this build: does nothing and fails.

Original name: _DMG_SET_FRONT_VECT.

set_damage_amount

extern void set_damage_amount(int handle, int damage) NATIVE(208);

Disabled in this build: prints an error and fails.

Original name: _DMG_SET_DAMAGE.

create_attack

extern void create_attack(string damage_name, OPTIONAL(int owner)) NATIVE(210);

Gives this effect an attack shape set up from the damage table row named damage_name, replacing any attack it had. owner defaults to the effect's owner; for rows that pick targets by owner, owner 0 hits monsters and any other owner hits the player. Place it with set_attack_shape.

Original name: _COLPRIM_CREATE.

VM_ARGS

extern void set_attack_shape VM_ARGS(any start_x, any start_y, OPTIONAL(any start_z, float radius_or_end_x, float end_y, float end_z, float radius)) NATIVE(211);

Places this effect's attack. Four forms: (x, y, z, radius) a sphere; (start x, y, z, end x, y, z, radius) a line with that radius; (frame_name, radius) a sphere following that frame of the effect's model; (frame_name, end_frame_name, radius) a line between two frames of the model.

Original name: _COLPRIM_SET_COORD.

delete_attack

extern void delete_attack(int unused) NATIVE(212);

Removes this effect's attack. The argument is read and ignored; scripts pass -1.

Original name: _COLPRIM_DELETE.

get_attack_hit_count

extern int get_attack_hit_count(void) NATIVE(213);

Returns how many hits this effect's attack has dealt.

Original name: _COLPRIM_GET_HITCNT.

set_attack_damage

extern void set_attack_damage(int damage) NATIVE(214);

Sets the damage each hit of this effect's attack deals, overriding the damage table value.

Original name: _COLPRIM_SET_DAMAGE.

get_attack_hit_pos

extern void get_attack_hit_pos(float *x, float *y, float *z) NATIVE(215);

Writes the position of the last hit of this effect's attack into the three out variables.

Original name: _COLPRIM_GET_HIT_POS.

set_attack_gift

extern void set_attack_gift(int item1, int item2, int item3) NATIVE(216);

Marks this effect's attack as carrying a gift of three item numbers. A monster accepts the gift only when all three equal the gift item it wants.

Original name: _COLPRIM_GET_GIFT.

get_attack_knockback

extern void get_attack_knockback(int *knocked_back, OPTIONAL(float *dir_x, float *dir_y, float *dir_z)) NATIVE(217);

Writes nonzero into knocked_back when another attack has knocked this effect's attack back, and the knockback direction into dir_x, dir_y, dir_z when given.

Original name: _COLPRIM_GET_REVCNT.

play_owner_se

extern void play_owner_se(int se, OPTIONAL(float x, float y, float z)) NATIVE(220);

Plays sound effect se from the owner character's sound bank. With x, y, z the volume and pan come from that position, fading out between 160 and 1200 world units. Fails when the effect has no owner.

Original name: _MON_SE_PLAY.

stop_owner_se

extern void stop_owner_se(int se) NATIVE(221);

Stops sound effect se in the owner character's sound bank.

Original name: _MON_SE_STOP.

play_battle_se

extern void play_battle_se(int se, OPTIONAL(float x, float y, float z)) NATIVE(222);

Plays sound effect se from the scene's battle sound bank. With x, y, z the volume and pan come from that position, fading out between 160 and 1200 world units.

Original name: _BTL_SE_PLAY.

stop_battle_se

extern void stop_battle_se(int se) NATIVE(223);

Stops sound effect se in the scene's battle sound bank.

Original name: _BTL_SE_STOP.

play_base_se

extern void play_base_se(int se) NATIVE(224);

Plays sound effect se from the scene's base sound bank.

Original name: _BSE_SE_PLAY.

stop_base_se

extern void stop_base_se(int se) NATIVE(225);

Stops sound effect se in the scene's base sound bank.

Original name: _BSE_SE_STOP.

play_chara_se

extern void play_chara_se(int chara, int se, OPTIONAL(float x, float y, float z)) NATIVE(226);

Plays sound effect se from the sound bank of the scene character in slot chara. With x, y, z the volume and pan come from that position, fading out between 160 and 1200 world units.

Original name: _MON_SE_PLAY2.

stop_chara_se

extern void stop_chara_se(int chara, int se) NATIVE(227);

Stops sound effect se in the sound bank of the scene character in slot chara.

Original name: _MON_SE_STOP2.

set_sprite_lighting

extern void set_sprite_lighting(int on) NATIVE(230);

With on = 1 this effect's sprites take their red, green and blue from the scene light and ambient colour instead of their own; alpha is kept. 0 turns it off.

Original name: _SET_LIGHT_FLAG.

get_chara_entry_pos

extern void get_chara_entry_pos(int chara, int index, float *x, float *y, float *z) NATIVE(231);

Writes the world position of entry point index (an attachment frame such as a weapon mount) on the scene character in slot chara, or the character's own position when it has none.

Original name: _SCN_GET_CHR_ENTOBJ_POS.

get_chara_frame_dir

extern void get_chara_frame_dir(int chara, string frame_name, float *x, float *y, float *z) NATIVE(232);

Writes the world direction of the +Z axis of the frame named frame_name on the scene character in slot chara into the three out variables.

Original name: _SCN_GET_CHR_FRM_DIR.

get_chara_frame_rot

extern void get_chara_frame_rot(int chara, string frame_name, float *rot_x, float *rot_y, float *rot_z) NATIVE(233);

Writes the pitch, yaw and 0, in radians, that face along the +Z axis of the frame named frame_name on the scene character in slot chara.

Original name: _SCN_GET_CHR_FRM_ROT.

get_entry_object_pos

extern void get_entry_object_pos(int chara, int index, float *x, float *y, float *z) NATIVE(234);

Same as get_chara_entry_pos, but index must be 0 or 1.

Original name: _SCN_GET_ENTRY_OBJ_POS.

start_child_effect

extern void start_child_effect(string effect_name, OPTIONAL(int *handle)) NATIVE(240);

Starts the effect named effect_name, owned by this effect's owner; it runs its program 200. With handle it is also entered in the owner's slot table (8 slots) and handle receives its slot number, or -1 on failure. The set_child_* natives address it by that handle, or without one by the effect started most recently.

Original name: _ES_CREATE.

VM_ARGS

extern void set_child_vector1 VM_ARGS(any handle_or_x, float x_or_y, float y_or_z, OPTIONAL(float z)) NATIVE(241);

Sets the first work vector of a child effect, read there with get_work_vector1. Pass (x, y, z) for the most recently started effect, or (handle, x, y, z) for the effect in that slot.

Original name: _ES_SET_VECT1.

VM_ARGS

extern void set_child_vector2 VM_ARGS(any handle_or_x, float x_or_y, float y_or_z, OPTIONAL(float z)) NATIVE(242);

Sets the second work vector of a child effect, read there with get_work_vector2. Pass (x, y, z) for the most recently started effect, or (handle, x, y, z) for the effect in that slot.

Original name: _ES_SET_VECT2.

set_child_target

extern void set_child_target(int handle_or_target, OPTIONAL(int target)) NATIVE(243);

Sets the target scene character slot of a child effect, read there with get_target_id. Pass (target) for the most recently started effect, or (handle, target) for the effect in that slot.

Original name: _ES_SET_TARGET_ID.

share_attack_with_child

extern void share_attack_with_child(void) NATIVE(244);

Gives the most recently started child effect a pointer to this effect's attack.

Original name: _ES_SET_COLPRIM.

VM_ARGS

extern void set_child_value VM_ARGS(int handle_or_index, any index_or_value, OPTIONAL(any value)) NATIVE(245);

Stores an int or float in value slot index (0 to 7) of a child effect, read there with get_effect_value. Pass (index, value) for the most recently started effect, or (handle, index, value) for the effect in that slot.

Original name: _ES_SET_VALUE.

get_event_object_pos

extern void get_event_object_pos(int handle, float *x, float *y, float *z) NATIVE(251);

Writes the position of whatever event object handle number handle refers to into the three out variables.

Original name: _GET_EOH_POS.

set_model_frame_visible

extern void set_model_frame_visible(string frame_name, int visible, int include_children) NATIVE(252);

Shows (1) or hides (0) the frame named frame_name in the effect's model. With include_children nonzero the change also applies to the frames under it.

Original name: _CHR_SET_FRAME_SHOW.

check_model_motion_end

extern int check_model_motion_end(void) NATIVE(253);

Returns 1 when the effect model's motion reaches its last frame within the next two steps or no motion plays, else 0.

Original name: _CHR_CHK_MOT_END.

VM_ARGS

extern void _EXT_250 VM_ARGS(...) NATIVE(250);

Numbers the disc calls that this table never registers. The engine prints "not found ext" and moves on, so these calls do nothing.

Helpers

Inline helper functions that wrap common sequences of native calls.

Helper What it does
spawn_child_effect Starts a child effect and sets its first and second work vectors, which it reads with get_work_vector1 and get_work_vector2.
spawn_child_effect_at Starts a child effect and sets its first work vector, usually where it appears.
get_work_vectors Reads both work vectors the effect's starter passed in.
place_model Sets the position of the effect's model and turns it to a rotation at once.
fade_in_model_at_scale Sets the effect model's scale to the same value on all three axes and fades the model in.
create_attack_with_damage Gives this effect an attack from the named damage table row and sets the damage each hit deals.
setup_sprites Sets the sprite texture, allocates count sprites, resets them and shows them all with one blend mode.
show_sprites Resets the first count sprites and shows them with one blend mode.
get_unit_dir_from_rot Writes the unit direction that a rotation in radians faces into x, y, z.
get_unit_direction Writes the unit vector pointing from the from point to the to point into x, y, z.
get_offset_step Writes the vector from the from point to the to point, divided by divisor, into x, y, z, such as the step that covers that distance in divisor frames.
get_scaled_vector Writes the vector src_x, src_y, src_z multiplied by factor into x, y, z.
set_vector_length Scales the vector held in x, y, z to the given length, keeping its direction.
move_model_facing Turns the model to face the point x, y, z from where it stands, writing that rotation into rot_x, rot_y, rot_z, then moves it there.
step_model_facing Adds dx, dy, dz to the position held in x, y, z, then moves the model there facing its direction of travel, writing that rotation into rot_x, rot_y, rot_z.
advance_point Copies the point held in x, y, z into old_x, old_y, old_z, then adds dx, dy, dz to it.

spawn_child_effect

Starts a child effect and sets its first and second work vectors, which it reads with get_work_vector1 and get_work_vector2.

static inline void spawn_child_effect(string effect_name, float x, float y, float z, float x2, float y2, float z2)
{
    start_child_effect(effect_name);
    set_child_vector1(x, y, z);
    set_child_vector2(x2, y2, z2);
}

spawn_child_effect_at

Starts a child effect and sets its first work vector, usually where it appears.

static inline void spawn_child_effect_at(string effect_name, float x, float y, float z)
{
    start_child_effect(effect_name);
    set_child_vector1(x, y, z);
}

get_work_vectors

Reads both work vectors the effect's starter passed in.

static inline void get_work_vectors(float *x, float *y, float *z, float *x2, float *y2, float *z2)
{
    get_work_vector1(x, y, z);
    get_work_vector2(x2, y2, z2);
}

place_model

Sets the position of the effect's model and turns it to a rotation at once.

static inline void place_model(float x, float y, float z, float rot_x, float rot_y, float rot_z)
{
    set_model_pos(x, y, z);
    set_model_rot(rot_x, rot_y, rot_z);
}

fade_in_model_at_scale

Sets the effect model's scale to the same value on all three axes and fades the model in.

static inline void fade_in_model_at_scale(float scale, float fade_speed)
{
    set_model_scale(scale, scale, scale);
    set_model_visible(1, 1, fade_speed);
}

create_attack_with_damage

Gives this effect an attack from the named damage table row and sets the damage each hit deals.

static inline void create_attack_with_damage(string damage_name, int damage)
{
    create_attack(damage_name);
    set_attack_damage(damage);
}

setup_sprites

Sets the sprite texture, allocates count sprites, resets them and shows them all with one blend mode.

static inline void setup_sprites(string texture_name, int count, enum blend_mode blend_mode)
{
    set_sprite_texture(texture_name);
    allocate_sprites(count);
    reset_sprites(0, count);
    set_sprite_blend(0, blend_mode, count);
    set_sprite_visible(0, 1, count);
}

show_sprites

Resets the first count sprites and shows them with one blend mode.

static inline void show_sprites(int count, enum blend_mode blend_mode)
{
    reset_sprites(0, count);
    set_sprite_blend(0, blend_mode, count);
    set_sprite_visible(0, 1, count);
}

get_unit_dir_from_rot

Writes the unit direction that a rotation in radians faces into x, y, z.

static inline void get_unit_dir_from_rot(float rot_x, float rot_y, float rot_z, float *x, float *y, float *z)
{
    get_dir_from_rot(rot_x, rot_y, rot_z, x, y, z);
    normalize_vector(x, y, z);
}

get_unit_direction

Writes the unit vector pointing from the from point to the to point into x, y, z.

static inline void get_unit_direction(float *x, float *y, float *z, float to_x, float to_y, float to_z, float from_x, float from_y, float from_z)
{
    copy_vector(x, y, z, to_x, to_y, to_z);
    subtract_vector(x, y, z, from_x, from_y, from_z);
    normalize_vector(x, y, z);
}

get_offset_step

Writes the vector from the from point to the to point, divided by divisor, into x, y, z, such as the step that covers that distance in divisor frames.

static inline void get_offset_step(float *x, float *y, float *z, float to_x, float to_y, float to_z, float from_x, float from_y, float from_z, float divisor)
{
    copy_vector(x, y, z, to_x, to_y, to_z);
    subtract_vector(x, y, z, from_x, from_y, from_z);
    divide_vector(x, y, z, divisor);
}

get_scaled_vector

Writes the vector src_x, src_y, src_z multiplied by factor into x, y, z.

static inline void get_scaled_vector(float *x, float *y, float *z, float src_x, float src_y, float src_z, float factor)
{
    copy_vector(x, y, z, src_x, src_y, src_z);
    scale_vector(x, y, z, factor);
}

set_vector_length

Scales the vector held in x, y, z to the given length, keeping its direction.

static inline void set_vector_length(float *x, float *y, float *z, float length)
{
    normalize_vector(x, y, z);
    scale_vector(x, y, z, length);
}

move_model_facing

Turns the model to face the point x, y, z from where it stands, writing that rotation into rot_x, rot_y, rot_z, then moves it there.

static inline void move_model_facing(float x, float y, float z, float *rot_x, float *rot_y, float *rot_z)
{
    get_model_rot_toward(x, y, z, rot_x, rot_y, rot_z);
    set_model_pos(x, y, z);
    set_model_rot(*rot_x, *rot_y, *rot_z);
}

step_model_facing

Adds dx, dy, dz to the position held in x, y, z, then moves the model there facing its direction of travel, writing that rotation into rot_x, rot_y, rot_z.

static inline void step_model_facing(float *x, float *y, float *z, float dx, float dy, float dz, float *rot_x, float *rot_y, float *rot_z)
{
    add_vector(x, y, z, dx, dy, dz);
    get_model_rot_toward(*x, *y, *z, rot_x, rot_y, rot_z);
    set_model_pos(*x, *y, *z);
    set_model_rot(*rot_x, *rot_y, *rot_z);
}

advance_point

Copies the point held in x, y, z into old_x, old_y, old_z, then adds dx, dy, dz to it.

static inline void advance_point(float *old_x, float *old_y, float *old_z, float *x, float *y, float *z, float dx, float dy, float dz)
{
    copy_vector(old_x, old_y, old_z, *x, *y, *z);
    add_vector(x, y, z, dx, dy, dz);
}

Programs

Program entry-point numbers started by the engine (enum program). Register an entry point in a script with PROGRAM(name, function);.

Program Number When it runs
unused 100 Present in every effect script but never selected by the engine: new effects start at 200 and only 300 is requested later (effscript.cpp), and every retail body is empty.
play 200 Runs when the effect is created (effscript.cpp sets prog_no 200 on a new effect script) and is resumed every frame; the effect is deleted when it ends.
finish 300 Runs when the owner asks the effect to wind down through _ESM_FINISH from action, monster or event scripts or when a held item is thrown (SetScriptProgNo(300)); retail bodies fade the sprites out before ending.

Constants

Name Value What it is
PI 3.1415927

enum blend_mode

Sprite alpha blend modes passed to mgCDrawEnv::SetAlpha (mg_drawenv.hpp mgAlphaMacroID); 0 keeps the current mode.

Name Value
MG_ALPHA_MACRO_NONE 0
MG_ALPHA_MACRO_BLEND 1
MG_ALPHA_MACRO_ADD 2
MG_ALPHA_MACRO_SUB 3
MG_ALPHA_MACRO_OPAQUE 4
MG_ALPHA_MACRO_ADD_FIX 5

enum coll_query

Collision query bits matched against CCPoly::ignore_mask; polygons with a matching bit let that query through (1 player moves, 2 monster moves, 4 shots and thrown objects, 8 the fishing line).

Name Value
COLL_QUERY_PLAYER 1
COLL_QUERY_MONSTER 2
COLL_QUERY_PROJECTILE 4
COLL_QUERY_FISHING_LINE 8

enum motion_flags

Motion playback flags (character.hpp CharaMotionFlag): pause, stop on the last frame, restart without blending.

Name Value
CHARA_MOTION_PAUSE 1
CHARA_MOTION_HOLD 2
CHARA_MOTION_RESTART 4