Skip to content

Action scripts: <action.h>

Natives for character action scripts (mainchr, dungeon/act_script). They act on the character running the script.

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/action.h and sdk/helpers/action.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
VM_ARGS 0 Clears the character's action setup: registered object slots, body collisions, damage entries, motion sound triggers and sword trails, and drops whatever it holds and any pending impulse or knockback.
VM_ARGS 1 Stores a 16-bit value on the character that the action script keeps for its own use between program runs, such as a combo step counter.
get_saved_value 2 Returns the value last stored with set_saved_value.
get_attack_type 3 Returns the character's attack type, taken from its setup data.
get_move_type 4 Returns the character's movement type: 0 on foot, 1 or 4 ridepod legs, 2 or 5 ridepod treads, 3 ridepod wheels (or a monster), 6 or 7 ridepod flight.
set_move_speed 5 Sets the character's movement speed used by the stick movement handlers.
VM_ARGS 30 Pulses the character's lighting toward an RGB colour (0 to 255 each).
get_equip_item 31 Returns the item number equipped in an equipment slot of the active character.
VM_ARGS 32 Shakes the dungeon camera with the given strength, fading linearly to nothing over the given number of frames.
check_pause_flag 33 Returns the dungeon pause flags ANDed with mask, so it is nonzero when any of those flags is set.
get_status_flags 34 Returns the active character's status ailment bits (such as poison or slow).
VM_ARGS 35 Plays a sound effect from the character's own sound bank.
VM_ARGS 36 Keeps a looping sound effect from the character's own sound bank playing for keep_frames more frames; call it again before they run out to sustain it.
VM_ARGS 37 Returns the attack type of the active character's sub weapon (equipment slot 1), for example 0 or 11 normal gun, 10 grenade, 20 laser, 30 machine gun.
get_monster_form 38 Returns the monster id of the active character's monster transformation, or -1 when the active character is not a transformed monster.
get_front_vec 39 Writes the character's facing direction vector into three float out parameters.
VM_ARGS 40 Returns the bitmask of controller buttons currently held.
get_pad_pressed 41 Returns the bitmask of controller buttons pressed this frame.
VM_ARGS 42 Returns the bitmask of controller buttons released this frame.
get_pad_button 43 Returns the state of a logical game button (nonzero when it triggers this frame).
get_attack_presses 45 Returns the attack press history: every frame the attack button (logical button 50) state is ORed in, so it is nonzero if attack was pressed since the last reset_attack_presses.
VM_ARGS 46 Clears the attack press history read by get_attack_presses.
get_attack_hold_frames 47 Returns how many frames in a row the attack button (logical button 56) has been held; it drops to 0 when released.
reset_attack_hold_frames 48 Sets the attack hold frame counter read by get_attack_hold_frames back to 0.
run_stick_move 49 Runs one frame of normal stick movement for the character: on-foot walking and running for a human, or monster-form movement for a monster type.
run_carry_move 50 Runs one frame of stick movement while carrying something overhead: slower movement with the lift-stand and lift-walk motions, turning toward the locked-on target when standing still.
run_charge_move 51 Runs one frame of slow stick movement while charging an attack, switching between the charge stand and charge walk motions.
VM_ARGS 52 Runs one frame of slow stick movement while aiming or guarding.
get_chara_pos 53 Writes the character's world position into three float out parameters.
get_stick_alignment 54 Returns, as a float, the dot product of the camera-relative left stick direction and the character's facing: near 1 when pushing forward, near -1 when pushing backward.
check_back_key 55 Returns 1 when the character is locked on and the left stick points within about 72 degrees of straight behind it, otherwise 0.
face_blow_source 56 Turns the character to face opposite its current knockback direction, toward where the hit came from.
set_move_impulse 57 Pushes the character along its facing for frames frames, starting at speed and slowing by decel each frame.
start_knockback 58 Starts knocking the character back along its knockback direction for frames frames.
set_menu_allowed 59 Allows (1) or blocks (0) opening the menu and starting field events this frame.
run_ridepod_move 60 Runs one frame of ridepod stick movement for the current movement type (legs, treads, wheels or flight).
get_chara_rot 61 Writes the character's rotation into three float out parameters, in radians.
add_attack_hit 71 Registers an attack hitbox swept between two model frames while a motion plays (up to 11).
set_object_slot 72 Registers the named model frame in object slot 0 to 7 (or the first free slot with -1).
add_body_collision 73 Adds a body collision sphere centred on a registered object slot.
add_sword_trail 75 Schedules a sword trail between two model frames while a motion plays between start_ratio and end_ratio (0.0 to 1.0 of the motion).
add_motion_se 76 Registers a sound trigger for the window between start_ratio and end_ratio (0.0 to 1.0) of a motion, up to 10.
set_charge_effect_slot 77 Sets the object slot the charge effect is drawn at and its effect number, and marks the charge effect inactive.
set_charge_effect_mode 78 Changes the charge effect mode.
get_target_status 90 Returns the status value that the locked target monster's own script has published, or 0 when there is no target.
set_menace 91 Sets a menace level (0 or 1) on the character for frames frames.
get_target_distance 92 Returns, as a float, the distance from the character to its target, or -1 when there is no target.
VM_ARGS 93 Turns the character toward its target monster when it is closer than twice radius plus the monster's body width.
set_guarding 94 Turns guarding on (1) or off (0).
set_invincible 95 Makes the character invincible for the given number of frames; 0 ends it.
get_held_type 96 Returns what the character holds: 0 nothing, 1 an item to throw, 3 a caught monster, 4 a stone from the map.
use_active_item 97 Uses the active item and returns the result: 0 nothing happened, 1 the item was used (healing items flash the character), 2 the item is a throwable now held, 3 the active item slot is 3.
throw_held_item 98 Throws the held item 120 units ahead of the character and removes one from the inventory.
try_grab 99 With only object_name, grabs a monster or a map stone near that model frame if possible (a grabbed monster costs 5% HP).
VM_ARGS 100 Lets go of whatever the character holds.
VM_ARGS 101 Fires the active character's sub weapon from an object slot: Max's gun by its type, or Monica's magic with damage scaled by scale (default 1.0).
VM_ARGS 102 Fires the ridepod's arm weapon (rocket, machine gun, missile, cannon or beam by attack type), alternating muzzles.
VM_ARGS 103 Writes the world position of a named model frame of the character into three float out parameters.
enable_gun_aim 104 Lets the character aim its gun at the locked-on target this frame; the engine clears it every frame.
VM_ARGS 105 Fires the magic stored in the sword from the named model frame toward the target, using the stored element and power, then clears it.
get_hp_rate 106 Returns, as a float, current HP divided by maximum HP.
set_low_hp 107 Sets the active character's HP to 5% of maximum.
get_weapon_model 108 Returns the model number of the active character's main weapon.
get_weapon_attack 109 Returns the attack stat of a weapon slot of the active character.
get_ring_color 110 Writes the RGB colour (0 to 255) of the element of the equipped magic ring into three out parameters.
play_motion 130 Plays a motion on the character and its linked model parts.
is_motion_done 131 Writes 1.0 into a float out parameter when the current motion has reached its last frame (or none is set), otherwise 0.0.
get_motion_progress 132 Writes how far the current motion has played into a float out parameter, from 0.0 at the start to 1.0 at the end (0.0 while blending in).
get_motion_status 133 Writes the motion state into the out parameter: 0 none, 1 on its first frame, 2 playing, 3 blending in, 4 reached the end.
set_motion_blend_speed 134 Sets how much the blend into the next motion advances each frame; 1.0 or more makes it switch at once.
set_motion_speed 135 Sets the playback step of the character's current motion, in frames per update.
advance_motion_sequence 136 Tells the character's motion sequence to move on to its next step.
reset_motion 137 Clears the current and pending motions of the character and its linked model parts.
set_default_motion 138 Sets the motion the character returns to by default, such as its standing motion.
get_motion_blend 139 Returns, as a float, the progress of the blend into the new motion, or -1.0 when not blending.
apply_slow_status 140 If the active character has the slow status, sets the current motion to play at 70% of its default speed.
create_effect 150 Starts the named effect script on the character.
set_effect_vec1 151 Sets the first vector of an effect, usually its position.
set_effect_vec2 152 Sets the second vector of an effect, such as its direction or scale.
finish_effect 153 Switches an effect to its finishing program (300) so it can end on its own.
delete_effect 154 Removes an effect immediately.
VM_ARGS 155 Sets numbered value index of an effect to an int or float.
VM_ARGS 6 Numbers the disc calls that this table never registers.
VM_ARGS 7
VM_ARGS 13
VM_ARGS 14
VM_ARGS 44
VM_ARGS 80

VM_ARGS

extern void reset_action_setup VM_ARGS(OPTIONAL(void *ignored)) NATIVE(0);

Clears the character's action setup: registered object slots, body collisions, damage entries, motion sound triggers and sword trails, and drops whatever it holds and any pending impulse or knockback. Arguments are ignored.

Original name: _INIT_SCRIPT.

VM_ARGS

extern void set_saved_value VM_ARGS(any value) NATIVE(1);

Stores a 16-bit value on the character that the action script keeps for its own use between program runs, such as a combo step counter. It starts at 0.

Original name: _PROG_SET.

get_saved_value

extern int get_saved_value(void) NATIVE(2);

Returns the value last stored with set_saved_value.

Original name: _PROG_GET.

get_attack_type

extern int get_attack_type(void) NATIVE(3);

Returns the character's attack type, taken from its setup data. The robot script branches on it to pick the arm weapon's attacks (0, 20 and so on).

Original name: _GET_ATTK_TYPE.

get_move_type

extern int get_move_type(void) NATIVE(4);

Returns the character's movement type: 0 on foot, 1 or 4 ridepod legs, 2 or 5 ridepod treads, 3 ridepod wheels (or a monster), 6 or 7 ridepod flight.

Original name: _GET_MOVE_TYPE.

set_move_speed

extern void set_move_speed(float speed) NATIVE(5);

Sets the character's movement speed used by the stick movement handlers. A value of 0 or less restores the default of 3.0.

Original name: _SET_MOVE_SPEED.

VM_ARGS

extern void flash_chara_color VM_ARGS(int red, any green, OPTIONAL(int blue, int pulses, int frames, int repeats)) NATIVE(30);

Pulses the character's lighting toward an RGB colour (0 to 255 each). pulses is how many pulses one cycle holds, frames is the cycle length (0 turns it off), and repeats is how many more cycles follow (-1 repeats forever, default 0).

Original name: _SET_PALLET.

get_equip_item

extern int get_equip_item(enum equip_slot slot, ...) NATIVE(31);

Returns the item number equipped in an equipment slot of the active character.

Original name: _CHECK_EQUIP.

VM_ARGS

extern void shake_camera VM_ARGS(float power, any frames, OPTIONAL(any extra3, any extra4, any extra5, any extra6)) NATIVE(32);

Shakes the dungeon camera with the given strength, fading linearly to nothing over the given number of frames.

Original name: _CAMERA_QUAKE.

check_pause_flag

extern int check_pause_flag(enum pause_flags mask, ...) NATIVE(33);

Returns the dungeon pause flags ANDed with mask, so it is nonzero when any of those flags is set. For example 8192 (0x2000) is set while weapons are hidden.

Original name: _CHECK_PAUSE.

get_status_flags

extern int get_status_flags(void) NATIVE(34);

Returns the active character's status ailment bits (such as poison or slow).

Original name: _GET_STATUS_ATTR.

VM_ARGS

extern void play_chara_se VM_ARGS(enum se_bank bank, int se_no, OPTIONAL(any extra3)) NATIVE(35);

Plays a sound effect from the character's own sound bank. bank must be -1 (the character's bank); any other value fails without playing.

Original name: _SE_PLAY.

VM_ARGS

extern void play_chara_loop_se VM_ARGS(OPTIONAL(enum se_bank bank, int se_no, int keep_frames)) NATIVE(36);

Keeps a looping sound effect from the character's own sound bank playing for keep_frames more frames; call it again before they run out to sustain it. bank must be -1 (the character's bank).

Original name: _SE_LOOP_PLAY.

VM_ARGS

extern int get_shot_type VM_ARGS(...) NATIVE(37);

Returns the attack type of the active character's sub weapon (equipment slot 1), for example 0 or 11 normal gun, 10 grenade, 20 laser, 30 machine gun.

Original name: _GET_SHOT_TYPE.

get_monster_form

extern int get_monster_form(void) NATIVE(38);

Returns the monster id of the active character's monster transformation, or -1 when the active character is not a transformed monster.

Original name: _GET_MONS_ID.

get_front_vec

extern void get_front_vec(float *x, float *y, float *z) NATIVE(39);

Writes the character's facing direction vector into three float out parameters.

Original name: _GET_FRONT_VEC.

VM_ARGS

extern int get_pad_held VM_ARGS(...) NATIVE(40);

Returns the bitmask of controller buttons currently held.

Original name: _GET_PADON.

get_pad_pressed

extern int get_pad_pressed(void) NATIVE(41);

Returns the bitmask of controller buttons pressed this frame.

Original name: _GET_PADDOWN.

VM_ARGS

extern int get_pad_released VM_ARGS(...) NATIVE(42);

Returns the bitmask of controller buttons released this frame.

Original name: _GET_PADUP.

get_pad_button

extern int get_pad_button(enum pad_button button, ...) NATIVE(43);

Returns the state of a logical game button (nonzero when it triggers this frame). Action buttons are 50 attack (confirm, pressed), 51 square, 52 cancel and 56 attack held.

Original name: _GET_BTN.

get_attack_presses

extern int get_attack_presses(void) NATIVE(45);

Returns the attack press history: every frame the attack button (logical button 50) state is ORed in, so it is nonzero if attack was pressed since the last reset_attack_presses.

Original name: _GET_PAD_HISTORY.

VM_ARGS

extern void reset_attack_presses VM_ARGS(OPTIONAL(any ignored)) NATIVE(46);

Clears the attack press history read by get_attack_presses. Arguments are ignored.

Original name: _RESET_PAD_HISTORY.

get_attack_hold_frames

extern int get_attack_hold_frames(void) NATIVE(47);

Returns how many frames in a row the attack button (logical button 56) has been held; it drops to 0 when released.

Original name: _GET_ACUMU_PAD.

reset_attack_hold_frames

extern void reset_attack_hold_frames(void) NATIVE(48);

Sets the attack hold frame counter read by get_attack_hold_frames back to 0.

Original name: _RESET_ACUMU_PAD.

run_stick_move

extern void run_stick_move(void) NATIVE(49);

Runs one frame of normal stick movement for the character: on-foot walking and running for a human, or monster-form movement for a monster type. Other movement types do nothing.

Original name: _RUN_MAIN_MOVE.

run_carry_move

extern void run_carry_move(void) NATIVE(50);

Runs one frame of stick movement while carrying something overhead: slower movement with the lift-stand and lift-walk motions, turning toward the locked-on target when standing still.

Original name: _RUN_SHROW_MOVE.

run_charge_move

extern void run_charge_move(void) NATIVE(51);

Runs one frame of slow stick movement while charging an attack, switching between the charge stand and charge walk motions.

Original name: _RUN_TAME_MOVE.

VM_ARGS

extern void run_aim_move VM_ARGS(OPTIONAL(string stand_motion, string move_motion)) NATIVE(52);

Runs one frame of slow stick movement while aiming or guarding. It plays stand_motion and switches to move_motion while the stick moves, turning toward the locked-on target if there is one. Both names are required; calls without them do nothing.

Original name: _RUN_HOLD_MOVE.

get_chara_pos

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

Writes the character's world position into three float out parameters.

Original name: _GET_POS.

get_stick_alignment

extern float get_stick_alignment(void) NATIVE(54);

Returns, as a float, the dot product of the camera-relative left stick direction and the character's facing: near 1 when pushing forward, near -1 when pushing backward.

Original name: _CHECK_FRONT_KEY.

check_back_key

extern int check_back_key(void) NATIVE(55);

Returns 1 when the character is locked on and the left stick points within about 72 degrees of straight behind it, otherwise 0.

Original name: _CHECK_BACK_KEY.

face_blow_source

extern void face_blow_source(void) NATIVE(56);

Turns the character to face opposite its current knockback direction, toward where the hit came from.

Original name: _SET_BLOW_ANGLE.

set_move_impulse

extern void set_move_impulse(float speed, float decel, int frames, OPTIONAL(float angle)) NATIVE(57);

Pushes the character along its facing for frames frames, starting at speed and slowing by decel each frame. angle rotates the push direction from the facing, in degrees (default 0).

Original name: _SET_BLOW_MOVE.

start_knockback

extern void start_knockback(float speed, float decel, int frames) NATIVE(58);

Starts knocking the character back along its knockback direction for frames frames. speed is scaled by the character's knockback rate and drops by decel each frame.

Original name: _BLOW_START.

set_menu_allowed

extern void set_menu_allowed(int allowed) NATIVE(59);

Allows (1) or blocks (0) opening the menu and starting field events this frame. The engine clears it every frame, so the script sets it each frame it wants to allow them; holding something also blocks them.

Original name: _SET_MENU_FLAG.

run_ridepod_move

extern void run_ridepod_move(int all_parts) NATIVE(60);

Runs one frame of ridepod stick movement for the current movement type (legs, treads, wheels or flight). With all_parts nonzero the walk motions are applied to the whole linked model chain, otherwise only to the body.

Original name: _RUN_ROBO_MOVE.

get_chara_rot

extern void get_chara_rot(float *x, float *y, float *z) NATIVE(61);

Writes the character's rotation into three float out parameters, in radians.

Original name: _GET_ROT.

add_attack_hit

extern void add_attack_hit(string frame_a, string frame_b, string hit_name, float radius, float power_rate, string motion_name, float start_ratio, float end_ratio, OPTIONAL(string chara_name)) NATIVE(71);

Registers an attack hitbox swept between two model frames while a motion plays (up to 11). hit_name names the damage entry, radius is doubled for the hit size, power_rate scales damage, and start_ratio and end_ratio are positions in the motion from 0.0 to 1.0. chara_name picks a linked model part whose motion is checked instead of the character's.

Original name: _SET_DMG2.

set_object_slot

extern void set_object_slot(int slot, string frame_name) NATIVE(72);

Registers the named model frame in object slot 0 to 7 (or the first free slot with -1). Other natives refer to the frame by this slot number.

Original name: _SET_OBJ.

add_body_collision

extern void add_body_collision(int slot, float radius) NATIVE(73);

Adds a body collision sphere centred on a registered object slot. The radius argument is doubled.

Original name: _SET_BODY.

add_sword_trail

extern void add_sword_trail(int trail_slot, string motion_name, float start_ratio, float end_ratio, string frame_a, string frame_b, int length, int hold_frames, int fade_frames, OPTIONAL(string chara_name)) NATIVE(75);

Schedules a sword trail between two model frames while a motion plays between start_ratio and end_ratio (0.0 to 1.0 of the motion). trail_slot is 0 to 2, length is the trail's opaque point count, hold_frames delays the fade and fade_frames is how long it fades. chara_name picks a linked model part whose motion and frames are used.

Original name: _SW_EFFECT.

add_motion_se

extern void add_motion_se(int se_no, string motion_name, float start_ratio, float end_ratio, OPTIONAL(string chara_name)) NATIVE(76);

Registers a sound trigger for the window between start_ratio and end_ratio (0.0 to 1.0) of a motion, up to 10. The disc uses ids like 400 for attacks and -2 or -3 on walk and run motions. chara_name picks a linked model part whose motion is used.

Original name: _SET_SND.

set_charge_effect_slot

extern void set_charge_effect_slot(int slot, int effect_no) NATIVE(77);

Sets the object slot the charge effect is drawn at and its effect number, and marks the charge effect inactive.

Original name: _SET_ACCUME_FX.

set_charge_effect_mode

extern void set_charge_effect_mode(enum charge_effect_mode mode) NATIVE(78);

Changes the charge effect mode. 1 starts it at the slot from set_charge_effect_slot, 0 stops it and clears the attack hold counter, 3 and 4 set that mode and mark it inactive, other values only set the mode.

Original name: _SET_ACCUME_FLAG.

get_target_status

extern int get_target_status(void) NATIVE(90);

Returns the status value that the locked target monster's own script has published, or 0 when there is no target.

Original name: _GET_MONSTER_NOWSTS.

set_menace

extern void set_menace(enum menace_level level, int frames) NATIVE(91);

Sets a menace level (0 or 1) on the character for frames frames. While it lasts, the monster it targets may roll to flee using that monster's escape rate for the level.

Original name: _SET_MURDEROUS.

get_target_distance

extern float get_target_distance(void) NATIVE(92);

Returns, as a float, the distance from the character to its target, or -1 when there is no target.

Original name: _GET_TRG_DISTANCE.

VM_ARGS

extern void turn_to_target VM_ARGS(OPTIONAL(float radius, float turn_divisor)) NATIVE(93);

Turns the character toward its target monster when it is closer than twice radius plus the monster's body width. Each call turns it 90/turn_divisor degrees toward the target, snapping when closer than that. Both arguments are required; calls with fewer do nothing.

Original name: _SET_TRG_ANGLE.

set_guarding

extern void set_guarding(int on) NATIVE(94);

Turns guarding on (1) or off (0). While guarding, incoming damage is scaled by the hit's guard rate, unless the hit ignores guard, which also turns guarding off.

Original name: _SET_GUARD_FLAG.

set_invincible

extern void set_invincible(int frames) NATIVE(95);

Makes the character invincible for the given number of frames; 0 ends it.

Original name: _SET_MUTEKI.

get_held_type

extern int get_held_type(void) NATIVE(96);

Returns what the character holds: 0 nothing, 1 an item to throw, 3 a caught monster, 4 a stone from the map.

Original name: _CHECK_HAND_OBJ.

use_active_item

extern int use_active_item(void) NATIVE(97);

Uses the active item and returns the result: 0 nothing happened, 1 the item was used (healing items flash the character), 2 the item is a throwable now held, 3 the active item slot is 3.

Original name: _SET_ITEM_USED.

throw_held_item

extern void throw_held_item(void) NATIVE(98);

Throws the held item 120 units ahead of the character and removes one from the inventory.

Original name: _THROW_HAND_OBJECT.

try_grab

extern void try_grab(string object_name, OPTIONAL(int pick_up, int *found)) NATIVE(99);

With only object_name, grabs a monster or a map stone near that model frame if possible (a grabbed monster costs 5% HP). With all three arguments it checks for a stone within 30 units (40 with pick_up nonzero, which also picks it up) and writes 1 or 0 into found.

Original name: _CHECK_CATCH.

VM_ARGS

extern void release_held VM_ARGS(OPTIONAL(int throw, any extra2, any extra3)) NATIVE(100);

Lets go of whatever the character holds. With throw = 1 a caught monster is thrown ahead (up to 120 units, toward the locked target) and a held item is kept for the throw; with 0 or no argument a held item is discarded and a monster is dropped.

Original name: _RELEASE_OBJ.

VM_ARGS

extern void fire_sub_weapon VM_ARGS(any slot, OPTIONAL(string unused_name, int unused, int wait_frames, float scale)) NATIVE(101);

Fires the active character's sub weapon from an object slot: Max's gun by its type, or Monica's magic with damage scaled by scale (default 1.0). The second and third arguments are read but unused, and wait_frames sets the delay before the next shot. With an empty gun it plays a click instead.

Original name: _SET_SHOT.

VM_ARGS

extern void fire_ridepod_weapon VM_ARGS(any left) NATIVE(102);

Fires the ridepod's arm weapon (rocket, machine gun, missile, cannon or beam by attack type), alternating muzzles. For the beam type left nonzero picks the left muzzle.

Original name: _SHOT.

VM_ARGS

extern void get_object_pos VM_ARGS(any object_name, OPTIONAL(float *x, float *y, float *z)) NATIVE(103);

Writes the world position of a named model frame of the character into three float out parameters.

Original name: _GET_OBJECT_POS.

enable_gun_aim

extern void enable_gun_aim(void) NATIVE(104);

Lets the character aim its gun at the locked-on target this frame; the engine clears it every frame.

Original name: _SET_DIR_GUN.

VM_ARGS

extern void fire_sword_magic VM_ARGS(any object_name) NATIVE(105);

Fires the magic stored in the sword from the named model frame toward the target, using the stored element and power, then clears it. Does nothing when no magic is stored or a shot was fired in the last 5 frames.

Original name: _SET_SPECIAL_SHOT.

get_hp_rate

extern float get_hp_rate(void) NATIVE(106);

Returns, as a float, current HP divided by maximum HP. The division is done in integers, so it is 1.0 at full HP and 0.0 otherwise.

Original name: _GET_NOW_HP_RATE.

set_low_hp

extern void set_low_hp(void) NATIVE(107);

Sets the active character's HP to 5% of maximum.

Original name: _SET_BOMB.

get_weapon_model

extern int get_weapon_model(void) NATIVE(108);

Returns the model number of the active character's main weapon.

Original name: _GET_ACTION_CODE.

get_weapon_attack

extern int get_weapon_attack(enum equip_slot weapon_slot) NATIVE(109);

Returns the attack stat of a weapon slot of the active character.

Original name: _GET_ATTK_POINT.

get_ring_color

extern void get_ring_color(int *red, int *green, int *blue) NATIVE(110);

Writes the RGB colour (0 to 255) of the element of the equipped magic ring into three out parameters.

Original name: _GET_RING_COLOR.

play_motion

extern void play_motion(string motion_name, OPTIONAL(float speed, enum motion_flags flags, string chara_name)) NATIVE(130);

Plays a motion on the character and its linked model parts. speed above 0 sets the playback step (-1 keeps the motion's own). flags: 1 pause, 2 stop on the last frame instead of looping, 4 restart from the first frame without blending. chara_name starts from that linked part instead.

Original name: _SET_MOS.

is_motion_done

extern void is_motion_done(void *is_done, OPTIONAL(string chara_name)) NATIVE(131);

Writes 1.0 into a float out parameter when the current motion has reached its last frame (or none is set), otherwise 0.0. chara_name checks that linked model part instead.

Original name: _CHECK_MOS_END.

get_motion_progress

extern void get_motion_progress(float *progress, OPTIONAL(string chara_name)) NATIVE(132);

Writes how far the current motion has played into a float out parameter, from 0.0 at the start to 1.0 at the end (0.0 while blending in). chara_name reads that linked model part instead.

Original name: _NOW_MOS_WAIT.

get_motion_status

extern void get_motion_status(int *status, OPTIONAL(string chara_name)) NATIVE(133);

Writes the motion state into the out parameter: 0 none, 1 on its first frame, 2 playing, 3 blending in, 4 reached the end. chara_name reads that linked model part instead.

Original name: _GET_MOS_STATUS.

set_motion_blend_speed

extern void set_motion_blend_speed(float speed) NATIVE(134);

Sets how much the blend into the next motion advances each frame; 1.0 or more makes it switch at once.

Original name: _SET_XCHG_STEP.

set_motion_speed

extern void set_motion_speed(float step) NATIVE(135);

Sets the playback step of the character's current motion, in frames per update.

Original name: _SET_MOS_STEP.

advance_motion_sequence

extern void advance_motion_sequence(void) NATIVE(136);

Tells the character's motion sequence to move on to its next step.

Original name: _TRG_ON_MOS.

reset_motion

extern void reset_motion(void) NATIVE(137);

Clears the current and pending motions of the character and its linked model parts.

Original name: _RESET_MOS.

set_default_motion

extern void set_default_motion(string motion_name) NATIVE(138);

Sets the motion the character returns to by default, such as its standing motion.

Original name: _SET_DEFAULT_MOS.

get_motion_blend

extern float get_motion_blend(void) NATIVE(139);

Returns, as a float, the progress of the blend into the new motion, or -1.0 when not blending.

Original name: _NOW_MOS_CHGWAIT.

apply_slow_status

extern void apply_slow_status(void) NATIVE(140);

If the active character has the slow status, sets the current motion to play at 70% of its default speed.

Original name: _SET_NEBA2.

create_effect

extern void create_effect(string effect_name, OPTIONAL(int *effect_id)) NATIVE(150);

Starts the named effect script on the character. With the out parameter it writes the new effect's slot id, used by the other effect natives; it fails if no slot is free.

Original name: _ESM_CREATE.

set_effect_vec1

extern void set_effect_vec1(int effect_id, float x, float y, float z) NATIVE(151);

Sets the first vector of an effect, usually its position. effect_id -1 means the most recently created effect.

Original name: _ESM_SET_VECT1.

set_effect_vec2

extern void set_effect_vec2(int effect_id, float x, float y, float z) NATIVE(152);

Sets the second vector of an effect, such as its direction or scale. effect_id -1 means the most recently created effect.

Original name: _ESM_SET_VECT2.

finish_effect

extern void finish_effect(int effect_id) NATIVE(153);

Switches an effect to its finishing program (300) so it can end on its own.

Original name: _ESM_FINISH.

delete_effect

extern void delete_effect(int effect_id) NATIVE(154);

Removes an effect immediately.

Original name: _ESM_DELETE.

VM_ARGS

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

Sets numbered value index of an effect to an int or float. effect_id -1 means the most recently created effect.

Original name: _ESM_SET_VALUE.

VM_ARGS

extern void _EXT_6 VM_ARGS(...) NATIVE(6);

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

VM_ARGS

extern void _EXT_7 VM_ARGS(...) NATIVE(7);

VM_ARGS

extern void _EXT_13 VM_ARGS(...) NATIVE(13);

VM_ARGS

extern void _EXT_14 VM_ARGS(...) NATIVE(14);

VM_ARGS

extern void _EXT_44 VM_ARGS(...) NATIVE(44);

VM_ARGS

extern void _EXT_80 VM_ARGS(...) NATIVE(80);

Helpers

Inline helper functions that wrap common sequences of native calls.

Helper What it does
advance_combo Stores the next combo step, clears the attack press history and sets menace level 0 for 3 frames, as each hit of a combo does when it starts.
start_combo_hit Starts the next hit of a sword combo: plays its motion once from the first frame, turns toward a target within reach, stores the combo step, clears the attack press history and sets menace.
play_motion_once Plays a motion once at its own speed, from its first frame without blending, stopping on its last frame (flags 4 | 2).
add_blade_trail Schedules a sword trail in slot 0 between the blade frames "dcol00" and "dcol01" with length 77, while the motion plays between start_ratio and end_ratio.

advance_combo

Stores the next combo step, clears the attack press history and sets menace level 0 for 3 frames, as each hit of a combo does when it starts.

static inline void advance_combo(int step)
{
    set_saved_value(step);
    reset_attack_presses();
    set_menace(MENACE_MELEE, 3);
}

start_combo_hit

Starts the next hit of a sword combo: plays its motion once from the first frame, turns toward a target within reach, stores the combo step, clears the attack press history and sets menace.

static inline void start_combo_hit(string motion, int step)
{
    play_motion(motion, -1, CHARA_MOTION_RESTART | CHARA_MOTION_HOLD);
    turn_to_target(2.0 * 20.0, 2.0);
    set_saved_value(step);
    reset_attack_presses();
    set_menace(MENACE_MELEE, 3);
}

play_motion_once

Plays a motion once at its own speed, from its first frame without blending, stopping on its last frame (flags 4 | 2).

static inline void play_motion_once(string motion)
{
    play_motion(motion, -1, CHARA_MOTION_RESTART | CHARA_MOTION_HOLD);
}

add_blade_trail

Schedules a sword trail in slot 0 between the blade frames "dcol00" and "dcol01" with length 77, while the motion plays between start_ratio and end_ratio.

static inline void add_blade_trail(string motion_name, float start_ratio, float end_ratio, int hold_frames, int fade_frames)
{
    add_sword_trail(0, motion_name, start_ratio, end_ratio, "dcol00", "dcol01", 77, hold_frames, fade_frames);
}

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
init 100 Runs once when the character's action script is set up (actionchara.cpp CActionChara::InitScript, ACTION_PROG_INIT), before 200 takes over.
reset 150 Runs when the character is put back into its normal state (actionchara.cpp CActionChara::ResetAction, ACTION_PROG_RESET, also reached from the event native that resets a character), before 200 takes over.
update 200 Normal control loop: resumed every frame and restarted whenever the running program ends (actionchara.cpp CActionChara::RunScript, ACTION_PROG_MAIN).
damage 500 Runs when a hit asks for a small damage reaction (actionchara.cpp ACTION_DAMAGE_REQ_SMALL, ACTION_PROG_DAMAGE_SMALL).
stopped 550 Runs when the character is frozen by the stop status, from a hit with that reaction or from the menu while the status is set (actionchara.cpp SetHold and ACTION_DAMAGE_REQ_HOLD, status bits 0x8/0x20); retail bodies hold the damage pose until it clears.
knockdown 600 Runs when a hit asks for a large damage reaction (actionchara.cpp ACTION_DAMAGE_REQ_LARGE, ACTION_PROG_DAMAGE_LARGE); retail bodies blow the character away and get up.
blocked 700 Runs after the character's melee hit is guarded by a monster or deals no damage (monster.cpp sets melee_hit, actionchara.cpp switches to 700); retail bodies play the after-guard recoil motion.
death 1400 Runs when the character's HP reaches zero (actionchara.cpp ACTION_DAMAGE_REQ_DEAD, ACTION_PROG_DEAD), which also queues dungeon event 1200.
land 1500 Runs when Max or Monica lands hard after falling at 3.5 units per frame or faster (actionchara.cpp ACTION_PROG_LAND).

Constants

Name Value What it is
PI 3.1415927

enum charge_effect_mode

Charge effect modes of _SET_ACCUME_FLAG: 0 stops it and clears the hold counter, 1 starts it.

Name Value
CHARGE_EFFECT_OFF 0
CHARGE_EFFECT_START 1

enum equip_slot

Equipment slots of a character (userdata.hpp CHARA_DATA::equip); 0 and 1 are the two weapons, 2 the hat model.

Name Value
EQUIP_MAIN_WEAPON 0
EQUIP_SUB_WEAPON 1
EQUIP_HAT 2
EQUIP_SHOES 3
EQUIP_BODY 4

enum menace_level

Murderous mode that picks which escape rate the target monster rolls (escape_rate0 for melee, escape_rate1 for shots).

Name Value
MENACE_MELEE 0
MENACE_SHOT 1

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

enum pad_button

Logical button numbers of CPadControl (padcontrol.hpp PadCtrlButton, bindings from mainloop.cpp pad_table).

Name Value
PAD_BTN_CONFIRM 0
PAD_BTN_CANCEL 1
PAD_BTN_R1_HELD 2
PAD_BTN_L1_HELD 3
PAD_BTN_L2 4
PAD_BTN_MENU 5
PAD_BTN_RIGHT 9
PAD_BTN_LEFT 10
PAD_BTN_START 15
PAD_BTN_PAUSE 21
PAD_BTN_EVENT_SKIP 22
PAD_BTN_QUICK_CHANGE 23
PAD_BTN_ACTION_CONFIRM 50
PAD_BTN_ACTION_SQUARE 51
PAD_BTN_ACTION_CANCEL 52
PAD_BTN_ACTION_L1_HELD 53
PAD_BTN_ACTION_R1_HELD 54
PAD_BTN_ACTION_SELECT 55
PAD_BTN_ACTION_HELD 56

enum pause_flags

Dungeon battle-area pause bits (scenesnd.hpp DNG_PAUSE_*), each stopping one dungeon system while set.

Name Value
DNG_PAUSE_MONSTER_AI 1
DNG_PAUSE_PLAYER_STEP 2
DNG_PAUSE_PLAYER_CONTROL 4
DNG_PAUSE_MONSTER_DRAW 16
DNG_PAUSE_SKY_DRAW 32
DNG_PAUSE_MAP_DRAW 128
DNG_PAUSE_MINIMAP 256
DNG_PAUSE_PICKUPS 512
DNG_PAUSE_PLAYER_STATUS 1024
DNG_PAUSE_EXIT_HEAL 2048
DNG_PAUSE_ENEMY_STEP 4096
DNG_PAUSE_WEAPON_DRAW 8192
DNG_PAUSE_BATTLE_MUSIC 16384
DNG_PAUSE_PAD_RESET 32768
DNG_PAUSE_MONSTER_NAMES 65536

enum se_bank

Sound bank selector of _SE_PLAY and _SE_LOOP_PLAY; only -1, the character's own bank, plays.

Name Value
SE_BANK_OWN -1