Scripts

Script Triggers

Scripts are organized by triggers, which describes how to execute functions.

specific: [trigger,subject]
category: [trigger,_category]
global: [trigger,_]

op: Operable within 1 tile, requires line of walk, restricted to cardinal directions.
ap: Approachable within 10 tiles, requires line of sight.

Name	Description	Subject	Allows Parameters	Allows Returns	Allow Global	Allow Category
proc	Routine to call and return from	Name	Yes	Yes	No	No
label	Routine to jump to	Name	Yes	No	No	No
debugproc	Player cheat handler	Name	Yes	No	No	No
apnpc1-5	Using npc option 1-5 from AP distance	NPC type	No	No	Yes	Yes
apnpcu	Using obj on npc from AP distance	NPC type	No	No	Yes	Yes
apnpct	Casting spell (targeting) on npc from AP distance	Component	No	No	No	No
opnpc1-5	Using npc option 1-5 from OP distance	NPC type	No	No	Yes	Yes
opnpcu	Using obj on npc from OP distance	NPC type	No	No	Yes	Yes
opnpct	Casting spell (targeting) on npc from OP distance	Component	No	No	No	No
ai_apnpc1-5	NPC using npc option 1-5 from AP distance	NPC type	No	No	Yes	Yes
ai_opnpc1-5	NPC using npc option 1-5 from OP distance	NPC type	No	No	Yes	Yes
apobj1-5	Using obj option 1-5 from AP distance	Object type	No	No	Yes	Yes
apobju	Using obj on obj from AP distance	Object type	No	No	Yes	Yes
apobjt	Casting spell (targeting) on obj from AP distance	Component	No	No	No	No
opobj1-5	Using obj option 1-5 from OP distance	Object type	No	No	Yes	Yes
opobju	Using obj on obj from OP distance	Object type	No	No	Yes	Yes
opobjt	Casting spell (targeting) on obj from OP distance	Component	No	No	No	No
ai_apobj1-5	NPC using obj option 1-5 from AP distance	Object type	No	No	Yes	Yes
ai_opobj1-5	NPC using obj option 1-5 from OP distance	Object type	No	No	Yes	Yes
aploc1-5	Using loc option 1-5 from AP distance	Location type	No	No	Yes	Yes
aplocu	Using obj on loc from AP distance	Location type	No	No	Yes	Yes
aploct	Casting spell (targeting) on loc from AP distance	Component	No	No	No	No
oploc1-5	Using loc option 1-5 from OP distance	Location type	No	No	Yes	Yes
oplocu	Using obj on loc from OP distance	Location type	No	No	Yes	Yes
oploct	Casting spell (targeting) on loc from OP distance	Component	No	No	No	No
ai_aploc1-5	NPC using loc option 1-5 from AP distance	Location type	No	No	Yes	Yes
ai_oploc1-5	NPC using loc option 1-5 from OP distance	Location type	No	No	Yes	Yes
applayer1-5	Using player option 1-5 from AP distance	Player type	No	No	Yes	Yes
applayeru	Using obj on player from AP distance	Player type	No	No	Yes	Yes
applayert	Casting spell (targeting) on player from AP distance	Component	No	No	No	No
opplayer1-5	Using player option 1-5 from OP distance	Player type	No	No	Yes	Yes
opplayeru	Using obj on player from OP distance	Player type	No	No	Yes	Yes
opplayert	Casting spell (targeting) on player from OP distance	Component	No	No	No	No
ai_applayer1-5	NPC using player option 1-5 from AP distance	Player type	No	No	Yes	Yes
ai_opplayer1-5	NPC using player option 1-5 from OP distance	Player type	No	No	Yes	Yes
weakqueue	Weakqueued script	Name	Yes	No	No	No
queue	Queued script	Name	Yes	No	No	No
ai_queue1-20	NPC queued script	NPC type	int only	No	Yes	Yes
softtimer	Soft timer	Name	Yes	No	No	No
timer	Timer	Name	Yes	No	No	No
ai_timer	NPC timer	NPC type	No	No	Yes	Yes
opheld1-5	Using obj option 1-5 from inv	Object type	No	No	Yes	Yes
opheldu	Using obj on obj from inv	Object type	No	No	Yes	Yes
opheldt	Casting spell (targeting) on obj from player inv	Component	No	No	No	No
if_button	Button pressed	Component	No	No	No	No
inv_button1-5	Using inv option 1-5 from inv	Component	No	No	Yes	Yes
inv_buttond	Dragging inv item to new slot	Component	No	No	Yes	Yes
if_close	On Close	Component	No	No	No	No
login	On Login	None	No	No	Yes	No
logout (add)	On Loguot Request	None	No	No	Yes	No
mapenter (remove)	On Map Region Enter	None	No	No	Yes	No
move (add)	On Move	None	No	No	Yes	No
movecheck (add)	On Pre Move	Name	No	No	No	No
ai_movecheck (add)	On Pre Move for NPCs	Name	No	No	No	No
levelup	On Stat Change	Stat	No	No	Yes	No

proc

A basic trigger type, this is used for defining functions that contain shared logic you want to reuse.
You can call these triggers using ~name or gosub(name). It will execute and return to the same place it was called from.

label

Another basic trigger type, this is used for functions that take over the program's control flow.
You jump to these triggers using @name or jump(name). The program continues executing from the label and does not return to the original calling location.

debugproc

apnpc1-5

apnpcu

apnpct

opnpc1-5

opnpcu

opnpct

Syntax

Types

Name	Description	Example
int
boolean
string
loc
npc
obj
coord
namedobj
player_uid
npc_uid
stat
component
interface
inv
enum
struct
param
dbtable
dbrow
dbcolumn
varp
mesanim

def_type: Define a local variable of type.

Comparators

! - not equal
= - equal
< - less than
> - greater than

if ($var = 1) {
    // do something
}

// equivalent to $var = -1 on ints
if ($var = null) {
    // do something
}

Math

def_int $i = 0;

// incrementing:
$i = calc($i + 1);

// multiplying:
$i = calc($i * 2);

// fractionally scaling (floors):
$i = scale(3, 2, $i); // 1.5x
$i = scale(60, 100, $i); // 0.6x

String Interop

<...> is used to escape a variable name in a string. It only accepts strings, so other types must be converted to strings to use it.

def_string $var1 = "1":
def_int $var2 = 2;
def_string $str = "<var1> <tostring(var2)>";

Concepts

Delays

Queues

Strong-queued Scripts

Weak Queues

Timers

Soft Timers

TODO: Explain what "soft" means

Protected

TODO: Explain commands prefixed with p_, and why this exists

Active

TODO: Explain commands prefixed with obj_, npc_, loc_, and the . verion of commands

Table of Commands

These can be found in their signature format as data/src/scripts/engine.rs2.

Server

Name	Description	Example
map_clock	# of ticks the world has been up	if (%skill_clock < map_clock) {}
map_members	Returns if the player is inside a members of free to play world	if (map_members = true) {}
map_playercount	Returns the current number of players between two coords	def_int $count = map_playercount($coord1, $coord2);
huntall
huntnext
inarea
inzone
lineofwalk	Returns if the player has line of walk to a coord	def_boolean $west = lineofwalk(coord, movecoord(coord, -1, 0, 0));
objectverify	Returns if the input obj and last verify obj are the same or not	if (objectverify($item, last_verifyobj) = false) {}
stat_random	Interpolates a stat success chance. Used for gathering skills	if (stat_random(stat(cooking), $low, $high) = true) {}
spotanim_map	Plays a spot anim directly on the world. Imps use this when they teleport	spotanim_map(spotanim_111, coord, 100, 0);
distance	Returns the number of tiles distance between two coords	def_int $distance = distance($coord1, $coord2);
movecoord	Move an input coord with input offsets	def_coord $coord = movecoord(coord, -1, 0, 0);
seqlength	Returns the length of a sequence in the number of client ticks	def_int $client_ticks = seqlength(emote_dance);
split_init
split_pagecount
split_get
split_linecount
split_getanim
struct_param
coordx	Extract the X component from a coord	def_int $x = coordx($coord);
coordy	Extract the level component from a coord	def_int $level = coordy($coord);
coordz	Extract the Z component from a coord	def_int $z = coordz($coord);
playercount	Returns the current number of players in the world	def_int $count = playercount;
map_blocked	Returns if a specified coord is walk blocked	def_boolean $blocked = map_blocked;

Player

Name	Description	Example
finduid
p_finduid
strongqueue	Enqueue a script into the queue with type=strong	strongqueue(finish_bury, 1);
weakqueue	Enqueue a script into the weak queue	weakqueue(start_smelting_ore, calc(%skill_clock - map_clock - 1), $struct);
anim	Play an animation on the active player	anim(human_cooking, 0);
buffer_full	Mostly used for when text is being transmitted to an if so that the text can be broken up a bit rather than being transmitted all at once.	if (buffer_full = true) p_delay(0);
buildappearance	Build the player appearance from a specified inv	buildappearance(worn);
cam_lookat
cam_moveto
cam_reset
coord	Get the active player's coord	def_coord $coord = coord;
displayname
facesquare	Make the player face a specified coord	facesquare(npc_coord);
healenergy
if_close		if_close;
last_com
last_int	Returns the numerical input entered by a p_countdialog; command	def_int $input = last_int;
last_item
last_slot
last_useitem
last_useslot
last_verifyobj
mes	Say a chat box message	mes("Welcome to RuneScape.");
name	Get the active player's name
p_aprange	Set the range for approachable ops to become triggered	p_aprange(2);
p_arrivedelay	Make the player wait until they reach the correct distance before interacting
p_countdialog	Opens the input X chat dialogue to enter a numerical input	p_countdialog;
p_delay	Set a delay on the active player, starting at `World.currentTick + n`. "0" will produce a 1-tick delay	p_delay(0);
p_opheld	Set the current interaction to opheld(x) for the next tick
p_oploc	Set the current interaction to oploc(x) for the next tick
p_opnpc	Set the current interaction to opnpc(x) for the next tick
p_pausebutton
p_stopaction
p_telejump	Teleport and jump the player to a specified jagex coord. Does not use walk animations	p_telejump(1_41_51_41_57);
p_walk	Walk the player somewhere with full pathfinding support	p_walk(movecoord(coord, 0, 0, 1));
say	Make the player force say something
sound_synth	Play a synth to the player	sound_synth(found_gem, 0, 0);
staffmodlevel	Checks the staff level of the player	0, 1, 2
stat	Return the player stat you want	def_stat $cooking = stat(cooking);
stat_base	Return the base stat level of the player you want	def_int $level = stat_base(magic);
stat_heal
uid	Gets the current player UID in the world
p_logout	Logout the player from the world
if_setcolour	Change the color of an if child	if_setcolour($component, 0x07E0);
if_openchat		if_openchat(levelup_magic);
if_openmodalsideoverlay		if_openmodalsideoverlay(bank, bank_deposit);
if_sethide		if_sethide(crafting_jewelry:amulets_layer, false);
if_setobject		if_setobject(crafting_jewelry:rings1, sapphire_ring, 105);
if_settabactive
if_setmodel
if_setmodelcolour
if_settabflash
if_closesub
if_setanim		if_setanim(player_line1:com_0, split_getanim($page));
if_settab		if_settab(inventory, 3);
if_openmainmodal		if_openmainmodal(xplamp);
if_openchatsticky
if_opensideoverlay
if_setplayerhead		if_setplayerhead(player_line1:com_0);
if_settext		if_settext(quest_complete:com_3, $questmessage);
if_setnpchead		if_setnpchead(npc_line1:com_0, npc_type);
if_setposition
if_multizone
givexp	Give experience in a specified stat to the player	givexp(cooking, 3000);
damage
if_setresumebuttons
text_gender
midi_song	Play a song to the player
midi_jingle	Play a single to the player	midi_jingle(^treasure_hunt_win_jingle, ^treasure_hunt_win_jingle_millis);
last_inv
hintcoord
cam_shake
softtimer
cleartimer
stat_add
stat_sub
spotanim_pl
hint_stop
if_closesticky
inv_clear	Completely clear an inv of objs
p_exactmove	Force walk the player somewhere	p_exactmove(0_49_51_61_13, 0_49_51_61_12, 30, 64, ^exact_west);
queue
busy	Checks if the player has open interfaces and is currently delayed	if (busy = true) {}
getqueue
getweakqueue
p_locmerge	Merge the player with a loc. Mostly used for Agility	p_locmerge(30, 64, 0_49_51_61_12, 0_49_51_61_13);
last_login_info	Sends the last login information to the player containing the last ip their account was logged in from.	last_login_info;
p_teleport	Teleport the player to a specified jagex coord. Enables walk animation if the distance is short enough	p_teleport(movecoord(coord, 0, 0, 1));
bas_readyanim	Set the player bas readyanim (standing) seq. Use buildappearance; after setting bas seqs	bas_readyanim(human_ready);
bas_turnonspot	Set the player bas turnonspot (turning) seq. Use buildappearance; after setting bas seqs	bas_turnonspot(human_turnonspot);
bas_walk_f	Set the player bas walk_f (walking forward) seq. Use buildappearance; after setting bas seqs	bas_walk_f(human_walk_f);
bas_walk_b	Set the player bas walk_b (walking backward) seq. Use buildappearance; after setting bas seqs	bas_walk_b(human_walk_b);
bas_walk_l	Set the player bas walk_l (walking left) seq. Use buildappearance; after setting bas seqs	bas_walk_l(human_walk_l);
bas_walk_r	Set the player bas walk_r (walking right) seq. Use buildappearance; after setting bas seqs	bas_walk_r(human_walk_r);
bas_running	Set the player bas running (running) seq. Use buildappearance; after setting bas seqs	bas_running(human_running);
gender	Get the gender id of the player	def_int $gender = gender;

Npc

Name	Description	Example
npc_finduid
npc_add	Add an npc to a specified coord	npc_add($coord, npc_494, 0);
npc_anim	Make an npc play a seq	npc_anim(seq_401, 0);
npc_basestat
npc_category	Returns the category of an npc	if (npc_category = bank_teller) {}
npc_coord	Returns the coord of an npc	def_coord $coord = npc_coord;
npc_del	Delete an npc from the world	if (npc_type = restless_ghost) npc_del;
npc_delay	Delay an npc	npc_delay(2);
npc_facesquare	Make an npc face a coord	npc_facesquare(coord);
npc_findexact
npc_findhero	Returns who killed this npc
npc_param	Returns an npc param	%shop_sell = npc_param(shop_sell_multiplier);
npc_queue
npc_range	Returns the distance of an npc from a coord	if (npc_range(coord) > 1) {}
npc_say	Make an npc force say something	npc_say("Quack!");
npc_sethunt
npc_sethuntmode
npc_setmode
npc_stat
npc_statheal
npc_type	Returns the config type for an npc	if (npc_type = doric) {}
npc_damage
npc_name	Returns the name of an npc	if (npc_name = "Doric") {}
npc_uid
npc_settimer
spotanim_npc
npc_findallzone	Finds all npcs within the zone of a jagex coord	npc_findallzone(coord);
npc_findnext	Iterates through the found npcs within the zone of a jagex coord	while (npc_findnext = true) {}
npc_tele	Teleport an npc to a specified jagex coord	npc_tele(movecoord($coord, 0, 0, 2));
npc_changetype	Change an npc into another npc	npc_changetype(ernest_human);

Loc

Name	Description	Example
loc_add	Add a loc to a specified coord	loc_add(0_45_153_8_38, loc_1546, 3, loc_shape, 2);
loc_angle	Returns the angle of a loc	def_int $angle = loc_angle;
loc_anim	Make a loc play a seq	loc_anim(spinningwheel);
loc_category	Returns the category of a loc	if (loc_category = taverly_dungeon_prison_door) {}
loc_change
loc_coord	Returns the coord of a loc	def_coord $coord = loc_coord;
loc_del	Deletes a loc from the world	loc_del;
loc_find	Returns if a loc at a coord is found or not	if (loc_find(coord, loc_type) = true) {}
loc_findallzone	Finds all locs within the zone of a jagex coord	loc_findallzone(coord);
loc_findnext	Iterates through the found locs within the zone of a jagex coord	while (loc_findnext = true) {}
loc_param	Returns a param of a loc	def_int $is_empty = loc_param(mining_rock_empty);
loc_type	Returns the config type for a loc	if (loc_type = loc_818) {}
loc_name	Returns the name of a loc	if (loc_name = "Magic Tree") {}
loc_shape	Returns the shape of a loc	if (loc_shape = centrepiece_straight) {}

Obj

Name	Description	Example
obj_add	Add an obj to a specified coord	obj_add(coord, needle, 1, 200);
obj_addall
obj_param	Returns a param of an obj
obj_name	Returns the name of an obj	if (obj_name = "Coins") {}
obj_del	Deletes an obj from the world	obj_del;
obj_count		def_int $count = obj_count;
obj_type	Returns the config type for an obj	if (obj_type = coins) {}
obj_takeitem	Move an obj from the floor to a specified inventory	obj_takeitem(inv);

Npc config

Name	Description	Example
nc_name	Returns the name of an npc	if (nc_name(doric) = "Doric") {}
nc_param	Returns a param of an npc
nc_category	Returns a category of an npc	if (nc_category(npc_494) = bank_teller) {}
nc_desc	Returns the description of an npc	def_string $desc = nc_desc(hans);
nc_debugname	Returns the leaked debug name of an npc	def_string $debugname = nc_debugname(hans);

Loc config

Name	Description	Example
lc_name	Returns the name of a loc	if (lc_name(magic_tree) = "Magic Tree") {}
lc_param	Returns a param of a loc
lc_category	Returns a category of a loc	if (lc_category(loc_2143) = taverly_dungeon_prison_door) {}
lc_desc	Returns the description of a loc	def_string $desc = lc_desc(magic_tree);
lc_debugname	Returns the leaked debug name of a loc	def_string $debugname = lc_debugname(magic_tree);

Obj config

Name	Description	Example
oc_name	Returns the name of an obj	if (oc_name(coins) = "Coins") {}
oc_param	Returns a param of an obj	def_coord $coord = oc_param($clue, trail_coord);
oc_category	Returns a category of an obj	if (oc_category($clue) = trail_clue_easy) {}
oc_desc	Returns the description of an obj	def_string $desc = oc_desc(coins);
oc_members	Returns if an obj is members or not	if (oc_members($chocolate) = true) {}
oc_weight	Returns the weight of an obj	def_int $weight = oc_weight(coins);
oc_wearpos	Returns the primary slot of an obj
oc_wearpos2	Returns the secondary override slot of an obj
oc_wearpos3	Returns the secondary override 2 slot of an obj
oc_debugname	Returns the leaked debug name of an obj	def_string $debugname = oc_debugname(coins);
oc_cert	Returns the cert of an obj	def_obj $cert_logs = oc_cert(logs);
oc_uncert	Returns the uncert of an obj	def_obj $logs = oc_uncert(cert_logs);
oc_stackable	Returns if an obj is stackable or not	def_boolean $stackable = oc_stackable(coins);

Inventory

Name	Description	Example
inv_add	Add an obj to an inv. Any overflow is placed on the ground	inv_add(bank, coins, ^max_32bit_int);
inv_changeslot
inv_del	Delete an obj from an inv	inv_del(inv, coins, 10);
inv_getobj	Return an obj from an inv	def_obj $amulet = inv_getobj(worn, 2);
inv_itemspace2	Returns an overflow for adding an obj to an inv	def_int $overflow = inv_itemspace2($inv, $cert_or_uncert, $amount, inv_size($inv));
inv_moveitem	Moves an obj from one inv to another inv	inv_moveitem(bank, $inv, $obj, sub($amount, $overflow));
inv_resendslot	Refreshes an inv from the input slot to the inv capacity	inv_resendslot(bank, 0);
inv_setslot	Sets the slot of an inv with an obj	inv_setslot(crafting_rings, 3, null, 0);
inv_size	Returns the capacity of an inv	inv_size(bank);
inv_total	Returns the total amount of an obj in an inv	if (inv_total(inv, coins) < 10) {}
inv_transmit	Transmits an inv to another inv	inv_transmit(inv, bank_deposit:inv);
inv_stoptransmit	Stops transmits of an inv to another inv	inv_stoptransmit(inv, shop_sell:inv);
inv_itemspace	Returns if there is overflow or not for adding an obj to an inv	if (inv_itemspace(inv, $slotobj, inv_total(reward_inv, $slotobj), inv_freespace(inv)) = true) {}
inv_freespace	Returns if there is any free space in an inv	if (inv_freespace(inv) = 0) {}
inv_allstock	Returns if an inv is an allstock. Used for shop type invs	if (inv_allstock = false) {}
inv_exists	Returns if an obj exists in an inv	def_boolean $exists = inv_exists(inv, coins);
inv_getnum	Returns the number of an obj in an inv	def_int $slot_count = inv_getnum(bank, $count);
inv_moveitem_cert	Moves an obj from one inv to another inv forcing cert	inv_moveitem_cert(bank, $inv, $obj, sub($amount, $overflow));
inv_moveitem_uncert	Moves an obj from one inv to another inv forcing uncert	inv_moveitem_uncert($inv, bank, $obj, sub($amount, $overflow));
inv_movetoslot	Moves an obj from one inv to another inv. Does a direct swap if the destination slot is occupied.	inv_movetoslot(inv, worn, $from_slot, to_slot);
inv_movefromslot	Moves an obj from one inv to another inv. Adds to the destination inv at the next available slot. Adds overflow objs to the ground similar to inv_add.	inv_movefromslot(reward_inv, inv, $from_slot);
inv_delslot	Delete a number of obj from a specified slot in an inv	inv_delslot(worn, ^wearpos_quiver);
inv_dropslot	Drop a specified slot from an inventory to the floor with a specified count	inv_dropslot(inv, coord, last_slot, 200);
inv_dropitem	Drop an obj from an inventory to the floor with a specified count	inv_dropitem(inv, coord, coins, $count, 200);
both_moveinv

Enum

Name	Description	Example
enum
enum_getoutputcount

String

Name	Description	Example
append_num
append
append_signnum
lowercase
tostring
compare
append_char
string_length
substring
string_indexof_char
string_indexof_string
uppercase

Number

Name	Description	Example
add
sub
multiply
divide
random
randominc
interpolate
setbit
testbit
modulo
pow
invpow
and
or
max
min
scale
bitcount
togglebit
setbit_range
clearbit_range
getbit_range
setbit_range_toint
sin_deg
cos_deg
atan2_deg
abs

DB

Name	Description	Example
db_find_with_count
db_findnext
db_getfield
db_getfieldcount
db_listall_with_count
db_getrowtable
db_findbyindex
db_find_refine_with_count
db_find
db_find_refine
db_listall

Debug

Name	Description	Example
error
active_npc
.active_npc
active_player
.active_player
active_loc
.active_loc
active_obj
.active_obj