# Declarations

plotscript, name, argumentnames (statements)
plotscript
The plotscript command contains a list of commands that can be triggered directly by an event in your game. Plotscript starts with the keyword plotscript, a comma, and then the name of the plotscript. If there are any arguments to the script, you list their names separated by commas after the name of the script, optionally with default values declared like arg = defaultvalue. Then comes the text of the script. It is enclosed in begin and end statements. Scripts that are defined as plotscripts can be called directly from "trigger" events in your game, or by name within other scripts.

What's the difference between

plotscript

and script? The only difference is that plotscripts are listed in the game editor, allowing them to be attached to triggers (such as the new-game script), while plain scripts are hidden and can't be selected. (Technically you can use a script as a trigger, but only by using a command like setdeathscript.)
# example of a simple script plotscript,my first script,begin # commands go here end
# example of a script with arguments # (It can called with between 1 and 3 arguments.) plotscript,my fancy script,fe,fi=0,fo=0,begin # commands go here, # and they can use the aruments fe, fi, and fo # that where passed to the script end
script, name, argumentnames (statements)
script
The script command contains a list of commands. Script starts with the keyword script, a comma, and then the name of the script. If there are any arguments to the script, you list their names separated by commas after the name of the script with optional default values. Then comes the text of the script. It is enclosed in begin and end statements. Scripts that are defined as script cannot be called directly from events in your game. They can only be called by name within other scripts. To make a script that can be run directly from your game, use plotscript.
# example of a simple script script,my first script,begin # commands go here end
# Example of a script with arguments # (It can called with between 1 and 3 arguments.) script,my fancy script,fe,fi=0,fo=0,begin # Commands go here, # and they can use the aruments fe, fi, and fo # that where passed to the script. end
subscript, name, argumentnames (statements)
subscript

subscript

is just like script except that it must placed inside another script (or even inside another subscript). See script for details of syntax of arguments. The difference from a regular script is that a subscript can only be called from its parent script (or some other subscript), and it can directly access its parent script's variables in addition to its own arguments and variables. Subscripts can be useful when you have some piece of repeated code that you want to "de-duplicate" by moving into another script which you can call repeatedly, but without having to turn local variables into global variables.
# Some nearby NPCs move into a line to the north of the hero plotscript, line up soldiers, begin show textbox(32) # "Yes sir!" wait for textbox suspend player set hero direction(me, up) variable (x, y) # The position of the start of the line x := hero X(me) -- 2 y := hero Y(me) -- 4 subscript, line up NPC, npc, begin # Increment X to get next position in the line x += 1 walk NPC to X(npc, x) wait for NPC(npc) walk NPC to Y(npc, y) wait for NPC(npc) set NPC direction(npc, down) end # NPCs move one at a time line up NPC(1) line up NPC(3) line up NPC(11) line up NPC(10) line up NPC(5) resume player end
global variable (id,name)
global variable
Creates a global variable that can be used in any script. The first argument to the global variable declaration is a unique ID number. The second argument is the name of the variable. The ID number for a global variable is a number from 0 to 16383. Each global variable must have a unique number, but this number will not conflict with the ID numbers you use for scripts. It is all right to have a script and a global variable with the same ID number. See also variable
# any script can read and set the value of a global global variable(1,mini game score)
variable (name)
variable
Creates a local variable that can only be used inside the script where it was created. The value of this variable is lost when the script ends. If you need a variable who's value persists between calls to a script, or that is automatically saved when the player saves their game, you will need to use a globalvariable instead.
variable(points) # make a new variable variable+=1 # add one to it
define constant (number,name)
define constant
Creates a global constant. The first argument is the number that the constant will represent, and the second argument is the name of the constant. Use constants to replace commonly used numbers with friendly names. The following are some general purpose constants have been defined for you (there are hundreds more intended for specific commands): zero one two three four five six seven eight nine ten false true off on north east south west up down left right me none
include, filename
include
The include command effectively inserts another text file into your script. It is followed by a single filename that tells what file will be included. This can be used to organise your scripts and other definitions like defineconstant into multiple files. The filename can include a path, for example

include, ..\utility scripts\math.hss

. You can optionally include quote marks around the filename, e.g.

include, "misc.hss"

, which causes normal string parsing (for example, allowing a # character in a filename). Previously every plotscript file had to start with

include, plotscr.hsd

but this is now optional.

plotscr.hsd

,

scancode.hsi

, and the exported

your game name.hsi

file are all automatically included.
include, cutscenes.hss # All scripts for cutscenes include, ..\utility scripts\math.hss # A few useful scripts shared between multiple games

# Math, Comparison, and Logic Operators

## Working with Variables

variable := value
:=
This command assigns a new value to a variable. If you do not specify the new value, the variable will be reset to zero. This command works exactly the same for global and local variables. The := operation actually returns

value

, so you can use it as an expression, for example in temp1 := (temp2 := 1).
increment (variable,amount)
increment
or

variable += amount

This command adds an amount to the current value of a variable. If you do not specify the amount, then the variable will be incremented by one. This command works exactly the same for global and local variables. The += operation actually returns the new value of

variable

, so you can use it as an expression, for example in while ((index += 1) < 10).
decrement (variable,amount)
decrement
or

variable -= amount

This command subtracts an amount from the current value of a variable. If you do not specify the amount, then the variable will be decremented by one. This command works exactly the same for global and local variables. The -= operation actually returns the new value of

variable

, so you can use it as an expression, for example in while (index -= 1).
read global (id)
read global
A function that returns the value of a global variable using its ID number instead of its name. Why would you want to do a silly thing like that? Because it allows you to simulate simple fake arrays, in the old C-pointer style.
writeglobal
write global (id,value)
write global
A function that writes a value into a global variable using its ID number instead of its name. Why would you want to do a silly thing like that? Because it allows you to simulate simple fake arrays, in the old C-pointer style
readglobal
number + number
add
Adds two values together and returns the result. This can also be written as

add(number,number)

number -- number
subtract
Subtracts the second number from the first number and returns the result. It is necessary to use the double minus so that HSPEAK.EXE can tell the difference between subtraction, and a minus sign that indicates a negative number. You can also write

subtract(number,number)

number * number
multiply
Multiplies two values together and returns the result. This can also be written as

multiply(number,number)

number / number
divide
Divides the second number into the first number and returns the result. The result is rounded down to an integer. This can also be written as

divide(number,number)

number,mod,number
mod
Divides the second number into the first number and returns the remainder. This can also be written as

modulus(number,number)

number ^ power
^
Raises a number to a power and returns the result. (If the result is too large and overflows no error occurs: the value is simply wrapped around a 32 bit signed integer.) This can also be written as

exponent(number,power)

abs (number)
abs
Returns the absolute value of a value. That is, negative values are made positive and others are unchanged: abs(-14) is 14, and abs(14) is 14.
sign (number)
sign
Returns -1 if

number

is negative, 0 if it is 0, and 1 if

number

is positive.
sqrt (number)
sqrt
Returns the squareroot of a number, rounded to the nearest integer.
number == number
==
Checks to see if the two numbers are equal. If they are equal it returns true, otherwise it returns false. This can also be written as

equal(number,number)

number <> number
<>
Checks to see if the two numbers are not equal. If they are not equal it returns true. If they are equal it returns false. This can also be written as

not equal(number,number)

number < number
<
Checks to see if the first number is less than the second number. If it is, it returns true, otherwise it returns false. This can also be written as

less than(number,number)

and as

number << number

number > number
>
Checks to see if the first number is greater than the second number. If it is, it returns true, otherwise it returns false. This can also be written as

greater than(number,number)

and as

number >> number

number <= number
<=
Checks to see if the first number is less than or equal to the second number. If it is, it returns true, otherwise it returns false. This can also be written as

less than or equal to(number,number)

number >= number
>=
Checks to see if the first number is greater than or equal to the second number. If it is, it returns true, otherwise it returns false. This can also be written as

greater than or equal to(number,number)

value,and,value
and
Returns the bitwise AND of both values. In other words, for each bit in each value, they are compared to see if they are both "1". If they are, the result bit is set to 1. Otherwise, it's set to 0.
logicaland
value,or,value
or
Returns the bitwise OR of both values. In other words, for each bit in each value, they are compared to see if either bit is "1". If one is, the result bit is set to 1. Otherwise, it's set to 0.
logicalor
value,xor,value
xor
Returns the bitwise AND of both values. In other words, for each bit in each value, they are compared to see if either (but not both!) bit is "1". If ONE is, the result bit is set to 1. Otherwise, it's set to 0.
logicalxor
value && value
&&
Returns true if both of the values are true (non-zero). If either of them is false, and returns false. This command uses shortcut evaluation: if the first argument is false, the second argument is never evaluated.
value || value
||
Returns true if at least one of the values are true (non-zero). Only if both of them are false does or return false. This command uses shortcut evaluation: if the first argument is true, the second argument is never evaluated.
value ^^ value
^^
Returns true if one, but not both of the values are true (non-zero). If both of them are true, or both of them are false, ^^ returns false.
not (value)
not
Returns the logical complement/negation of a value. That is, it returns true (1) if the value is false (0), or false (0) if the value is true (non-zero).
random (lownumber, highnumber)
random
Returns a random integer in the range of the two numbers. The returned value will be greater than or equal to the first number, and less than or equal to the second number
seed random (seed)
seedrandom
Reseeds the random number generator. If you pass in a

seed

(number) other than 0, the random number generator will be seeded with that number, allowing for repeatable random sequences - random will always return the same sequence of random numbers afterwards. Each seed causes a completely different sequence. If called with no argument (or

seed

= 0), this will reseed the random number generator to a new random sequence (which is useful only if you've previously called seed random(...) to put it into a predictable sequence.)

You don't need to call this command before using random. In fact, this command is useful only if you don't want completely random numbers.

random

# Flow Control

begin,other commands,end
begin
Begin is a synonym for ( and end is a synonym for ). Parentheses are normally used for bracketing things that all fit on the same line, and begin/end statements are often used to enclose very long things such as whole scripts or long flow control blocks that take up several lines. For example, the following two blocks of code are identical:
if (check tag(tag:have rusty sword)) then (show text box (5), wait for text box)
if (check tag(tag:have rusty sword)) then begin show text box (5) wait for text box end
begin
end
if(condition) then(commands) else(commands)
if
The

if

statement checks the value of its condition, and if the value is true (or actually any value other than false, which is zero), it runs the commands in the

then

block. If the value is false, it runs the commands in its

else

block. The conditional is usually a comparison operator such as equal or notequal, or a command which returns either true or false, such as checktag. The

else

is optional as long as you have a

then

, and the

then

is optional as long as you have an

else

. There are several examples of

if

statements in the HamsterSpeak Specification, and throughout this document. You can also place one or more elseifs after the

then

(or immediately after the

if

if you skip the

then

) instead of nesting multiple

if

statements.
elseif
... else if(condition) then(commands) ...
else if
This can appear after an if or then block. It is a shortcut for else followed by if which lets you omit a pairs of brackets/begin and end, as this example shows: if (inventory (item:apple)) then ( show text box (10) # "Apples! My favourite!" ) else if (inventory (item:orange)) then ( show text box (11) # "My, what a tasty looking orange..." ) else if (inventory (item:pear)) then ( show text box (12) # "Perhaps if you gave me that pear..." ) else ( show text box (13) # "Come back when you have something tasty for me!" )
if
then
if
else
while(condition) do(commands)
while
The while command checks the value of its condition, and if the value is true it runs the commands in the do block. It keeps checking the conditional and runs the do block over and over again until the conditional returns false. The conditional is usually an equality operator such as equal or notequal, or it is a check tag command.
do
do
Used to group several statements together. Normally appears after a while, for or switch. However,

do

blocks can actually appear by themselves. This is useful if you want to break out of them to skip to the end. (continue inside an orphan

do

block acts just like

break

.)
while
for
switch
for(counter,start,finish,step) do(commands)
for
The for command runs the commands in the do block a specified number of times. The first argument to for is the counter. It must be a variable. The next two arguments are the starting value and the finishing value. For example, if you use a start value of 1 and a finish value of 10 then the do block will run 10 times. The first time the do block runs, the counter will be 1, then it will be 2, then 3 and so on until it reaches 10, the finish value. The fourth argument of for is optional. It is the step by which the counter will change each loop. If you use a step of 2 then the counter will count 1,3,5,7,9. If you switch the start and finish values and use a step of -1 then the counter will go backwards. If you use 0 as the step, the counter will never change, so the do block will repeat forever. See return and puthero for examples.
return(value)
return

return

in HamsterSpeak is completely different from

return

in nearly all other programming languages! Sets the value to be returned by the script. This is only useful when the script has been called as a function from another script. It is irrelevant to scripts called directly from your RPG, for example, text box scripts or menu scripts. This command only matters when you are calling one script from another script. This command does NOT cause the script to terminate, it just sets the return value. If you never use the

return

command, the script will return zero. If return is used more than once in the same script, only the last one executed matters. script, key wait, ticks, begin # Returns true if a key was pressed during the wait, # or false (0) if the wait finished uninterrupted. # The wait duration is always the same. variable(i) for(i, 1, ticks) do, begin wait(1) if(key is pressed(key:ENTER)) then(return(true)) if(key is pressed(key:SPACE)) then(return(true)) if(key is pressed(key:CTRL)) then(return(true)) if(key is pressed(key:ALT)) then(return(true)) if(key is pressed(key:ESC)) then(return(true)) if(key is pressed(joy:button 1)) then(return(true)) if(key is pressed(joy:button 2)) then(return(true)) end end plotscript, usage example, begin show text box(5) # let all volunteers take one step forward! if(key wait(40)) then( walk hero(me, north, 1) wait for hero(me) show text box(6) # You there! I saw you move! You volunteer! )else( show text box(7) # a bunch of lily livered cowards, eh? ) end
exitreturning
exit returning(value)
exit returning
ubersetzung
Sets the value to be returned by the script, and exits the script. This is only useful when the script has been called as a function from another script. script, key wait, ticks, begin # Returns true if the wait was cancelled by a keypress. variable(i) for(i, 1, ticks) do, begin wait(1) if(key is pressed(key:ENTER)) then(exit returning(true)) if(key is pressed(key:SPACE)) then(exit returning(true)) if(key is pressed(key:CTRL)) then(exit returning(true)) if(key is pressed(key:ALT)) then(exit returning(true)) if(key is pressed(key:ESC)) then(exit returning(true)) if(key is pressed(joy:button 1)) then(exit returning(true)) if(key is pressed(joy:button 2)) then(exit returning(true)) end exit returning(false) end plotscript, usage example, begin show text box(5) # let all volunteers take one step forward! if(key wait(40)) then( walk hero(me, north, 1) wait for hero(me) show text box(6) # You there! I saw you move! You volunteer! )else( show text box(7) # a bunch of lily livered cowards, eh? ) end The

exit returning

command works exactly the same as the return command followed immediately by exitscript. Whether you decide to use return or

exit returning

to set your script's return value is often just a matter of style and taste.
return
exitscript
exit script
exit script
ubersetzung
Causes the script to end immediately
exitreturning
break
break
ubersetzung
Breaks out of a for or while loop or switch and continues the script after the end of the do block.
continue
continue
ubersetzung
When used inside the do block of a for or while command,

continue

skips the rest of the do block and continues on to the next loop. When used inside a switch statement, continue causes a jump to after the next case block.
switch(expression)
switch
ubersetzung
Select between a number of case blocks to execute based on the value of an expression. The switch command is an alternative to a big block of nested if/then/else commands that all check the same value. Switch can be easier to read than a lot of if's. Consider the follow script snippet: if (v == 0) then ( something ) else if (v == 1 || v == 2) then ( something else ) else if (v == 3 || v == 4) then ( yet another thing ) else if (v == 10) then ( #nothing happens here ) else ( something to do if none of the other ifs are true ) This is a good candidate for using switch. The example below shows how this can be done: switch(v) do( case(0) do( something ) case(1, 2) do( # A case can contain multiple values... something else ) case(3) case(4) do( # ...or you can use multiple cases after another yet another thing ) case(10) do() #nothing happens here else( something to do if none of the cases happen ) ) The

else

section is optional. There are two different styles (syntaxes) in which switch can be written. The second style looks like this (completely equivalent to the above example): switch(v) do( case(0) something case(1, 2) something else case(3) case(4) yet another thing case(10) do() #nothing happens here case(else) something to do if none of the cases happen ) Besides readability, there is one other important difference between using switch and using a sequence of if's. The switch command only checks the value of the expression (v) once. The if/then/else method checks v repeatedly, so it could be slower, and could be susceptible to errors if you accidentally change the value of v somewhere in the middle.
case(value)
case
ubersetzung
The case command is used to enclose a block of commands for one possible result of a switch command. See switch for more details.

# Wait Commands

Note that all of the wait commands wait for at least one tick, even if the thing they are waiting for is false (unless you call a command with invalid arguments, causing a script error instead). For example, "wait for textbox" waits for one tick even if there is no textbox.

If a battle occurs, a menu is entered (unless it 'Allows Scripts') or another script is triggered, your script will be paused until the other thing finishes. While paused, any wait commands don't continue checking. For example, wait stops counting down, and waitfornpc doesn't end if the NPC it's waiting for stops moving while a script is paused but then starts again before it the script resumes.

wait (ticks)
wait
Makes the script wait for the specified number of ticks. There are roughly 18 ticks to a second, but this can vary under some conditions. If you leave out the argument, it will wait for one tick.
show text box(2) # Show a text box wait(50) # Wait about 3 seconds advance text box # "hit spacebar"
wait for text box
wait for text box
Makes the script wait until there is no text box displaying on the screen. Useful to know when to move on after using a showtextbox command. wait for text box doesn't wait if suspendboxadvance has been used, because it's impossible for the player to advance the textbox!
show text box(2) # Show a text box wait for text box # wait until the player continues
wait for menu (menu handle)
wait for menu
Given a menuhandle, causes the script to wait until that menu has been closed.
wait for hero (who)
wait for hero
Waits for the specified hero stop walking. Use the constant me to refer to the leader, or use numbers 0,1,2,3 to refer to a specific hero. If you leave out the argument, the first hero will be assumed.
move hero to y (me, 10) # move hero to (x, 10) wait for hero (me) # wait until he stops
walkhero
pathfindheroto
wait for key (key)
wait for key
Waits for the player to press a key.

key

is an optional scancode such as a keyboard key (e.g. key:ctrl) a joystick button (e.g. joy:left), or a virtual scancode such as usekey. If you do not specify

key

, then anykey will be used, which waits for any keyboard or joystick button.

usekey

will wait for Space, Ctrl or Enter; and

cancelkey

and

menukey

(which are identical) both wait for Alt or Esc. If and only if anykey is used, then

waitforkey

will return the scancode of the keyboard or joystick key that was pressed, but won't ever be a constant like usekey.

Previously you couldn't use scancodes like key:x, and there was a separate waitforscancode command for those, but now you can use any scancode with wait for key, and use any of the codes like use key with other key commands like keyispressed.

show text box(623) # "press cancel!" wait for key(cancel key)
wait for scancode (key)
wait for scancode
ubersetzung
Identical to waitforkey.
wait for NPC (who)
wait for NPC
Waits for the specified NPC to stop walking. The argument is either an NPC reference, or an NPC ID (if more than one copy of that NPC exists on the map, it only waits for the first one). Be aware that this command has the potention to wait forever, if the NPC will continue moving forever.

If the NPC ceases to exist, or if you move to a different map, then

wait for npc

stops waiting (continues).
walk NPC (2,up,3) # make NPC 2 go up three spaces wait for NPC (2) # wait until the NPC'S done
walknpc
pathfindnpcto
wait for camera
wait for camera
Wait for the camera to stop panning after a pancamera, focuscamera or pixelfocuscamera command.
pan camera (left,10) # show the villain 10 tiles off screen wait for camera # wait until he's on screen
wait for all
wait for all
Waits for any camera motion due to pancamera, focuscamera, etc. to stop, waits for all heroes to stop walking and pathfinding, and waits for NPCs to stop scripted pathfinding (e.g. pathfindnpcto). If suspendnpcs has been used then waitforall also waits for all NPCs to come to a halt. Beware that without suspendnpcs, automatic NPC walking such as wandering, pacing, avoiding, or pathfinding, as well as movement due to walknpc/walknpctox/walknpctoy are ignored! That means that NPCs might still be partway between tiles.

wait for all

does NOT wait for text boxes.
# do a bunch of things all at once suspend NPCs walk hero(me, south, 3) pathfind NPC to(4, 30, 35, 10) NPC chases NPC(5, 4, false, 10) pan camera(north, 20, 1)

# wait until everything is done wait for all

camera follows hero(me) resume NPCs

# Working with Tags

set tag (tag,value)
set tag
Sets the value of a tag. The available constants are: off, on, true, or false. You can specify the number of the tag, or you can use the constants in your HSI file. These constants are in the form of tag:name.
check tag (tag)
check tag
A function that checks the value of a tag, and returns true if the tag is turned on, and false if the tag is turned off. It can be used in if and while statements. You can specify the number of the tag, or you can use the constants in your HSI file. These constants are in the form of tag:name.
set onetime (onetime,value)
set onetime
Sets the value of an NPC onetime use flag. NPC onetime use flags behave like tags but are stored separately.

value

is the new setting; for clarity you can use the constants off, on, true, or false.
check onetime (onetime)
check onetime
A function that checks the value of an NPC onetime flag, and returns true if the one-time NPC has already been used, and false if the onetime NPC has not yet been used. It can be used in if and while statements. NPC onetime flags are similar to tags, but stored separately.

# Suspend and Resume

suspend player
suspend player
Blocks the player from controlling the game, so the plotscript can have exclusive control. The exceptions to this are text boxes and menus. The player can advance text boxes no matter what, unless you use suspendboxadvance. suspend player prevents the player from opening the main menu using the menu key (ESC/etc), but it doesn't suspend controls on any menu or the player's ability to close menus with the menu key. (You can change that with setmenubit(menu handle, menubit:no controls, true) where menu handle might for example be topmenu.)
suspend player # do stuff resume player
resume player
resume player
Restores normal control after a suspendplayer command. This is very important. If you use suspendplayer, but forget resume player, the game will be stuck after the script ends.
player is suspended
player is suspended
Returns true if suspendplayer is active.
suspend NPCs
suspend NPCs
Stops NPCs from walking around automatically (ie, suspends NPC AI). When suspend NPCs is run, all NPCs stop in their tracks once they've finished their current step to the next tile, ready for you to control them with commands like walknpc and pathfindnpcto. You should use a wait command like waitfornpc to ensure an NPC has finished its current movement before getting it to start a new one (which could cause tile misalignment). Use setnpcmoves(who, false) instead to prevent a single NPC from moving.
suspend NPCs # do stuff resume NPCs
waitfornpc
waitforall
setnpcmoves
resume NPCs
resume NPCs
Restores automatic NPC movement after a suspendnpcs command. This does not resume NPCs suspended with setnpcmoves.
npcs are suspended
npcs are suspended
Returns true if suspendnpcs is active.
suspend obstruction
suspend obstruction
Allows heroes to walk through NPCs, allows NPCs to walk through heroes, and allows NPCs to walk through each other. Also, when obstruction is suspended, step-on activated NPCs won't be activated, and of course NPCs can't be pushed. Use resumeobstruction to restore normal obstruction behavior. Use setnpcobstructs(who, false) instead to allow a single NPC to move through heroes and NPCs, and vice-versa.
suspend obstruction # walk through things resume obstruction
setnpcobstructs
resume obstruction
resume obstruction
Restores normal obstruction after a suspendobstruction command. This doesn't undo the effect of setnpcobstructs.
obstruction is suspended
obstruction is suspended
Returns true if suspendobstruction is active.
suspend hero walls
suspend hero walls
Allows heroes to walk through walls, and to walk off the edge of the map. Use resumeherowalls to restore normal wall behavior.
suspend hero walls # hero is now a ghost # walk through things resume hero walls # back to mortality...
resume hero walls
resume hero walls
Restores normal wall behavior after a suspendherowalls command
hero walls are suspended
hero walls are suspended
Returns true if suspendherowalls is active.
suspend NPC walls
suspend NPC walls
Allows NPCs to walk through walls, including to leave the zone they are restricted to, and to walk off the edge of the map. Use resumenpcwalls to restore normal wall behavior. Use setnpcignoreswalls(who, true) instead to allow a single NPC to walk through walls.

If you use this command on a map with NPCs walking about normally you should use suspendnpcs first, otherwise NPCs will start walking into walls and get stuck there when you call resumenpcwalls! Usually it is better to use setnpcignoreswalls to allow just a specific NPC to walk through walls.

NPCs will still be unable to walk through each other, or to walk through the hero. Use suspendobstruction to allow that.

suspend NPC walls # npc is now a ghost # walk through things resume NPC walls # back to mortality...
resume NPC walls
resume NPC walls
Restores normal wall behavior after a suspendnpcwalls command. This doesn't undo the effect of setnpcignoreswalls.
npc walls are suspended
npc walls are suspended
Returns true if suspendnpcwalls is active.
suspend caterpillar
suspend caterpillar
Stops your other heroes from following the leader. This is useful when you want to control them individually with walkhero commands. In earlier versions this was misspelled as suspend catapillar. The old spelling still works for backwards compatibility.

If you want to set whether the other heroes in the party are visible, use setcaterpillarmode.

suspend caterpillar # cutscene # move heroes, probably fight a battle or two... resume caterpillar # normal game again.
resume caterpillar
resume caterpillar
Reverses the suspendcaterpillar command, and makes your other heroes follow the leader as normal. In earlier versions this was misspelled as resume catapillar. The old spelling still works for backwards compatibility.
caterpillar is suspended
caterpillar is suspended
Returns true if suspendcaterpillar is active.
suspendcaterpillar
suspend catapillar
May 22 2001
resumecaterpillar
resume catapillar
May 22 2001
suspend doors
suspend doors
Stops doors from triggering when stepped on by the lead hero. One use is to allow you to script your own transitions between maps, using dooratspot, etc. While doors are suspended usedoor still works.
resume doors
resume doors
Restores normal door triggering after a suspenddoors command. If the lead hero is already standing on a door, it will not be triggered.
doors are suspended
doors are suspended
Returns true if suspenddoors is active.
suspend random enemies
suspend random enemies
Prevents enemies from attacking your party while walking over tiles that can normally spawn random battles. This is useful to prevent battles from interrupting a plotscript. In earlier versions, this was misspelled as suspend random enemys. The old spelling still works for backwards compatibility.
suspend random enemies # no battles for now walk hero (me, up, 10) # cross pit of evil monsters of doom resume random enemies # back to normal
resume random enemies
resume random enemies
Undoes the suspendrandomenemies command and allows random battles to occur as normal. In earlier versions, this was misspelled as resume random enemys. The old spelling still works for backwards compatibility.
random enemies are suspended
random enemies are suspended
Returns true if suspendrandomenemies is active.
suspendrandomenemies
suspend random enemys
resumerandomenemies
resume random enemys
suspend box advance
suspend box advance
Prevents the player from advancing text boxes by pressing the 'use' key. While this is active, the only way to make a text box advance is with the advancetextbox command (or showtextbox) or using the "Advance text box when menu closes" menu bit. Useful for cut-scenes that play out like a movie, where the player just watches the dialogue unfold. Be very careful with this command, since you do not want to leave the player stuck on a text box forever. Undo with resumeboxadvance. Note that the player can still move the cursor in choiceboxes while this is active, use suspendtextboxcontrols to disable that. waitfortextbox does't wait while suspend box advance is active!
suspend box advance # stop players from mucking things up show text box(2) # Show a text box wait(45) # Wait about 3 seconds advance text box # Next text box. Maybe it ends with "Press USE key to continue" resume box advance # go back to normal
resume box advance
resume box advance
Undoes the suspendboxadvance command, allowing the player to advance text boxes by pressing the use key, as normal.
box advance is suspended
box advance is suspended
Returns true if suspendboxadvance is active.
suspend text box controls
suspend text box controls
Prevents the player from moving the cursor in choice boxes. In future this will also prevent the player from skipping pauses and fade-in animations for text boxes, once they are implemented. This does not prevent the player from advancing the text box, use suspendboxadvance for that. Undo with resumetextboxcontrols.
resume text box controls
resume text box controls
Undoes the suspendtextboxcontrols command, allowing the player to control choice boxes, as normal.
textbox controls are suspended
textbox controls are suspended
Returns true if suspendtextboxcontrols is active.
suspend overlay
suspend overlay
Draws old-style overhead tiles under heroes and NPCs instead of over them. This does not affect the drawing of normal layers. You might still find this useful for creating bridges or catwalks that can be walked on or passed under. Undo with resumeoverlay.
resume overlay
resume overlay
Undoes the suspendoverlay command, causing overhead tiles to be drawn over heroes and NPCs as normal.
overlay is suspended
overlay is suspended
Returns true if suspendoverlay is active.
suspend map music
suspend map music
serendipity
Causes ambient music not to automatically play when you enter a map. Does not affect the currently playing music, or the map's ambient music. Use when playing thematic music during a scene that involves changing maps.
# begin scene play song(song:Happy Times) show textbox (117) wait for textbox # goto another map without triggering music fade screen out wait suspend map music use door(3) fade screen in # continue scene show textbox (118) wait for textbox # return to normal music behaviour and play the ambient music resume map music play song (get ambient music)
setambientmusic
getambientmusic
resume map music
resume map music
serendipity
Causes ambient music to automatically start playing when you enter a map again after a suspendmapmusic command.
map music is suspended
map music is suspended
Returns true if suspendmapmusic is active.
suspend timers
suspend timers
Causes all plot timers started with settimer to be paused. It does not cancel them. Undo with resumetimers
resume timers
resume timers
Undoes suspendtimers. All previously paused plot timers will become active again.
timers are suspended
timers are suspended
Returns true if suspendtimers is active.

# Moving Heroes

walk hero (who, direction, distance)
walk hero
Makes the specified hero move in the specified direction for the specified number of tiles. The first argument tells who to move. Use me or numbers 0-3. The second argument is the direction. Use the constants: north, south, east, west, up, down, left, or right. The third argument is the number of tiles to move. If you leave out the third argument, the hero will move one tile. If you use a negative number for walk distance, the hero will walk backwards. Walk hero is usually used with the waitforhero command. You should normally use the suspendplayer command before moving heroes, and if you want to move heroes other than the leader, you should use the suspendcaterpillar command.
suspend player # stop player walk hero(me,up,3) # move him up 3 tiles resume player # OK, done
pathfind hero to (who, x, y, stuck ticks)
pathfind hero to
Makes the specified hero walk along the shortest path to the destination position. They will go around obstacles. If the destination cannot be reached at all, they will go to the closest reachable tile. The first argument

who

is the hero's rank in the caterpillar party, or me for the leader. When the caterpillar party is enabled, this command only works on the leader, and will do nothing for other heroes. Use suspendcaterpillar if you want to make the other heroes pathfind. Non-leader heroes do not treat NPCs as obstacles when they pathfind. The second argument is the destination

x

tile coordinate. The third argument is the destination

y

tile coordinate. The fourth argument

stuck ticks

is optional. If it is included, a hero who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If

stop ticks

is omitted or zero, the hero will keep pathfinding even if it gets stuck, and will not stop until it reaches the destination, or is stopped with the cancelherowalk command. Be careful if you are using waitforhero to wait for pathfindheroto when no

stuck ticks

timeout is used, since waitforhero might wait forever if the hero has no way to get to its destination.
herochasesnpc
cancelherowalk
waitforhero
hero chases hero (who, npc, stop when reached, stuck ticks)
hero chases NPC
Makes the specified hero walk along the shortest path to the destination NPC, even if the destination NPC is moving. The chasing hero will go around obstacles. If the destination NPC cannot be reached at all, the chasing hero will go to the closest reachable tile. The first argument

who

is the caterpillar rank of the hero who will be chasing, or me for the leader. When the caterpillar party is enabled, this command only works on the leader, and will do nothing for other heroes. Use suspendcaterpillar if you want to make the other heroes pathfind. Non-leader heroes do not treat NPCs as obstacles when they pathfind. The second argument

npc

is the NPC to chase. You can use an npcreference or the NPC's ID number. The third argument

stop when reached

can be true if you want the chasing hero to stop after the first time it reaches the destination NPC. If ommitted or false, the hero will keep chasing even after it reaches a moving destination NPC. The fourth argument

stuck ticks

is optional. If it is included, a hero who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If

stop ticks

is omitted or zero, the hero will keep pathfinding even if it gets stuck, and will not stop until it reaches the destination, or is stopped with the cancelherowalk command. Be careful if you are using waitforhero to wait for herochasesnpc when no

stuck ticks

timeout is used, since waitforhero might wait forever if the hero has no way to get to its destination.
pathfindheroto
cancelherowalk
waitforhero
cancel hero walk (who)
cancel hero walk
If the specified hero is walking with a command like walkhero or pathfinding (due to a command like pathfindheroto or because the player clicked somewhere), they will stop. They are allowed to finish their current step to the next tile, so they will not end up misaligned with the tile grid.

If you want to stop a hero immediately without letting them finish their step, use walkhero with a distance of zero tiles, like: cancel hero walk(who) # Cancel any pathfinding walk hero(who, hero direction(hero), 0) This will misalign the hero with the tile grid, breaking movement and wall and collision checking! You are responsible for realigning the hero afterwards somehow.

pathfindheroto
herochasesnpc
walkhero
cancelnpcwalk
set hero direction (who, direction)
set hero direction
Makes the specified hero face in the specified direction. The hero is specified by their rank in the walkabout caterpillar, 0-3. The following constants are available for direction: north, south, east, west, up, down, left, or right.
set hero direction (me,right) # face right
hero direction (who)
hero direction
Returns the specified hero's direction. The hero is specified by their rank in the walkabout caterpillar, 0-3
set hero frame (who, frame)
set hero frame
Sets the walking frame of the specified hero to 0 or 1. The hero is specified by their rank in the walkabout party, 0-3
heroframe
hero frame (who)
hero frame
Returns the walking frame (0 or 1) of the specified hero. The hero is specified by their rank in the walkabout party, 0-3
set hero position (who, x, y)
set hero position
Instantly moves the specified hero to an X,Y position on the map. The coordinates are in units of tiles. For pixel-positioning use the puthero command.
herox
heroy
heropixelx
heropixely
put hero (who, x, y)
put hero
Moves a hero to a precise location on the map. The first argument is the hero's position in the walkabout party. The second and third arguments are the X,Y pixel position of the top left corner of the hero walkabout sprite, relative to the top left corner of the map. Be aware that using this command can misalign your hero with the tile-grid, preventing it from walking normally. To position the hero by tile, use the setheroposition command. Normally you will use this command to escape the tile-based movement system.
# This script will make the hero jump in an arch 15 pixels high 2 tiles to the right, # but it won't animate it. You can use setheroframe or setheropicture to do that. variable (i, jump) suspend player set hero direction (me, right) jump := -5 for (i, 0, 10) do ( put hero (me, hero pixel X (me) + 4, hero pixel Y (me) + jump) jump += 1 wait ) resume player
hero X (who)
hero X
Returns the specified hero's X position in tiles. Note that a hero's tile is the tile its top left corner is on.
hero Y (who)
hero Y
Returns the specified hero's Y position in tiles. Note that a hero's tile is the tile its top left corner is on.
hero pixel X (who)
hero pixel X
Returns the hero's X position on the map in pixels. To find the hero's position in tiles, use the herox function instead.
hero pixel Y (who)
hero pixel Y
Returns the hero's Y position on the map in pixels. To find the hero's position in tiles, use the heroy function instead.
hero Z (who)
hero Z
Returns the specified hero's Z position in pixels. The Z value is the number of pixels they are above the tile that they are 'standing' on, not including the map's foot offset. All heroes normally have a Z value of 0 (even on maps with a foot offset) unless they are riding a vehicle which rises.
setheroz
npcz
set hero z (who, z)
set hero z
Sets the Z location of the specified hero. The Z value is the number of pixels they are above the tile that they are 'standing' on. Useful for scripts where you want a hero to jump or levitate. All heroes normally have a Z value of 0 (even on maps with a foot offset: the foot offset is added to the Z value) unless they are riding a vehicle which rises.

Hero Z values are reset to 0 when you change map or dismount a vehicle, and aren't saved in saved games.

heroz
setnpcz
walk hero to x (who,x)
walk hero to x
Makes the specified hero walk to a given X coordinate on the map
walk hero to y (who,x)
walk hero to y
Makes the specified hero walk to a given Y coordinate on the map
check hero wall (who,direction)
check hero wall
Returns true if there is a wall blocking the hero from moving in the specified direction. No actual movement takes place.

This command should only be used when the hero is standing still and aligned with the tile grid. You can use the checkwallcollisionxy commands for much more flexible wall-checking, which works from any starting position on the map.

get hero speed (who)
get hero speed
Returns the walking speed of the specified hero, in pixels per tick.
setherospeed
set hero speed (who, speed)
set hero speed
Changes the walking speed (pixels per tick) of the specified hero, from 0 to 20.

who

is a caterpillar slot; use me to refer to the leader. Normally only the speed of the leader matters, unless you use suspendcaterpillar, because the whole party moves at the leader's speed.

speed

defaults to 4. Tiles are 20 pixels in size, and speeds that do not divide evenly or nearly evenly into 20 will result in jerky movement. So only use speeds 0, 1, 2, 3, 4, 5, 7, 10, or 20.

Changes to hero speed aren't saved in saved games!

Hero speed is weird. It isn't actually a property of the hero, but of the caterpillar slot. So if you change the leader's speed and then a different hero is swapped into the leader position, the leader (and party) speed doesn't change. That's usually a good thing!

Don't set speed to zero while a hero is moving, it will cause the hero to stop mid-step and become misaligned with the grid and stuck. Wait for the hero to stop first or check with heroiswalking. (You probably shouldn't use speed 0 at all.)
getherospeed
teleport to map (map, x, y)
teleport to map
An alternative to usedoor, teleport to map moves you to a given x,y position on the specified map without the need to create a door-link on the map. Teleport to map does not fade to black.

An automatic wait(1) occurs immediately after this command.

hero is walking (who)
hero is walking
Returns true if the specified hero (by position in the caterpillar) is currently walking. Returns false if the hero is standing still.

# Doors

use door (number, fade screen)
use door
Instantly uses door

number

, just as if you had stepped into it.

fade screen

is an optional argument, defaulting to true. If true, the screen will fade out before using the door (even if it leads to the same map), and fade back in one tick later. Otherwise, there are no automatic screen fades.

An automatic wait(1) occurs immediately after this command.

If you call fadescreenout immediately after use door, then the screen won't fade back in afterwards. (But you might have to do this in the map autorun script, if there is one, since it will suspend the script that called use door!)

door exists (number, map)
door exists
Returns true if there is a door with ID

number

on the specified

map

. If you leave out the map number, the current map will be assumed. This command is useful for avoiding script errors due to invalid door IDs.
get door x (number, map)
get door x
Returns the x coordinate (in tiles) of the door with ID

number

on the specified

map

. If you leave out the map number, the current map will be assumed.
dooratspot
get door y (number, map)
get door y
Returns the y coordinate (in tiles) of the door with ID

number

on the specified

map

. If you leave out the map number, the current map will be assumed.
dooratspot
get door destination id (number, map)
get door destination id
Returns the door ID of the door currently linked to by the door with ID

number

on the specified

map

. If you leave out the map number, the current map will be assumed. To get the door's location, use getdoorx and getdoory. If door

number

does not exist, or is not currently linked to any other door, then -1 is returned.

A door's destination can vary depending on tags. Check your doorlinks if you get unexpected results! There's no script command to get information about doorlinks currently inactive due to tags.

getdoorx
getdoory
getdoordestinationmap
get door destination map (number, map)
get door destination map
Returns the map ID of the destination door currently linked to by the door with ID

number

on the specified

map

. If you leave out the map number, the current map will be assumed. If door

number

does not exist, or is not currently linked to any other door, then -1 is returned.

A door's destination can vary depending on tags. Check your doorlinks if you get unexpected results! There's no script command to get information about doorlinks currently inactive due to tags.

door at spot (x, y)
door at spot
Checks whether there is a door on the position given by

x

,

y

in tiles and if so returns its ID; otherwise returns -1. Note that the door might not have any active doorlink, or no door links at all. You can use getdoordestinationid to check if a door is active. If you want to script your own map transitions, you will find suspenddoors helpful.
getdoorx
getdoory

# Moving NPCs

NPC reference (ID, copy, allow disabled?)
NPC reference
What is an NPC reference? A reference is a number that uniquely identifies an NPC on a map. You can use an NPC reference to specify which NPC you are controlling in most NPC-related commands. The first argument to NPC reference is the

ID

number of the NPC you want to work with. The ID is the same number that appears in CUSTOM.EXE when you are editing NPCs or placing NPCs on the map. The second argument,

copy

is optional. It specifies which copy of the NPC you want, in case there are more than one on the map. If you don't specify which copy you want, you will just get a reference to the first NPC on the map with the right ID. Copies are counted starting from zero. You can see the copy number of NPCs in the Map Editor if you placed them in Custom, at the bottom of the NPC. (You can also see them using the F6 NPC debugger, by hoving the mouse over an NPC.) The third argument,

allow disabled?

is optional, and defaults to false. If true, when used on a copy of an NPC hidden due to tag conditions, NPC reference will return a reference instead of returning false. If the NPC ID/copy which you asked for is not found on the map then NPC reference will return false (zero). (Unlike other NPC commands, this one does not accept an NPC reference in place of the NPC ID.) If you plan on using the same NPC reference many times in a script you can store it in a variable.
#---NPC reference example---

plotscript,ref example,begin

variable(Fred)

# find the first copy of NPC 10, # and store the reference in a variable Fred := NPC reference(10,0)

# now we can manipulate that NPC with the variable walk NPC (Fred,south,3) wait for NPC (Fred)

# make the NPC spin! set NPC direction (Fred,east) wait(2) set NPC direction (Fred,north) wait(2) set NPC direction (Fred,west) wait(2) set NPC direction (Fred,south) wait(2)

end
npcatspot
npcatpixel
createnpc
getnpcid
npccopynumber
npccopycount
nextnpcreference
next NPC reference (npcref)
next NPC reference
This command is for looping over all the npcs on the map, in the same way that firstchild and nextsibling can be used to iterate over all the children of a slice. When called with no argument or 0, it returns a reference to the first NPC on the map. When you give it an NPC reference it returns a reference to the next NPC. It returns 0 when there are no more NPCs, and skips over NPCs that are disabled by a tag condition (including used one-time-use NPCs). It's safe to delete NPCs while you're iterating over them (unlike nextsibling!), but creating NPCs at the same time might result in them getting skipped.
# Iterate over all NPCs... and delete them all! variable(npcref) npcref := next NPC reference() # The first NPC while (npcref) do ( delete NPC(npcref) npcref := next NPC reference(npcref) )
npcreference
npcatspot
npcatpixel
NPC at spot (x, y, number)
NPC at spot
This command returns a reference to the NPC at the given X and Y coordinate, in tiles, on the map. The optional third argument lets you choose which NPC to reference in case there is more than one NPC standing on that same spot (starting from the bottom-most NPC, which is number 0). false is returned if there is no NPC there, or

number

is too large (greater than or equal to the number of NPCs). You can also pass the constant getcount for the third argument to return the total number of NPCs on that tile.

An NPC's tile is the tile its top left corner is on.

npcreference
NPC at pixel (x, y, number)
NPC at pixel
This command returns a reference to the NPC at the given X and Y coordinate in pixels. That is, any npc whose 20x20 sprite (including transparent sections) is over that pixel. The optional third argument lets you choose which NPC to reference in case there is more than one NPC standing on that same spot (starting from the bottom-most NPC, which is number 0). false is returned if there is no NPC there, or

number

is too large (greater than or equal to the number of NPCs). You can also pass the constant getcount for the third argument to return the total number of NPCs on that tile.
npcreference
walk NPC (who, direction, distance)
walk NPC
Makes the specified NPC move in the specified direction for the specified number of tiles. The first argument tells who to move. You can use an npcreference or the NPC's ID number. The second argument is the direction. Use the constants: north, south, east, west, up, down, left, or right. The third argument is the number of tiles to move. If you leave out the third argument, the NPC will move one tile. If you use a negative number for walk distance, the npc will walk backwards. walk NPC is usually used with the waitfornpc command. You should normally use the suspendnpcs command before moving NPCs to prevent their automatic movements from interfering with your scripted movements.
set NPC direction (who, direction)
set NPC direction
Makes the specified NPC face in the specified direction. The following constants are available for direction: north, south, east, west, up, down, left, or right. You can use either an npcreference or the NPC's ID number to specify which NPC will turn.
pathfind NPC to (who, x, y, stuck ticks)
pathfind NPC to
Makes the specified NPC walk along the shortest path to the destination position. They will go around obstacles. If the destination cannot be reached at all, they will go to the closest reachable tile. The first argument

who

is the NPC. You can use an npcreference or the NPC's ID number. The second argument is the destination

x

tile coordinate. The third argument is the destination

y

tile coordinate. The fourth argument

stuck ticks

is optional. If it is included, an NPC who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If

stop ticks

is omitted or zero, the npc will keep pathfinding even if it gets stuck, and will not stop until it reaches the destination, or is stopped with the cancelnpcwalk command. Be careful if you are using waitfornpc to wait for pathfindnpcto when no

stuck ticks

timeout is used, since waitfornpc might wait forever if the NPC has no way to get to its destination.
npcchasesnpc
cancelnpcwalk
waitfornpc
NPC chases NPC (who, other who, stop when reached, stuck ticks)
NPC chases NPC
Makes the specified NPC walk along the shortest path to the destination NPC, even if the destination NPC is moving. The chasing NPC will go around obstacles. If the destination NPC cannot be reached at all, the chasing NPC will go to the closest reachable tile. The first argument

who

is the NPC who will be chasing. The second argument

other who

is the NPC to chase. You can use an npcreference or the NPC's ID number. The third argument

stop when reached

can be true if you want the chasing NPC to stop after the first time it reaches the destination NPC. If omitted or false, the NPC will keep chasing even after it reaches a moving destination NPC. The fourth argument

stuck ticks

is optional. If it is included, an NPC who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If

stop ticks

is omitted or zero, the npc will keep pathfinding even if it gets stuck, and will not stop until it reaches the destination, or is stopped with the cancelnpcwalk command. Be careful if you are using waitfornpc to wait for npcchasesnpc when no

stuck ticks

timeout is used, since waitfornpc might wait forever if the NPC has no way to get to its destination. If the destination NPC is deleted or disappears due to a tag condition, the chasing NPC stops.
pathfindnpcto
cancelnpcwalk
waitfornpc
cancel NPC walk (who)
cancel NPC walk
If the specified NPC is walking with a command like walknpc or pathfinding with a command like pathfindnpcto, they will stop. They are allowed to finish their current step, so they will not end up misaligned with the tiles. This command has no effect on automatic NPC movement patterns, it only stops scripted movement.

If you want to stop an NPC immediately without letting them finish their step, use walknpc with a distance of zero tiles, like: cancel NPC walk(npc) # Cancel any pathfinding walk NPC(npc, NPC direction(npc), 0) This will misalign the NPC with the tile grid, breaking movement and wall and collision checking! You are responsible for realigning the NPC afterwards somehow.

pathfindnpcto
npcchasesnpc
walknpc
cancelherowalk
NPC direction (who)
NPC direction
Returns the specified NPC's direction.
set NPC frame (who, frame)
set NPC frame
Sets the walking frame of the specified NPC to 0 or 1. You can use either an npcreference or the NPC's ID number to specify which NPC will change.
npcframe
NPC frame (who)
NPC frame
Returns the walking frame (0 or 1) of the specified NPC.
set NPC position (who, X, Y)
set NPC position
Instantly moves the specified NPC to an X,Y position on the map. The coordinates are in units of tiles. You can use either an npcreference or the NPC's ID number to specify which NPC will be moved.
put npc (who,x,y)
put npc
Moves an NPC to a location on the map in pixels. The first argument is and npcreference or an NPC ID number. The second and third arguments are the X,Y pixel position relative to the top left corner of the map. Be aware that using this command can mis-align your NPC with the tile-grid, preventing it from walking normally. To position the NPC by tile, use the setnpcposition command.
NPC X (who)
NPC X
Returns the specified NPC's X position in tiles. Note that an NPC's tile is the tile its top left corner is on.
npcatspot
NPC Y (who)
NPC Y
Returns the specified NPC's Y position in tiles. Note that an NPC's tile is the tile its top left corner is on.
npcatspot
NPC pixel X (who)
NPC pixel X
Returns the NPC's X position on the map in pixels. The argument is an npcreference or an NPC ID number. To find the NPC's position in tiles, use the npcx function instead.
NPC pixel Y (who)
NPC pixel Y
Returns the NPC's Y position on the map in pixels. The argument is an npcreference or an NPC ID number. To find the NPC's position in tiles, use the npcy function instead.
npc Z (who)
npc Z
Returns the specified NPC's Z position in pixels. The Z value is the number of pixels they are above the tile that they are 'standing' on, not including the map's foot offset. All NPCs normally have a Z value of 0 (even on maps with a foot offset) unless they are used as a vehicle which rises.
setnpcz
heroz
set npc z (npc, z)
set npc z
Sets the Z location of the specified NPC. The Z value is the number of pixels they are above the tile that they are 'standing' on. Useful for scripts where you want a NPC to jump or levitate. All NPCs normally have a Z value of 0 (even on maps with a foot offset) unless they are a vehicle which rises.
npcz
setheroz
walk NPC to X (who, X)
walk NPC to X
Makes the specified NPC walk to a given X coordinate on the map. You can use either an npcreference or the NPC's ID number to specify which NPC will move.
walk NPC to Y (who, Y)
walk NPC to Y
Makes the specified NPC walk to a given Y coordinate on the map. You can use either an npcreference or the NPC's ID number to specify which NPC will move.
check NPC wall (who, direction)
check NPC wall
Returns true if there is a wall blocking the NPC from moving in the specified direction. No actual movement takes place. It does not matter whether the NPC is set to ignore walls or ignore the passmap.

This command should only be used when the NPC is standing still and aligned with the tile grid. You can use the checkwallcollisionxy commands for much more flexible wall-checking, which works from any starting position on the map.

get NPC speed (who)
get NPC speed
Returns the walking speed of the specified NPC (either NPC reference or ID number) in pixels per tick. (This is just an alias for readnpc(who, NPCstat:movespeed)).
set NPC speed (who, speed)
set NPC speed
Changes the walking speed of the specified NPC.

speed

defaults to 4. Tiles are 20 pixels in size, and speeds that do not divide evenly or nearly evenly into 20 will result in jerky movement. So only use speeds 0, 1, 2, 3, 4, 5, 7, 10, or 20. Normally you would only use an NPC ID number for

who

, but if you want to use an npcreference it will still work. Just remember that set NPC speed changes every copy of the NPC on the map, not just the specific one you referenced. (This is just an alias for alternpc(who, NPCstat:movespeed, speed)). Don't set speed to zero while an NPC is moving, it will cause the NPC to stop mid-step and become misaligned with the grid. Get all instances of the NPC to stop first and wait for them, or check with npciswalking.
NPC is walking (who)
NPC is walking
Returns true if the specified NPC is currently walking. Returns false if the NPC is standing still. You can use either an npcreference or the NPC's ID number to specify which NPC will be checked.
NPC extra (who, which)
NPC extra
Returns the npc instance-specific extra data field requested in

which

, a number from 0 to 2. You may use the constants

extra 0

,

extra 1

and

extra 2

to refer to them. If you use an NPC ID for

who

, the first instance's data will be used.
setnpcextra
set NPC extra (who, which, value)
set NPC extra
Sets the npc instance-specific extra data field requested in

which

, a number from 0 to 2. You may use the constants

extra 0

,

extra 1

and

extra 2

to refer to them. If you use an NPC ID for

who

, the first instance's data will be used.

Unlike other NPC instance data, the extra data for NPCs on the current map is not saved in save games! However, it is saved in mapstate NPC saves (see savemapstate)

npcextra
get NPC ID (reference)
get NPC ID
This command opposite to npcreference (along with npccopynumber). If you give

get NPC ID

a reference to an NPC it will return the NPC's ID. If the reference is not valid then

get NPC ID

will return -1. This command can be used on tag-disabled NPCs too, returning their ID number.
NPC copy number (reference)
NPC copy number
This command opposite to npcreference (along with getnpcid). That is, it returns the copy number that you need to pass to npcreference to get this NPC. If you give

NPC copy number

a reference to an NPC it will return which copy of that NPC definition it is - 0 if it's the first NPC, 1 is the second, etc. This number is also shown in the map editor at the bottom of an NPC, and in the F6 NPC debug mode when you mouse-over an NPC. If the reference is not valid then

NPC copy number

will return -1. This command also works on references to tag-disabled NPCs.
NPC copy count (ID)
NPC copy count
This command tells you how many copies of a particular NPC ID exist on the map. This can be very useful if you want apply the same action to each copy of an NPC on the map by looping over them. Generally this is used together with the npcreference command.

This command does not count tag-disabled NPCs. So if there are four copies of NPC 2 on a map, but they only appear when tag 5 is on, then npc copy count(2) returns 4 when tag 5 is on and 0 when it isn't.

#---NPC copy count example---

plotscript, every NPC example, begin

variable(copy number, guard count, current guard)

# The guard is NPC 10, and there are many copies of him on the map guard count := NPC copy count(10)

# This loop repeats once for each copy of NPC 10 for (copy number, 0, guard count -- 1) do, begin current guard := NPC reference(10, copy number) walk NPC(current guard, south, 4)

# if we added a "wait for NPC(current guard)" right here # then the guards would walk one at time end

end
change NPC ID (reference,new ID)
change NPC ID
This command takes an npcreference and lets you change the ID number of the NPC it points to. This means that the NPC will now use a different picture, an different palette, a different walking speed, an different text box, everything. This change is not permanent. It only lasts until the next time a map gets loaded.
create NPC (ID,X,Y,direction)
create NPC
This command will magically create a new copy of an NPC with the given ID number. You can specify an X and Y position where it will be created, and optionally a direction too (if you leave out the direction, the new NPC will be facing south). create NPC returns an npcreference that you can use to refer to the new NPC in other commands like walknpc. If the new NPC cannot be created (there is a maximum of 300 total NPC copies in memory at a time) then create NPC will return false (zero). The new NPC is not permanent. It only lasts until a new map is loaded.
destroy NPC (reference)
destroy NPC
This command will erase the specified NPC. You can use either an npcreference or the NPC's ID number. The deletion is not permanent. Unless this is an NPC that you created with createnpc, the NPC will be back again next time the map gets loaded. If you need to permanently remove an NPC, use tags.

This only deletes the one NPC you specify. If you use an NPC ID number as the argument, only the first copy of the NPC on the map will be deleted.

This command can be also be written as

delete NPC

.
destroynpc
delete NPC (reference)
NPC is disabled (reference)
NPC is disabled
This command returns true if the npcreference points to an NPC who does not exist, or has been disabled because of tags or one-time-use.

# The Camera

camera pixel X
camera pixel X
Returns the X position of the top left corner of the screen in pixels.
camera pixel Y
camera pixel Y
Returns the Y position of the top left corner of the screen in pixels.
camera follows hero (who)
camera follows hero
Normally, the camera follows your leader. With this command, you can make the camera follow any hero you want. If you leave out the argument, the camera will follow your leader as normal.
camera follows NPC (who)
camera follows NPC
With this command, you can make the camera follow an NPC instead of the hero. If more than one copy of the specified NPC exists, the camera will follow the first one. To revert the camera to normal, use camerafollowshero.
camera follows slice (slice)
camera follows slice
With this command, you can make the camera follow a slice instead of the hero. The slice will be centered on the screen. To revert the camera to normal, use camerafollowshero.
pan camera (direction,distance,pixelstep)
pan camera
This command causes the camera to stop following your leader and pan in the specified direction. For direction, you can use the constants: north, south, east, west, up, down, left, or right. The distance is the number of tiles you want the camera to move before it stops. You can also specify the number of pixels you want the camera to move for each tick. if you leave the last argument out, the camera will move by 2 pixels per tick. This command is normally used with waitforcamera. To revert the camera to normal, use camerafollowshero.
focus camera (x,y,speed)
focus camera
This command causes the camera to focus itself on the specified X,Y tile coordinates of the map. These coordinates are in units of tiles. The third argument, the speed, tells how fast the camera will pan. If you do not specify a speed, the camera will pan 2 pixels per tick. This command is normally used with waitforcamera. To revert the camera to normal, use camerafollowshero.
pixel focus camera (x,y,speed)
pixel focus camera
This command causes the camera to focus itself on the specified X,Y pixel coordinates of the map. These coordinates are in units of pixels. The third argument, the speed, tells how fast the camera will pan. If you do not specify a speed, the camera will pan 2 pixels per tick. This command is normally used with waitforcamera. To revert the camera to normal, use camerafollowshero.
put camera (x,y)
put camera
This command causes the top left corner of the camera to instantly jump to the specified X,Y pixel coordinates of the map. These coordinates are in units of pixels, not tiles. To position the camera by tiles, just multiply the tile position by 20. To revert the camera to normal, use camerafollowshero.

# Text Boxes

show text box (number)
show text box
Displays the numbered text box, just as if you had talked to an NPC. The text box will not actually pop up until the next wait command. This command is most often used with the waitfortextbox command.
show text box(2) # Show a text box wait for text box # wait until the player continues
advance text box
advance text box
Advances a text box just as if the player had pressed a key. For use while suspendboxadvance is active.
current text box
current text box
Returns the number of the currently displayed text box, or -1 if there's none.
speakingnpc
showtextbox
advancetextbox
speaking npc
speaking npc
If the player activated an NPC which showed a textbox and the hero and NPC are still "speaking" (the textbox chain isn't done), returns the NPC reference for that NPC. Otherwise returns false.
currenttextbox
string from textbox (ID, textbox, line, ignored)
string from textbox
Loads one of the

line

s of a

textbox

into a string

ID

. Valid numbers for

line

are 0-7. Trailing and leading whitespace is stripped from the line, and embedded codes like ${H1} in the string are automatically substituted.

This command is obsolete and exists only for compatibility with old games: It has been replaced with textboxline. The fourth argument does nothing.

expandstring
textboxline
textbox line (string ID, textbox, line, expand, strip)
textbox line
Loads one of the

line

s of a

textbox

into a

string ID

. Valid numbers for

line

are 0-7. If

expand

is true (which is the default) codes such as ${H1} in the string will be substituted automatically. If

strip

is true (which is NOT the default), white space at the beginning and end of the string are removed.
expandstring
textboxtext
textbox text (string ID, textbox, expand, strip)
textbox text
Loads all lines of a

textbox

into a single

string ID

. If

expand

is true (which is the default) codes such as ${H1} in the string will be substituted automatically. If

strip

is true (which is NOT the default), white space at the beginning and end of the string are removed.
textboxline

# Triggering Stuff

fight formation (number)
fight formation
Starts a battle with the numbered enemy formation. This command returns true on victory and false if the battle ends for any other reason. However if all heroes die the game will still end as normal unless you set a death script. In that case, false is returned after the death script has finished. The situations which cause true to be returned are:

- Normal victory
- An attack with the "Force battle victory" bit ends the battle

The situations which cause false to be returned are:

- All heroes died
- Player ran from battle
- An attack with the "Force battle loss & heroes run away" bit ends the battle
- An attack with the "Force battle loss & exit" bit ends the battle
- A timer with timerflag:critical runs out and ends the battle
- The end-battle-instantly debug key is used

An automatic wait(1) occurs immediately after this command.

setdeathscript
use NPC (who)
use NPC
Remotely trigger an NPC. You can use either an npcreference or an NPC ID number. Whatever actions are associated with triggering that NPC will be taken, text box, script, vehicle, item, whatever. This command works even if the NPC has been made un-usable with setnpcusable and regardless of any "suspend" commands. However you can't activate an NPC that's tag-disabled (including one-time-use flags).

An automatic wait(1) occurs immediately after this command.

use shop (shop)
use shop
Takes you directly to a shop. You can specify the shop's ID number or its name in the form shop:name
force mount vehicle (npc)
force mount vehicle
Makes you mount the vehicle specified by NPC ID or NPC reference. Unlike usenpc,

force mount vehicle

does not bother checking the tile you are currently standing on. If the NPC is not a vehicle, nothing will happen.
current vehicle id
current vehicle id
Returns the vehicle ID number of the vehicle your hero is currently riding. If you are not riding a vehicle, it will return -1
current vehicle npc
current vehicle npc
Returns an NPC reference to the vehicle your hero is currently riding. If you are not riding a vehicle, it will return 0 or false
dismount vehicle
dismount vehicle
Makes you dismount whatever vehicle you are riding. If you are not riding a vehicle, nothing will happen.
game over
game over
Resets the game and returns you to the title screen. This command is most useful for after-you-win-the-game type scripts, and for death-scripts that are triggered when you lose in battle. (The script calling game over ends immediately.) This command is similar to resetgame, the main difference being that if the title screen and load screen have both been disabled (the Skip title/load screen preference bitsets), game over will completely exit the game (either taking you back to the game select screen, or exiting to the operating system), while resetgame starts a new game.

The game will instantly transition to the title screen (or load menu, if the title is disabled) without a screen fade. So you probably want to call fadescreenout beforehand.

By using resetgame or loadfromslot instead, you can pass arguments to the newgame and loadgame scripts.

reset game(args...)
reset game
Resets and starts a new game, skipping both title and load game screens. It can be necessary to use this instead of gameover so that the program will not exit if the title screen and load screen have both been disabled. It always resets the game back to the beginning and runs the new-game script. (The script calling reset game ends immediately.) You can pass any number of optional

args

, which become the arguments to the newgame script. For an example, see loadfromslot, which passes its arguments to the loadgame script in the same way. The default arguments of a newgame script (and all other triggered scripts) are currently ignored. If you don't pass enough

args

, then the remaining arguments default to zero.

Unlike gameover, the screen will always automatically fade out to black when calling reset game.

gameover
loadfromslot

# Basic Display Commands

show value (number)
show value
Displays the number in the bottom left corner of the screen. Useful for count-down timers, and for debugging complicated scripts. See tracevalue for a more powerful debugging tool.
show string (ID)
show string
Displays string #ID in the bottom left corner of the screen, as with the showvalue command. Use shownovalue to remove the string from the screen. Note that this command displays the value of the string at the moment the command was run. Later changes to the value of the string will not appear unless you run show string again. If you need real-time display of changes to a string, use showstringat or centerstringat instead.
showvalue
shownovalue
showstringat
centerstringat
show no value
show no value
Gets rid of the number in the bottom left corner of the screen after a showvalue or showstring command.
cancel map name display
cancel map name display
If the map name is being displayed, this command makes it disappear. For example, this may be useful if you want the map name to appear when you enter a map normally, but not when you jump to the map for a plotscripted cutscene.
show backdrop (number)
show backdrop
Displays the specified full screen backdrop on the screen. This allows you to show full screen pictures without attaching them to text boxes. Use showmap or show backdrop(-1) to hide the backdrop and show the map again. You can also do some simple animation effects by calling show backdrop many times with wait commands in between. Whether and which backdrop is displaying is saved in save games.

It's also possible to display backdrops as sprite slices using loadbackdropsprite.

showmap
loadbackdropsprite
show map
show map
shows the map again after a showbackdrop command. Don't confuse this with showminimap

# Opening Built-in Menus

main menu
main menu
Opens the main menu; exactly equivalent to openmenu(0). If menu 0 is already open, it is brought to the top. Returns the menu handle of the new or existing instance of menu 0. If menu 0 does NOT have the "Allow gameplay & scripts" bit set, then your script will pause as soon as the menu opens, until either it's closed or another menu with that bit ON is opened. And once the menu has closed the menu handle is invalid!
show mini map
show mini map
Displays the mini-map
items menu
items menu
Takes you directly to the items menu. Note that if the player uses an item that calls up a text box, the items menu command will behave like a showtextbox command for that text box.

If the player uses a item which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

status screen (who)
status screen
Takes you directly to a hero's status screen. Specify the hero using its position in the party 0-3. Use findhero if you want to specify the hero by name. The pickhero command can also be useful.
spells menu (who)
spells menu
Takes you directly to a hero's spells menu. Specify the hero using its position in the party 0-3. Use findhero if you want to specify the hero by name. The pickhero command can also be useful.

If the player uses a spell which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

equip menu (who, allow switching)
equip menu
Takes you directly to a hero's equip menu. Specify the hero using its position in the party 0-3. Use findhero if you want to specify the hero by name. The pickhero command can also be useful. If you do not specify any hero, the first hero in the party will be used. The optional second argument

allow switching

says whether to allow the player to switch to a different hero by pressing Left and Right keys. It defaults to true.
save menu (reallysave)
save menu
Takes you directly to the save menu. Will return the number from 1 to 1000 of the slot the player saved in, or false if the player did not save. You can optionally pass an argument of false to make the menu display without actually saving.
autosave
saveinslot
load menu (reallyload, show new game)
load menu
Displays the load game menu. The player can pick a saved game to load or Exit or New Game (New Game only appears if

show new game

is

true

, which is the default). If the player picks New Game then the calling script continues, otherwise the current game is terminated and either quits to the titlescreen (if there is one) or a game is loaded. If you want the New Game option to actually reset the game, call resetgame immediately after

load menu

. You can optionally pass the value false as the

reallyload

argument, to make the menu display without actually loading or quiting. If you do this, you'll need to interpret the return value to find out which option the player selected: positive values (1 to 1000) are save slot numbers, 0 means New Game and -1 is Quit or cancelled (pressed ESC).
loadfromslot
order menu
order menu
Takes you directly to the order menu, where you can change the order of the heroes in your active party.
team menu
team menu
Takes you directly to the team menu, where you can change the order of the heroes in your active party, and swap heroes in and out of your reserve.

# The Party

You should definitely read Ways to refer to a hero in a script to understand the differences between hero ID numbers (including hero:name constants), hero party slots, and walkabout rank!

## Inspecting the Party

leader
leader
Returns the hero ID number (as given in the Edit Hero Stats menu) of the current caterpillar party leader.
find hero (who)
find hero
Searches through your (battle) party to see if the specified hero is there, and returns the position where the hero was found, or -1 if the hero was not found. The position in the party is needed by most commands operating on heroes. You can use the names defined in your HSI file in the format hero:name for the ID number of the hero (as it has in the Edit Hero Stats menu). Not only does this tell you if a hero is in your party, but you can also use it to tell whether or not the hero is in your active party. find hero will return 0, 1, 2 or 3 if the hero is in the active party, and 4 or higher if the hero is in the reserve. Note that position in the battle party is not the same as position in the caterpillar: the leader is not necessarily hero 0. The opposite to find hero is herobyslot.
rankincaterpillar
hero by slot (where)
hero by slot
This command is the reverse of findhero. Given a position in your party, it will tell you which hero is in that slot, or -1 if no hero is in that slot. The number returned can be compared with the names defined in your HSI file in the format hero:name.
rank in caterpillar (who)
rank in caterpillar
Searches through your active party to see if the specified hero is there, and returns the position int the walkabout caterpillar where the hero was found, or -1 if the hero was not found. Use the names defined in your HSI file in the format hero:name. This is particularly useful if you need to use a command like walk hero but you are not sure which position the hero is in.
findhero
hero by rank (where)
hero by rank
This command is the reverse of rankincaterpillar. Given a position in your walkabout party, it will tell you which hero is in that position, or -1 if no hero is in that position. The number returned can be compared with the names defined in your HSI file in the format hero:name.
room in active party
room in active party
A function that returns the number of available spaces in your active party. It will return zero or false if there is no room.

## Changing the Party

add hero (who)
add hero
Puts the named hero in your party. If there is no room, the hero will be added to your reserve. Use the constants defined in your HSI file. They are in the form of hero:name. This command returns the party slot that the hero was added to, or -1 if both the active and reserve parties are completely full.
delete hero (who)
delete hero
Removes the named hero from your party. If you have more than one copy of the hero in your party, only the first one will be deleted. Use the constants defined in your HSI file. They are in the form of hero:name
swap in hero (who)
swap in hero
Moves the named hero in your from your reserves to your active party. If there is no room in your active party, the hero will not be moved. Use the constants defined in your HSI file. They are in the form of hero:name
swap out hero (who)
swap out hero
Moves the named hero from your active party into your reserve. Use the constants defined in your HSI file. They are in the form of hero:name
lock hero (who)
lock hero
Locking a hero prevents the player from moving the hero on the party menu. Locked heroes in the active party cannot be moved into the reserve, and locked heroes in the reserve are completely hidden. Also prevents a hero from being moved by swapinhero or swapouthero. Use the constants defined in your HSI file. They are in the form of hero:name
unlock hero (who)
unlock hero
Reverses lockhero, and makes it possible to move a hero in and out of the active party again. Use the constants defined in your HSI file. They are in the form of hero:name
swap by name (name,name)
swap by name
Swaps two named heroes in your party no matter what position they are in. Use the names defined in your HSI file in the form hero:name
swap by position (slot1, slot2)
swap by position
Swaps two heroes in your party by their positions in the party (ie, by party slot).

# Money

party money
party money
Returns how much money your party has.
get money (amount)
get money
Adds the specified amount to your party's money
lose money (amount)
lose money
Subtracts the specified amount from your party's money.
set money (amount)
set money
Changes the amount of money your party has.
pay money (amount)
pay money
A function that checks to see if you have enough money to pay the amount specified. If you do, it subtracts it, and returns true. If you do not have enough, it subtracts nothing, but returns false. Intended for use in if statements.
if(pay money(1000)) then, begin get item(item:uber sword) end, else, begin show text box(61) # ha ha, no uber sword for you! wait for text box end

# Items

Currently there are almost no script commands to get or set any item data, except for the name and description of an item.
use item (item)
use item
Attempts to use an item as if you had selected it in the items menu. The argument is the item's ID number, or one of the

item:name

constants in your .hsi file. This command will only work if the item can be used outside of battle, either as a cure attack, or to teach a hero a spell, or to trigger a text box. This command does not care if you actually have any of the item in your inventory, and if it is a consumable item, you will not lose any. The return value is true if you successfully used the item, or false if the item was unusable or the user cancelled.

If the item causes an attack to happen which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

useiteminslot
get item name (ID, item)
get item name
This command will take the name of item #

item

and stick it in string #

ID

, overwriting its contents. This can be useful for "You got <item>!" type messages.
get item description (ID, item)
get item description
This command will take the description of item #

item

and stick it in string #

ID

, overwriting its contents.
get item maximum stack size (item)
get item maximum stack size
Returns the maximum allowed size of a stack of items in the inventory. The

item

argument is an item ID; you can refer to the item by number, or you can use the constants defined in your .hsi file, which are in the form of item:name. If the item uses the default stack size, then the default value is returned.
itemcountinslot
getinventorysize

## Inventory

get item (item, number)
get item
Adds the specified number of the specified item to your inventory. If you do not specify a number, only one will be added. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name
delete item (item, number)
delete item
Removes the specified number of the specified item from your inventory. If you do not specify a number, only one will be removed. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name
item in slot (slot)
item in slot
Return a the item ID number at a specific slot in your inventory. If the inventory slot is empty, it will return -1. Slots are numbered from 0 to getinventorysize-1.
setiteminslot
itemcountinslot
setitemcountinslot
getinventorysize
set item in slot (slot, item)
set item in slot
Change the item ID number at a specific slot in your inventory. The

slot

argument is the position in your inventory screen (slots are numbered from 0 to getinventorysize-1), and the

item

argument is the item ID number, or one of the

item:name

constants defined in your .hsi file. If you want to erase an item slot, use -1 as the item ID. If the slot was empty, one copy of the item will be placed in it. Otherwise the original item count is preserved. If the maximum stack size of the new item type is less than the number of items in that slot, the extra items will be removed from that slot and placed whereever there is room.
iteminslot
itemcountinslot
setitemcountinslot
getinventorysize
getitemmaximumstacksize
item count in slot (slot)
item count in slot
Return the count of items at a specific slot in your inventory, or 0 if that slot is empty. Slots are numbered from 0 to getinventorysize-1.
iteminslot
setiteminslot
setitemcountinslot
getinventorysize
getitemmaximumstacksize
set item count in slot (slot, count)
set item count in slot
Change the count of items at a specific slot in your inventory. The

count

argument is the new number of items from 1 up to the maximum count (which is dependent on the item, but no more than 99; see getitemmaximumstacksize), or 0 if you want to delete any items currently in the slot. If the slot is empty or if the item count is out of bounds, this command will fail.
iteminslot
setiteminslot
setitemcountinslot
getinventorysize
getitemmaximumstacksize
use item in slot (slot)
use item in slot
Attempts to use whatever item is in a given inventory slot as if you had selected it in the items menu. The argument is the inventory slot number. This command will only work if there is actually an item in the slot, and the item can be used outside of battle, either as a cure attack, or to teach a hero a spell, or to trigger a text box. The return value is true if you successfully used the item, or false if the item was unusable or the user cancelled.

If the item causes an attack to happen which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

useitem
inventory (item)
inventory
Returns a count of how many of the specified item are in your inventory. If you do not have the item, it returns zero or false. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name
get inventory size
get inventory size
Returns the number of inventory slots.
setinventorysize
set inventory size (new size)
set inventory size
Changes the number of inventory slots that are available. Use the constant

inv:max

to restore the maximum value. The number you give will be rounded up to the nearest multiple of 3.
getinventorysize

## Equipment

unequip (hero, slot)
unequip
Removes the item that the specified hero has equipped in the specified slot. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use findhero if you want to refer to the hero by name). The second argument is the slot to unequip. Use the slot:weapon, slot:armor, etc. constants from your .hsi file.

When a hero's equipment changes, the current values of all stats other than HP and MP for the hero are reset to their new maximum values. The current values of the HP and MP stats are capped to the new maximums but not otherwise changed. If you want to cause the HP and MP to be scaled up or down proportionally (so that e.g. 8/10 HP becomes 16/20 HP), the easiest way to do that is to make use of a side-effect of gainherostat: gain hero stat(who, stat:hp, 0) gain hero stat(who, stat:mp, 0)

forceequip
checkequipment
force equip (hero, slot, item)
force equip
Forces a hero to equip an item, even if it is not normally equipable. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use findhero if you want to refer to the hero by name). The second argument is the slot to equip. Use the slot:weapon, slot:armor, etc. constants from your .hsi file. The third argument is the item to equip. You can use the item's number or the item:name constants from your .hsi file. The item quipped will be taken from your inventory, but if you

force equip

an item that you do not already have then a free copy of it will be created.

When a hero's equipment changes, their current HP and MP stats aren't updated. See the Note at unequip for more information.

unequip
equipwhere
checkequipment
equip where (hero, item)
equip where
Returns the number of the slot that a hero can equip an item in (a constant of the form slot:weapon, etc, in your .hsi file), or false if the hero cannot equip it. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use findhero if you want to refer to the hero by name). The second argument is the item to check the equipability of. You can use the item's number or the item:name constants from your .hsi file. If the item can be equipped in more than one different slot, this command only returns the first valid slot.

When a hero's equipment changes, their current HP and MP stats aren't updated. See the Note at unequip for more information.

unequip
checkequipment
check equipment (hero, slot)
check equipment
Returns the number of the item that the specified hero has equipped in the specified slot, or -1 if there is nothing equipped there. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use findhero if you want to refer to the hero by name). The second argument is the slot to check. Use the slot:weapon, slot:armor, etc. constants from your .hsi file.
forceequip
unequip
equipwhere
get default weapon (hero)
get default weapon
Returns the number of the item that the specified hero uses as a default weapon when no other weapon is equipped. The argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use findhero if you want to refer to the hero by name).
set default weapon (hero, item)
set default weapon
Changes the item that the specified hero uses as a default weapon when no other weapon is equipped. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use findhero if you want to refer to the hero by name). The second argument is the item to use as the new default weapon. You can use the item's number or the item:name constants from your .HSI file.

# Effects

## Music

play song (song)
play song
Plays the specified song. Use the constants defined in your HSI file. They appear in the form of song:name
current song
current song
Returns the number of the currently playing song, or -1 if none.
stop song
stop song
Stops whatever music is currently playing.
set victory music (song)
set victory music
Changes the after-battle victory music to the specified song. Use the constants defined in your HSI file. They appear in the form of song:name
get victory music
get victory music
Returns the number of the after-battle victory music. Compare with the constants defined in your HSI file. They appear in the form of song:name
set ambient music (song)
set ambient music
Plays a song and sets it as the map's ambient music, that is the song that is played when you enter the map (if you call savemapstate with mapstate:all or mapstate:mapsettings) or after a textbox with 'restore music' set. Unless you save the mapstate, the effect goes away if you change maps or fight a battle. You can use the constants song:silence and song:sameaslastmap for

song

, the default is silence.
playsong
get ambient music
get ambient music
Returns the song number of the map's ambient music, either a song ID or the constants song:silence or song:sameaslastmap.
currentsong
set music volume (volume)
set music volume
Sets the volume at which music is played,

volume

being a number on the scale of 0 to 255, 0 being silent, 255 loudest. This is the same as the Volume setting in the in-game menu. If you want to manipulate the sound (e.g. fading out the music) you should take note of the original volume that the player has set and return to this later. The default volume is not the maximum 255, so you should not hardcode fades to begin at volume 255.

The actual resolution at which the volume is set is not necessarily 1/255th of full volume but depends on the engine version. For example, music_sdl only supports 128 different volume levels. So if you set the volume and then read it back, it might change slightly.

get music volume
get music volume
Returns the volume at which music is played, on a scale of 0 to 255, 0 being silent, 255 loudest. This is the same as the Volume setting in the in-game menu.

## Master Palette and Screen Fades

Everything displayed on-screen uses colors from a 256-color master palette. Screen fading works by momentarily changing the colors in the palette, for example shifting them all to black. The screen fade commands are a very common source of confusion because they pause the engine during the fade, and don't redraw the screen at all. Instead, what is already on-screen (which was drawn in the previous game tick) is re-displayed with a new palette. So fade screen out show backdrop (1) fade screen out will not work as expected: the screen fades out, then it fades back in, then the backdrop appears instantly. You need to add a wait(1) immediately after the showbackdrop so that the engine repaints the screen (still entirely black) with the backdrop before it fades the backdrop into view. This works because there's both a 'visible' master palette and a 'loaded' one. fadescreenout smoothly changes the visible one to be all the same color but doesn't modified the loaded one. fadescreenin changes the visible one smoothly back to the loaded one. loadpalette, tweakpalette, writecolor, etc modify the loaded palette but not the visible one. You need to call either fadescreenin or updatepalette to copy the loaded palette to the visible one to make your changes visible. updatepalette instantly changes the visible palette to the loaded one. For example, this means you can fade between two different master palettes like so: load palette(2) fade screen in
fade screen out (red, green, blue)
fade screen out
Fades the screen to a solid color. If you do not specify any arguments, the screen will fade to black. The red, green, blue values are numbers from 0 to 63 that tell how bright that particular color should be. (63,0,0) would be blood red. (40,0,40) would be purple. (63,63,63) would be bright white. The screen will remain faded out until you run fadescreenin, fight a battle, or use a door.
fade screen in
fade screen in
Fades the screen back to normal after a fadescreenout command, or applies the changes made with other palette commands such as greyscalepalette, tweakpalette, resetpalette, and writecolor.
load palette (palette number)
load palette
Loads a different master palette (one of the palettes on the "View Master Palettes..." menu), and the user interface colors for that palette. Use this if a backdrop or entire map was imported/drawn with a palette other than the default. Changes to the palette do not take effect until you call updatepalette or fadescreenin, however the UI colors are changed immediately.
update palette
update palette
Instantly returns from fade screen out, and applies changes made by other palette command such as greyscalepalette, tweakpalette, resetpalette, and writecolor.
greyscale palette (first, last)
greyscale palette
Converts a section of the master palette from color to greyscale. The two arguments determine what range of colors will be affected. If called with no arguments, the entire palette is affected. Changes do not take effect until you call updatepalette or fadescreenin. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-load plotscript trigger.
tweak palette (red, green, blue, first, last)
tweak palette
Color-adjusts a section of the master palette. The first three arguments are the changes to make to the red, green, and blue values of each palette color. For example, tweak palette (20,-30,0) would redden everything, and drop out most of the green. These arguments expect values in the range -63 to 63, NOT -255 to 255. The last two arguments determine what range of colors will be affected. If they are left out, the entire palette is affected. Changes do not take effect until you call updatepalette or fadescreenin. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-load plotscript trigger.
reset palette
reset palette
Reloads the default master palette and its user interface colors, undoing any changes you have made with other palette-altering commands such as tweakpalette or greyscalepalette. Changes to the palette do not take effect until you call updatepalette or fadescreenin. However the UI color indices (those in the 'Change User-Interface Colors' menu) are changed immediately (if you're not using multiple master palettes, then UI color indices never change).
read color (index, element)
read color
Returns a color value from the master palette, in the range 0 to 63. The first argument is the index in the palette to read from, 0 to 255. The second argument is the color value to read, red, green, or blue. You can use 0,1, and 2, or you can use the predefined constants colorred, colorgreen, and colorblue. The counterpart to this is writecolor.

This command converts color components from the usual 0-255 down to 0-63, for compatibility with old OHRRPGCE versions which ran on DOS! For operation on full color values (0-255), use getcolor.

getcolor
write color (index, element, value)
write color
Writes a color value into the master palette. The first argument is the index in the palette to write to, 0 to 255. The second argument is the color value to write, red, green, or blue. You can use 0, 1, and 2, or you can use the predefined constants colorred, colorgreen, and colorblue. The third argument is the color value to write. It should be in the range of 0 to 63, NOT 0 to 255 as is used in nearly all computer programs. Use setcolor if you want to set color values in the 0-255 range. Changes do not take effect until you call updatepalette or fadescreenin. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-loadgame plotscript trigger.
setcolor
readcolor
get color (index)
get color
Returns a color value from the master palette. The argument is which index in the palette to return. The value is a 32-bit number representing the red, green and blue components of the palette entry. See rgb for more details on its format.
setcolor
extractcolor
set color (index, value)
set color
Updates the master palette with a new 32-bit color. The

value

, a 32-bit number representing the red, green and blue components of the color, can come from rgb or getcolor. Changes do not take effect until you call updatepalette or fadescreenin. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-loadgame plotscript trigger.
getcolor
rgb
find color (r, g, b, searchstart)
find color
Searches the master palette for the color most similar to the given

r

,

g

,

b

triple and returns its index, from 0 to 255. The color is selected using an approximate perceptual distance function.

r

,

g

,

b

should be in the range 0-255 (but out-of-bounds values are allowed, which weights those colors even more heavily). The

searchstart

argument is optional, and defaults to 0. It says how many colors at the beginning of the palette to ignore. For example, if

searchstart

is 1, then color 0 will never be returned, which is useful because 0 is often used as the transparent color.
RGB (red, green, blue)
RGB
Combines the individual red, green and blue components of a color into a single 32-bit number. The formula used is "red * 256 * 256 + green * 256 + blue". The highest byte is unused, but reserved for future potential use for alpha transparency.
extractcolor
extract color (color, component)
extract color
Takes a 32-bit color value (as returned by getcolor), and extracts the red, green or blue component, based on the

component

parameter. You may use the colorred, colorgreen and colorblue parameters to choose which one.
rgb

## Sound Effects

play sound (num, loop, preempt)
play sound
Plays or resumes a sound effect. Pass true to

loop

if you want the sound effect to start over when it finishes instead of stopping (it defaults to false). Pass true to

preempt

if you want to automatically stop the sound before playing it. If

preempt

is false (which is the default), and the sound is already playing (and not paused) then this command will do nothing.

There isn't yet a way to play a sound effect twice at the same time.

stopsound
stop sound (num)
stop sound
Stops a sound effect. If the sound is not playing, nothing will happen.
playsound
pause sound (num)
pause sound
Temporarily stops a sound effect. It can be resumed with playsound, which causes it to continue from whence it left off.
playsound
sound is playing (num)
sound is playing
Checks to see whether a sound effect is playing or not. Useful for synchronization, etc. Returns true if the sound is paused but not stopped.
playsound
stopsound
waitforsound
wait for sound (num)
wait for sound
Waits until a sound effect has finished playing. Useful for synchronization, etc.
soundisplaying

# Hero Data

rename hero (who)
rename hero
Pops up a name-editing box that allows you to change a hero's name. The argument is the hero's ID number, or name in the format hero:name. The return value is true if the player renamed the hero, or false if they cancelled.
rename hero by slot (who)
rename hero by slot
Pops up a name-editing box that allows you to change a hero's name. The argument is the hero's position in the party as returned by findhero. The return value is true if the player the hero renamed, or false if they cancelled.

## Hero Graphics

set hero picture (who, picture, type)
set hero picture
Permanently changes a hero's picture. The first argument is the hero's position in the party. (Use findhero if you want refer to the hero by name.) The second argument is the index number of the picture to use, and the last argument is a constant insidebattle or outsidebattle or heroportrait, which determines if you are changing the hero's battle picture or their walkabout picture or their portrait. If the last argument is left out, outsidebattle is assumed.
resetheropicture
set hero palette (who, palette, type)
set hero palette
Permanently changes a hero's 16-color palette. The first argument is the hero's position in the party. (Use findhero if you want refer to the hero by name.) The second argument is the index number of the 16-color palette to use, and the last argument is a constant insidebattle or outsidebattle or heroportrait, which determines if you are changing the hero's battle palette or their walkabout palette or their portrait palette. If the last argument is left out, outsidebattle is assumed.
resetheropalette
get hero picture (who, type)
get hero picture
A function that returns the index number of a hero's picture. The first argument is the hero's position in the party as returned by findhero. The second argument is a constant insidebattle or outsidebattle or heroportrait, which determines if you are checking the hero's battle picture or their walkabout picture or their portrait. If the second argument is left out, outsidebattle is assumed.
get hero palette (who, type)
get hero palette
A function that returns the index number of a hero's 16-color palette. The first argument is the hero's position in the party as returned by findhero. The second argument is a constant insidebattle or outsidebattle or heroportrait, which determines if you are checking the hero's battle palette or their walkabout palette or their portrait palette. If the second argument is left out, outsidebattle is assumed.
reset hero picture (who, type)
reset hero picture
Resets a hero's picture that was previously changed with setheropicture back to the default picture. The first argument is the hero's position in the party. (Use findhero if you want refer to the hero by name). The second argument is a constant insidebattle or outsidebattle or heroportrait, which determines if you are resetting the hero's battle picture or their walkabout picture or their portrait. If the last argument is left out, outsidebattle is assumed.
setheropicture
reset hero palette (who, type)
reset hero palette
Resets a hero's palette that was previously changed with setheropalette back to the default palette. The first argument is the hero's position in the party. (Use findhero if you want refer to the hero by name.) The second argument is a constant insidebattle or outsidebattle or heroportrait, which determines if you are resetting the hero's battle palette or their walkabout palette or their portrait palette. If the last argument is left out, outsidebattle is assumed.
setheropicture

## Hero Hand Position

get hero hand x (who, frame)
get hero hand x
Get the x position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants

hand:Attack A

and

hand:Attack B

getherohandx
getherohandy
setherohandx
setherohandy
getdefaultherohandx
getdefaultherohandy
get hero hand y (who, frame)
get hero hand y
Get the y position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants

hand:Attack A

and

hand:Attack B

getherohandx
getherohandy
setherohandx
setherohandy
getdefaultherohandx
getdefaultherohandy
set hero hand x (who, frame, new x)
set hero hand x
Change the x position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants

hand:Attack A

and

hand:Attack B

The third argument is the new x position.
getherohandx
getherohandy
setherohandx
setherohandy
getdefaultherohandx
getdefaultherohandy
set hero hand y (who, frame, new y)
set hero hand y
Change the y position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants

hand:Attack A

and

hand:Attack B

The third argument is the new y position.
getherohandx
getherohandy
setherohandx
setherohandy
getdefaultherohandx
getdefaultherohandy
get default hero hand x (who, frame)
get default hero hand x
Get the original x position of a hero's weapon hand in battle as specified in the hero editor. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants

hand:Attack A

and

hand:Attack B

getherohandx
getherohandy
setherohandx
setherohandy
getdefaultherohandx
getdefaultherohandy
get default hero hand y (who, frame)
get default hero hand y
Get the original y position of a hero's weapon hand in battle as specified in the hero editor. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants

hand:Attack A

and

hand:Attack B

getherohandx
getherohandy
setherohandx
setherohandy
getdefaultherohandx
getdefaultherohandy

## Hero Stats

get hero stat (who, stat, type)
get hero stat
A function that returns one of a hero's stats. The first argument is the position of the hero you want to check in your party as as returned by findhero. The second argument is the name of the stat that you want to check. The names of the stats are defined in your HSI file in the form stat:name. The third argument is either currentstat or maximumstat or basestat. Follow those links for explanations. If you leave out the type, currentstat will be assumed.
setherostat
gainherostat
getlevelmp
getherolevel
totalexperience
herototalelementalresistasint
setenemystat
getenemystat
set hero stat (who, stat, value, type)
set hero stat
A command that changes one of a hero's stats. The first argument is the position of the hero you want to change in your party as returned by find hero. The second argument is the name of the stat that you want to change. The names of the stats are defined in your HSI file in the form stat:name. The third argument is the new value of the stat. The last argument is either currentstat or maximumstat or basestat. Follow those links for explanations. If you leave the last argument blank, currentstat will be assumed. You can set the current value of a stat to more than the maximum value. If you want to permanently change a stat you would change both the current value and just one of either the maximum value or the base value.

Cap stats are ignored by this command. Use setcappedherostat if you want to limit the current or maximum value of a stat to a cap. But the stat will be capped later due to certain events such as equipping or unequipping an item, levelling up, or using setherostatcap. Caps don't apply to base stats.

The maximum and base values of a stat are tied together. Modifying the max will always modify the other by the same amount.

If you want to increase or decrease a stat by a certain amount, just use gainherostat.

# Use this script to reset a stat to its max value script, reset stat, hero slot, stat, begin set hero stat(hero slot, stat, get hero stat(hero slot, stat, maximum stat), current stat) end
# Use this script to permanently increase (or decrease, if amount is negative) a stat, without violating stat caps script, adjust stat, hero slot, stat, amount, begin set capped hero stat(hero slot, stat, get hero stat(hero slot, stat, current stat) + amount, current stat) set hero stat(hero slot, stat, get hero stat(hero slot, stat, base stat) + amount, base stat) end
gainherostat
getherostat
setcappedherostat
setherostatcap
setenemystat
getenemystat
gain hero stat (who, stat, amount, reset to max)
gain hero stat
Increase or decrease one of a hero's stats. The base, maximum and current value of the stat are all changed, consistently. The first argument who is the position in your party of the hero you want to change, as returned by findhero. The second argument is the name of the stat that you want to change. The names of the stats are defined in your HSI file in the form stat:name, such as stat:hp. The third argument is the amount to change the stat; it will be added to the base value and maximum value of the stat. The optional fourth argument reset to max says how the current value of the stat should be updated. If false (which is the default), the current value will be set so that it's the same percentage of the max before and after. For example, 8/10 HP become 12/15 HP. If reset to max is true, then the current value is set equal to the max. The maximum and current stat values are capped to the stat cap, if any. (Base stats are by definition not capped.)
getherostat
setherostat
setcappedherostat
setherostatcap
set capped hero stat (who, stat, value, type)
set capped hero stat
A command that changes one of a hero's stats. The first argument is the position of the hero you want to change in your party as returned by find hero. The second argument is the name of the stat that you want to change. The names of the stats are defined in your HSI file in the form stat:name. The third argument is the new value of the stat. Unlike setherostat, if you try to set a stat to a value larger than the stat cap it will be reduced to the stat cap (without an error). The last argument is either currentstat or maximumstat (basestat will also work but will not be capped). If you leave the last argument out, currentstat will be assumed.
setherostat
getherostatcap
setherostatcap
gainherostat
get hero stat cap (stat)
get hero stat cap
A function that returns the maximum allowed value for a hero stat (as set in the Stat Caps menu in Custom). The argument is the stat you want to check; one of the stat:name constants defined in your HSI file. If the return value is 0 or false there is no stat cap for that stat.
setcappedherostat
setherostatcap
set hero stat cap (stat, value)
set hero stat cap
Set the maximum allowed value for a hero stat. The

stat

argument is the stat to affect; one of the stat:name constants defined in your HSI file. The

value

argument should be either greater than zero to set a cap, or 0/false to remove the cap for that stat.

The new cap comes into immediate force: the current and maximum values of all stats of all heroes in the party are capped according to the caps. In addition, the current values of all stats other than HP and MP for all heroes are reset to their new maximum values. The current values of the HP and MP stats are not otherwise changed aside from being capped, so you might like to check and scale up HP and MP of heroes if the new max is more than the old cap.

getherostatcap
get level MP (who, mp level slot, type)
get level MP
Returns a hero's level MP (FF1-style MP). The argument

who

is the hero's position in the party, as returned by findhero. The argument

mp level slot

is a number from 0 to 7 that represents a row of spells in the hero's spell list (the level is NOT counted from 1 to 8, as it's displayed in-game and in the spell-list editor!) The optional third argument is either currentstat or maximumstat. If you leave out the type currentstat will be assumed. Pass maximumstat instead to get the hero's maximum amount of level MP for that slot. The maximum depends only on the hero's experience level.
set level MP (who, mp level slot, new value)
get level MP
Changes a hero's level MP (FF1-style MP). The argument

who

is the hero's position in the party, as returned by findhero. The argument

mp level slot

is a number from 0 to 7 that represents a row of spells in the hero's spell list (the level is NOT counted from 1 to 8, as it's displayed in-game and in the spell-list editor!) The argument

new value

is the new number of level MP points. Each point represents one spell from that row.
hero base elemental resist as int (who, element)
hero base elemental resist as int
Gets the 'intrinsic' amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. (That is, the value entered in the 'Elemental Resistances' menu in Custom. Equipment elemental modifiers are added onto this value.) The argument

who

is the hero's position in the party, as returned by findhero. The argument

element

is a number from 0 to whatever the highest enabled element is. The result is rounded to the nearest integer. For example, if the hero takes 2.6% damage (1/40 normal), then the result will be 3.

When floating point support is added to HamsterSpeak, an alternative to this command will be added.

setherobaseelementalresist
herototalelementalresistasint
set hero base elemental resist (who, element, percent)
set hero base elemental resist
Sets the 'intrinsic' amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. (That is, the value entered in the 'Elemental Resistances' menu in Custom. Equipment elemental modifiers are added onto this value.) The argument

who

is the hero's position in the party, as returned by findhero. The argument

element

is a number from 0 to whatever the highest enabled element is. The argument

percent

is the percentage (written without a percent sign). For example -50 means the hero is healed by 50% of the attack damage instead of being hurt.

Unlike the elemental resist editors in Custom, you can't use fractions of a percent here.

herobaseelementalresistasint
hero total elemental resist as int (who, element)
hero total elemental resist as int
Gets the amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. The argument

who

is the hero's position in the party, as returned by findhero. The argument

element

is a number from 0 to whatever the highest enabled element is. The result is rounded to the nearest integer. For example, if the hero takes 2.6% damage (1/40 normal), then the result will be 3. This is the value calculated from the hero's 'intrinsic' resistances combined with the equipment they are wearing.

When floating point support is added to HamsterSpeak, an alternative to this command will be added.

herobaseelementalresistasint

### Experience and Levels

get hero level (who)
get hero level
A function that returns a hero's current level. The argument is the position of the hero you want to check in your party as as returned by findhero. The return value with be your current level, from 0 to 99
setherolevel
totalexperience
set hero level (who, level, forgetspells)
set hero level
A command that sets a hero's current level. The first argument is the position of the hero you want to change in your party as as returned by findhero. You can specify any hero in the active or reserve party and any (non-negative) level (even above the level cap). Unlike old workarounds, this command teaches the hero any spells they would have learnt by that level and correctly sets the experience to next level-up (experience gained to the current next level is lost). You can also decrease the hero's level, which will cause spells to be forgotten, unless the optional 3rd argument (defaulting to true) is set as false.
getherolevel
herolevelled
spellslearnt
setexperience
set experience (who, experience, allowforget)
set experience
Sets a hero's total experience and updates their experience level, stats and spell list. The argument is the position of the hero you want to check in your party as as returned by findhero. To decrease a hero's level without forgetting spells which are learnt at a certain experience level, pass false as the optional third argument. Heroes won't level beyond the level cap (which is 99 usually), though you can temporarily raise the cap using setlevelcap to get around this.
setherolevel
totalexperience
herolevelled
spellslearned
hero levelled (who)
hero levelled
Returns the number of levels the specified hero gained.

who

is the hero's position in the battle party. If you want to use

hero:Name

you should use findhero. This command only applies to the most recent battle or giveexperience, setherolevel or setexperience command that targeted either this hero (or who party) - levels gained from previous battles or commands are forgotten. If the hero lost levels, the result is negative. In other words, this does not return true or false, but can be be used in an if statement like:
give experience (party, 50) if (herolevelled (find hero (hero: Bob))) then ( $31="Bob gained " append number(31, hero levelled (find hero (hero: Bob))) $31+" level(s)!" show textbox (233) # ${S31} :show string 31 )
total experience (who)
total experience
Returns a hero's total experience. The argument is the position of the hero you want to check in your party as as returned by findhero.
setexperience
experience to next level (who)
experience to next level
Returns experience required by a hero to reach the next level. The argument is the position of the hero you want to check in your party as as returned by findhero.
experience to level (level, hero slot)
experience to level
Returns the total experience required to reach a specified level from level 0. The second argument is a hero slot. Different heroes may have different experience curves. If the

hero slot

argument is left out, then the default experience curve will be used.
give experience (hero, amount)
give experience
Gives experience to either a hero by position in party (use result returned by findhero command if you want to give experience by name or ID) or the whole party, if the constant party is passed as first argument. If you give experience to the whole party, then it will be split amongst the heroes as it is in battle; dead heroes get experience depending on whether the "Dead heroes gain share of experience" general bitset is set, and swapped out heroes gain according to the options in the Battle System Options menu. This command can cause heroes to level up and learn spells but does not inform the player or trigger any effects. See herolevelled and spellslearned for dealing with this. This command can give negative experience, but it will never cause a hero to delevel. You should use setexperience to remove experience in a way that allows delevelling. You can't give experience to heroes with level equal to or greater than the level cap (which is 99 usually), though you can temporarily raise the cap using setlevelcap to get around this.

## Hero's Spells

teach spell (hero, attack)
teach spell
Tries to teach a hero a spell. This only works when the spell is set to "learned from item" in one of the hero's spell lists; it will not work for spells learned based on level. The first argument is the hero's position in the party (as returned by findhero). The second argument is the attack to learn. You can use the names defined in your .HSI file in the form atk:attackname. (You may also use the attack's ID number. This is the number you see in the attack editor + 1.) If the hero was taught the spell, teach spell will return true, or if the hero cannot learn the spell (perhaps because they already know it) it will return false. Use writespell to add a spell to a spell list without restriction.
forget spell (hero, attack)
forget spell
Causes a hero to forget a spell. The first argument is the hero's position in the party (as returned by findhero). The second argument is the attack to forget. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero does not know the spell, nothing happens.
read spell (hero, list, slot)
read spell
Returns the ID number of a chosen spell slot, or 0 (false) if there is no spell in that slot. The first argument is the hero's position in the party (as returned by findhero). The second argument is the number of the spell list to check. This is a value from 0 to 3. The third argument is the slot to check. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on.
write spell (hero, list, slot, attack)
write spell
Forces a hero to learn a particular spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the spell list to put the spell in. This is a number from 0 to 3. The third argument is the slot to put the spell in. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on. The last argument is the attack to put in the spell list. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). You can also erase a spell by writing 0 or none as the attack ID. Note that this command will overwrite and replace any spell that is already in that slot. If you overwrite a slot that can normally learn another spell, you will never learn that other spell (unless you first erase the spell you wrote there)
knows spell (hero, attack)
knows spell
Checks to see if a hero already knows a spell. The first argument is the hero's position in the party (as returned by findhero). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero knows the spell, knows spell will return true. If the hero does not know the spell, it will return false
can learn spell (hero, attack)
can learn spell
Checks to see if a hero is capable of learning a spell from an item or from the teach spell command. The first argument is the hero's position in the party (as returned by findhero). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero can learn the spell, can learn spell will return true. If the hero cannot learn the spell (or learns it from level-ups), it will return false
spells learnt (hero, number)
spells learnt
zenzizenzic
This is deprecated, do not use it. It is identical to spellslearned except it returns the id numbers of spells, instead of the id numbers +1. The attack constants exported in your .hsi file are all +1 the attack IDs in Custom.
spells learned (hero, number)
spells learned
Returns the id numbers (+1) of spells the hero learned from the last battle or giveexperience, setherolevel or setexperience command that targeted either this hero or the whole party. If the second argument is getcount then the number of spells that the hero learned is returned. Pass 0 for number to get the first spell learnt, 1 to get the second, etc. You can use a loop and strings to list to the player all the spells a hero learned:

If you want to use this command with attack ID numbers, you must add 1 to the ID number.

# the following script uses strings 0, 1, 2 for its use (will be overwritten) plotscript, print learned spells, who=0, begin variable(i) get hero name (1, who) # construct the static part of the text in string 1 $1+" learned spell " for (i, 0, spells learned (who, get count) -- 1) do ( read attack name (2, spells learned (who, i)) # get the i-th spell learnt 0 $= 1 # copy the static part to the displayed string 0 $+ 2 # combine with the spell name show string at (0, 160, 100) wait for keypress (anykey) ) hide string (0) end
update level up learning(who, allowforget)
update level up learning
Update a hero to make sure they know the spells they are supposed to have learned for their current level. The

who

is the hero's position in the battle party. You can optionally pass false as the

allowforget

argument if you want to make sure the hero will not forget any spells that they are not supposed to know yet. This command is most useful for situations where you are manipulating the hero's level, and for some reason do not want to use setherolevel which automatically handles spell learning. This command can also be handy when playtesting a game in progress, since it can be used to make sure that heroes loaded from a saved-game will learn spells that did not exist yet at the time when they got their last level-ups.

## Out-of-battle Attacks

outside battle cure (attack minus 1, target, attacker)
outside battle cure
zenzizenzic
Obsolete, replaced by mapcure. This is identical to mapcure except for the

attack

argument differing by one.
map cure (attack, target, attacker)
map cure
Uses an attack on a hero outside of battle as if you had used it from an item or cast it as a spell. In spite of the name, it works for both cure spells and damage spells. The first argument,

attack

is name of the attack from your HSI file in the form atk:name. (You may also use the attack's ID number. This is the number you see in the attack editor + 1.) The second argument,

target

is the position in the party of the hero to cure (or harm). The third optional argument,

attacker

is the position in the party of the hero who is using the attack. If this argument is omitted or set to -1, then the average stats of the active party will be used, just like when the attack is used from an item. The return value is true if the cure/attack succeeded, and false if it did nothing.

The

map cure

command replaces the old command

outside battle cure

which had a bug which required you to use

atk:name -- 1

instead of

atk:name

for the

attack

argument.

If the attack results in all the heroes in the party being dead (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

If you want to cure a hero that has 0 HP with an attack, then the attack's Target Class needs to be set to something that allows targetting dead heroes. Otherwise the attack doesn't happen and this command returns false. Other Target settings, including "Spread Attack", are ignored.

useitem
setherostat
setdeathscript

# NPC Data

alter NPC (who, NPCstat, value)
alter NPC
Changes the stats of an NPC type. alter NPC can be used for many purposes. The following constants for this command are available:

- alter NPC (who,NPCstat:picture,picture number)
- alter NPC (who,NPCstat:palette,palette number) Set the palette number to -1 to use the default palette.
- alter NPC (who,NPCstat:move type,move type code) Available move types:
  - NPCmovetype:standstill
  - NPCmovetype:wander
  - NPCmovetype:pace
  - NPCmovetype:rightturns
  - NPCmovetype:leftturns
  - NPCmovetype:randomturns
  - NPCmovetype:chaseyou (aka NPCmovetype:chaseyoumeandering)
  - NPCmovetype:chaseyoudirect
  - NPCmovetype:avoidyou (aka NPCmovetype:avoidyoumeandering)
  - NPCmovetype:avoidyoudirect
  - NPCmovetype:walkinplace
  - NPCmovetype:followwallsright
  - NPCmovetype:followwallsleft
  - NPCmovetype:followwallsrightstopsforothers
  - NPCmovetype:followwallsleftstopsforothers
  - NPCmovetype:chaseyoupathfinding
- alter NPC (who,NPCstat:move speed,speed)
- alter NPC (who,NPCstat:display text,text box number)
- alter NPC (who,NPCstat:when activated,when activated code) Available whenactivated codes:
  - NPCwhenactivated:changedirection
  - NPCwhenactivated:faceplayer
  - NPCwhenactivated:donotfaceplayer
- alter NPC (who,NPCstat:give item,item number + 1) ... Note that the item number is offset + 1. A zero means no item.
- alter NPC (who,NPCstat:pushability,pushability code) Available pushability codes:
  - NPCpush:off
  - NPCpush:full
  - NPCpush:horizontal
  - NPCpush:vertical
  - NPCpush:uponly
  - NPCpush:rightonly
  - NPCpush:downonly
  - NPCpush:leftonly
- alter NPC (who,NPCstat:activation,activation code) Available activation codes:
  - NPCactivation:use
  - NPCactivation:touch
  - NPCactivation:stepon
- alter NPC (who,NPCstat:onetime use flag,onetime flag ID) The onetime flag (see checkonetime) is zero if the NPC is usable repeatedly.
- alter NPC (who,NPCstat:tag1,tag ID)
- alter NPC (who,NPCstat:tag2,tag ID) These are two tag conditions which both have to be true for the NPC to appear. A tag ID of 0 means no check is done (the condition is true). A positive condition means that tag needs to be ON, a negative means that tag needs to be OFF. For example, tag1 = -4 and tag2 = 0 means the NPC appears only when tag 4 is OFF.
- alter NPC (who,NPCstat:script,script ID)
- alter NPC (who,NPCstat:script argument,number)
- alter NPC (who,NPCstat:vehicle,vehicle ID+1)
- alter NPC (who,NPCstat:default movement zone,zone ID)
- alter NPC (who,NPCstat:default avoidance zone,zone ID)
- alter NPC (who,NPCstat:ignore passmap, true or false) This is for the NPC editor setting, not the setnpcignoreswalls command.
- alter NPC (who,NPCstat:pathfinding rule,rule) The rule (see the F1 help page for the NPC editor for more info) is one of:
  - pathfinding:default
  - pathfinding:npcs obstruct
  - pathfinding:npcs ignored

Normally you would only give an NPC ID number to alter NPC, but if you want to use an npcreference it will still work. Just remember that alter NPC changes every copy of the NPC on the map, not just the specific one you referenced. A good way to make use of alter NPC is to wrap it in your own script. For example: # Example alter NPC wrapper for changing NPC appearance # Palette -1 means the default palette. plotscript, change NPC, who, picture, palette = -1, begin alter NPC(who, NPCstat:picture, picture) alter NPC(who, NPCstat:palette, palette) end
setnpcusable
setnpcmoves
setnpcignoreswalls
setnpcobstructs
read NPC (who, NPCstat)
read NPC
Returns data such as picture, palette, walking speed, text box, etc. for an NPC. Use the same constants as alternpc.

If you use this command to read the give item number, the result is offset + 1. A zero means no item.

alternpc
set NPC ignores walls (who, value)
set NPC ignores walls
Given an npcref or npcid (in which case the first NPC with that ID is used), set whether that NPC can walk through walls, including off the edge of a map, and violating its zone restrictions.

value

should be true or false. Turning this on doesn't let the NPC walk through the lead hero and other NPCs; you need setnpcobstructs for that. This command is just like suspendnpcwalls/resumenpcwalls, but only affects a single npc.

Don't confuse this with alternpc(who, NPCstat:ignore passmap, value), which sets whether an NPC ID can pass through walls on the wallmap, but doesn't allow it to ignore zones or walk off the map.

getnpcignoreswalls
suspendnpcwalls
setnpcobstructs
alternpc
get NPC ignores walls (who)
get NPC ignores walls
Given an npcref or npcid (in which case the first NPC with that ID is used), returns whether that NPC can walk through walls.

Don't confuse this with readnpc(who, NPCstat:ignore passmap), which tells whether an NPC ID can pass through walls on the wallmap, but doesn't allow it to ignore zones or walk off the map.

setnpcignoreswalls
readnpc
set NPC moves (who, value)
set NPC moves
Given an npcref or npcid (in which case the first NPC with that ID is used), set whether that NPC moves according to its move-type, or whether it stands still and waits for you to control it with walknpc.

value

should be true or false. This command is just like suspendnpcs/resumenpcs, but only affects a single npc.

If you set an NPC to not move by itself, it will still complete its current step, moving the rest of the way to the next tile.

getnpcmoves
suspendnpcs
alternpc
get NPC moves (who)
get NPC moves
Given an npcref or npcid (in which case the first NPC with that ID is used), returns true or false indicating whether that NPC moves according to its move-type, or whether it is suspended. This is always true, even for "Stand Still" NPCs unless setnpcmoves has been used.
setnpcmoves
readnpc
set NPC obstructs (who, value)
set NPC obstructs
Given an npcref or npcid (in which case the first NPC with that ID is used), set whether the NPC should be an obstruction to heroes and other NPCs. If set to false, the NPC can move through heroes and other NPCs and vice-versa. Heroes can always pass through Step-on NPCs.

value

should be true or false. This command is almost like suspendobstruction/resumeobstruction, but it only affects a single npc and it doesn't stop activation of step-on NPCs.

If you want to allow an NPC to walk through all obstacles, you also need to use the setnpcignoreswalls command.
getnpcobstructs
suspendobstruction
get NPC obstructs (who)
get NPC obstructs
Given an npcref or npcid (in which case the first NPC with that ID is used), returns false if that NPC's obstruction has been suspended with setnpcobstructs (and is always true otherwise).
setnpcobstructs
set NPC usable (who, value)
set NPC usable
Given an npcref or npcid (in which case the first NPC with that ID is used), set whether the NPC can be activated by the player as normal (as defined in the NPC ID data). usenpc will still work on the NPC.

value

should be true or false.
getnpcusable
alternpc
get NPC usable (who)
get NPC usable
Given an npcref or npcid (in which case the first NPC with that ID is used), returns false if normal activation of that NPC has been suspended with setnpcusable. This is always true otherwise, even for NPC types which are not activatable.
setnpcusable

# Enemy and Formation Functions

get enemy stat(enemy, stat)
get enemy stat
Returns the selected stat from the selected enemy. The first argument is the number of the enemy whose stats you want to check. The second argument is the name of the stat that you want to check. The names of the stats are defined in your HSI file in the form stat:name.
setenemystat
enemyelementalresistasint
getherostat
setherostat
set enemy stat(enemy, stat, value)
set enemy stat
Sets the selected stat of the selected enemy to the value you supply. The first argument is the number of the enemy whose stats you want to set. The second argument is the name of the stat that you want to set. The names of the stats are defined in your HSI file in the form stat:name. The third is the new value of the stat.

Enemy stat changes are temporary. They are not saved in the game save.

getenemystat
getherostat
setherostat
enemy elemental resist as int (enemy, element)
enemy elemental resist as int
Gets the amount of damage that an enemy receives from attacks of a certain element, as a percentage of normal. The argument

enemy

is the enemy's ID number. The argument

element

is a number from 0 to whatever the highest enabled element is. The result is rounded to the nearest integer. For example, if the enemy takes 2.6% damage (1/40th normal), then the result will be 3.

When floating point support is added to HamsterSpeak, an alternative to this command will be added.

getenemystat
herototalelementalresistasint
get enemy name (enemyid, stringid)
get enemy name
Lets you use the enemy name in a string. The first argument is the number of the enemy you want to get the name from, second argument is the number of the string that you want to store the name of the enemy.
setenemyname
set enemy name (enemyid, stringid)
set enemy name
Lets you set the enemy name from a string, the string length cannot be more then 16 characters, if it is more then 16 the name will be truncated. The first argument is the number of the enemy's name you want to change, second argument is the number of the string that you supply the name of the enemy from.

Enemy name changes are temporary. They are not saved in the game save.

getenemyname
get enemy appearance (enemyid, appearance)
get enemy appearance
Returns data on the appearance of a enemy. Enemyid is the enemy number that you want to return the appearance of, appearance is either picture, palette, or size. You can use the following constants for appearance:

- enemy:picture
- enemy:palette
- enemy:picturesize

You can compare the values returned from enemy:picturesize with the constants enemysize:small, enemysize:medium and enemysize:large.
setenemyappearance
set enemy appearance (enemyid, appearance,value)
set enemy appearance
Lets you change an enemy's appearance. Enemyid is the number of the enemy's appearance that you want to change, appearance is one of the constants given in getenemyappearance. Value can is the new number that you want to assign, constants enemysize:small, enemysize:medium, or enemysize:large when changing picture size, or palette number when changing palette.

Enemy appearance changes are temporary. They are not saved in the save game.

getenemyappearance
read enemy data (enemyid, data)
read enemy data
Returns the enemy's reward values. Enemyid is the number of enemy, data is a predefined constant defining the data you want returned. Use the following constants:

- enemy:gold
- enemy:experience
- enemy:item
- enemy:itempercent
- enemy:rareitem
- enemy:rareitempercent
- stealability
- stealableitem
- stealableitemchance
- stealablerareitem
- stealablerareitemchance

writeenemydata
write enemy data (enemyid, data, value)
write enemy data
Lets you set items of an enemy's data. Enemyid is the number of enemy, data is a predefined constant for the data you want to change. Value is the new value given to that setting. Use the same constants as are given at readenemydata.

Enemy data changes are temporary. They are not saved in saved games.

readenemydata

## Formations

add enemy to formation (formation, enemy id, x, y, slot)
add enemy to formation
Adds an enemy with given

enemy id

(use the constants of the form

enemy:name

in your exported .hsi file) to the specified

formation

.

x

(0 to 320) and

y

(from roughly 17 to 240, depending on enemy size) give the position of the center of the bottom edge of the enemy - approximately where it appears to stand.

slot

(0 to 7) is an optional argument, if you specify it, then the enemy is created in the suggested slot if empty. If you omit

slot

or

slot

isn't empty, the enemy is put in the first empty slot. The actual slot number used is returned, or -1 if the enemy couldn't be added.

Changes to enemy formations are temporary: they are not saved in save files.

deleteenemyfromformation
delete enemy from formation (formation, slot)
delete enemy from formation
Deletes an enemy in the given

slot

(as returned by findenemyinformation for example) in the

formation

.

Changes to enemy formations are temporary: they are not saved in save files.

addenemytoformation
find enemy in formation (formation, enemy id, copy number)
find enemy in formation
Searches for an enemy in a formation, returning the slot number, or -1 if not found.

copy number

is optional, use 0 or greater specify which enemy to return if there is more than one, or the constant getcount. The first (searching the slots sequentially) enemy copy is number 0. The number of specified enemies in the formation is returned if the constant get count is used.

enemy id

can be either an enemy id, or the constant

any enemy

, which searches for any enemy (the first enemy in the formation by default), or the total number of enemies with getcount.
plotscript, look at formation, formation, begin # In this example, we'll pick a random enemy from a formation, and check if there are any plips. # You'll need an enemy named plip to try this out, or change the "enemy:plip" constant below to something else variable (number of enemies, random enemy slot)

# The total number of enemies number of enemies := find enemy in formation (formation, any enemy, get count) # Pick an enemy at random random enemy slot := find enemy in formation (formation, any enemy, random(0, number of enemies -- 1))

$30 = "There is a " # Here we append the enemy's name to string 30 get enemy name (formation slot enemy (formation, random enemy slot), 30) $30 + " in this formation" show string (30)

# Let's check whether there is at least one plip in this formation variable (number, plip slot) number := find enemy in formation (formation, enemy:plip, get count) if (number > 0) then ( # We'll put a string onscreen where the plip appears in battle $31 = "Plip!" plip slot := find enemy in formation (formation, enemy:plip) center string at (31, formation slot x (formation, plip slot), formation slot y (formation, plip slot) -- 20) ) end
deleteenemyfromformation
formationslotenemy
formationslotx
formationsloty
formation slot enemy (formation, slot)
formation slot enemy
Returns the ID number of the enemy in the specified formation slot (0 to 7), or -1 if the slot is empty.
findenemyinformation
formation slot x (formation, slot)
formation slot x
Returns the x position of the center of the enemy in the specified formation slot (0 to 7). An enemies position is the center of the bottom edge of the enemy - approximately where it appears to stand.
findenemyinformation
formation slot y (formation, slot)
formation slot y
Returns the y position of the bottom edge of the enemy sprite in the specified formation slot (0 to 7). An enemies position is the center of the bottom edge of the enemy - approximately where it appears to stand.
findenemyinformation
set formation background (formation, background, animation frames, animation ticks)
set formation background
Sets the background and the background animation for a

formation

. The animation arguments do not need to be given, producing a static background.

animation frames

, optional, is the number of frames (1 to 50) to use for the background animation. 1 is non-animating.

animation ticks

, also optional, is the number of ticks to display each backdrop for. The engine normally (but not reliably) runs at 18 ticks per second.

Changes to enemy formations are temporary: they are not saved in save files.

getformationbackground
get formation background (formation)
get formation background
Gets the background used by a

formation

. If the backdrop is animated, this returns the ID of the first backdrop (the one set in Custom).
setformationbackground
set formation song (formation, song)
set formation song
Changes an enemy formation to use

song

as its music. Use the constants of the form

song:songname

from your exported .hsi file, or the special constants song:silence or song:sameasmap

Changes to enemy formations are temporary: they are not saved in save files.

getformationsong
get formation song (formation)
get formation song
Returns the song associated with

formation

. Compare the result with the constants of the form

song:songname

from your exported .hsi file, or the special constants song:silence or song:sameasmap.
setformationsong
reset formation (formation)
reset formation
Reset any scripted changes to

formation

. This script erases changes made with addenemytoformation, deleteenemyfromformation, setformationbackground, and setformationsong and changes the formation back to the way it was defined in the Formation Editor in custom.
resetformationslot
reset formation slot (formation, slot)
reset formation slot
Reset any scripted changes to a specific

slot

in a

formation

. This script erases changes to enemy id, enemy x, and enemy y made with addenemytoformation or deleteenemyfromformation and changes the formation slot back to the way it was defined in the Formation Editor in custom.
resetformation
last formation
last formation
Returns the last formation fought. If the player hasn't fought any formations yet (since starting or loading the game), it returns -1.
random formation (formation set)
random formation
Picks a formation randomly from the given

formation set

(1 to 255), returning the formation number.
formationprobability
formation set frequency (formation set)
formation set frequency
Returns the formation frequency (from 0 to 200) of a

formation set

(1 to 255), as set in the Formation Set Editor. Note that the frequency is not actually a probability (as a percentage) of a battle occurring each step, but is roughly the number of battles per 100 steps, spaced randomly. The frequency is used to update the random battle countdown every step (see getbattlecountdown).
randomformation
getbattlecountdown
setbattlecountdown
get battle countdown
get battle countdown
Returns the random battle countdown value. This counter starts at a random value from 40 to 160, and is reduced by the formation set frequency whenever the player steps on a tile marked on the foemap. When it reaches zero a formation from that formation set is triggered and it resets.
formationsetfrequency
getbattlecountdown
setbattlecountdown
set battle countdown (value)
set battle countdown
Sets the random battle countdown value (see getbattlecountdown). Setting the value to 0 or less means that the next step will trigger a battle (even if the frequency is 0!) The counter is saved in save games, but resets when fighting a battle (for any reason), using a door (even to the same map) or teleporttomap, or dismounting a vehicle.
formationsetfrequency
getbattlecountdown
setbattlecountdown
formation probability (formation set, formation)
formation probability
Returns the probability of a particular

formation

in a

formation set

being fought, as a percentage from 0 to 100. This does take the number of times the formation appears in the formation set into account.
randomformation
random

# Getting Player Input

pick hero (message, skip if alone)
pick hero
Pops up a hero-picker box that lets you choose one of the heroes in your active party. The return value is the position in the party of the hero you picked, or -1 if the player cancelled. Both arguments are optional.

message

is the ID of the string to use for the prompt, which defaults to "Which Hero?". If you leave it out or pass -1, the default message is used, which is defined in the Global Text Strings menu (search it for "pick hero"). If

skip if alone

is true then if there's only one hero in the active party then will automatically be picked, without showing the menu. It defaults to false!

## Keyboard Input

There are two main commands for checking for keypresses: keypress and keyispressed. Use keyispressed (which checks whether a key is down) when you want the player to do something continually, such as if they're controlling a character's movement or jumping. For nearly everything else you will use keypress, such as when you script a menu (both activating menu items and moving the cursor - since the cursor moves in jumps rather than continually), or to use a special ability such throwing a ball. Use newkeypress instead of keypress if you don't want key repeat.

You can NOT wait for the player to press a key by continually polling keyispressed, etc, in a while loop unless you stick a wait in your loop. That's because key, joystick and mouse commands don't return real time data, but the state of the devices at the beginning of the current game tick.

key is pressed (scancode, joystick num)
key is pressed
Returns true if the keyboard or joystick key with the specified scancode is being pressed (either held down or pressed since last tick), or false if it is not. The

scancode

argument is a scancode such as a keyboard key (e.g. key:ctrl) a joystick button (e.g. joy:left), or a virtual scancode such as usekey. The

joystick num

argument is optional, and defaults to 0. It's only used with joystick scancodes such as joy:button 1, and tells which joystick to read: 0 is the first one, 1 is the second, etc.

Previously you couldn't use virtual scancodes like usekey, which could only be used with waitforkey. Now all key commands accept any kind of constant; what a relief!

You can't rely on the behaviour of the caps-, scroll- and num-lock keys. They might report on/off state instead of pressed/not pressed, depending on the graphics backend, operating system, and engine version.

keypress
newkeypress
keyval
keypress (scancode, joystick num)
keypress
Checks for a keypress event, and returns true or false. A keypress happens either when there's a new keypress (the key/button gets pressed down), or each time it repeats once it's been held down for a little while (18 times a second after it's been held half a second, by default). The

scancode

argument is a scancode such as a keyboard key (e.g. key:ctrl) a joystick button (e.g. joy:left), or a virtual scancode such as usekey. The

joystick num

argument is optional, and defaults to 0. It's only used with joystick scancodes such as joy:button 1, and tells which joystick to read: 0 is the first one, 1 is the second, etc. It's not a good idea to rely on the key repeat rate for things that affect gameplay such as the rate at which you can shoot bullets! The repeat rate is once every 55 milliseconds (18 times a second), independent of the frames per second (fps) that the game is running at. Suppose you use key repeat to shoot bullets and your game runs at 36 fps, then a bullet will be fired every other frame. But if played on a really slow computer that only ran the game at 18 fps, a bullet will be fired every frame!
keyispressed
newkeypress
keyval
new keypress (scancode, joystick num)
new keypress
Checks for a new keypress (the key/button gets pressed down), and returns true or false. The

scancode

argument is a scancode such as a keyboard key (e.g. key:ctrl) a joystick button (e.g. joy:left), or a virtual scancode such as usekey. The

joystick num

argument is optional, and defaults to 0. It's only used with joystick scancodes such as joy:button 1, and tells which joystick to read: 0 is the first one, 1 is the second, etc.
keyispressed
keypress
keyval
keyval (scancode, joystick num)
keyval
Returns a bitmask for the state of the specified key, joystick button, or virtual scancode. The

scancode

argument is a scancode such as a keyboard key (e.g. key:ctrl) a joystick button (e.g. joy:left), or a virtual scancode such as usekey. The

joystick num

argument is optional, and defaults to 0. It's only used with joystick scancodes such as joy:button 1, and tells which joystick to read: 0 is the first one, 1 is the second, etc. The result holds the same information as given by the keyispressed and keypress commands, so you can use those instead. The first (least significant) bit is whether the key was depressed at the beginning of the current tick. The second bit is whether a keypress event happened (either this is a new keypress, or key repeat occurred) - same as keypress. It can therefore return 0, 1, 2 or 3: 0 = not pressed 1 = key held down since last tick, but is not a new press 2 = the player pressed the key and released it, all in the same tick 3 = new keypress (or typematic repeat)

Previously you couldn't use virtual scancodes like usekey, which could only be used with waitforkey. Now all key commands accept any kind of constant; what a relief!

keyispressed
keypress
newkeypress
last ascii
last ascii
This command is obsolete. Use getinputtext instead, if possible.Returns the character code of any currently pressed key, or 0 if none are. If more than one key corresponding to an ascii character is being pressed, then only one can be returned.
enable input text (enable)
enable input text
This command needs to be called before getinputtext can be used. If the optional argument is true or not given then

get input text

is enabled, otherwise it is disabled. Enabling getinputtext may cause some of the keys on international keyboards ("combining" keys, which are usually punctuation keys) to go "dead" --- that is, commands such as keyispressed and waitforkey will stop showing that they are pressed. For that reason,

get input text

is disabled by default. You don't need to use this command before calling inputstring.
getinputtext
get input text (string id)
get input text
Places in the specified string any text that the player has typed since the last tick. (The string will be empty if nothing has been.) Textual input must be enabled using enableinputtext before this command can be used! See that command for details. You will normally call this every tick in a loop and use concatenatestrings to read the player's complete input. However it is much easier to call the inputstring function instead, which does this for you.
inputstring
input string (ID, maxlength, use current, center, position x, position y)
input string
Allows the player to type in a string (until they press ENTER). Returns false if they press ESC to cancel.

ID

is the string you want to use. All other arguments are optional:

maxlen

is the length of input, if left blank the limit will be equal to the maximum length that fits on-screen (40 characters if the screen is the default 320 pixels wide).

use current

is whether you want to add to the existing string, or clear the string before typing. The default is to clear the string before typing, valid arguments are true or false. The string will be centered (see centerstringat unless

center

is false. If the string is not visible, then it will automatically be placed onscreen (centered if not specified) and hidden when done.

position x

and

position y

are optional (defaulting to the center of the screen), and are the position at which the string will be shown as it is being typed; otherwise the string will use its current positioning if already visible.
getinputtext
input string with virtual keyboard (ID, maxlength, onlyplayer)
input string with virtual keyboard
Allows the player to input a string using a virtual keyboard. The exact appearance and behavior of the virtual keyboard will vary on different platforms, for example, on Android a touch-screen keyboard will appear, but when playing on a console, the virtual keyboard will be controlled with the d-pad and buttons. You have no control over what portion of the screen is obscured by the virtual keyboard. The virtual keyboard will vanish when the command is finished.

ID

is the string you want to use. All other arguments are optional:

maxlen

is the length of input, if left blank the limit will be set to 40 (max visible onscreen length). The

onlyplayer

is optional. It only matters when the game is played on a console with multiple gamepads configured. It can be a number from 0 to 3, being that only that specific player has control over the virtual keyboard. By default onlyplayer is -1, which means that any player can control it.
inputstring
inputstringwithmousekeyboard

## Joystick Input

Joystick buttons and up/down/left/right directions can also be read using the keypress, newkeypress, keyispressed and waitforkey commands, by using the joy:... constants instead of keyboard scancodes. But the best way to support joysticks is to use virtual scancodes such as usekey instead of keyboard scancodes, e.g. write if (keypress(use key)) instead of if (keypress(key:space) || keypress(key:enter) || keypress(key:ctrl)).
joystick button (button, joystick)
joystick button
Returns true or false depending on whether button #

button

on joystick #

joystick

is pressed.

button

can be from 1-32 (assuming the joystick has that many buttons), and

joystick

can be from 0-7. Most of the time, you will want to use joystick #0, so that is what

joystick

defaults to.

If you want to check for new button presses, or want key-repeat to happen, use the keypress or newkeypress commands instead.

joystick axis (axis, multiplier, joystick)
joystick axis
Returns the position of the joystick along the X or Y axis on joystick #

joystick

.

axis

can be one of the constants xaxis or yaxis.

multiplier

is slightly complicated: The position of the joystick is actually a decimal between -1 and 1. Since plotscripting can't handle decimals, this position must be multiplied and rounded off until it is within plotscripting's capabilities. By default, it is 100 (so it will return -100 - 100).

joystick

can be from 0-7. Most of the time, you will want to use joystick #0, so that is what

joystick

defaults to.

## Mouse Input

init mouse
init mouse
Informs the engine that you intend to use the mouse. This command should be run before any mouse functions are be used. It causes the normal mouse cursor to be hidden when over the game's window, and causes mouse buttons to trigger on-keypress scripts. Therefore, it is a good idea to place this command in the newgame and loadgame scripts if you are going to use the mouse.

Running this command does not draw a cursor onscreen. Either you can enable the default mouse cursor with unhidemousecursor, or your script may display the cursor itself by placing a slice at the appropriate location. If you use a slice, your cursor will appear below menus and text and strings shown with showvalue, showstringat, etc., which is currently unavoidable.

Here is an example:
#Simple Mouse cursor example

plotscript, display mouse, begin

# Hide the normal mouse cursor init mouse # Re-enables the normal mouse cursor unhide mouse cursor

end
#Custom Mouse cursor example

plotscript, display mouse, begin

# Hides the normal mouse cursor init mouse

# Use a small enemy sprite (ID 1) slice as a mouse cursor variable (cursor) cursor := load small enemy sprite (1) # The following is optional: causes the mouse to be displayed # above textboxes and above all other slices (it still appears behind menus though) move slice above (cursor, lookup slice (sl:textbox layer))

# Loop while the game is running while (true) do, begin put slice (cursor, mouse pixel x, mouse pixel y) wait (1) end end
mouse pixel X
mouse pixel X
Returns the X coordinate in pixels of the mouse on the screen.
mouse pixel Y
mouse pixel Y
Returns the Y coordinate in pixels of the mouse on the screen.
mouse button (which)
mouse button
Returns true if the specified mouse button is currently pressed down. You can use the constants leftbutton, middlebutton or rightbutton to specify the button.

Just like keyboard commands such as keyispressed, you can not wait for the player to click the mouse with a while loop that doesn't contain a wait command, because the mouse state is only updated once per frame.

mouseclick
mouserelease
mouse click (which)
mouse click
Returns true if the specified mouse button has been 'clicked' down in the last tick. You can use the constants leftbutton, middlebutton or rightbutton to specify the button.

Just like keyboard commands such as keyispressed, you can not wait for the player to click the mouse with a while loop that doesn't contain a wait command, because the mouse state is only updated once per frame.

mousebutton
mouserelease
mouse release (which)
mouse release
Returns true if the specified mouse button has been released since the last tick. You can use the constants leftbutton, middlebutton and rightbutton to specify the button.

Just like keyboard commands such as keyispressed, you can not wait for the player to click the mouse with a while loop that doesn't contain a wait command, because the mouse state is only updated once per frame.

mousebutton
mouseclick
put mouse (X, Y)
put mouse
Changes the location of the mouse on the screen, in pixels. Note that this function might do nothing, if the game's window is not active. initmouse should be called before this command is used.
mouse region (x min, x max, y min, y max)
mouse region
Constricts the mouse to a rectangular part of the window/screen, such as a choice selection box. It is recommend you do not use this command, as it is very annoying in windowed mode. The maximum values are inclusive. Call without arguments to free the mouse to leave the window. initmouse should be called before this command is used.
input string with mouse keyboard (ID, maxlength)
input string with mouse keyboard
Allows the player to input a string using a virtual keyboard that respons to mouse clicks or touchscreen touches. You have no control over what portion of the screen is obscured by the virtual keyboard. The virtual keyboard will vanish when the command is finished.

ID

is the string you want to use. All other arguments are optional:

maxlen

is the length of input, if left blank the limit will be set to 40 (max visible onscreen length).
inputstring
inputstringwithvirtualkeyboard
unhide mouse cursor
unhidemousecursor
Causes the normal OS mouse cursor to be displayed. You may want to run this command right after initmouse unless you plan to use a customized mouse cursor. Note that this command has no effect if the game is running on Android, because a mouse cursor is usually inappropriate on a touch screen.
hide mouse cursor
hidemousecursor
Causes the normal OS mouse cursor to be hidden. This command is seldom needed, because the cursor is hidden by default when you run initmouse.
unhidemousecursor
show mouse cursor

### Helpful Related Commands

# String Functions

In HamsterSpeak, strings are special variables which hold pieces of text, and are referred to by their ID numbers. There are 100 string variables, with IDs 0 to 99. Strings variables can be displayed onscreen directly, or alternatively embedded in textboxes or displayed with text slices. For more information, see the wiki article on strings. You can set the value of a string directly with __setstring__ and append to an existing string with __appendstring__. There is no limit on string length.

Unlike almost all other indices in the OHRRPGCE, when referring to a position in a string,

position

is a 1-based index into the string, not a 0-based index. For example, given a string "ABCDEFG", position=3 is "C", not "D". This means that position 0 is invalid. Beware!

Strings are not saved in saved games by default, but this can be enabled in the Saved Game Settings menu.

expand string(ID, saveslot)
expand string
Expands codes in

ID

such as ${H1}. This does the same thing that textboxes do automatically. The

saveslot

argument is optional. If you leave it out, the string's codes will be expanded based on the currently running game state. If you specify a save slot number from 1-1000 then the string will be expanded based on hero names, variables, and strings in that save slot.

## Basic String Commands

$id="some text"
$id="..."
Sets the contents of a string variable given by

id

, which can be a constant like 0 or 1, a variable, or even an expression like a call to a script, to a piece of text. The previous contents are erased. The whole statement must be on a single line; you can't split the text onto multiple lines (use multiple __appendstring__ statements instead). The value of the whole statement is equal to

id

for convenience (see the example). The text (which is called a string literal) can contain certain escape codes (see examples below): \\ turns into a single \ \" turns into a single " without signalling the end of the literal \n is a new line character, which can be used in text slices, showstring, showstringat and trace. \t is a tab character (which isn't useful at all as it doesn't actually cause a tab except when printing to a file with trace). \x## where ## is a two digit hexidecimal number adds an ASCII character to the string. For example \x4b is the letter K.
# This displays Some text! in the corner of the screen $1 = "Some text!" showstring(1)

# This displays # Guard: # "Halt!" # near the bottom left corner of the screen (at 30,150) for a moment show string at ($1="Guard:\n \"Halt!\"", 30, 150) wait (40) hide string (1)
$id+"some text"
$id+"..."
Appends a string literal to a string variable. This is the same as __setstring__, except that the existing contents of the string are preserved and appended to.
clear string(ID)
clear string
Erases the string buffer #ID to the empty string (""). That's all.
append number (ID, number, min length, pad with zeros)
append number
Appends the decimal representation of

number

to the string with ID #

ID

. The optional

min length

argument can be used to add padding to the left or right. It's the minimum length of the string to append - if the number of digits (including the leading negative sign, if any) is less than this, then spaces or zeroes are added as padding:

- If the optional argument

  pad with zeros

  (which defaults to false) is false, then spaces are added to the left (left of the negative sign, if any)
- If

  pad with zeros

  is true, then zeroes are added to the left (to the right of the negative sign, if any)
- If

  min length

  is negative, then the padding is added to the right instead. E.g. -4 means a minimum length of 4, padded to the right.

  pad with zeros

  is ignored.

append number(1, 65) # Appends "65" to string 1. append number(1, 1234, 3) # Appends "1234" to string 1: no padding added

append number(1, 65, 4) # Appends " 65" to string 1. append number(1, 65, 4, true) # Appends "0065" to string 1.

append number(1, -65, 4) # Appends " -65" to string 1. append number(1, -65, 4, true) # Appends "-065" to string 1.

append number(1, 65, -4) # Appends "65 " to string 1. append number(1, 65, -4, true) # Appends "65 " to string 1: the 4th argument is ignored append number(1, -65, -4) # Appends "-65 " to string 1.
appendascii
stringsprintf
numberfromstring
string sprintf (dest string ID, format string ID, arguments...)
string sprintf
Builds a string from a template (given by

format string ID

) and zero or more additional arguments, and puts the result in the string

dest string ID

. This is a restricted version of the sprintf function in other programming languages. This function takes at least 2 arguments. The format string is a mix of regular text and codes like %d. For each code, one argument is read and used to substitute for the code. The codes are:

%d

: substituted with a number, printed as a decimal.

%x

: substituted with a number, printed as a unsigned 32 bit hexidecimal, in lower case and without a leading 0x.

%o

: substituted with a number, printed as a unsigned 32 bit octal number, without a leading 0o.

%b

: substituted with a number, printed as a unsigned 32 bit binary number, with a space between every 8 bits, without a leading 0b.

%s

: substituted with a string. The argument should be a valid string ID.

%c

: substituted with a single character. The argument should be an ASCII code (that is, a number between 0 and 255).

%%

: substituted with a single %. In this case an argument is NOT used up. More sophisticated formatting codes like %-04d that are possible in other programming languages are not supported yet.

Modifiers like field width and precision which are available in other programming languages, e.g. "%4d" or "%.2f", aren't available. But appendnumber has extra options for these.

# This displays some text like "HP: 30 MP: 12 $: 104" at the bottom of the screen $1 = "HP: %d MP: %d $: %d" string sprintf(0, 1, getherostat(me, stat:HP), getherostat(me, stat:MP), partymoney) show string(0)
# This displays some text like "Ah Bob! You've brought me 5 apples." # in the centre of the screen, and waits for the player to press a key. $10 = "Ah %s! You've brought me %d apples." getheroname(11, findhero(leader)) string sprintf(12, 10, 11, inventory(item:apple)) center string at(12, 160, 100) wait for key(anykey) hide string(12)
# This displays "1abcdef ffffffff A%" # Notice that the expression '$1="%x %x %c%%"' returns the string ID 1 as a side effect. string sprintf(0, $1="%x %x %c%%", 28036591, -1, 65) show string(0)
appendascii
appendnumber
number from string (ID, default)
number from string
Try to read the string specified by

ID

as a number and return it. Blank spaces at the beginning of the string will be ignored, and the string can start with a - sign for negatives. No other characters except numerical digits can appear in the string. You can also provide an optional default value that will be returned if the string is not a valid number (for example, if it contains a non-numeric letter)
appendnumber
copy string (dest, source)
copy string
Copies the text from string #

source

to string #

dest

, overwriting the existing string completely. If you prefer, you can write

dest $= source

instead. You must supply string id numbers, not strings, as arguments.
concatenate strings (dest, source)
concatenate strings
Copies the text from string #

source

to string #

dest

. However, unlike copystring, the text is appended to the end of

dest

. If you prefer, you can write

dest $+ source

instead. You must supply string id numbers, not strings, as arguments.
string length (ID)
string length
Returns the length of string #

ID

.
string equal (ID1, ID2)
string equal
Returns true if the two strings #

ID1

and #

ID2

are identical, case sensitive.
stringequal
string compare
search string (ID1, ID2, start)
search string
Searches the string for a specified string, returns the position at which the string was found.

start

is the position at which you want to start looking, default is 1.

ID1

is the the string you want to search,

ID2

is the string expression you want to find. Returns false if the string wasn't found
trim string (ID, start, length)
trim string
Cuts the string to the specified length, OR removes blank space from the beginning and ends of the string.

ID

is the string you want to be cut. If you wish to cut

ID

to a certain length, you must specify

start

and

length

.

start

is the position at which you want to start cutting, anything to the left of this number will be deleted in a string.

length

is the size of the string you want to preserve, anything to the right of this number will be deleted in a string. If you leave these parameters blank, it will trim whitespace from the beginning and ends of

ID

.
replace substring (in string, replace what, with what, max replacements, case insensitive)
replace substring
Replace occurrences in string ID

in string

of a substring (ID

replace what

) with a different string (ID

with what

). By default, replaces all occurrences of replace what, but optionally you can limit the number of times to do the replacement by passing

max replacements

; there's no limit if it's < 0. Inserted text is not eligible for further replacements (see examples). If you pass true as the optional argument

case insensitive

(which defaults to false), then the search for replace what is case-insensitive. For example, "hi" matches "hi", "Hi", "HI" and "hI". Returns the number of replacements done.
$1 = "This is an example of replace substring" # Shows '2' show value (replace substring (1, $2="is", $3="iiss")) wait for key # Note that although "iiss" contains "is", it isn't replaced again with "iiisss" show string (1) # "Thiiss iiss an example of replace substring" wait for key

$1 = "AaabaAaa" replace substring (1, $2="AA", $3="CA", 2, true) # Do only 2 replacements, case insensitively # Again, Aaab becomes CAab but the new Aa isn't replaced, because part of it was a replacement show string (1) # "CAabCAaa"
append ascii (ID, char)
append ascii
Appends the character with ASCII code 'ascii' to the string with ID #ID. The font editor lists ASCII codes. For example numbers are 48 - 57, uppercase letters are 65 - 90, lowercase letters are 97 - 122.
stringsprintf
appendnumber
replace char (ID, position, char)
replace char
Replaces the character at

position

in string #

ID

with a character with ascii code

char

. The first position of the string is 1, and the last position of the string is the same as stringlength.
delete char (ID, position)
delete char
This deletes the character at

position

in string #

ID

, causing all the following characters to move over a slot. The first position of the string is 1, and the last position of the string is the same as stringlength.
ascii from string (ID, position)
ascii from string
Returns the ascii code of the character at

position

in string #

ID

. The first position of the string is 1, and the last position of the string is the same as stringlength. If you pass 0 as the position or a position past the end of the string, 0 will be returned.

## Get/Set Names of Things

This section is a catch-all for commands that get or set bits of game data that are strings, however a number of such commands, like getmenuitemcaption live elsewhere, in more sensible sections!
get hero name (ID, hero)
get hero name
This command will take the name of the hero in the party slot #

hero

, and stick it in string #

ID

, overwriting its contents.

Remember that this command expects the hero's position in the party, not the hero:name constants nor the hero's position in the walkabout party. If you want to get the name of a hero according to their position in the walkabout party, you should use herobyrank and findhero

# This example gets the name of the leader and stores it in string ID 1

get hero name (1, find hero (leader))
set hero name (ID, hero)
set hero name
This command changes the name of the hero in party slot #

hero

(as returned by findhero) to the contents of string #

ID

. The length is not limited by the hero's Max Name Length setting.
get map name (ID, map)
get map name
This command will take the name of map #

map

and stick it in string #

ID

, overwriting its contents.
readattackname
get attack name
read attack name (ID, attack)
read attack name
This command will take the name of

attack

and stick it in string #

ID

, overwriting its contents. Use the

atk:name

constants from your HSI file.

If you want to use this command with attack ID numbers, you must add 1 to the ID number.

This command replaces the old

get attack name

which required you to use

atk:name -- 2

or the attack id number

-- 1

get attack caption (ID, attack)
get attack caption
This command will take the caption of

attack

and stick it in string #

ID

, overwriting its contents. Use the

atk:name

constants from your HSI file.

If you want to use this command with attack ID numbers, you must add 1 to the ID number.

get song name (ID, song)
get song name
Gets the name of song #

song

and puts it in string #

ID

.

## Showing Plotstrings

These commands are an old (and largely obsolete) method of showing strings on the screen. They completely separate to, and superceded by Text Slices. The showstring command is yet another separate way to display a string.
show string at (ID, x, y)
show string at
Displays string #

ID

on the screen, positioning its top left corner at the given (

x

,

y

) coordinates. Unlike showstring, changes to the string will be displayed in real-time. The string will not auto-wrap at the edge of the screen, but it can contain new lines (\n).
center string at (ID, x, y)
center string at
Displays string #

ID

on the screen, positioning its top-middle at the given (

x

,

y

) coordinates. Unlike showstring, changes to the string will be displayed in real-time.

x

,

y

are optional: if they are missing then the string is centered in the center of the screen.

The string is not re-centered automatically if its length changes. If you change the string and want to keep it centered, call showstringat again. Otherwise, its top-left corner will stay fixed.

The string position will be miscalculated if it contains newlines (\n characters).
hide string (ID)
hide string
Makes a string previously displayed with showstringat or centerstringat disappear. Has no effect on strings displayed with showstring
string is visible (ID)
string is visible
Returns true if a string is being displayed by showstringat or centerstringat. Otherwise, returns false. Is not effected by showstring
string style (ID, style)
string style
Changes the appearance of a string. Use this in conjunction with (before or after) showstringat or centerstringat. Choice of

style

is string:outline and string:flat. string:outline is the style of string you are familiar with in textboxes: they are outlined with colour 0 (black). string:flat have no outline but can have a solid rectangular background of any colour displayed behind the string.
string color (ID, foreground color, background color)
string color
Changes the color of a string. Use this in conjunction with (before or after) showstringat or centerstringat. Foreground color is the colour of the text itself. Background color has no meaning for style:outline strings (the outline is always black). For style:flat strings, it is the color of the solid background if 1 to 255, or causes no background if 0. If you omit

background color

, the background will be transparent. Omit

foreground color

as well to reset the color to default ('Text' User-interface color).
positionstring (ID, x, y)
position string
Positions the top left corner of string #

ID

at the given

x

,

y

coordinates. Unlike showstringat, this command will not affect the visibility of a string.
string X (ID)
string X
Returns the horizontal X position of the top left corner of string #

ID

string Y (ID)
string Y
Returns the vertical Y position of the top left corner of string #

ID

## Obsolete Commands

string to globals (ID, starting global, length)
string to globals
This command will fill global variables (starting with #

starting global

), up to

length

globals, with the ascii values of the characters in string #

ID

. If the string is not long enough, the rest of the globals in this "field" are padded with the value 256. If the string is too long, then only part of it is saved.

This command is deprecated. The Saved Game Settings menu now has an option to store strings in saved games. There is no reason to use this command in new games, unless you're using importglobals/exportglobals.

globalstostring
globals to string(ID, starting global, length)
globals to string
This command is the opposite of stringtoglobals. It will build a new string in slot #

ID

, using the ascii values from the global variables #

starting global

and

length

globals thereafter. Pass the same value for

length

as you did to stringtoglobals if you don't know the length of the string. If a global has a value greater than 255, the value will be ignored.

This command is deprecated. The Saved Game Settings menu now has an option to store strings in saved games. There is no reason to use this command in new games, unless you're using importglobals/exportglobals.

stringtoglobals

# Menu Functions

open menu (ID, allow duplicate)
open menu
Opens the menu specified by

ID

. You can also use the constants defined in your HSI file in the form menu:name. The menu will be opened on top of any menus that are already open. The optional second argument

allow duplicates

(defaulting to false) can be true if you want to be able to open more than one copy of the same menu at the same time. If

allow duplicates

is false and the menu is already open, then the existing menu (the top-most one, if there's more than one) is brought to the top. The return value is a menu handle that you should store in a variable for use with other menu-related commands. (If an existing menu was brought to top, its handle is returned If

ID

isn't a valid menu, this acts like createmenu. If menu 0 does NOT have the "Allow gameplay & scripts" bit set, then your script will pause as soon as the menu opens, until either it's closed or another menu with that bit ON is opened. And once the menu has closed the menu handle is invalid!
create menu
create menu
Create a new empty menu. You can add menu items to it with the addmenuitem command. The return value is a menu handle that you should save in a variable for use with other menu related commands. Menus created with this command have the "Allow gameplay and scripts" bitset turned on by default.
close menu(menu handle, run close script)
close menu
Close a menu. The first argument is a

menu handle

(for example, the one returned by openmenu or topmenu). The second argument

run close script

, which defaults to false, states whether to run the menu's on-close script, if there is one.
top menu
top menu
Return a menu handle for the topmost menu. Returns false if no menus are open.
bottom menu
bottom menu
Return a menu handle for the bottom menu (the menu underneath all other open menus). Returns false if no menus are open.
previous menu(menu handle)
previous menu
Return a menu handle for the menu beneath the one specified by

menu handle

, or false if there is no menu underneath.
variable(menu) menu := topmenu while(menu) do, begin # do things to each menu menu := previous menu(menu) end
next menu(menu handle)
next menu
Return a menu handle for the menu on top of the one specified by

menu handle

, or false if there is no menu on top
variable(menu) menu := bottom menu while(menu) do, begin # do things to each menu menu := next menu(menu) end
bring menu forward(menu handle)
bring menu forward
Given a menuhandle, move the menu to the top of all other open menus.
find menu ID(menu ID)
find menu ID
Given a

menu ID

number or a constant in the form of

menu:name

, check to see if it is already open, and if so return a menuhandle to it. Otherwise returns false.
menu is open(menu handle)
menu is open
Given a menuhandle, checks to see whether it is still open, and returns true if it is, or false if it has been closed.
parent menu(menu item handle)
parent menu
Given a menuitemhandle, return a menu handle for the menu that the menu item belongs to.
get menu ID(menu handle)
get menu ID
Given a menuhandle, return the ID number of the menu, or -1 if the men was created with the createmenu command.

## Menu Items

add menu item(menu handle)
add menu item
Given a menuhandle, adds a new blank menu item to the end of the menu. Returns a menu item handle, which you can store in a variable for use with commands like setmenuitemcaption or setmenuitemtype.
delete menu item(menu item handle)
delete menu item
Given a menuitemhandle, delete the menu item from the menu. (The change does not affect other copies/instances of the same menu if this menu was created in the menu editor.)
swap menu items(handle1, handle2)
swap menu items
Given two menuitemhandles switch the positions of the two menu items. Note that this works both to rearrange menu items within one menu, or to move menu items between different menus.
select menu item(menu item handle)
select menu item
Given a menuitemhandle, move the menu selection cursor to point to that menu item. Unselectable menu items (see menuitemselectable) can't be selected; if you try to select one this command silently fails and returns false; normally it returns true.
selected menu item(menu handle)
selected menu item
Returns the handle for the selected menu item in the topmost menu if the optional

menu handle

is omitted, or, with a menuhandle returns the selected item in that menu. Returns false if no menus are open, or if the topmost or specified menu has no selection (which happens if it's empty, or all menu items are unselectable or hidden).
menu item disabled(menu item handle)
menu item disabled
Given a menuitemhandle, returns whether that menu item is disabled (true or false). Menu items can be disabled for a range of reasons such as tag conditions.
menu item visible(menu item handle)
menu item visible
Given a menuitemhandle, returns whether that menu item is visible (true or false). A menu item is hidden only if it's disabled and has the "Hide if disabled" bit set.
menu item selectable(menu item handle)
menu item selectable
Given a menuitemhandle, returns true or false, telling whether that menu item is visible and can be selected by normal controls, (rather than being skipped over). Currently only hidden menu items and Labels which "Can't be selected" return false.
use menu item(menu item handle)
use menu item
Given a menuitemhandle, activate the menu item. This will cause whatever actions (text box, menu, script, tag changes, etc.) that have been configured for this menu item to be triggered.
first menu item(menu handle)
first menu item
Given a menuhandle, return a menu item handle for the menu item at the top of the menu, or 0 (false) if there are no visible menu items.

This is NOT the handle for the first menu item defined in the menu editor. Use menuitembytrueslot(menu, 0) to get that one.

last menu item(menu handle, visible only)
last menu item
Given a menuhandle, by default returns a menu item handle for the last visible menu item, at the bottom of the menu.

visible only

defaults to true. If you pass

false

as the

visible only

argument, then returns the last visible or invisible menu item (last as seen by menuitembyslot or nextmenuitem).

last menu item(menu, false) does NOT return the handle for the last menu item that appears in the menu editor, because menu items are sorted based on visibility: all invisible items to the end. Use menuitembytrueslot(menu, menuitemcount(menu) -- 1) to get that one.

next menu item(menu item handle, visible only)
next menu item
Given a menuitemhandle, return a menu item handle for the menu item below the specified one, or false there is no next menu item. You can optionally include invisible items by using the optional argument

visible only

, which defaults to true.

Invisible menu items are always at the end of the menu, after the last visible menu item, not in the order in which they are defined in the menu editor! See menuitembytrueslot if that's undesirable.

variable(mi) mi := first menu item while(mi) do, begin # do things to each visible menu item mi := next menu item(mi) end
previous menu item(menu item handle, visible only)
previous menu item
Given a menuitemhandle, return a menu item handle for the menu item above the specified one, or false there is no previous menu item. You can optionally include invisible items by using the optional argument

visible only

, which defaults to true. Note that invisible menu items are always at the end of the menu, after the last visible menu item. See menuitembytrueslot if that's undesirable.
variable(m) m := previous menu item(selected menu item)
menu item count(menu handle)
menu item count
Returns the total number of menu items in a menu, both visible and invisible (disabled).
visiblemenuitemcount
visible menu item count(menu handle)
visible menu item count
Returns the number of visible menu items in a menu.
menuitemcount
menu item by true slot(menu handle, slot)
menu item by true slot
Given a menuhandle, return a menu item handle for the menu item at the position specified by

slot

. The first slot in the menu is 0. This command uses the ordering of menu items as they appear in the Menu Editor in Custom. The "true order" doesn't change as menu items are hidden or unhidden, unlike the slot returned by menuitemslot.
menuitembyslot
menu item true slot(menu item handle)
menu item true slot
Given a menuitemhandle, return the slot number of the menu item, as it appears in the Menu Editor. The first slot in the menu is 0. The "true order" doesn't change as menu items are hidden or unhidden, unlike the slot returned by menuitemslot.
menuitemslot
menuitembytrueslot
menu item by slot(menu handle, slot, visible only)
menu item by slot
Given a menuhandle, return a menu item handle for the menu item at the position specified by

slot

. The first slot in the menu is 0. You can optionally include invisible items by using the optional argument

visible only

, which defaults to true. Note that invisible menu items are always at the end of the menu, after the last visible menu item -- menu items are NOT in the same order as they appear in the Menu Editor! This means menu item slot numbers change as menu items are hidden or unhidden. Use menuitembytrueslot if you want to use the order shown in the Menu Editor.
menuitemslot
menuitembytrueslot
menuitemcount
visiblemenuitemcount
menu item slot(menu item handle)
menu item slot
Given a menuitemhandle, return a the slot number of the menu item. The first slot in the menu is 0. Menu item slot numbers change as menu items are hidden or unhidden. Use menuitemtrueslot if you want to know the slot number as it appears in the Menu Editor.
menuitembyslot
menuitemtrueslot
find menu item caption(menu handle, string ID, search after handle, visible only)
find menu item caption
Given a menuhandle, and a string identified by

string ID

, Search the menu for a menu item with a label that is the same as the string, and return a handle to the matching menu item. The optional third argument

search after handle

is a menu item handle to start searching after instead of searching from the top of the menu (so it must belong to the same menu). The optional fourth argument

visible only

is a true or false value that determines whether or not to include hidden items. It defaults to true.
variable(menu, mi) menu := open menu(menu:test menu) $0="Puppies" mi := find menu item caption(menu, 0) while(mi) do, begin # do something to each menu item labelled "Puppies" mi := find menu item(menu, 0, mi) end
menu item at pixel(x, y)
menu item at pixel
Given a position on the screen (for example

menu item at pixel

(mousepixelx, mousepixely)), returns the handle for the menu item at that position, or

false

if none. If multiple menus overlap at that location the top-most one is returned. You can find the menu that the menu item belongs to with parentmenu.

The menu item might not actually be selectable. Check with menuitemselectable.

selectedmenuitem

### Menu Item Data

get menu item caption(menu item handle, string ID)
get menu item caption
Given a menuitemhandle, take the caption and copy it into the string identified by

string ID

.
set menu item caption(menu item handle, string ID)
set menu item caption
Given a menuitemhandle, replace the caption with the string identified by

string ID

.
get menu item type(menu item handle)
get menu item type
Given a menuitemhandle, return the type of the menu item.
set menu item type(menu item handle, new type)
set menu item type
Given a menuitemhandle, change the type of the menu item to

new type

. Available constants are: menutype:label (aka menutype:caption), menutype:special, menutype:menu, menutype:textbox, and menutype:script. You will also need to call setmenuitemsubtype to fully specify the action attached to the menu item. Setting just the item type does NOT change the subtype to a sensible value!
get menu item subtype(menu item handle)
get menu item subtype
Given a menuitemhandle, return the subtype of the menu item. The meaning of the subtype varies depending on the type (see setmenuitemsubtype).
setmenuitemsubtype
set menu item subtype(menu item handle, new subtype)
set menu item subtype
Given a menuitemhandle, change the subtype of the menu item to

new subtype

. The meaning of the subtype varies depending on the type of the menu item, which is changed with setmenuitemtype:

- For menutype:label use the constants:

  - menulabel:selectable

  - menulabel:disabled

    - The menu item is always disabled, regardless of tags. Hence, the Set Tag and Toggle Tag options and the "Close menu when activated" bitset are ignored.

  - menulabel:unselectable

    - (aka

    menulabel:cant be selected

    ) Can't be selected with normal controls. Can still be selected using selectmenuitem (but can't be activated).
- For menutype:special use the constants:

  - menuspecial:items

  - menuspecial:spells

  - menuspecial:status

  - menuspecial:equip

  - menuspecial:order

    - Reorder the active party

  - menuspecial:team

    - Reorder, or swap heroes in and out of the active party

  - menuspecial:order team

    - Either the Team menu if the "Hero Swapping Always Available" general preference bitset is turned on, otherwise the Order menu.

  - menuspecial:map

    - Minimap. Appears only if allowed in the Map General Settings.

  - menuspecial:save

    - Appears only if allowed in the Map General Settings.

  - menuspecial:load

  - menuspecial:quit

  - menuspecial:volume

    - Obsolete. This lets you adjust the music volume, and pressing Enter opens a new menu with Music and Sound Volume options.

  - menuspecial:map always

    - Minimap. Appears even if the minimap isn't allowed in Map General Settings.

  - menuspecial:save always

    - Appears even if saving isn't allowed in Map General Settings.

  - menuspecial:margins

    - An option to adjust margins at the edges of the screen, when playing a game on a console like the Ouya which displays on a TV. (Only appears on consoles)

  - menuspecial:purchases

    - Appears only if a store has been set in the In-App Purchases menu.

  - menuspecial:windowed

    - Appears only if currently playing fullscreen, and switching to windowed is supported.

  - menuspecial:fullscreen

    - Appears only if currently playing windowed, and switching to fullscreen is supported. You must add BOTH Fullscreen and Windowed menu items next to each other to allow players to switch to-and-fro.

  - menuspecial:music volume

  - menuspecial:sound volume

- For menutype:textbox use the textbox's ID number.

- For menutype:menu use the menu's ID number or a menu:name constant from your HSI file.
- For menutype:script use script references in the form @scriptname.

get menu item tag(menu item handle, whichtag)
get menu item tag
Given a menuitemhandle, and a tag number

whichtag

which can be 1 or 2, return the a tag required for the menu item to be available. The tag number will be positive if the tag needs to be ON, or negative if the tag needs to be OFF.
set menu item tag(menu item handle, new tag, whichtag)
set menu item tag
Given a menuitemhandle, and a tag number

whichtag

which can be 1 or 2, set the tag required for the menu item to

new tag

. Use a positive number if the tag needs to be turned ON, and a negative number if the tag needs to be turned OFF.
get menu item settag(menu item handle)
get menu item settag
Given a menuitemhandle, return the number of the tag that will be set when the menu item is selected. The tag number will be positive if the tag will be set ON, or negative if the tag will be set OFF.
set menu item settag(menu item handle, new settag)
set menu item settag
Given a menuitemhandle, change the tag that will be set when the menu item is selected. Use a positive number if the tag should be turned ON, and a negative number if the tag should be turned OFF.
get menu item togtag(menu item handle)
get menu item togtag
Given a menuitemhandle, return the number of the tag that will be toggled when the menu item is selected. (The tag number will always be a positive number).
set menu item togtag(menu item handle, new settag)
set menu item togtag
Given a menuitemhandle, change the tag that will be toggled when the menu item is selected. (The tag number will always be positive).
get menu item bit(menu item handle, bit)
get menu item bit
Given a menuitemhandle, and bit number

bit

, return true if the bitset is ON, and false if the bitset is OFF. See setmenuitembit for the constants you can pass as the value of

bit

.
set menu item bit(menu item handle, bit, value)
set menu item bit
Given a menuitemhandle, and bit number

bit

, set the bitset is ON or OFF depending on

value

. You can use the following constants for

bit

:

- menu item bit:Hide when disabled

- menu item bit:Close menu when activated

  (the old name,

  menu item bit:Close menu when selected

  , can also be used)

- menu item bit:Skip close script

  (ie "Don't run on-close script")

get menu item extra(menu item handle, extra)
get menu item extra
Given a menuitemhandle, and an

extra

data number which can be 0, 1, or 2, return the the number stored in the extra data space. This extra data has no meaning of its own, and is just useful for advanced menu scripting.
set menu item extra(menu item handle, extra, num)
set menu item extra
Given a menuitemhandle, and an

extra

data number which can be 0, 1, or 2, change the number stored in the extra data space to

num

. This extra data has no meaning of its own, and is just useful for advanced menu scripting.
get menu item color(menu item handle)
get menu item color
Given a menuitemhandle, get its normal color (when it isn't disabled). This will be a colorcode. 0 means the default for the menu is used.
getmenutextcolor
menuitemdisabled
set menu item color(menu item handle, colorcode)
set menu item color
Given a menuitemhandle, set its normal color (when it isn't disabled). This should be a colorcode. 0 means to use the default for the menu.
setmenutextcolor
menuitemdisabled
get menu item disabled color(menu item handle)
get menu item disabled color
Given a menuitemhandle, get the color it uses when disabled. This will be a colorcode. 0 means the default for the menu is used.
setmenudisabledtextcolor
menuitemdisabled
set menu item disabled color(menu item handle, colorcode)
set menu item disabled color
Given a menuitemhandle, set its color it uses when disabled. This should be a colorcode. 0 means to use the default for the menu.
setmenudisabledtextcolor
menuitemdisabled

## Menu Data

get menu bit(menu handle, bit)
get menu bit
Given a menuhandle, and bit number

bit

, returns true if the bitset is ON, and false if the bitset is OFF. For the

bit

bit number you should use one of the constants:

- menubit:translucent box
- menubit:never show scrollbar
- menubit:allow gameplay
- menubit:suspend player even if gameplay allowed
- menubit:no box
- menubit:no close
- menubit:no controls
- menubit:prevent main menu
- menubit:advance text box when menu closes
- menubit:highlight selection background
- menubit:remember selection

set menu bit(menu handle, bit, value)
set menu bit
Given a menuhandle, and bit number

bit

, sets the bitset is ON or OFF depending on

value

. For the

bit

bit number you should use one of the

menubit:...

constants. See getmenubit for the available constants. Note that this command only changes an open instance of a menu, it doesn't change the menu definition, so if the menu is closed and reopened any edits are reverted.
get menu boxstyle(menu handle)
get menu boxstyle
Given a menuhandle, return a the boxstyle of the menu. This will be a number from 0 to 15.
set menu boxstyle(menu handle, new box style)
set menu boxstyle
Given a menuhandle, change the boxstyle of the menu.

new box style

will be a number from 0 to 15.
get menu textcolor(menu handle)
get menu textcolor
Given a menuhandle, return the default text color of the menu items. This will be a colorcode. 0 means the default is used, which is the "Menu item" color in the User Interface Colors menu.
set menu textcolor(menu handle, new textcolor)
set menu textcolor
Given a menuhandle, change the default text color of its menu items.

new textcolor

should be a colorcode. 0 means the default is used, which is the "Menu item" color in the User Interface Colors menu.
get menu disabled textcolor(menu handle)
get menu disabled textcolor
Given a menuhandle, return the default text color of disabled menu items. This will be a colorcode. 0 means the default is used, which is the "Disabled menu item" color in the User Interface Colors menu.
set menu disabled textcolor(menu handle, new textcolor)
set menu disabled textcolor
Given a menuhandle, change the default text color of disabled menu items.

new textcolor

should be a colorcode. 0 means the default is used, which is the "Disabled menu item" color in the User Interface Colors menu.
get menu max rows(menu handle)
get menu max rows
Given a menuhandle, return a max rows to display of the menu, or 0 if the menu is auto-sizing. If the actual number of menu items is larger than the max rows, the menu will be scrollable.
set menu max rows(menu handle, new max rows)
set menu max rows
Given a menuhandle, change the max rows to display of the menu to

new max rows

. Use 0 if you want the menu to be auto-sizing. If the actual number of menu items is larger than the max rows, the menu will be scrollable.
get menu offset x(menu handle)
get menu offset x
Given a menuhandle, return the x offset position of the menu's anchor point in pixels relative to the center of the screen.
getmenuoffsety
setmenuoffsetx
setmenuoffsety
get menu offset y(menu handle)
get menu offset y
Given a menuhandle, return the y offset position of the menu's anchor point in pixels relative to the center of the screen.
getmenuoffsetx
setmenuoffsetx
setmenuoffsety
set menu offset x(menu handle, new x)
set menu offset x
Given a menuhandle, change the x offset position of the menu's anchor point in pixels relative to the center of the screen.
getmenuoffsetx
getmenuoffsety
setmenuoffsety
set menu offset y(menu handle, new y)
set menu offset y
Given a menuhandle, change the y offset position of the menu's anchor point in pixels relative to the center of the screen.
getmenuoffsetx
getmenuoffsety
setmenuoffsetx
get menu anchor x(menu handle)
get menu anchor x
Given a menuhandle, return the x anchor position of the menu. The return value will be

align:center

,

align:left

or

align:right

. (Not the edge: constants used by slices!)
getmenuanchory
setmenuanchorx
setmenuanchory
get menu anchor y(menu handle)
get menu anchor y
Given a menuhandle, return the y anchor position of the menu. The return value will be

align:center

,

align:top

or

align:bottom

. (Not the edge: constants used by slices!)
getmenuanchorx
setmenuanchorx
setmenuanchory
set menu anchor x(menu handle, new anchor)
set menu anchor x
Given a menuhandle, change the horizontal x anchor position of the menu. The

new anchor

can be

align:center

,

align:left

or

align:right

.
getmenuanchorx
getmenuanchory
setmenuanchory
set menu anchor y(menu handle, new anchor)
set menu anchor y
Given a menuhandle, change the vertical y anchor position of the menu. The

new anchor

can be

align:center

,

align:top

or

align:bottom

. (Not the edge: constants used by slices!)
getmenuanchorx
getmenuanchory
setmenuanchorx
get menu text align(menu handle)
get menu text align
Given a menuhandle, return the text alignment of the menu. The return value will be

align:center

,

align:left

or

align:right

. (Not the edge: constants used by slices!)
setmenutextalign
set menu text align(menu handle, new align)
set menu text align
Given a menuhandle, change the text alignment of the menu. The

new align

can be

align:center

,

align:left

or

align:right

. (Not the edge: constants used by slices!)
getmenutextalign
get menu min chars(menu handle)
get menu min chars
Given a menuhandle, return the minimum width of the menu in chars, or 0 for menus that have their width autodetected.
setmenuminchars
set menu min chars(menu handle, new min)
set menu min chars
Given a menuhandle, change the minimum width of the menu in chars, or use 0 to make the menu width autodetected.
getmenuminchars
get menu max chars(menu handle)
get menu max chars
Given a menuhandle, return the maximum width of the menu in chars, or 0 for menus that do not have a maximum.
setmenumaxchars
set menu max chars(menu handle, new max)
set menu max chars
Given a menuhandle, change the maximum width of the menu in chars, or use 0 for no maximum.
getmenumaxchars
get menu border(menu handle)
get menu border
Given a menuhandle, return the border thickness of the menu in pixels. Positive numbers indicate a thicker border. Negative numbers indicate a thinner border.
setmenuborder
set menu border(menu handle, new border)
set menu border
Given a menuhandle, change the border thickness of the menu in pixels. Positive numbers will result in a thicker border. Negative numbers will result in a thinner border.
getmenuborder
get menu on close script(menu handle)
get menu on close script
Given a menuhandle, return a scriptid for the script that will be run when the menu is closed, or

false

if there is none. This command is only useful with scripts that have the

allow gameplay and scripts

bitset turned on.
variable(m, s) m := open menu(5) s := get menu on close script(m) run script by id(s)
runscriptbyid
setmenuonclosescript
set menu on close script(menu handle, script id)
set menu on close script
Given a menuhandle, assign the scriptid that will be run when the menu is closed, or

false

to disable any on-close script that has already been set. The script trigger only takes effect the next time you close the menu. If you re-open the menu again, you will need to re-set the on-close script again. This command is only useful with scripts that have the

allow gameplay and scripts

bitset turned on.
variable(m, s) m := open menu(5) set menu on close script(m, @my menu exit handler)
runscriptbyid
setmenuonclosescript
get menu cancel button menu(menu handle)
get menu cancel button menu
Given a menuhandle, returns the action that happens when the player presses a cancel button. -1 means the menu simply closes. 0 or greater is a menu ID to open in its place
setmenucancelbuttonmenu
set menu cancel button menu(menu handle, menu)
set menu cancel button menu
Given a menuhandle, sets the action that happens when the player presses a cancel button.

menu

can be either -1, in which the menu simply closes, or a menu ID to open in its place (which is 0 or greater).
getmenucancelbuttonmenu
get menu item spacing(menu handle)
get menu item spacing
Given a menuhandle, returns the amount of extra spacing in pixels between menu items. 0 is the default.
setmenuitemspacing
set menu item spacing(menu handle, spacing)
set menu item spacing
Given a menuhandle, sets the amount of extra spacing in pixels between menu items. 0 is the default.
getmenuitemspacing

# Slices

To learn what a slice is, read the Slices article on the wiki, or a tutorial linked to from it. Although there are many commands here for manipulating slices, it's much easier to create slices in the Slice Collection Editor and then use loadslicecollection. Slices are referred to with slicehandles.
set parent (handle, parent handle)
set parent
Moves a slice

handle

to a different

parent handle

. A slice is connected to its parent, and is positioned based on its parent's position. When you move a slice to a new parent, it will become that parent's last child, meaning it will be drawn on top of any other children that the parent already had.
parentslice
checkparentage
slicechild
slice is valid (id)
slice is valid
Returns true if the given

id

is a valid slice handle to some existing slice. However this tells you nothing about whether the slice it points to is the original one. You should almost never use this command. Just because a slice handle is valid doesn't mean it points to the slice that you expected. After a slice is deleted, its handle can be reused for new slices! If you delete a slice but still have a slice handle to it stored in a variable, you must never access that handle again, because it will either be invalid, causing an error when you use it, or even worse, it will point to some random slice, which is a bug in your script! For alternatives to sliceisvalid, please see the examples. When you want to check whether the result of a slice command is a valid slice, you can just test whether the handle is

false

, as this example shows: variable(sl) # Let's find a slice. sl := lookup code(sl:textbox portrait box) # Does this special slice exist? # You could write if(slice is valid(sl)) then (....), # and it would be correct to do so, but it's pointless. # You should just write this instead: if (sl) then (....) # All commands that normally return a slice handle and might fail will return 'false', # so there is never a need to use sliceisvalid in that situation. The following example shows how to be safe when deleting a slice: global variable (1, bullet slice) ###### Suppose we have one script that creates a temporary slice: plotscript, fire bullet, begin bullet slice := create rect (3, 3) ... end ###### And somewhere else (say, inside our main loop) we want to use it: # Test for collision with the player if (slice collide (bullet slice, get hero slice(me))) then ( ... ###### Also, the temp slice can be deleted: # Bullet is destroyed free slice (bullet slice) ) ###### Wait! First we need to test if there is a bullet slice at all, or we have an error. ###### You might be tempted to use sliceisvalid: if (slice is valid (bullet slice)) then ( # <--- Sometimes returns WRONG result! # Test for collision with the player if (slice collide (bullet slice, get hero slice(me))) then ( ... ) ) ###### That's a mistake. Instead, you should make sure to set the variable ###### bulletslice to 0 in every single place you delete it. ###### Some of other places aren't obvious! They include leaving the map, or loading a saved game! if (bullet slice) then ( # <--- Since we do the needed bookkeeping, this is correct # Test for collision with the player if (slice collide (bullet slice, get hero slice(me))) then ( ... # Bullet is destroyed free slice (bullet slice) bullet slice := 0 # <--- Very important! ) )
free slice (handle)
free slice
Deletes a slice and any child slices. This works on any type of slice. This removes the slice from the screen and removes it from memory. You should free your slices after you are completely done with them. Freeing the same slice handle twice shows a warning (if slice error reporting is enabled, e.g. while testing your game). However, free slice (0) is fine. It's good practice to set a variable containing a slice handle to 0 after you free it, so that the script can test whether the slice exists or not. (sliceisvalid is not reliable.)
script, simple example, begin variable(sl) sl := load hero sprite(0) wait(20) free slice(sl) end

script, example with children, begin variable(box, sl)

# create a box box := create rect(100, 60)

# center a hero as a child of the box sl := load hero sprite(0) set parent(sl, box) center slice(sl)

wait(20)

# when you free the box, the hero will be freed too free slice(box)

# The sprite is gone now, so if you use the handle that used to point # to it, you will get an error message in your g_debug.txt file position sprite(sl, 25, 25) end

script, wrong way to free in a loop, begin # this loop is the WRONG way to remove all sprites that show frame number 1 # because removing a slice inside a loop will interfere with the "next sibling" # command causing the loop to end early variable(sl) sl := first child(sprite layer) while(sl) do, begin if(slice is sprite(sl)) then, begin if(get sprite frame(sl) == 1) then(free slice(sl)) end sl := next sibling(sl) end end

script, right way to free in a loop, begin # this loop is the right way to remove all sprites that show frame number 1 # by waiting until AFTER the "next sibling" command, we can free the slice # without ending the loop early variable(sl, deleteme) sl := first child(sprite layer) while(sl) do, begin deleteme := 0 if(slice is sprite(sl)) then, begin if(get sprite frame(sl) == 1) then(deleteme := sl) end sl := next sibling(sl) if(deleteme) then(free slice(deleteme)) end end
freesprite
freeslicechildren
free slice children (handle)
free slice children
Frees all the children of a slice, but not the slice itself. See freeslice for more details.
freeslice
clone slice (handle, recurse)
clone slice
Copies (clones) a slice. If the optional argument

recurse

is true (which is the default), then all its children and descendents are copied too. Returns the slice handle for the copy, which has the same parent, and becomes the previous sibling to

handle

. You can copy a protected slice (such as an NPC); the result isn't protected. Any slices with special lookup codes (those listed in lookupslice) won't have their lookup codes copied; they'll be set to 0 instead. Passing the root slice or a Map slice as

handle

is an error. Trying to clone a slice which has a Map slice as a descendent is OK, the Map slices just won't be copied. Any slices of type Special (such as the textbox or script layers) will be copied as plain Container slices (there isn't really any difference between them).
set slice extra (handle, extra, value)
set slice extra
Sets one of three extra data variables that every slice has, on the slice

handle

.

extra

is a number from 0 to 2 which indicates which extra data field to write (you may also use the constants

extra 0

,

extra 1

,

extra 2

). The extra data has no meaning to the slice, it is only for use by scripts.
getsliceextra
get slice extra (handle, extra)
get slice extra
Retrieve an extra data value previously set on a slice

handle

with setsliceextra.

extra

is a number from 0 to 2 which indicates which extra data field to read.
reparent to npc (handle, npc)
reparent to npc
Reparent a slice

handle

so that it is attached to an NPC's sprite. The

npc

argument can be an ID number or an NPC reference. The slice will be parented to the NPC's sprite component. If you want it to be parented to the NPC's container slice you should use setparent(

handle

, getnpcslice(

npc

)) instead.
reparent to hero (handle, hero)
reparent to hero
Reparent a slice

handle

so that it is attached to an hero's walkabout caterpillar sprite. The

hero

argument is the hero's rank in the caterpillar party. The slice will be parented to the hero's sprite component. If you want it to be parented to the hero's container slice you should use setparent(

handle

, getheroslice(

hero

)) instead.

## Getting Slices

This section describes commands to find existing slices or load them from a defined slice collection. Commands to create slices are in other sections.
load slice collection (id)
load slice collection
Loads a collection of slices that you have defined in the slice collection editor. The argument is the

id

number of the collection. The return value is a handle to the container that holds the loaded collection.
lookup slice (lookup code, start slice)
lookup slice
Search for an important slice using a lookupcode, and return a handle to it, or 0 if it is not found. You can optionally specify a slice for the

lookup slice

command to start searching from, but if you do not, the whole slice tree will be searched.

You can use a number as a lookup code, but usually you use a builtin code constant, starting with sl: (see below), or name a code in the slice editor, in which case the constant will start with sli:. Don't mix them up!

Although the user-defined slice lookup codes are always safe to use for any purpose, there is a lot of potential mischief that you can do with a handle to a special slice. If you do anything dubious, like reordering, reparenting, or god forbid freeing the special slice, don't expect your scripts to work in later versions of the engine, which are likely to impose stricter restrictions! Deleting or reparenting special slices generally won't work. You may parent your own slices to these special slices, though.

Be aware that when there is more than one slice with the same lookup code, the

lookup slice

command will only return the first one it finds in a depth-first search. If you need to find multiple slices with the same lookup code, you must search manually using getslicelookup. You may setparent a slice to a map layer to make it move with the camera just like heroes and NPCs do.
# this example loads a saved slice collection, # and gets a handle to a slice in it that you # have marked with a slice lookup code name. variable(collection, sl) collection := load slice collection(5) sl := lookup slice(sli:my special slice, collection)
# this example gets a handle to the portrait of the currently displaying # text box (if any) and allows you to manipulate it. variable(portrait) portrait := lookup slice(sl:textbox portrait) if(portrait) then( replace portrait sprite(portrait, 5) )

# This is a list of special slice lookup codes lookup slice(sl:root) lookup slice(sl:textbox text) lookup slice(sl:textbox portrait) lookup slice(sl:textbox choice0) lookup slice(sl:textbox choice1) lookup slice(sl:textbox box) lookup slice(sl:textbox portrait box) lookup slice(sl:textbox choice box) lookup slice(sl:textbox root) lookup slice(sl:script layer) lookup slice(sl:textbox layer) lookup slice(sl:string layer) lookup slice(sl:maproot) lookup slice(sl:obsolete overhead) lookup slice(sl:map overlay) lookup slice(sl:walkabout layer) lookup slice(sl:hero layer) lookup slice(sl:npc layer) lookup slice(sl:walkabout sprite component) lookup slice(sl:walkabout shadow component) lookup slice(sl:backdrop) lookup slice(sl:map layer0) lookup slice(sl:map layer1) lookup slice(sl:map layer2) lookup slice(sl:map layer3) lookup slice(sl:map layer4) lookup slice(sl:map layer5) lookup slice(sl:map layer6) lookup slice(sl:map layer7) lookup slice(sl:map layer8) lookup slice(sl:map layer9) lookup slice(sl:map layer10) lookup slice(sl:map layer11) lookup slice(sl:map layer12) lookup slice(sl:map layer13) lookup slice(sl:map layer14) lookup slice(sl:map layer15) lookup slice(sl:status portrait) lookup slice(sl:status walkabout) lookup slice(sl:status battlesprite) lookup slice(sl:status page select) lookup slice(sl:status statlist) lookup slice(sl:status hide if no mp) lookup slice(sl:status hide if no lmp) lookup slice(sl:status hide if max lev) lookup slice(sl:plank holder) lookup slice(sl:status hide if no portrait) lookup slice(sl:item itemlist) lookup slice(sl:item exitbutton) lookup slice(sl:item sortbutton) lookup slice(sl:item trashbutton) lookup slice(sl:plank menu selectable) lookup slice(sl:spell listlist) lookup slice(sl:spell spelllist) lookup slice(sl:spell hide if no list) lookup slice(sl:spell cancelbutton) lookup slice(sl:virtual keyboard button) lookup slice(sl:virtual keyboard buttontext) lookup slice(sl:virtual keyboard shift) lookup slice(sl:virtual keyboard symbols) lookup slice(sl:virtual keyboard select) lookup slice(sl:virtual keyboard entrytext) lookup slice(sl:virtual keyboard del) lookup slice(sl:virtual keyboard enter) lookup slice(sl:shop buy info panel) lookup slice(sl:status hide if no hp) lookup slice(sl:pathfind dest display)
setslicelookup
getslicelookup
sprite layer
sprite layer
Returns a slice handle for the slice (also called the 'script layer') which is the default parent of all new script-created slices, such as created by loadherosprite and createrect. You can move slices elsewhere in the slice tree with setparent. You can use spritelayer together with firstchild if you want to loop through all your slices without knowing their handles. Another way to get this slice is to use lookupslice:

lookup slice(sl:script layer)

.
variable(sl) sl := first child(sprite layer) while (sl) do, begin if (slice is sprite(sl)) then, begin # do an operation on each sprite end sl := next sibling(sl) end
get slice lookup (handle)
get slice lookup
Returns the lookupcode of a slice, or false if it has none. You can compare the result with the

sli:

slice lookup values in your hsi file, or with the

sl:

special builtin lookup values
lookupslice
setslicelookup
set slice lookup (handle, code)
set slice lookup
Changes the lookup code of a slice. The first argument is the slicehandle, the second is the new lookupcode. You can pass false as the lookup code to remove it. The

code

can be either a lookup code you named in the slice editor, which is available as a constant with a sli: prefix added (e.g. "menubg" becomes sli:menubg), or any positive number - you don't have to give a name to a lookup code before using it! (The values of sli: codes count up from 1, so use large numbers for unnamed lookup codes, to avoid clashing). You can't use sl: special builtin lookup codes, nor can you modify the lookup code of slices that already have special lookup codes. Only user-defined lookup codes can be changed. Built-in special lookup codes cannot.
lookupslice
getslicelookup
get hero slice (rank)
get hero slice
Get a hero walkabout container slice (the parent of all slices for the hero).

rank

is the hero's rank in the walkabout caterpillar. You will not be able to manually reposition this slice (e.g. putslice does not work) - use puthero instead. Once you have this slice you can access any other slices attached to the hero, such as the sprite slice (e.g. lookupslice(sl:walkabout sprite component, get hero slice(rank)), which is equivalent to getherosprite(rank)), or attach other slices to a hero walkabout. See lookupslice for the different walkabout components.
herorankfromslice
getnpcslice
get hero sprite (rank)
get hero sprite
Get the walkabout sprite slice for a hero.

rank

is the hero's rank in the walkabout caterpillar. This is equivalent to lookupslice(sl:walkabout sprite component, get hero slice(rank)).
getheroslice
hero rank from slice (handle)
hero rank from slice
The opposite of getheroslice: Given a slice

handle

, check whether it's the walkabout container slice of some hero, and if so, returns the hero walkabout rank (a number between 0 and 3). If it doesn't belong to any hero, returns -1, not 0/false, like npcreferencefromslice does! This also returns -1 for slices parented to a hero slice, such as the 'walkabout sprite component'. This command is useful if you've detected a collision between two slices (e.g. using findcollidingslice), such as a projectile and another slice, and you want to check whether the projectile hit a hero, and which one. There are always four hero walkabout slices, even if there aren't that many heroes in the active party! The extra hero slices are set to hidden.
getheroslice
npcreferencefromslice
get npc slice (npc)
get npc slice
Get an NPC walkabout container slice (the parent of all slices for the NPC). The argument is the NPC id or an npcreference. If the NPC is tag-disabled, it has no slice so this command returns 0/false. If there are no copies of an NPC ID on the map, an error is thrown. You will not be able to manually reposition this slice (e.g. putslice does not work) - use putnpc instead. Once you have this slice you can access any other slices attached to the npc, such as the sprite slice (e.g. lookupslice(sl:walkabout sprite component, get npc slice(npc)), which is equivalent to getnpcsprite(npc)), or attach other slices to an npc walkabout.
npcreferencefromslice
getheroslice
get npc sprite (npc)
get npc sprite
Get the walkabout sprite slice for a npc.

npc

is an NPC id or npcreference. This is equivalent to lookupslice(sl:walkabout sprite component, get npc slice(npc)).
getnpcslice
npc reference from slice (handle)
npc reference from slice
The opposite of getnpcslice: Given a slice

handle

, check whether it's the walkabout container slice of some NPC, and if so, returns the npcreference number. If it doesn't belong to any NPC, returns 0. This also returns 0 for slices parented to the NPC's slices, such as the 'walkabout sprite component'. This command is useful if you've detected a collision between two slices (e.g. using findcollidingslice), such as a projectile and another slice, and you want to check whether the projectile hit an NPC, and which one.
herorankfromslice
getnpcslice

## Slice Sizing

slice width (handle)
slice width
Returns the width of any slice, for example a sprite.
sliceheight
setslicewidth
slice height (handle)
slice height
Returns the height of any slice, for example a sprite.
slicewidth
setsliceheight
set slice width (handle, width)
set slice width
Changes the width of a slice. This command doesn't work (and shows an error) on sprite and map slices, on text slices that aren't set to wrap, and on slices set to Fill Parent, because they all have a fixed size.
slicewidth
setsliceheight
setslicesize
set slice height (handle, height)
set slice height
Changes the height of a slice. This command doesn't work (and shows an error) on sprite and map slices, on text slices that aren't set to wrap, and on slices set to Fill Parent, because they all have a fixed size.
sliceheight
setslicewidth
setslicesize
set slice size (handle, width, height)
set slice size
Changes the width and height of a slice. This command doesn't work (and shows an error) on sprite and map slices, on text slices that aren't set to wrap, and on slices set to Fill Parent, because they all have a fixed size.
setslicewidth
setsliceheight
clamp slice (handle1, handle2)
clamp slice
Try to move the slice

handle1

so that its screen position will be inside the screen position of slice

handle2

. The size of the slices will not be changed. It does not matter if the slices are related.
slicecontains
fill parent (handle, true_or_false)
fill parent
Make a slice

handle

automatically fill its parent. This will change the position and size of the slice so that it completely fills the parent (minus the parent's padding). You can also disable filling with this command by passing

false

as the second argument, such as

fill parent(handle, false)

. If a slice is filling its parent, then any commands which modify the width or height of the slice will fail. You should resize the parent instead. This command only works on rects and containers. It will not work on sprites because they cannot change size.
isfillingparent
is filling parent (handle)
is filling parent
Returns true if a slice

handle

is set to automatically fill its parent, or false if it is not. This command always returns false for sprite slice handles because sprites cannot be set to fill parent.
fillparent

## Positioning Slices

slice x (handle)
slice x
Returns the X position of any slice, for example a sprite. This position is relative to the slice's parent, and may depend upon the slice's Align settings.
slicey
setslicex
slicescreenx
slice y (handle)
slice y
Returns the Y position of any slice, for example a sprite. This position is relative to the slice's parent, and may depend upon the slice's Align settings.
slicex
setslicey
slicescreeny
put slice (handle, X, Y)
put slice
Changes the position of any slice, for example a sprite. This position is relative to the slice's parent, and may depend upon the slice's Align settings.
putsprite
putslicescreen
movesliceto
set slice x (handle, X)
set slice x
Changes the X position of any slice, for example a sprite. This position is relative to the slice's parent. More exactly, it's the relative displacement between this slice's anchor point, and the selected align point on the parent. The position of the parent's align point also depends on the amount of padding the parent has.
putslice
slicex
setslicey
set slice y (handle, Y)
set slice y
Changes the Y position of any slice, for example a sprite. This position is relative to the slice's parent. More exactly, it's the relative displacement between this slice's anchor point, and the selected align point on the parent. The position of the parent's align point also depends on the amount of padding the parent has.
putslice
slicey
setslicex
slice screen x (handle)
slice screen x
Returns the X position on the screen of the anchor point of a slice. This position is relative to the screen, so it is calculated based on not only the slice's X position, but also its alignment, and the position and size of its parents. However, the slice's anchor point setting doesn't affect this, because that specifies which point on the slice is attached to the anchor point.
slicescreeny
slicex
slice screen y (handle)
slice screen y
Returns the Y position on the screen of the anchor point of a slice. This position is relative to the screen, so it is calculated based on not only the slice's Y position, but also its alignment, and the position and size of its parents. However, the slice's anchor point setting doesn't affect this, because that specifies which point on the slice is attached to the anchor point.
slicescreenx
slicey
put slice screen (handle, x, y)
put slice screen
Change the screen position of any slice. The position of the slice relative to its parent will automatically be corrected. Alignment and anchor will not be changed. Note that this does not work when a slice is filling its parent.
putslice
slicescreenx
setslicescreeny
set slice screen x (handle, x)
set slice screen x
Change the screen X position of any slice. The position of the slice relative to its parent will automatically be corrected. Alignment and anchor will not be changed. Note that this does not work when a slice is filling its parent.
putslicescreen
slicescreenx
setslicescreeny
set slice screen y (handle, y)
set slice screen y
Change the screen Y position of any slice. The position of the slice relative to its parent will automatically be corrected. Alignment and anchor will not be changed. Note that this does not work when a slice is filling its parent.
putslicescreen
slicescreeny
setslicescreenx

## Visibility and Clipping

set slice visible (handle, vis)
set slice visible
Makes slice

handle

invisible or visible, according to

vis

. Slices are automatically visible when you load them, but you can make them invisible with

set slice visible(handle, off)

. If the slice has children, they will become invisible too.
setslicevisible
set sprite visible
get slice visible (handle)
get slice visible
Returns the visibility setting for slice

handle

. This is true for visible, or false for invisible. Note that this only tells you if the slice is set to be invisible, it will not tell you if the slice is invisible for some other reason, such as if it is offscreen, or if it is the child of an invisible parent or grandparent.
set slice clipping (handle, clip)
set slice clipping
Changes whether or not a slice will clip its children if they overflow its edges. The first argument is a slice

handle

. The second argument is true to make the slice clip, or false to allow its children to overflow. (newly created slices do not clip by default)
get slice clipping (handle)
set slice clipping
Returns true if the slice

handle

is set to clip drawing its children, or false if child slices are allowed to be drawn overflowing its edges.

## Alignment and Anchor Points

slice edge x (handle, edge)
slice edge x
Returns the x position of a particular edge of a slice. Use the constants

edge:left

,

edge:center

,

edge:right

. (Not the align: constants used by menus!)
sliceedgey
setsliceedgex
setsliceedgey
slice edge y (handle, edge)
slice edge y
Returns the y position of a particular edge of a slice. Use the constants

edge:top

,

edge:middle

,

edge:bottom

. (Not the align: constants used by menus!)
sliceedgex
setsliceedgex
setsliceedgey
set slice edge x (handle, edge, value)
set slice edge x
Changes the X position of a specific edge of a slice. This is like setslicex, except that you can set by any edge regardless of the slice's anchor. Use the constants

edge:left

,

edge:center

,

edge:right

. (Not the align: constants used by menus!)
sliceedgex
sliceedgey
setsliceedgey
set slice edge y (handle, edge, value)
set slice edge y
Changes the Y position of a specific edge of a slice. This is like setslicey, except that you can set by any edge regardless of the slice's anchor. Use the constants

edge:top

,

edge:middle

,

edge:bottom

. (Not the align: constants used by menus!)
sliceedgex
sliceedgey
setsliceedgex
set horiz align (handle, edge)
set horiz align
Changes the horizontal alignment of any slice relative to its parent. The available edges are

edge:left

,

edge:center

,

edge:right

. (Not the align: constants used by menus!) The default value is edge:left.
setvertalign
sethorizanchor
setvertanchor
gethorizalign
set vert align (handle, edge)
set vert align
Changes the vertical alignment of any slice relative to its parent. The available edges are

edge:top

,

edge:middle

,

edge:bottom

. (Not the align: constants used by menus!) The default value is edge:top.
sethorizalign
sethorizanchor
setvertanchor
getvertalign
set horiz anchor (handle, edge)
set horiz anchor
Changes the horizontal anchor of any slice. The available anchor values are

edge:left

,

edge:center

,

edge:right

. (Not the align: constants used by menus!) The default value is edge:left.
setvertalign
sethorizalign
setvertanchor
gethorizanchor
set vert anchor (handle, edge)
set vert anchor
Changes the vertical anchor of any slice. The available anchor values are

edge:top

,

edge:middle

,

edge:bottom

. (Not the align: constants used by menus!) The default value is edge:top.
setvertalign
sethorizalign
sethorizanchor
getvertanchor
get horiz align (handle)
get horiz align
Returns the horizontal alignment of any slice relative to its parent. The return value will be one of

edge:left

,

edge:center

,

edge:right

. (Not the align: constants used by menus!)
getvertalign
gethorizanchor
getvertanchor
sethorizalign
get vert align (handle)
get vert align
Returns the vertical alignment of any slice relative to its parent. The return value will be one of

edge:top

,

edge:middle

,

edge:bottom

. (Not the align: constants used by menus!)
gethorizalign
gethorizanchor
getvertanchor
setvertalign
get horiz anchor (handle)
get horiz anchor
Returns the horizontal anchor that a slice uses to position itself relative to its parent. The return value will be one of

edge:left

,

edge:center

,

edge:right

. (Not the align: constants used by menus!)
getvertanchor
gethorizalign
getvertalign
sethorizanchor
get vert anchor (handle)
get vert anchor
Returns the vertical anchor that a slice uses to position itself relative to its parent. The return value will be one of

edge:top

,

edge:middle

,

edge:bottom

. (Not the align: constants used by menus!)
gethorizanchor
gethorizalign
getvertalign
setvertanchor
realign slice (handle, horiz align, vert align, horiz anchor, vert anchor)
realign slice
A quick way to set the alignment and optionally the anchor of a slice with a single command. If you leave out the arguments for the anchor then only the alignment will be changed.
sethorizalign
setvertalign
sethorizanchor
setvertanchor
center slice (handle)
center slice
A quick way to center the alignment and the anchor of a slice with a single command. Equivalent to

realign slice(handle, edge:center, edge:center, edge:middle, edge:middle)

.
realignslice
sethorizalign
setvertalign
sethorizanchor
setvertanchor

## Padding

set padding (handle, pixels)
set padding
Sets the padding value in pixels for all the edges of a slice

handle

. This is a positive number to move children attached to the edges towards the center of the slice, or a negative number to move attached children further from the center.
settoppadding
setleftpadding
setrightpadding
setbottompadding
get top padding (handle)
get top padding
Get the padding value in pixels for the top edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
settoppadding
getleftpadding
getrightpadding
getbottompadding
set top padding (handle, pixels)
set top padding
Set the padding value in pixels for the top edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
gettoppadding
setleftpadding
setrightpadding
setbottompadding
get left padding (handle)
get left padding
Get the padding value in pixels for the left edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
setleftpadding
gettoppadding
getrightpadding
getbottompadding
set left padding (handle, pixels)
set left padding
Set the padding value in pixels for the left edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
getleftpadding
settoppadding
setrightpadding
setbottompadding
get right padding (handle)
get right padding
Get the padding value in pixels for the right edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
setrightpadding
gettoppadding
getleftpadding
getbottompadding
set right padding (handle, pixels)
set right padding
Set the padding value in pixels for the right edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
getrightpadding
settoppadding
setleftpadding
setbottompadding
get bottom padding (handle)
get bottom padding
Get the padding value in pixels for the bottom edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
setbottompadding
gettoppadding
getleftpadding
getrightpadding
set bottom padding (handle, pixels)
set bottom padding
Set the padding value in pixels for the bottom edge of a slice

handle

. This is a positive number to move children attached to this edge towards the center of the slice, or a negative number to move attached children further from the center.
getbottompadding
settoppadding
setleftpadding
setrightpadding

## Moving Slices

set slice velocity x (handle, pixels per tick, ticks)
set slice velocity x
Cause slice

handle

to start moving horizontally. A negative value for

pixels per tick

moves left, and a positive value for

pixels per tick

moves right. The

ticks

argument is optional. If you do not specify the number of ticks, the slice will keep moving indefinitely. If you specify the number of ticks, the velocity will expire and be set back to zero automatically after that number of ticks has passed.

Movement in horizontal and vertical directions is independent, and can timeout after different numbers of ticks. For example if you set a slice's x velocity to 10 for 5 ticks, and y velocity to 10 for 2 ticks, it'll move diagonally down-right for 2 ticks and then right for 3 ticks.

setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
set slice velocity y (handle, pixels per tick, ticks)
set slice velocity y
Cause slice

handle

to start moving vertically. A negative value for

pixels per tick

moves up, and a positive value for

pixels per tick

moves down. The

ticks

argument is optional. If you do not specify the number of ticks, the slice will keep moving indefinitely. If you specify the number of ticks, the velocity will expire and be set back to zero automatically after that number of ticks has passed.

Movement in horizontal and vertical directions is independent, and can timeout after different numbers of ticks. For example if you set a slice's x velocity to 10 for 5 ticks, and y velocity to 10 for 2 ticks, it'll move diagonally down-right for 2 ticks and then right for 3 ticks.

setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
get slice velocity x (handle)
get slice velocity x
Returns a number representing the horizontal velocity of slice

handle

. The return value is in pixels per tick. A negative value means the slice is moving left, and a positive value means the slice is moving right.
setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
get slice velocity y (handle)
get slice velocity y
Returns a number representing the vertical velocity of slice

handle

. The return value is in pixels per tick. A negative value means the slice is moving up, and a positive value means the slice is moving down.
setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
set slice velocity (handle, horiz pixels per tick, vert pixels per tick, ticks)
set slice velocity
Cause slice

handle

to start moving. This is similar to using both setslicevelocityx and setslicevelocityy at the same time. The

ticks

argument is optional. If you do not specify the number of ticks, the slice will keep moving indefinitely. If you specify the number of ticks, the velocity will expire and be set back to zero automatically after that number of ticks has passed.
setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
stop slice (handle)
stop slice
Cause slice

handle

to stop moving. This cancels any previous slice velocity and move slice commands.
setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
move slice to (handle, x, y, ticks)
move slice to
Instruct slice

handle

to move in a straight line to a specific

x

and

y

position over a given number of

ticks

. (As always, the position is an offset relative to its parent.)

If you change the slice's position manually during that time (eg. with putslice), it'll continue to move towards the original target in a straight line. Use setslicevelocity instead if you don't want this.

setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
move slice by (handle, relative x, relative y, ticks)
move slice by
Instruct slice

handle

to move in a straight line to an

x

and

y

offset relative to its current position over a given number of

ticks

. (As always, the position is an offset relative to its parent.) A negative

relative x

moves left. A positive

relative x

moves right. A negative

relative y

moves up. A positive

relative y

moves down.

If you change the slice's position manually during that time (eg. with putslice), it'll continue to move towards the original target in a straight line. Use setslicevelocity instead if you don't want this.

setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
wait for slice (handle)
wait for slice
Cause the script to wait until slice

handle

has stopped moving. This only applies to commands that operate over time like setslicevelocityx or setslicevelocity or movesliceto or movesliceby. There is no reason to use this command for instantaneous slice moving commands like putslice or setslicex or setslicey.
setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving
slice is moving (handle)
slice is moving
Returns true if the slice

handle

is moving (has velocity or has been instructed to move to some point). Returns false if the slice is not moving.
setslicevelocityx
setslicevelocityy
getslicevelocityx
getslicevelocityy
setslicevelocity
stopslice
movesliceto
movesliceby
waitforslice
sliceismoving

## Moving Around the Slice Tree

slice child (handle, number)
slice child
Returns a handle for the nth child of a slice, counting from 0. Returns

false

if

number

is too large (

last child(handle)

is equivalent to

slice child(handle, child count(handle) -- 1)

). Note that you will need to use firstchild and nextsibling to iterate over the children of a slice, rather than this command, when you are moving the children around.
childcount
parentslice
firstchild
lastchild
child count (handle)
child count
Returns the number of children that slice

handle

has.
slicechild
firstchild
slice child index (handle)
slice child index
Returns an integer that that indicates which number this slice is among its sibling slices that share the same parent. The first slice will return index 0, the second slice 1, the third slice 2, etc...
slicechild
first child (handle)
first child
Returns a slice handle for the first child of a given slice

handle

. Returns

false

if the slice has no children. You can use this to loop through all the children of a slice.
variable(sl) sl := first child(sprite layer) while (sl) do, begin if (slice is sprite(sl)) then, begin # do an operation on each sprite end sl := next sibling(sl) end
slicechild
firstspritechild
firstrectchild
firstcontainerchild
lastchild
childcount
last child (handle)
last child
Returns a slice handle for the last child of a given slice

handle

. Returns

false

if the slice has no children.
slicechild
firstchild
childcount
next sibling (handle)
next sibling
Returns a slice handle for the next sibling of a given slice

handle

. Returns

false

if the given slice is the last sibling of its parent. This is useful when looping through slices.
variable(sl) sl := first child(sprite layer) while (sl) do, begin if (slice is sprite(sl)) then, begin # do an operation on each sprite end sl := next sibling(sl) end
previoussibling
nextspritesibling
nextrectsibling
nextcontainersibling
slicechild
freeslice
slicetofront
slicetoback
movesliceabove
moveslicebelow
previous sibling (handle)
previous sibling
Returns a slice handle for the previous sibling of a given slice

handle

, the inverse of nextsibling . Returns

false

if the given slice is the first sibling of its parent. This is useful when looping through slices.
nextsibling
slicechild
freeslice
slicetofront
slicetoback
movesliceabove
moveslicebelow
parentslice
slice parent
parent slice (handle)
parent slice
Returns a slice handle for the parent of slice

handle

, or 0 if

handle

is the root slice.
setparent
checkparentage
slicechild
check parentage (handle, parent handle)
check parentage
Checks to see if

handle

is a child (or grandchild, or great-grandchild, etc...) of

parent handle

. Returns true or false.
parentslice
setparent

### Type-specific iteration commands

first child of type(handle, type)
first child of type
Returns a slice handle for the first child of a given slice

handle

which has the given

type

.

type

is one of the slicetype: constants, such as slicetype:sprite. See slicetype for the full list. Returns

false

if the slice has no children of that type. Children of other types will be ignored. This is useful when looping through slices.
firstchild
next sibling of type (handle, type)
next sibling of type
Returns a slice handle for the next sibling of a given slice

handle

which has the given

type

.

type

is one of the slicetype: constants, such as slicetype:sprite. See slicetype for the full list. Returns

false

if there are no more children of that type. Children of other types will be ignored. This is useful when looping through slices.
nextsibling
first container child (handle)
first container child
An alias for firstchildoftype(handle, slicetype:container).
next container sibling (handle)
next container sibling
An alias for nextsiblingoftype(handle, slicetype:container).
first rect child (handle)
first rect child
An alias for firstchildoftype(handle, slicetype:rect).
next rect sibling (handle)
next rect sibling
An alias for nextsiblingoftype(handle, slicetype:rect).
first sprite child (handle)
first sprite child
An alias for firstchildoftype(handle, slicetype:sprite).
next sprite sibling (handle)
next sprite sibling
An alias for nextsiblingoftype(handle, slicetype:sprite).
first text child (handle)
first text child
An alias for firstchildoftype(handle, slicetype:text).
next text sibling (handle)
next text sibling
An alias for nextsiblingoftype(handle, slicetype:text).
first ellipse child (handle)
first ellipse child
An alias for firstchildoftype(handle, slicetype:ellipse).
next ellipse sibling (handle)
next ellipse sibling
An alias for nextsiblingoftype(handle, slicetype:ellipse).
first grid child (handle)
first grid child
An alias for firstchildoftype(handle, slicetype:grid).
next grid sibling (handle)
next grid sibling
An alias for nextsiblingoftype(handle, slicetype:grid).
first scroll child (handle)
first scroll child
An alias for firstchildoftype(handle, slicetype:scroll).
next scroll sibling (handle)
next scroll sibling
An alias for nextsiblingoftype(handle, slicetype:scroll).
first select child (handle)
first select child
An alias for firstchildoftype(handle, slicetype:select).
next select sibling (handle)
next select sibling
An alias for nextsiblingoftype(handle, slicetype:select).
first panel child (handle)
first panel child
An alias for firstchildoftype(handle, slicetype:panel).
next panel sibling (handle)
next panel sibling
An alias for nextsiblingoftype(handle, slicetype:panel).
first line child (handle)
first line child
An alias for firstchildoftype(handle, slicetype:line).
next line sibling (handle)
next line sibling
An alias for nextsiblingoftype(handle, slicetype:line).

## Reordering Slices

slice to front (handle)
slice to front
Sort a slice

handle

so that it is drawn in front of other slices with the same parent. This is done by moving it to the end of its parent's child list. If you use this command inside a loop that iterates through slices using nextsibling be careful not to accidentally create an endless loop.
script, simple example, begin # As long as you are not looping with the "next sibling" command # then "slice to front" is safe and easy to use. variable(sl) sl := first child(sprite layer) slice to front(sl) end

script, dangerous sorting, begin # this is an example of the WRONG way to move all rect slices to the # front in a loop. Because moving a slice to the front adds it to the # end of the list, the loop will go on forever. variable(sl) sl := first child(sprite layer) while(sl) do, begin if(slice is rect(sl)) then, begin slice to front(sl) end sl := next sibling(sl) end end

script, safe sorting, begin # This is an example of the right way to move all rect slices to the # front in a loop. By remembering which slice was last before the # loop starts (or by using "previous sibling") it is safe to move slices # to the end of the sibling list. # We also ensure the rects stay in the same relative order by writing # the loop so that we move the last slice to front if it is a rect. variable(sl, last, prev) last := last child(sprite layer) sl := first child(sprite layer) while(sl && sl <> last) do, begin prev := sl sl := next sibling(sl) if(slice is rect(prev)) then(slice to front(prev)) end end

script, easier safe sorting, begin # If you need to sort slices in a loop, you might find it easier # to avoid the "slice to front" command and use "set sort order" # and "sort children" instead. variable(sl) sl := first child(sprite layer) while(sl) do, begin if(slice is rect(sl)) then, begin set sort order(sl, 1) end sl := next sibling(sl) end sort children(sprite layer) end
slicetoback
movesliceabove
slice to back (handle)
slice to back
Sort a slice

handle

so it will be drawn behind other slices with the same parent. If you use this command inside a loop, be careful not to accidentally create an endless loop. Moving a slice to the back also moves it to the first position of its parent's sibling list.
script, simple example, begin # As long as you are not looping with the "next sibling" command # then "slice to back" is safe and easy to use. variable(sl) sl := load hero sprite(0) slice to back(sl) end

script, dangerous sorting, begin # This is an example of the WRONG way to move all rect slices to the # back in a loop. Because moving a slice to the back moves it to the # top of the list, the loop will be restarted each time variable(sl) sl := first child(sprite layer) while(sl) do, begin if(slice is rect(sl)) then, begin slice to back(sl) end sl := next sibling(sl) end end

script, safe but incorrect sorting, begin # This is an example of a safe way to move all the rect slices to the # back. HOWEVER the order in which all the rects will be drawn will # be reversed! That might be alright for your need. # By moving the slice AFTER using the "next sibling" command we avoid # re-starting the loop. variable(sl, moveme) sl := first child(sprite layer) while(sl) do, begin moveme := 0 if(slice is rect(sl)) then, begin moveme := sl end sl := next sibling(sl) if(moveme) then(slice to back(moveme)) end end

script, correct sorting, begin # This is an example of one right way to move all rect slices to the # back with a loop and preservw relative ordering between the rects. # Note that we ensure the rects stay in the same relative order by writing # the loop so that we also move the 'first' slice to back if it is a rect. variable(sl, first, prev) first := first child(sprite layer) sl := last child(sprite layer) while(sl && sl <> first) do, begin prev := sl sl := previous sibling(sl) if(slice is rect(prev)) then(slice to back(prev)) end end

script, easier safe sorting, begin # If you need to sort slices in a loop, you might find it easier # to avoid the "slice to back" command and use "set sort order" # and "sort children" instead. variable(sl) sl := first child(sprite layer) while(sl) do, begin if(slice is rect(sl)) then, begin set sort order(sl, -1) end sl := next sibling(sl) end sort children(sprite layer) end
slicetofront
moveslicebelow
move slice above (handle, above what handle)
move slice above
Given a slice

handle

, move it so that it is the next sibling of another slice given by

above what handle

(changing its parent if necessary). This will cause it to be drawn immediately after that slice.
moveslicebelow
slicetofront
slicetoback
nextsibling
move slice below (handle, below what handle)
move slice below
Given a slice

handle

, move it so that it is the previous sibling of another slice given by

below what handle

(changing its parent if necessary). This will cause it to be drawn immediately before that slice.
movesliceabove
slicetofront
slicetoback
previoussibling
Y sort children (handle)
Y sort children
Given a slice

handle

, sort all of its children according to their Y position. This means that sibling slices lower on the screen will be drawn over siblings higher on the screen.
sortchildren
set sort order (handle, order)
set sort order
Assign a sort order value to a slice

handle

. This can be any arbitrary number that will be used to sort the slice relative to its sibling slices the next time that sortchildren is called. Give a slice a low number to sort it to the back or a high number to sort it to the front. This means it functions like (or can be used as) a z-depth. If you give two sibling slices the same sort order number they will be sorted to the same depth, and they will remain in their original order in relation to one another.
getsortorder
get sort order (handle)
get sort order
Retrieve the sort order value previously set on a slice

handle

with getsortorder. Note that calling sortchildren by default resets all the sort order values to zero, unless false is passed as

wipe

.
sort children (handle, wipe)
sort children
Given a slice

handle

, sort all of its children according to the sort order that you previously set with the setsortorder command. If no sort order values have been set then no changes will be made to the order of the slices.

wipe

is an optional argument, defaulting to true, which specifies whether to zero out the sort order value for each slice after they have been sorted. This zeroing out behaviour is intended to let you use temporary sort values to perform some sorting operation on sibling slices (see especially the examples to slicetofront and slicetoback).
plotscript, reverse Y sort, begin variable(sl) sl := first child(sprite layer) while(sl) then, begin set sort order(sl, slice y(sl) * -1) sl := next sibling(sl) end sort children(sprite layer) end
setsortorder
getsortorder
ysortchildren

## Slice Types

For a description of the different slice types, see the Slices article on the wiki.

There are two types of slice used by the engine for which there are no commands: 'special' slices (such as sprite layer), and 'map' slices (which are map layers). However you can use lookupslice to find each instance of these. Special slices are nothing but container slices with special purposes (but not special behaviour). None of these kinds of slices can be created or manipulated in the slice collection editor either.

### Checking Slice Type

slice type (handle)
slice type
Returns the type of the given slice

handle

, one of the constants: slicetype:Special, slicetype:Container, slicetype:Rect, slicetype:Line, slicetype:Ellipse, slicetype:Sprite, slicetype:Text, slicetype:Map, slicetype:Grid, slicetype:Scroll, slicetype:Select, slicetype:Panel, slicetype:Layout.
slice is container (handle)
slice is container
Returns true if the given slice

handle

is a container, or false for any other type. It's an error to provide an invalid

handle

.
slice is sprite (handle)
slice is sprite
Returns true if the given slice

handle

is a sprite, or false for any other type. It's an error to provide an invalid

handle

.
slice is rect (handle)
slice is rect
Returns true if the given slice

handle

is a rect, or false for any other type. It's an error to provide an invalid

handle

.
slice is line (handle)
slice is line
Returns true if the given slice

handle

is a line, or false for any other type. It's an error to provide an invalid

handle

.
slice is ellipse (handle)
slice is ellipse
Returns true if the given slice

handle

is a ellipse, or false for any other type. It's an error to provide an invalid

handle

.
slice is text (handle)
slice is text
Returns true if the given slice

handle

is a text slice, or false for any other type. It's an error to provide an invalid

handle

.
slice is grid (handle)
slice is grid
Returns true if the given slice

handle

is a grid, or false for any other type. It's an error to provide an invalid

handle

.
slice is select (handle)
slice is select
Returns true if the given slice

handle

is a select slice, or false for any other type. It's an error to provide an invalid

handle

.
slice is scroll (handle)
slice is scroll
Returns true if the given slice

handle

is a scroll slice, or false for any other type. It's an error to provide an invalid

handle

.
slice is panel (handle)
slice is panel
Returns true if the given slice

handle

is a panel slice, or false for any other type. It's an error to provide an invalid

handle

.
slice is map layer (handle)
slice is map layer
Returns true if the given slice

handle

is a map layer, or false for any other type. It's an error to provide an invalid

handle

.

### Container Slices

create container (width, height)
create container
Create a new container slice and return a handle to it. Containers are invisible slices used only for grouping other slices. You can optionaly specify a

width

and

height

for the container. variable(holder, sl) holder := create container(200,100) sl := load hero sprite(0) set parent(sl, holder) set horiz align(sl, edge:left) sl := load hero sprite(1) set parent(sl, holder) set horiz align(sl, edge:right) The example above creates a container and then puts two hero sprites inside it, one aligned left and one aligned right. If you move or resize the container, the sprites inside it will also be moved.

### Sprite Slices

Unlike the other types of slices, sprite slices come in different subtypes for each of the different sprite sizes. A sprite slice of one subtype can be turned into another subtype with the

replace*sprite

commands.
load sprite (sprite type, num, palette)
load sprite
Creates a sprite slice by loading a sprite of the given

sprite type

(use a constant like spritetype:walkabout; see getspritetype for more), with sprite set number

num

and with given

palette

. Returns a handle for the slice. You may omit

palette

, in which case the default palette for that sprite will be loaded.

palette

is ignored for spritetype:backdrop. You must free it with freesprite when you are done.
replacesprite
loadherosprite
loadsmallenemysprite
loadmediumenemysprite
loadlargeenemysprite
loadwalkaboutsprite
loadattacksprite
loadbordersprite
loadportraitsprite
loadbackdropsprite
getspritetype
getspritesetnumber
freesprite
loadsprite
create sprite
replace sprite (slice, sprite type, num, palette)
replace sprite
Change an existing sprite

slice

into a different sprite, loading a sprite of the given

sprite type

(use a constant like spritetype:walkabout; see getspritetype for more), with sprite set number

num

and with given

palette

. You may omit

palette

, in which case the default palette for that sprite will be loaded.

palette

is ignored for spritetype:backdrop. The handle for the slice doesn't change, and everything except the size of the slice stays the same. You must free it with freesprite when you are done.
loadsprite
replaceherosprite
replacesmallenemysprite
replacemediumenemysprite
replacelargeenemysprite
replacewalkaboutsprite
replaceattacksprite
replacebordersprite
replaceportraitsprite
replacebackdropsprite
getspritetype
getspritesetnumber
freesprite
load hero sprite (num, palette)
load hero sprite
Loads hero battle sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replaceherosprite!
replaceherosprite
freesprite
replace hero sprite (handle, num, palette)
replace hero sprite
Given an existing sprite

handle

, changes it to hero battle sprite #

num

with palette

palette

. As with loadherosprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadherosprite.

loadherosprite
freesprite
load walkabout sprite (num, palette)
load walkabout sprite
Loads walkabout sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replacewalkaboutsprite!
replacewalkaboutsprite
freesprite
replace walkabout sprite (handle, num, palette)
replace walkabout sprite
Given an existing sprite

handle

, changes it to walkabout sprite #

num

with palette

palette

. As with loadwalkaboutsprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadwalkaboutsprite.

loadwalkaboutsprite
freesprite
load small enemy sprite (num, palette)
load small enemy sprite
Loads small enemy sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replacesmallenemysprite!
replacesmallenemysprite
freesprite
replace small enemy sprite (handle, num, palette)
replace small enemy sprite
Given an existing sprite

handle

, changes it to small enemy sprite #

num

with palette

palette

. As with loadsmallenemysprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadsmallenemysprite.

loadsmallenemysprite
freesprite
load medium enemy sprite (num, palette)
load medium enemy sprite
Loads medium enemy sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replacemediumenemysprite!
replacemediumenemysprite
freesprite
replace medium enemy sprite (handle, num, palette)
replace medium enemy sprite
Given an existing sprite

handle

, changes it to medium enemy sprite #

num

with palette

palette

. As with loadmediumenemysprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadmediumenemysprite.

loadmediumenemysprite
freesprite
load large enemy sprite (num, palette)
load large enemy sprite
Loads large enemy sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replacelargeenemysprite!
replacelargeenemysprite
freesprite
replace large enemy sprite (handle, num, palette)
replace large enemy sprite
Given an existing sprite

handle

, changes it to large enemy sprite #

num

with palette

palette

. As with loadlargeenemysprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadlargeenemysprite.

loadlargeenemysprite
freesprite
load attack sprite (num, palette)
load attack sprite
Loads attack battle sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replaceattacksprite!
replaceattacksprite
freesprite
replace attack sprite (handle, num, palette)
replace attack sprite
Given an existing sprite

handle

, changes it to attack battle sprite #

num

with palette

palette

. As with loadattacksprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadattacksprite.

loadattacksprite
freesprite
load weapon sprite (num, palette)
load weapon sprite
Loads weapon battle sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replaceweaponsprite!
replaceweaponsprite
freesprite
replace weapon sprite (handle, num, palette)
replace weapon sprite
Given an existing sprite

handle

, changes it to weapon battle sprite #

num

with palette

palette

. As with loadweaponsprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadweaponsprite.

loadweaponsprite
freesprite
load border sprite (num, palette)
load border sprite
Loads border battle sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replacebordersprite!
replacebordersprite
freesprite
replace border sprite (handle, num, palette)
replace border sprite
Given an existing sprite

handle

, changes it to border battle sprite #

num

with palette

palette

. As with loadbordersprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadbordersprite.

loadbordersprite
freesprite
load portrait sprite (num, palette)
load portrait sprite
Loads portrait battle sprite #

num

with palette

palette

, and returns a slicehandle.. You may omit

palette

, in which case the default palette for that sprite will be loaded. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replaceportraitsprite!
replaceportraitsprite
freesprite
replace portrait sprite (handle, num, palette)
replace portrait sprite
Given an existing sprite

handle

, changes it to portrait battle sprite #

num

with palette

palette

. As with loadportraitsprite, you may omit

palette

, in which case the default palette for that sprite will be loaded. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadportraitsprite.

loadportraitsprite
freesprite
load backdrop sprite (num)
load backdrop sprite
Loads backdrop #

num

as a sprite, and returns a slicehandle.. You must free it with freesprite when you are done.If you want to replace an existing sprite (or other slice) either use freesprite first, or use replacebackdropsprite!
showbackdrop
replacebackdropsprite
freesprite
replace backdrop sprite (handle, num)
replace backdrop sprite
Given an existing sprite

handle

, changes it to backdrop #

num

. You must free it with freesprite when you are done. This function is used when you merely wish to change the image, but not move it or anything. You must free it with freesprite when you are done.

You may use this on any sprite, not just ones loaded with loadbackdropsprite.

loadbackdropsprite
freesprite
free sprite (handle)
free sprite
Unloads a sprite loaded by any of the "load x sprite" functions. This removes the sprite from the screen and removes it from memory. It is a good idea to free sprites when you are completely done with them. Unlike freeslice, this command only works on sprites, but it will still also free any children of the sprite it is freeing regardless of what kind of children they are. The only purpose of this command is additional error checking.
freeslice
loadherosprite
clone sprite (handle)
clone sprite
Duplicates a sprite slice, returning a handle to it. The new sprite inherits only the sprite-related data; in all other ways it is like a freshly created new slice. For example, the parent of the new slice is spritelayer and it starts out visible, with default anchoring, is at position 0,0, has no children, etc.. If you clone a sprite, remember that you will need to call freesprite on both the original and the clone.

If you want to copy a non-sprite slice, copy all the properties of the slice, or copy its children, then use the cloneslice command instead.

freesprite
cloneslice
put sprite (handle, x, y)
put sprite
Moves sprite

handle

to position (

x

,

y

). This can only be used on sprites, use putslice in general.
putsprite
place sprite
get sprite type (handle)
get sprite type
Gets the type of sprite slice

handle

, or returns -1 if the slice is not a sprite. You can compare the result with the following constants:

- spritetype:hero
- spritetype:small enemy
- spritetype:medium enemy
- spritetype:large enemy
- spritetype:walkabout
- spritetype:weapon
- spritetype:attack
- spritetype:border
- spritetype:portrait
- spritetype:backdrop

getspritesetnumber
getspritepalette
getspriteframe
set sprite set number (handle, record)
set sprite set number
Changes the record number of the spriteset of a sprite slice

handle

.
getspritesetnumber
setspritepalette
setspriteframe
get sprite set number (handle)
get sprite set number
Gets the record number of the spriteset of a sprite slice

handle

.
getspritetype
getspritepalette
getspriteframe
set sprite palette (handle, num)
set sprite palette
Changes the palette of sprite slice

handle

to be

num

. If

num

is -1 or omitted, the default palette for that sprite is loaded.
getspritepalette
get sprite palette (handle)
get sprite palette
Returns the palette of sprite slice

handle

, or returns -1 if the sprite is set to use the default palette (use getspritedefaultpal to figure which that is).
getspritetype
getspritesetnumber
getspriteframe
get sprite default pal (handle)
get sprite default pal
Returns the default palette of sprite slice

handle

. You don't need to use this when you want to set a sprite to its default palette, because setting the palette number to -1 will have that effect. This command is for finding out the real palette number that would be used if the palette is set to -1.
getspritepalette
setspritepalette
set sprite frame (handle, num)
set sprite frame
Changes the frame of sprite slice

handle

to be

num

.
getspriteframe
get sprite frame (handle)
get sprite frame
Returns the current frame number of sprite slice

handle

.
getspritetype
getspritepalette
getspritesetnumber
sprite frame count (handle)
sprite frame count
Returns the total number of available frames for a given sprite slice

handle

. For example a backdrop has just one frame, an attack sprite has three.
horiz flip sprite (handle, flip)
horiz flip sprite
Flips a sprite slice

handle

horizontally. You can also unflip a previously flipped sprite using

horiz flip sprite(handle, false)

vertflipsprite
spriteishorizflipped
vert flip sprite (handle, flip)
vert flip sprite
Flips a sprite slice

handle

vertically. You can also unflip a previously flipped sprite using

vert flip sprite(handle, false)

horizflipsprite
spriteisvertflipped
sprite is horiz flipped (handle)
sprite is horiz flipped
Returns true if a sprite slice

handle

is flipped horizontally, or false if it is not.
horizflipsprite
spriteisvertflipped
sprite is vert flipped (handle)
sprite is vert flipped
Returns true if a sprite slice

handle

is flipped vertically, or false if it is not.
vertflipsprite
spriteishorizflipped
get sprite trans (handle)
get sprite trans
Given a sprite slice

handle

, returns true if the sprite is drawn with transparency (that is, color 0 is transparent). All sprites default to transparent.
setspritetrans
set sprite trans (handle, drawtransparent)
set sprite trans
Given a sprite slice

handle

, sets whether it should be drawn with transparency (that is, color 0 is transparent). All sprites default to transparent, so you are unlikely to have any use for this command.
getspritetrans
dissolve sprite (handle, dissolve type, total ticks, start tick, backwards, automatic)
dissolve sprite
Dissolve a sprite using pre-defined dissolve animations. The first argument is a sprite slice

handle

. The second argument is the

dissolve type

. There are dissolve:name constants with the same names as the enemy dissolve animations. Valiid dissolve type constands include:

dissolve:random scatter

,

dissolve:crossfade

,

dissolve:diagonal vanish

,

dissolve:sink into ground

,

dissolve:squash

,

dissolve:melt

,

dissolve:vapourise

,

dissolve:phase out

,

dissolve:squeeze

,

dissolve:shrink

,

dissolve:flicker

.

dissolve:shrink to center

, The third argument is the total number of ticks that the animation should run. You can use dissolvetime:default or -1 for the default number of ticks, which is equal to the sprites (width + height) / 10. The fourth argument is the tick to start on, or 0 to start from the beginning. The fifth argument is false for a normal dissolve, or true for a backwards dissolve. The sixth argument is true for an automatic dissolve (the default), or false to prevent the dissolve animation from proceeding automatically, in case you want to manually control it.
canceldissolve
spriteisdissolving
waitfordissolve
cancel dissolve (handle)
cancel dissolve
If a sprite slice

handle

is currently dissolving, cancel the dissolve animation, restoring the sprite to normal.
dissolvesprite
spriteisdissolving
waitfordissolve
sprite is dissolving (handle)
sprite is dissolving
Returns true if a sprite slice

handle

is currently dissolving, or false if it is not. Checks for both automatically dissolving sprites, and sprites that have been manually set to a partially dissolved state.
canceldissolve
spriteisdissolving
waitfordissolve
wait for dissolve (handle)
wait for dissolve
Pauses the current script until the sprite slice

handle

has finished dissolving. This command only waits if the dissolve is automatic. This command will not wait for sprites that have been manually set to a partially dissolved state.
canceldissolve
spriteisdissolving
waitfordissolve

### Rect Slices

create rect (width, height, style)
create rect
Create a new rectangle slice and return a handle to it. You can provide an optional

width

and

height

, and an optional

style

. The style is text box style number from 0 to 14, or -1 for an unstyled box. The default is box style 0. Like all slice types, a rect slice can be used as a container for other slices with setparent
get rect style (handle)
get rect style
Given a rect slice

handle

, return the style it is using. This will be a number from 0 to 14 representing a text box style, or -1 if the rect is not using a standard style. Using any of the setrectfgcol, setrectbgcol, setrectborder or setrectrawborder commands causes this command to return -1.
setrectstyle
set rect style (handle, style)
set rect style
Given a rect slice

handle

, change the box style it uses. The

style

should be a number from 0 to 14 representing a box style (edited in the "Edit Box Styles" menu). Setting the style changes the foreground (box) and background (edge) colors and the border.
getrectstyle
setrectfgcol
setrectbgcol
setrectborder
get rect bgcol (handle)
get rect bgcol
Given a rect slice

handle

, return the background color it is using, which is the color inside the box (unless the box is totally transparent!) This will be a number from 0 to 255 representing a color from the master palette.
setrectbgcol
getrectfgcol
set rect bgcol (handle, color)
set rect bgcol
Given a rect slice

handle

, change the background color it uses, which is the color of the box. The

color

should be a number from 0 to 255 representing a color from the master palette.
getrectbgcol
setrectfgcol
get rect fgcol (handle)
get rect fgcol
Given a rect slice

handle

, return the foreground color it uses for its simple border. This only matters when the rect has no graphical border, or when the graphical border allows the simple border to show through. This will be a number from 0 to 255 representing a color from the master palette.
setrectfgcol
getrectbgcol
set rect fgcol (handle, color)
set rect fgcol
Given a rect slice

handle

, change the foreground color it uses for its simple border. This only matters when the rect has no graphical border, or when the graphical border allows the simple border to show through. The

color

should be a number from 0 to 255 representing a color from the master palette.
getrectfgcol
setrectbgcol
get rect border (handle)
get rect border
Given a rect slice

handle

, return the style number of the graphical border it uses. This will be a number from 0 to 14 representing a text box border style, or

border:line

for a simple line border only, or

border:none

for no border at all, or

border:raw

if the box uses a "raw" box border spriteset number instead (in that case you need to call getrectrawborder to find out which it is).
setrectborder
getrectrawborder
get rect raw border (handle)
get rect raw border
Given a rect slice

handle

, return the spriteset ID number of the graphical border it uses, or

border:line

if it has a simple line border only, or

border:none

for no border at all. If the border is being determined by a box style number (e.g. due to setrectstyle or setrectborder), then this command returns the actual box border spriteset instead of the box style number.
setrectrawborder
getrectborder
set rect border (handle, border)
set rect border
Given a rect slice

handle

, change the graphical border it uses. The

border

should be a box style number from 0 to 14 representing a text box border style, or

border:line

for a simple line border only, or

border:none

for no border at all. (You can't use

border:raw

.) This command overrides both setrectstyle and setrectrawborder.

border

is not a box border spriteset number, it's a box style number! If you want to specify the box border spriteset directly, use setrectrawborder.
getrectborder
setrectrawborder
set rect raw border (handle, border)
set rect raw border
Given a rect slice

handle

, change the graphical border it uses. The

border

should be a border spriteset number (not a box style number), or

border:line

for a simple line border only, or

border:none

for no border at all. (You can't use

border:raw

.) This command overrides both setrectstyle and setrectborder.
getrectrawborder
setrectborder
get rect trans (handle)
get rect trans
Given a rect slice

handle

, returns one of: the constant

trans:fuzzy

if it is drawn semi-transparent (with any fuzziness percentage from 1 to 99: see getrectfuzziness),

trans:hollow

if it is fully transparent, or

trans:solid

(equal to false) if it is drawn solid.
setrecttrans
getrectfuzziness
set rect trans (handle, transparency setting)
set rect trans
Given a rect slice

handle

, change how transparently it is drawn. For

transparency setting

, pass in one of the constants

trans:fuzzy

for semi-transparency (checkered, ie. 50% fuzziness),

trans:hollow

for fully transparent (the border drawn only), or

trans:solid

(equal to false) for solid. Note that this command is strictly weaker than setrectfuzziness, which provides much finer control of rectangle slice transparency/translucency.
getrecttrans
setrectfuzziness
get rect fuzziness (handle)
get rect fuzziness
Given a rect slice

handle

, returns the percentage translucency of the slice, from 0 to 100: 0 if the rectangle is hollow, 100 if it is opaque, and a value between 1 and 99 if it is fuzzy. Rectangles set to trans:fuzzy using setrecttrans default to 50% translucency.
setrecttrans
getrecttrans
setrectfuzziness
set rect fuzziness (handle, percent)
set rect fuzziness
Sets the percentage translucency of a rect slice

handle

to

percent

. A

percent

of 0 is equivalent to setrecttrans(handle, trans:hollow), a

percent

of 100 is equivalent to setrecttrans(handle, trans:opaque), and anything in between 1 and 99 implicitly does setrecttrans(handle, trans:fuzzy) as well as setting the percentage.
setrecttrans
getrecttrans
getrectfuzziness

### Line Slices

Line slices are slighty different; their size doesn't exactly define the size of the rectangular part of the screen which they stretch across, but is instead used as the offset between their ends. Both ends are drawn inclusively. For example a width 10 height 0 Line slice positioned at x=50,y=20 will draw a line from 50,20 to 60,20, as a rectangle that's actually 11 pixels long and 1 pixel high. The line thickness is always 1 pixel. A width=0 height=0 line slice is a single pixel. So you can give line slices a negative width or height too, to draw a line at any angle. The "top-left" alignment point of a line slice is its start point, and the "bottom-right" is its end point.
create line (width, height, color)
create line
Create a new line slice and return a handle to it. You can provide an optional

width

and

height

and an optional

color

(all default to 0). Like all slice types, an line slice can be used as a container for other slices with setparent.
get line color (handle)
get line color
Given an line slice

handle

, return its color. This will be a number from 0 to 255 representing a color from the master palette, or less than 0 for a UI color.
setlinecolor
set line color (handle, color)
set line color
Given an line slice

handle

, change its color. The

color

should be a number from 0 to 255 representing a color from the master palette.
getlinecolor

### Ellipse Slices

create ellipse (width, height, border color, fill color)
create ellipse
Create a new ellipse slice and return a handle to it. You can provide an optional

width

and

height

, an optional

border color

and an optional

fill color

. The ellipse will be hollow if you do not specify a fill color. Like all slice types, an ellipse slice can be used as a container for other slices with setparent
get ellipse border col (handle)
get ellipse border col
Given an ellipse slice

handle

, return the color it uses for its border. This will be a number from 1 to 255 representing a color from the master palette, or 0 meaning transparent.
setellipsebordercol
setellipsefillcol
getellipsefillcol
set ellipse border col (handle, color)
set ellipse border col
Given an ellipse slice

handle

, change the color it uses for its border. The

color

should be a number from 1 to 255 representing a color from the master palette.

color

0 means 'transparent', which is not very useful.
getellipsebordercol
setellipsefillcol
getellipsefillcol
get ellipse fill col (handle)
get ellipse fill col
Given an ellipse slice

handle

, return the color it uses for its fill. This will be a number from 1 to 255 representing a color from the master palette, or 0 meaning transparent fill (hollow).
setellipsebordercol
getellipsebordercol
setellipsefillcol
set ellipse fill col (handle, color)
set ellipse fill col
Given an ellipse slice

handle

, change the color it uses for its fill. The

color

should be a number from 1 to 255 representing a color from the master palette, or 0 meaning transparent fill (hollow).
setellipsebordercol
getellipsebordercol
getellipsefillcol

### Text Slices

create text
create text
Creates a new blank text slice and returns a slicehandle to it. A text slice holds a string of text, but it can be positioned and handled just like any other slice. Use the setslicetext command to copy a string into the text slice.
setslicetext
set slice text(handle, string id)
set slice text
Copy a string specified by

string id

into the text slice specified by

handle

. Afterwards, there is no link between the text slice and the string; they have different contents.
createtext
getslicetext
get slice text(string id, slice handle)
get slice text
Copy the contents of the text slice specified by

slice handle

into a string specified by

string id

. Afterwards, there is no link between the text slice and the string; they have different contents.
createtext
setslicetext
get text color(handle)
get text color
Given a text slice

handle

, returns the current color of the text.
settextcolor
set text color(handle, color)
set text color
Given a text slice

handle

, change

color

used to display the text.
gettextcolor
get text bg(handle)
get text bg
Given a text slice

handle

, returns the current background color of the text. Note that this only matters if the text slice is not displaying an outline.
gettextcolor
settextbg
set text bg(handle, color)
set text bg
Given a text slice

handle

, change the background

color

used to display the text. This only matters if the text slice is set to not use an outline.
gettextbg
settextcolor
get outline(handle)
get outline
Given a text slice

handle

,

true

if the text slice is configured to display an outline, or

false

if it is configured not to display and outline.
setoutline
set outline(handle, outline)
set outline
Given a text slice

handle

, change whether or not it will be displayed with an outline. If the second argument is omitted or

true

, change the slice to show an outline, if the second argument is

false

change the slice to show no outline.
getoutline
get wrap(handle)
get wrap
Given a text slice

handle

,

true

if the text slice is configured to wrap, or

false

if it is configured not to wrap.
setwrap
set wrap(handle, wrap)
set wrap
Given a text slice

handle

, change whether or not it will wrap. If the second argument is omitted or

true

, change the slice to wrap-mode, if the second argument is

false

change the slice into non-wrapping mode.
getwrap

### Grid Slices

create grid (width, height, rows, columns)
create grid
Creates a new grid slice, and returns a slicehandle to it. Grid slices are special containers that automatically arrange their children into rows and columns. No manual child positioning is required. The first two arguments are the width and height of the whole grid. The next two arguments are the number of rows and columns that should appear in the grid. If rows or columns are left out, the grid with be a boring 1x1.
set grid columns (handle, columns)
set grid columns
Changes the number of columns in a grid slice. Child slices will be automatically repositioned. 1 is the minimum number of columns. If you attempt to set columns to zero, nothing will happen.
getgridcolumns
setgridrows
getgridrows
get grid columns (handle)
get grid columns
Returns the number of columns in a grid slice.
setgridcolumns
setgridrows
getgridrows
set grid rows (handle, rows)
set grid rows
Changes the number of rows in a grid slice. Child slices will be automatically repositioned. 1 is the minimum number of rows. If you attempt to set the rows to 0, nothing will happen.
setgridcolumns
getgridcolumns
getgridrows
get grid rows (handle)
get grid rows
Returns the number of rows in a grid slice.
setgridcolumns
getgridcolumns
setgridrows
show grid (handle, shown)
show grid
Grid slices are normally invisible, but they can optionally display gridlines. This command takes a grid slice

handle

and a true or false value. This command has no effect on the visibility of the grid's children. Don't confuse this command with setslicevisible.
gridisshown
grid is shown (handle)
grid is shown
This command takes a grid slice

handle

and returns true if the grid is showing its optional grid lines. If the grid is in its normal invisible state, this command returns false. Don't confuse this command with getslicevisible.
showgrid

### Select Slices

create select (width, height)
create select
Creates a new select slice, and returns a slicehandle to it. Select slices are special containers that automatically Manage the visibility of their children. Only one child of a select slice can ever be visible at the same time. The two arguments are the width and height of the select slice.
set select slice index (handle, index)
set select slice index
Changes the currently selected (visible) child of a select slice. The first argument is the handle of the select slice. The second argument is the index number of the child slice (not a handle or a lookup code!) this will be 0 for the first child, 1 for the second child, 2 for the third child, and so-on. An invalid index number means no child slices will be visible at all. Use setselectedchild instead if you want to set the selected child by its slice handles instead of index.
getselectsliceindex
get select slice index (handle)
get select slice index
Returns the index number of the currently selected (visible) child of a select slice. The first argument is the handle of the select slice. The return value the index number of the child slice (not a handle or a lookup code!) this will be 0 for the first child, 1 for the second child, 2 for the third child, and so-on. Use getselectedchild instead if you want a slice handle for the selected child instead of its index.
setselectsliceindex
set selected child (select, child)
set selected child
Given a select slice handle

select

and a slice handle for one of its children,

child

, selects that child. This is just a convenience wrapper around setselectsliceindex.
get selected child (handle)
get selected child
Given a select slice

handle

, returned the slice handle of the currently selected child. Returns false/0 if the selected index is out of range (including when slice has no children). This is just a convenience wrapper around getselectsliceindex.

### Scroll Slices

create scroll (width, height)
create scroll
Creates a new scroll slice, and returns a slicehandle to it. Scroll slices are special containers that automatically draw a scrollbar on ther right and bottom edges if their children do not fit inside them. The two arguments are the width and height of the scroll slice.
set scroll bar style (handle, style)
set scroll bar style
Changes the style of a scroll slice's scrollbar. The first argument is the handle of the scroll slice. The second argument is the style number. Scroll bar styles use the same colors as text box styles. The background color is used for the entire scrollbar, and the foreground color is used for the position indicator in the scrollbar.
getscrollbarstyle
get scroll bar style (handle)
get scroll bar style
Returns the current style number of a scroll slice's scrollbar. The first argument is the handle of the scroll slice. Scroll bar styles use the same numbering as text box styles.
setscrollbarstyle
set scroll check depth (handle, depth)
set scroll check depth
Changes the number of generations of children and grandchildren that a scroll slice cares about. The first argument is the handle of the scroll slice. The second argument is the desired depth, or 0 to check the entire family tree of all child slices. For example, a depth of 1 means the scroll only considers children. 2 means it considers children+grandchildren. 3 means it considers children+grandchildren+greatgrandchildren.
getscrollcheckdepth
get scroll check depth (handle)
get scroll check depth
Returns the number of generations of children and grandchildren that a scroll slice cares about, or 0 if it considers the entire family tree of every child. The first argument is the handle of the scroll slice. For example, a return value of 1 means the scroll only considers children. 2 means it considers children+grandchildren. 3 means it considers children+grandchildren+greatgrandchildren.
setscrollcheckdepth
scrolltoslice
scroll to child
scroll to slice (parent, sl, apply padding)
scroll to slice
Causes all the children of the

parent

slice to be shifted by the same offset so the screen position of

sl

(any child or descendent of

parent

) fits inside the parent. If

apply padding

is true (the default is false), then

sl

is scrolled within the area of

parent

with padding subtracted (the area covered by a child set to Fill Parent).

This is mainly intended for scroll slices, such as those created with the createscroll command, but it can be used on any type of slice. (Children that are set to fill their parents, or children that are automatically positioned by a grid parent will be unaffected, and an error or warning may be shown.)

This works for all descendent slices

sl

, not just children! It only changes the positions of the children of

parent

, but that causes the screen position of

sl

to also change.

### Panel Slices

Panel slices split up their area between their first two children in various ways, and don't display any other children.
create panel (width, height)
create panel
Creates a new panel slice, and returns a slicehandle to it. Panel slices are special containers that automatically move and resize their first two children. The first two children will fill the panel slice's area (while others aren't drawn). For example, a panel slice might be used to make to child slices share a 60%/40% split of an area regardless of the size or shape of that area. The two arguments are the width and height of the panel slice.
get panel is vertical (handle)
get panel is vertical
Returns true if the given panel slice

handle

is configured to orient its children vertically, or false if it orients them horizontally.
set panel is vertical (handle, value)
set panel is vertical
Changes how the given panel slice

handle

orients its children. If the

value

is true, they will be oriented vertically, or if false it will orient them horizontally.
get panel primary index (handle)
get panel primary index
Returns 0 or 1 to indicate whether the first or second child of the given panel slice

handle

is the primary one. The primary child gets its size based on the panel slices's percentage and pixels, while the other child slice takes the remaining space.
set panel primary index (handle, zero or one)
set panel primary index
Changes whether the first or second child of the given panel slice

handle

is the primary one. The primary child gets its size based on the panel slices's percentage and pixels, while the other child slice takes the remaining space.
get panel percent as int (handle)
get panel percent as int
Given a panel slice

handle

, returns an integer from 0 to 100 to indicate what percentage of the panel should be filled by the primary child slice
set panel percent (handle, percent)
set panel percent
Given a panel slice

handle

, changes the percentage of the panel that should be filled by the primary child slice. The panel's percentage size and pixel size will be added together to compute the actual size of the primary child.
get panel pixels (handle)
get panel pixels
Given a panel slice

handle

, returns the number of pixels of space that the panel will reserve for its primary child
set panel pixels (handle, pixels)
set panel pixels
Given a panel slice

handle

, changes the number of pixels of space that the panel will reserve for its primary child. The panel's percentage size and pixel size will be added together to compute the actual size of the primary child.
get panel padding (handle)
get panel padding
Given a panel slice

handle

, returns the number of pixels of padding that will be left between the primary and secondary children
set panel padding (handle, padding)
set panel padding
Given a panel slice

handle

, changes the number of pixels of padding that the panel will leave between the primary and secondary children.

### Map Layer Slices

Map Layer slices (also called Map slices) are special slices which display one of the tilemap layers of the current map. You can't create them; they always exist. Use lookupslice to get a handle for one of the map layer slices. They don't have any special attributes that you can access (use the map script commands to modify the map instead), and you can't resize them or change their parent, but you can do anything else, such as move them about to create parallax effects, make them invisible, reorder them, change their autosort mode, and so forth.

## Slice Collision Testing

For the purposes of collision testing, all slices are treated as solid rectangles, even if they are text slices, sprites, ellipses, or invisible. A point right on the boundary of this rectangle counts as a collision.

slice collide point (handle, x, y)
slice collide point
Return true if a given

x

and

y

coordinate point lies inside the bounding rectangle for slice

handle

's screen position.

x

and

y

are pixel coordinates relative to the screen, such as the ones returned by mousepixelx and mousepixely (but can also be off the screen).

Unlike sliceatpixel, this command ignores slice clipping.

slicecollide
slice collide (handle1, handle2)
slice collide
Given a pair of slice handles, return true if their screen positions overlap with one another (even if one or both are off the edge of the screen or hidden or clipped by one of their ancestors). Parent/child relationships have nothing to do with this test; it does not matter if the slices are related or what their children are.
slicecollidepoint
slicecontains
slice contains (handle1, handle2)
slice contains
Return true if the screen position of slice

handle2

is completely inside slice

handle1

(even if one or both are off the edge of the screen or hidden). Parent/child relationships have nothing to do with this test; it does not matter if the slices are related or what their children are.
slicecollide
slice at pixel (parent, x, y, number, check descendants, visible only)
slice at pixel
Searches through all the descendants of

parent

for a slice containing the given

x

,

y

pixel screen position. To search all your slices, you can often use spritelayer as

parent

, since that is the default parent of new slices.

number

is an optional argument indicating which slice to return if there is more than one at that point; the bottom-most one (returned by default) is number 0, next up is 1, etc. slice at pixel returns 0 if

number

is too large (larger than or equal to the number of overlapping slices). If you pass getcount as

number

the number of slices at that pixel is returned instead of a slice handle.

check descendants

is an optional argument defaulting to true. If false, then only

parent

's children will be checked, not all its descendants.

visible only

is an optional argument defaulting to false. If true, then only visible slices are counted or returned. (That is, slices marked not-visible are ignored while searching for slices, but whether

parent

itself is visible doesn't have any effect.) For example, pass true for

visibleonly

in order to avoid finding the children of Select slices which are not selected (and therefore invisible). This command never returns Special slices, such as the spritelayer slice.

A point on the left or top edge of a slice counts as inside the slice, while one on the bottom or right edges counts as outside. If a slice has zero width or zero height, then there are no points inside it, and slice at pixel will never return it!

If a slice clips its children, then any parts of those children that are clipped off are ignored when looking for

x

,

y

. However, it doesn't matter whether

parent

or any of its ancestors are set to clip; it's assumed that they don't. You can also use this to speed up the search, since all the children of a clipping slice will be skipped if that slice itself doesn't contain

x

,

y

.
slicecollidepoint
findcollidingslice
menuitematpixel
find colliding slice (parent, slice, number, check descendants, visible only)
find colliding slice
Searches through all the descendants of

parent

for a slice colliding (intersecting) with the given

slice

(by screen position). (Children of

slice

are ignored.) To search all your slices, you can often use spritelayer as

parent

, since that is the default parent of new slices.

number

is an optional argument indicating which slice to return if there is more than one at that point; the bottom most one (returned by default) is number 0, next up is 1, etc. 0 is returned if

number

is too large (larger than or equal to the number of overlapping slices). If you pass getcount as

number

the number of overlapping slices is returned instead.

check descendants

is an optional argument defaulting to true. If false, then only

parent

's children will be checked, not all its descendants. (That is, slices marked not-visible are ignored while searching for slices, but whether

parent

itself is visible doesn't have any effect.) Pass true for

visibleonly

in order to avoid finding the children of Select slices which are not selected (and therefore invisible).

visibleonly

defaults to false. This command never returns Special slices, such as the spritelayer slice, nor will it return

slice

or any of its descendants.

If a slice clips its children, then any parts of those children that are clipped off are ignored when checking collisions. However, it doesn't matter whether

parent

or any of its ancestors are set to clip; it's assumed that they don't. You can also use this to speed up the search, since all the children of a clipping slice will be skipped if that slice itself doesn't collide with

slice

.
sliceatpixel
slicecollide

# Time Functions

days of play
days of play
Returns the number of days that the game has been played
set days of play (days)
set days of play
Sets the number of days that the game has been "played" to

days

, as long as

days

is greater than 0. Useful if there are times that shouldn't count towards the play time, or for penalizing bad players >:)
hours of play
hours of play
Returns the number of hours that the game has been played, 0 to 23
set hours of play (hours)
set hours of play
Sets the number of hours that the game has been "played" to

hours

, as long as

hours

is within the 0-23 range.
minutes of play
minutes of play
Returns the number of minutes that the game has been played, 0 to 59
set minutes of play (min)
set minutes of play
Sets the number of minutes that the game has been "played" to

min

, as long as

min

is within the 0-59 range.
seconds of play
seconds of play
Returns the number of seconds that the game has been played, 0 to 59
set seconds of play (sec)
set seconds of play
Sets the number of seconds that the game has been "played" to

sec

, as long as

sec

is within the 0-59 range.
system year
system year
Returns the current real-world year
system month
system month
Returns the current real-world month, 1 to 12
system day
system day
Returns the current real-world day, 1 to 31
system hour
system hour
Returns the current real-world hour, 0 to 23
system minute
system minute
Returns the current real-world minute, 0 to 59
system second
system second
Returns the current real-world second, 0 to 59
override tick milliseconds (ms)
override tick milliseconds
Changes the number of milliseconds in a game tick. The

ms

argument is a number of milliseconds in the range of 16 to 200
cancel override tick milliseconds (ms)
cancel override tick milliseconds
Resets the number of milliseconds in a game tick to whatever default is set up in the "Edit General Game Settings" menu.

# Tweaking Maps

current map
current map
Returns the number of the current map.
map width (map)
map width
Returns the width of a map in tiles.

map

is optional; the width of the current map is returned if it is not specified.
map height (map)
map height
Returns the height of a map in tiles.

map

is optional; the height of the current map is returned if it is not specified.
get map tileset
get map tileset
Returns the ID number of the default tileset for the map. loadtileset does not affect the value returned by this function, but changetileset does. Use layertileset instead to find the actual currently in-use tileset(s).
layer tileset (layer)
layer tileset
Returns the ID number of the tileset that a certain tilemap layer is currently using.
changetileset
getmaptileset
load tileset (tileset, layer)
load tileset
Temporarily loads a different default or layer tileset for the currently displaying map.Use

load tileset

(with no arguments) to restore the old tilesets after using load tileset (this has no effect after changetileset).Use

load tileset (tileset)

to load a new default tileset.

tileset

is the ID number of the tileset to load. This changes the tileset for all layers that are set to 'Tileset: default'.Use

load tileset (tileset, layer)

to load in a new a tileset for a single layer.

layer

is the layer number to target.

This command has a temporary effect: even if the map state is saved, the new tilesets will not persist if you leave the map and come back. changetileset is a more powerful command for this.

getmaptileset
layertileset
change tileset (tileset, layer)
change tileset
An alternative to loadtileset: Changes and loads in the default or a map layer tileset for the current map. Unlike loadtileset, this command's effects last to the next time you come back to this map if you save the map state (in General Map Settings, or mapstate:mapsettings with savemapstate). To undo the effects, you'll need to use resetmapstate.

tileset

is the ID number of the tileset to load. You can use the constant

tileset:default

to set a layer to use the map's default tileset.

layer

is the layer number to change, or the constant

tileset:default

which changes the map's default tileset. It defaults to

tileset:default

if omitted.

change tileset

with no arguments undoes any changes to tilesets made using loadtileset (not change tileset).

Any call to change tileset undoes all changes made by loadtileset.

getmaptileset
layertileset

## Tilemap and Wallmap

read map block (x, y, layer)
read map block
Returns the value of a map tile on the current map at the specified X,Y position. Normal map tiles return values from 0-159, animating maptiles from set 1 return 160-207 and animating maptiles from set 2 return 208-255. The optional layer argument defaults to 0 for the bottom layer, but can be any layer number that is valid for the current map.
currentdisplaytile
write map block (x, y, value, layer)
write map block
Writes a new tile to the specified X,Y position on the current map. This change will only persist until you leave the map or fight a battle. The optional layer argument defaults to 0 for the bottom layer, but can be any layer number that is valid for the current map.
read wall bit (x, y, bit)
read wall bit
Check the value of a single bit of one tile of the wallmap of the current map. Returns true or false.

x

,

y

is the position in tiles.

bit

can be northwall, eastwall, southwall, or westwall to check of the four possible walls on the tile, or vehiclea, vehicleb, harmtile or overheadtile to check one of the other bits. See readpassblock for an example.
readpassblock
write wall bit (x, y, bit, value)
write wall bit
Set the value of a single bit of one tile of the wallmap of the current map.

x

,

y

is the position in tiles.

bit

can be northwall, eastwall, southwall, or westwall to set the presense of the four possible walls on the tile, or vehiclea, vehicleb, harmtile or overheadtile.

value

is optional should be either false or true (or any other non-zero value). The default is true.
writepassblock
read pass block (x, y)
read pass block
Returns the value of a passability (wallmap) tile on the current map at the specified

x

,

y

position. The return value will be from 0 to 255 and consists of eight flag bits.bit 1 = northwallbit 2 = eastwallbit 4 = southwallbit 8 = westwallbit 16 = vehicleabit 32 = vehiclebbit 64 = harmtilebit 128 = overheadtileTo check the value of a specific bit, use the and operator as in the following example, or just use the readwallbit command instead.
variable (pass) pass := read pass block(hero X(me), hero Y(me)) if (pass, and, harm tile) then ( # The hero is standing on a harm tile )

# The following is equivalent: if (read wall bit(hero X(me), hero Y(me), harm tile)) then ( # The hero is standing on a harm tile )
readwallbit
checkwallcollisionxy
write pass block (x,y,value)
write pass block
Writes a new passability (wallmap) information to the specified

x

,

y

position on the current map. This change will only persist until you leave the map or fight a battle. The value is a number from from 0 to 255 that consists of eight flag bits.bit 1 = northwallbit 2 = eastwallbit 4 = southwallbit 8 = westwallbit 16 = vehicleabit 32 = vehiclebbit 64 = harmtilebit 128 = overheadtileYou can add the constants together (but it might be easier to use writewallbit instead). For example:
variable (pass) pass := northwall+southwall+eastwall+westwall write pass block(15,3,pass) # this makes the fifteenth tile in the third column # impassable on all directions

write pass block(15,3,none) # Use 0 or none to remove walls from a tile
writewallbit

### Tile Animations

current display tile (tile number, layer)
current display tile
Returns the tile number from the tileset, in the range 0-159, that a given tile (read with readmapblock, which returns a value greater than 159 for animated tiles) is currently displayed as, taking the tile animation patterns into account. Because different layers can have different tilesets, you might need to specify the layer the tile is from; otherwise layer 0 is assumed.
animation start tile (tile number, layer)
animation start tile
Returns the tile number on the tileset (in the range 0-159) that this tile is displayed as at the start of its animation pattern (offset 0) if it is animated, else just returns the tile number. The

tile number

argument is typically returned from readmapblock. In effect, the result is what the tile number would be if you had not set the tile as animated in the tilemap editor. Because different layers can have different tilesets, you might need to specify the layer the tile is from; otherwise layer 0 is assumed.
currentdisplaytile
get tile animation offset (animation pattern, layer)
get tile animation offset
Returns the offset from the starting tile that the

animation pattern

(either 0 or 1) of the tileset in use by the

layer

(0 to 2) is currently at. For example, if the pattern has stepped 1 to the right, the offset is 1, if it has moved down 2 and 1 to the left, it is 31 (2 * 16 - 1). Because different layers can have different tilesets, you might need to specify the layer with the tileset to examine; otherwise layer 0 is assumed.

Layers that use the same tileset do NOT have different copies of the tileset. Layers with the same tileset will always have the same tile animation offsets.

readmapblock
animationstarttile
set tile animation offset (animation pattern, offset, layer)
set tile animation offset
Sets the offset from the starting tile that an

animation pattern

(either 0 or 1) of a tileset in use by a

layer

(0 to 2) is currently at. If there is a pattern defined, it will continue to step left, right, up and down from the offset you give it, until the end of the animation is reached, when the offset is reset to 0. Because different layers can have different tilesets, you might need to specify the layer with the tileset to examine; otherwise layer 0 is assumed.

Layers that use the same tileset do NOT have different copies of the tileset. Layers with the same tileset will always have the same tile animation offsets, you can not change them independently.

### Wall checking

check wall collision x (x, y, width, height, relative x, relative y, friction%)
check wall collision x/y
and

check wall collision y (x, y, width, height, relative x, relative y, friction%)

Check how far an object (with a rectangular "hitbox") could move in a straight line on the map before hitting a wall (and possibly sliding along that wall). Provide the starting

x

and

y

map position in pixels of the top left corner of the hitbox (relative to the top-left of the map), its

width

and

height

in pixels, and the

relative x/y

offset of the target position of the object (for example relative x is 20 for one tile to the right). See moveslicewithwallchecking for information about what the optional

friction%

argument (which defaults to 100) does. The return value is the maximum x/y offset that the object could move in a straight line towards the target before hitting a wall. If there are no walls in the way, then the return value is

relative x

or

relative y

. For example, to check whether the hero can walk a full tile north (-20 pixels in the 'y' direction), you could write if (check wall collision y(hero pixel x(me), hero pixel y(me), 20, 20, 0, -20) == -20) then (...) (The checkherowall command is a much easier way to check the same thing, but only works if the hero is tile-aligned.) These commands work on hitboxes of any size (as long as the size isn't negative), even several tiles wide. Even a one-pixel-wide overlap with the end of a wall counts as a collision, and edge-on walls count as obstructions too, as do tiles past the edge of the map (unless the map wraps around). However, if the hitbox starting position already overlaps any walls they will be ignored.

moveslicewithwallchecking is a more convenient way to check walls if you want to move a slice, e.g. when scripting a platformer.

If you're moving diagonally, you'll need to call both check wall collision x and check wall collision y with identical arguments to find the x,y position of the collision point.

This command hasn't been updated to support one-way walls yet. Running into a one-way wall edge-on will give strange results.
moveslicewithwallchecking
findcollidingslice
move slice with wallchecking (sl, relative x, relative y, friction%)
move slice with wallchecking
Instantly moves a slice

sl

as far as possible in a straight line towards a point until it hits a wall in the map's wallmap (and possibly slides along that wall).

relative x/y

provide the point to move to, relative to the slice's current position. This command can be used on any slice, regardless of whether it is parented to a map layer. Its position on the map is calculated based on its on-screen position (slicescreenx, etc). The slice's "colliding box" (or "hitbox") is, as you expect, the same as its size. It works on slices of any size (as long as the size isn't negative), even several tiles wide. Even a one-pixel-wide collision with the end of a wall will stop the slice, and edge-on walls count as obstructions too, as do tiles past the edge of the map (unless the map wraps around). However, if the slice already overlaps any walls they will be ignored.

friction%

is an optional percentage value from 0 to 100 which defaults to 100. When it's 100, movement stops as soon as a wall is hit. If it's less than 100 then the slice slides down the wall with part of its remaining movement (

relative x/y

), reduced by

friction%

percent. For example if relative x == 15, relative y == 3, friction% == 30 and the slice travelled right 5 pixels before hitting a wall to the north (x = 10, y = 2 movement remaining to go), then y movement gets set to 0 (because we hit a wall to the north) and x movement gets reduced by 30% to 7, and the slice slides up to another 7 pixels to the right (unless it hits another wall). If you're creating a platformer or zelda-like, you probably want friction to be 0% or a low value. The return value is a bitmask giving the directions in which the slice was blocked by a wall. The value is 0 if there was no collision. You can use the constants northwall, southwall, eastwall, westwall and the bitwise-and operator to 'test' the bitmask. For example bitmask, and, southwall 'tests' whether

sl

hit and is now resting against a wall on its south side (useful for a platformer). Diagonally hitting the corner or end of a wall exactly (including thin wall segments) is a special case. In that case the slice stops at the corner/end of the wall but is only touching it diagonally, and the return value is equal to one of the special constants

northeast corner

,

northwest corner

,

southeast corner

,

southwest corner

, all of which 'test' false when checked with northwall, southwall, eastwall, westwall. That's because the slice isn't actually resting against any walls, although it stopped! Use equal, not and, to check for these values. You can check for walls without needing a slice using the alternative checkwallcollisionxy commands. This command hasn't been updated to support one-way walls yet. Running into a one-way wall edge-on will give strange results.
# This script creates a rectangle slice which follows the mouse # but doesn't pass through walls. plotscript, box follows mouse, begin variable (xgo, ygo, box) box := create rect(14, 14) set rect border(box, border:line)

while(true) do ( # Calculate the offset from the center of the box to the mouse, # and divide by three to move a third of the way there. xgo := (mouse pixel x -- (slice screen x(box) + 7)) / 3 ygo := (mouse pixel y -- (slice screen y(box) + 7)) / 3 move slice with wallchecking(box, xgo, ygo) wait ) end
checkwallcollisionxy
findcollidingslice

## Zonemaps

write zone (zone id, x, y, value)
write zone
Sets whether the tile at (

x,y

) is part of the specified zone.

zone id

is a valid ID number (see readzone), and

value

is interpreted as either

true

(non-zero) or

false

(zero).

Only up to 15 zones may overlap at each tile. If you try to place 16 zones at one tile, write zone will fail, returning false. Normally it returns true. If you choose to "Show all warnings" in General Game Settings in Custom, you will also get a warning message.

Changes to zones are not stored in saved games, and are erased when you leave the map unless "Tile Data State" is "saved when leaving" (in the General Map Data settings).

readzone
read zone (zone id, x, y)
read zone
Returns true if the tile at (

x,y

) is part of the specified zone. The

zone id

is an ID number from 1 to 9999 for zones defined in the map editor, or can be the ID one of these special zones:

- zone:OneWayExit == 10000 - Marks tiles with one-way walls.

writezone
zoneatspot
zone at spot (x, y, count)
zone at spot
Used to get the set of all IDs of zones that contain the tile at (

x,y

). Since zones may overlap,

count

is used to specify which zone ID to return: 0 is the first, 1 the second, and so on.

count

may also be the constant getcount, in which case the total number of zones which overlap there is returned. If

count

too large (greater than or equal to the number of zones), 0 (false) is returned.

The order in which the ID numbers are returned is completely arbitrary.

readzone
get zone name (string id, zone id)
get zone name
Places in the string with id number

string id

the name of zone

zone id

.
get zone extra (zone id, extra num)
get zone extra
Returns the value in a zone's "extra data" field numbered

extra num

, which is a number from 0 to 2. You may use the constants

extra 0

,

extra 1

and

extra 2

to refer to them. You can set a zone's extra data in the Zone Info editor.
set zone extra (zone id, extra num, value)
set zone extra
Sets the value of a zone's "extra data" field numbered

extra num

, which is a number from 0 to 2. You may use the constants

extra 0

,

extra 1

and

extra 2

to refer to them.

Changes to zones are not stored in saved games, and are erased when you leave the map unless "Tile Data State" is saved when leaving in the General Map Data settings.

zone number of tiles (zone id)
zone number of tiles
Given a

zone id

(from 1 to 9999 or a special id), returns the number of tiles that the zone contains.

## General Map Settings

allow minimap (setting)
allow minimap
Sets whether the Map option appears in the menu. Give no argument or true to enable, or false to disable. The effect goes away if you change maps or fight a battle.
showminimap
allow save anywhere (setting)
allow save anywhere
Sets whether the Save option appears in the menu. Give no argument or true to enable, or false to disable. The effect goes away if you change maps or fight a battle.
savemenu
set harm tile damage (amount)
set harm tile damage
Sets the amount of damage taken when you step on a harm tile. The effect goes away if you change maps or fight a battle.
set harm tile flash (color)
set harm tile flash
Sets the color (from the master palette) which the screen flashes when you step on a harm tile. Call with no argument to disable the flash. The effect goes away if you change maps or fight a battle.
set foot offset (offset)
set foot offset
Sets the foot offset in pixels, the vertical displacement of npc and hero sprites from the base of the tiles on which they stand. The effect goes away if you change maps or fight a battle.
get foot offset
get foot offset
Returns the map's foot offset.
draw NPCs above heroes (setting)
draw NPCs above heroes
Sets whether NPCs are drawn above heroes or the default of beneath. The effect goes away if you change maps or fight a battle.
set map edge mode (mode, default tile)
set map edge mode
Sets the behaviour at the edge of the map. Use the constants crop, wrap and defaulttile. When the behaviour is default tile, you should give a second argument specifying which tile should be displayed off the boundaries of the map, otherwise ignore the second argument. The effect goes away if you change maps or fight a battle.
get map edge mode
get map edge mode
Returns the map's edge mode. Use the constants crop, wrap and defaulttile to compare with the value returned.

## Map State

save map state (whichdata, customid)
save map state
Saves the state of the current map to a temporary file which will be loaded (unless the map is set to ignore that particular data) when you reenter the current map, in the same way as a map set to save (remember) NPC or tile data: the saved state will be used instead of the map data in the RPG file. Both arguments are optional and are only for advanced uses. Map state is not saved in saved games, and the temporary files will be deleted when you load or start a new a game!

whichdata

is an or'd combination of the following constants, which specify exactly what you want to save:

- mapstate:all = mapstate:mapsettings, or, mapstate:npcs, or, mapstate:tiles
- mapstate:npcs = mapstate:npclocations, or, mapstate:npcdefinitions
- mapstate:tiles = mapstate:tilemap, or, mapstate:passmap, or, mapstate:zonemap
- mapstate:mapsettings
- mapstate:npclocations
- mapstate:npcdefinitions
- mapstate:tilemap
- mapstate:passmap
- mapstate:zonemap

The default is mapstate:all. If

customid

is passed, it is used to save the state in a separate state file with an id number of

customid

which can only be loaded with loadmapstate. There are 32 available slots for use: 0 - 31. Note that mapstate:mapsettings (also saved by mapstate:all) is special in that if you save it, it will always be loaded when the map is loaded regardless of settings. It saves all the settings found in the General Map Settings menu like the ambient music, footoffset, map trigger scripts, and so forth, and also the tileset for each layer.
plotscript, generic menu screen, begin variable (remember map, remember x, remember y) remember map := current map remember x := hero x remember y := hero y # we want NPCs and things to stay in the same place after we come back from the menu save map state

fade screen out wait teleport to map (map:generic menu) fade screen in wait

# menu code here #... #...

fade screen out wait teleport to map (remember map, remember x, remember y) # assume the map is set to load state only, the default (otherwise, use load map state) fade screen in wait

# we want the map to go back to resetting whenever you enter/exit it (like normal) delete map state end
load map state (whichdata, customid)
load map state
Load temporary map state data previously saved either by savemapstate or when leaving a map set to remember state. The two arguments are optional and for advanced use.

whichdata

is a set of bits in the savemapstate format to determine what exactly to load. The default is mapstate:all.

customid

is a number between 0 and 31 of a slot in which a custom save was made. Data from a different map can be loaded, but only tile data from a map of the same size! If you attempt to load state data which has not been saved then it will be loaded from the game files instead, unless you are using

customid

, in which case nothing will be loaded.
reset map state (whichdata)
reset map state
Reloads original unaltered map data from the RPG file.

whichdata

is a set of bits in the savemapstate format to determine what exactly to load. It is optional and the default is mapstate:all. This does not remove temp state files for the map, so they could still be loaded instead when you next enter the map, use deletemapstate to remove them if wanted.
delete map state (whichdata)
delete map state
Deletes temporary map state files for the current map, so that if the map is set to load NPC or tile data it will load the original data from the game files when it is entered.

whichdata

is a set of bits in the savemapstate format to determine what exactly to delete. The default is mapstate:all.

# Timers

set timer (id, count, speed, trigger, string, flags)
set timer
Changes the settings for a given timer, and starts it.

id

is the number of a timer -- by default, there are 16 timers, numbered 0 to 15 but you can change the number of available timers with allocatetimers. All other parameters are optional, or you can pass timer:default as any of them. This will leave the parameter unchanged (from the last time you set it or from the default initial value), it will NOT cause that timer setting to be reset to the default initial value.

Count

is the length of the timer. While it's running, the count will go down by one every

speed

game ticks (frames). I.e., if you set speed to 18, it will count down once every 18 ticks, close to one second. Use a speed of 1 to count down in ticks. Changing the timer's

count

(as opposed to passing

timer:default

as the second argument) will cause the timer to restart from the new value.

trigger

is what happens when the timer runs out. You can use the constant timer:gameover to indicate that the game should end (the gameover script is not called), or specify a plotscript (in the form "@my script") to have that run. A plotscript will get passed the id of the timer that triggered it as its first argument, if it has one. If the timer runs out during a battle then the effect happens after the battle ends. You can bind a timer to a string using the

string

parameter to create a countdown that shows up on screen. Pass it the id of a string, and that string will be updated every time the timer counts down. You are responsible for displaying and positioning the string. A timer also has a few other options in the form of

flags

. You can pass any combination of these flags (by oring them together; see the example):

- timerflag:battle
  to have it count down during battles (including in menus which pause the battle, except the Pause screen itself). You can turn on the "Never show script timers during battles" Peference Bitset to cause battle-timers to count down but not display. Note: Only the first battle-timer will show in battle! You can't show more than one.
- timerflag:menu
  to have it count down even while the player is in a menu which pauses the game (e.g. the status menu)
- timerflag:critical
  to have the timer end a battle or exit a menu if it runs out during it

Timers start counting down not from the current game 'tick', but from next one. So if you want to trigger something next tick (eg. run a script every frame) you need to pass

count

as 0 and

speed

as 1. A timer count set to 1 would counter-intuitively trigger in 2 ticks time.

Timer settings are not saved in game saves.

# This starts a 300 second (5 minute) timer that counts down once every 18 ticks (approximately one second). # If it runs out during battle, the battle won't end but a game-over will happen afterwards. set timer (0, 300, 18, timer: game over, 0, (timerflag: battle, or, timerflag: menu))
stoptimer
readtimer
systemsecond
secondsofplay
milliseconds
runscriptbyid
stop timer (id)
stop timer
Stops a timer by setting its speed to 0. All of its other settings remain the same.
settimer
allocate timers (number)
allocate timers
Changes the number of available timers. The range of valid timer IDs becomes 0 to

number

-1. You can reduce the number of timers down to zero, and increase it up to 100000 (not recommended, each timer must be processed continuously). All existing timers that are not removed continue to run. The default number of timers is 16.
read timer (id)
read timer
Returns the "count" of a given timer. A timer's count is at first equal to the

count

argument to settimer (or zero, if the timer hasn't been used). After

speed

ticks since settimer was called, the count is reduced by one. The timer is triggered when the count becomes negative. Normally a timer that has finished has a count of -1, unless it had a negative count to begin with, most likely to happen if you restart a timer by passing timer:default as the

count

argument to settimer. (So if you keep repeating it that way, each time its count will reduce further: -1, -2, -3, ...)
settimer

# Script Triggers

set death script (id)
set death script
Changes the script that is run when you die in battle. The argument is the script's ID number, NOT the script's name. Calling set death script with no argument disables the death script.
get death script
get death script
Returns the ID number of script that is run when you die in battle.
set load script (id)
set load script
Changes the script that will be run when you load this game after it is saved. The argument is the script's ID number, NOT the script's name. Calling set load script with no argument disables the load script. This command has no effect if the "Save gameover/loadgame script IDs" Preference Bitset is turned off!

Setting the load script and then loading an existing saved game has no effect, because the load game script already stored in that saved game is used instead. Unless "Save gameover/loadgame script IDs" is off, in which case the default one is used.

get load script
get load script
Returns the ID number of script that is run when you load a saved game.
set on keypress script (id)
set on keypress script
Changes the script that is run when you press a key. The argument is the script's name preceded by an @ sign. You can also use the ID number for old-style scripts. Calling set on keypress script with no argument disables the keypress script. The effect goes away if you change maps or fight a battle.
set on keypress script(@keyhandlerscript)
get on keypress script
get on keypress script
Returns the ID number of script that is run when you press a key.
set each step script (id)
set each step script
Changes the script that is run when you take a step. The argument is the script's name preceded by an @ sign. You can also use the ID number for old-style scripts. Calling set each step script with no argument disables the each step script. The effect goes away if you change maps or fight a battle.
get each step script
get each step script
Returns the ID number of script that is run when you take a step.
set instead of battle script (id)
set instead of battle script
Changes the script that is run instead of a random battle when one is triggered. The argument is a reference to the script in the form @scriptname. Calling set instead of battle script with no argument disables the instead of battle script. The effect goes away if you change maps or fight a battle.
get instead of battle script
get instead of battle script
Returns a reference to the script that is run instead of battles.

# General Game Settings

These commands access data in the General Game Settings menu.
set caterpillar mode (state)
set caterpillar mode
Sets whether or not to display the whole party in "caterpillar" style. This sets the "Enable Caterpillar Party" general preference bitset. If the argument is off then only the leader will be displayed. If the argument is on then the whole active (battle) party will be displayed and will normally walk behind the leader.

Do not confuse this with the suspendcaterpillar and resumecaterpillar commands, which only apply when caterpillar mode is ON.

set HP level up restore (state)
set HP level up restore
Sets whether or not a hero regains full HP after a level-up. If the argument is on then HP is restored on a level-up. If the argument is off then the hero's HP is not restored on a level-up.
set MP level up restore (state)
set MP level up restore
Sets whether or not a hero regains full MP after a level-up. If the argument is on then MP is restored on a level-up. If the argument is off then the hero's MP is not restored on a level-up.
set inn revive mode (state)
set inn revive mode
Sets whether or not inns restore dead heroes to life. If the argument is on then dead heroes are restored by inns. If the argument is off then dead heroes remain dead in inns.
set full hero swap mode (state)
set full hero swap mode
Sets whether or not you can swap heroes in and out of your active party from the menu. If the argument is off then the "Order" menu will be available. If the argument is on then the "Team" menu will be available.
set debug keys disable (state)
set debug keys disable
Sets whether or not the debugging keys are allowed. If the argument is off then debugging keys are allowed. If the argument is on then debugging keys are disabled.
extended scancodes enabled
extended scancodes enabled
Returns the state of the "Disable better scancodes for scripts" backcompat bitset, returning true if it's off. This means that numpad keys are distinguishable from Home, Up, etc. keys. See scancode.
get screen width
get screen width
Returns the width of the screen in pixels.
getscreenheight
get screen height
get screen height
Returns the height of the screen in pixels.
getscreenwidth
read preference bit (bitnum)
read preference bit
Returns the value (true or false) of one of the bits in the Preference Bitsets, Active-time Battle Bitsets or Backwards-compatibility Bitsets menus (in the General Game Settings menu). You can use this command if there isn't a dedicated command to read the bit, such as extendedscancodesenabled. Get the value of

bitnum

by checking this list on the wiki.

Some bits are shown with the opposite names on the wiki and in the editor! If that's the case, you need to set the bit off instead of on and vice versa. They might also have slightly different names. For example to check whether "Randomize initial ready meters" is on, use read preference bit(22) == off, because bit 22 is documented as "Don't randomize battle ready-meters".

writepreferencebit
write preference bit (bitnum, value)
write preference bit
Sets the

value

(true or false) of one of the bits in the Preference Bitsets, Active-time Battle Bitsets or Backwards-compatibility Bitsets menus (in the General Game Settings menu). You can use this command if there isn't a dedicated command to write the bit, such as setbattlewaitmode. Get the value of

bitnum

by checking this list on the wiki.

Some bits are shown with the opposite names on the wiki and in the editor! If that's the case, you need to set the bit off instead of on and vice versa. They might also have slightly different names. For example to turn on "Randomize initial ready meters", use write preference bit(22, off), because bit 22 is documented as "Don't randomize battle ready-meters".

Use common sense. Some bits, such as "Limit maximum tags to 999" might be disastrous to change in the middle of a game! Or they might have no effect.
readpreferencebit

## Battle System Settings

These commands access data either in the Battle Settings submenu in General Game Settings menu, or in the Preference Bitsets submenu.
set battle wait mode (state)
set battle wait mode
Set whether or not battles pause on spell and item menus. If the argument is off then enemies continue to attack while menus are up, if the argument is on then enemies wait while menus are up.
get active battle pause on all menus
get active battle pause on all menus
Returns true if active-time battles are configured to pause on all menus.
setactivebattlepauseonallmenus
set active battle pause on all menus (value)
set active battle pause on all menus
Changes whether active-time battles will pause on all menus. The argument should be

true

to pause, or

false

to not pause. This option has no effect on turn-based battles. This option is not stored in save-games, so changing it only lasts until the game is quit and reloaded.
getactivebattlepauseonallmenus
show battle ready meter (state)
show battle ready meter
Sets whether or not the ready meter appears in battle, or will be hidden.

state

should be true or false.
show battle health meter (state)
show battle health meter
Sets whether or not the health meter appears in battle, or will be hidden.

state

should be true or false.
set dead heroes gain experience (state)
set dead heroes gain experience
Sets whether or not dead heroes gain experience from battles. If the argument is false then only living heroes gain experience. If the argument is true then dead heroes get it too.

## Caps

get damage cap
get damage cap
Returns the current damage cap, or 0 if there is none.
set damage cap (cap)
set damage cap
Sets the current damage cap to

cap

. Use 0 for no cap.
get level cap
get level cap
Returns the current level cap.
set level cap (cap)
set level cap
Sets the level cap.

cap

must be a value from 0 to 99. Heroes with level equal to or greater than the level cap can't gain experience through battles, giveexperience, or setexperience, and the status screen doesn't show their experience to next level. You however can use setherolevel to set a hero's level above the level cap. The level cap does not change the amount of experience needed to gain a level, nor the stat increases at level-up.

# Saved Games

autosave
autosave
Transparently saves the game to the last save slot saved to or loaded from (see lastsaveslot), or if playing a new game which has not been saved yet, calls savemenu. Returns the number of the save slot saved to, or if the user cancelled the save menu, returns false.
lastsaveslot
save in slot (slot)
save in slot
Saves in the specified save slot (1 to 1000, regardless of how many are visible on the save and load menus). If a saved game already exists in the slot, it will be overwritten. If you want to make sure that no save game will be overwritten, use saveslotused. To display the save game menu instead, use savemenu.
load from slot (slot, args...)
load from slot
Loads a saved game from a save

slot

as if it had been loaded from the load game menu.

slot

is a slot number from 1 to 1000, (regardless of how many are displayed on the Load and Save menus). This command will end the current game (and fade out and in again) if it successfully loads. If the load fails because the slot has never been saved in, the script will continue. Anything that you want to happen after loading a saved game needs to be put in the 'load game' script instead (specified in Special Plotscripts). You can pass any number of additional optional

args

to the loadgame script. (

slot

is also always passed as the first argument to the loadgame script, so

args

are the 2nd and later arguments.) The default arguments of a loadgame script (and all other triggered scripts) are currently ignored. If you don't pass enough

args

, then the remaining arguments default to zero, so don't use defaults other than zero!
# This example shows automatically loading the last save when you die, # and does something special after loading by passing an argument to the loadgame # script. You could accomplish the same thing with a global variable instead.

# "slot" is the save slot number # "is quickload" defaults to 0 (false) if the game is loaded from the regular load menu, and # can be something else if we use "load from slot" plotscript, my loadgame script, slot, is quickload, begin if (is quickload) then ( show textbox(42) # "You died and have been restored from the last save point!" wait for textbox ) end

plotscript, my gameover script, begin fade screen out(63, 0, 0) # fade to red wait(10) fade screen out(0, 0, 0) # fade to black if (last save slot) then ( # On death, reload the last save automatically, and tell the loadgame script we're doing so load from slot(last save slot, true) ) else ( # The player hasn't saved yet... too bad! game over ) end
loadmenu
saveinslot
saveslotused
lastsaveslot
resetgame
delete save (slot)
delete save
Deletes a saved game in the specified save

slot

(1 to 1000, regardless of how many are displayed on the Load and Save menus). The save will no longer be visible on the load game menu or loadable with loadfromslot.
saveinslot
last save slot
last save slot
Returns the last save slot either loaded or saved to (whichever happened last) or false if this is an unsaved new game. Save slots are numbered starting at 1. savemenu(false) and loadmenu(false) (which show the menus but don't actually save or load) don't change the last save slot. last save slot returns the last save slot used, even if the save in it has since been deleted (e.g. with deletesave). In versions before Callipygous, saveinslot didn't change the value returned by last save slot, but savemenu(false) and loadmenu(false) did.
autosave
saveinslot
set last save slot (slot)
set last save slot
Sets the value returned by lastsaveslot. This changes the slot used by autosave.

slot

can be any slot from 1 to 1000, or 0 for none, even if the number of save slots visible to the player in the load/save menu is less.
save slot used (slot)
save slot used
Returns whether a game has been saved in the save slot. For example, you can use this if you don't want to overwrite a saved game with saveinslot. This returns false if the slot has never been saved to normally, but has been written to using exportglobals (which will create a nearly-empty .rsav file containing just globals, if it doesn't already exist).
import globals (slot, first, last)
import globals
and

import globals (slot, id)

Loads a range of globals from a saved game, overwriting the current globals in that range.

slot

is the save slot number, from 1 to 1000. Note that only slots 1-4 appear by default on the save/load menus.

first

and

last

are the id numbers of the globals at the beginning and end of the range (inclusive). If you leave out both of

first

and

last

all global variables will be imported. To read a single global from a save slot without modifying any of your globals, use the form var := import globals (slot, id) This is NOT the same thing as import globals (slot, id, id), which does modify the global variable. import globals and exportglobals can be used to save and retrieve info about a saved game without loading it, and also to store variables that any game the player starts can use, such as high scores and other "global" data, like in the following example: global variable (100, game completed) global variable (101, hours to complete) global variable (102, minutes to complete) plotscript, game finished, begin game complete := true hours to complete := hours of play minutes to complete := minutes of play export globals (5, 100, 102) #special slot that the player can not load, which we can use for anything end plotscript, check game finished, begin import globals (5, 100, 102) #copy saved values into globals 100, 101, 102 if (game completed) then ( show textbox (105) #"you have previously finished this game in ${V101} hours and ${V102} minutes" ) else ( show textbox (106) #"you have yet to complete the game!" ) wait for textbox end

You can import globals from an empty save slot; it's not an error to do so. This reads the value of all of the globals as zero. You can also export/import globals to/from an empty save slot that doesn't have a full saved game in it; see exportglobals.

exportglobals
readglobal
export globals (slot, first, last)
export globals
Writes a range of globals to a save game slot, overwriting the saved game's globals.

slot

is the save slot number, from 1 to 1000, regardless of how many save slots enabled in the save/load menus.

first

and

last

are the id numbers of the globals at the beginning and end of the range.

first

defaults to 0, and

last

defaults to 50000. Therefore, if you pass no range, all the globals will be written.

You can export globals to an empty slot! This doesn't create a visible save game that the player can load (and saveslotused will still return false for that slot), however you will be able to read them with importglobals. You can delete these globals using deletesave.

Unlike importglobals, export globals (slot, first) does NOT export a single global variable!

importglobals
writeglobal

# Advanced Functions

run script by ID (id, argument1, argument2, argument3...)
run script by ID
The

run script by id

command allows you to run a script using its scriptid. You can get the ID of a script by writing

@

(the 'reference' operator) in front of its name, see the example. You can not run a built-in command like wait; they aren't scripts. Arguments after the ID will be passed to the script. The return value of this command is whatever value the script returns. A run-time error is displayed and -1 is returned if the script does not exist. You can pass up to 31 arguments to the script. The advantage of this command as opposed to just calling the script directly is that the ID may be stored in a variable, or it could be the function return value of another script. For example, using setsliceextra you might want to store the ID of a script that should be run when the player clicks on a slice.

If you pass too few arguments, the unspecified ones will have value zero regardless of any default values given in the script declaration. If you pass too many (which does not cause an error), the extra ones are ignored.

plotscript,scriptcallingtest,begin show value (run script by id (@sum, 1, 2, 3)) end

script,sum,a,b,c,begin return(a+b+c) end
getscriptname
getcallingscriptid
run game(file string id)
run game
Quit the current game and switch to a different .rpg file/.rpgdir. When that game is quit, the program either exits or goes to the game browse as usual.

file string id

is the ID of a string that contains the filename of the game to load. If the game is not in the same directory, then you need to provide a relative path, like "bonus content\Prequel.rpg" or "../selectmenu.rpg". The path is case-insensitive and

/

and

\

are interchangeable.
# load another game in the same directory $0 = "part2.rpg" run game(0)
check game exists (file string id)
check game exists
Check whether an .rpg file/.rpgdir directory exists, returning true or false. This is useful before calling rungame, which will show an error if the game doesn't exist. See rungame for more information about the filename.
rungame
milliseconds
milliseconds
Use to measure time intervals accurately. Subtract two values returned by milliseconds at different times to find the number of ms (1000ths of a second) elapsed in between. A single value is useless (the computer's up-time or any random value).
microseconds
microseconds
microseconds
An alternative to milliseconds which measures millionths of a second. This command only exists for accurate benchmarking.
save screenshot
save screenshot
Saves a screenshot, as if the player pressed F12. A popup will appear telling the filename of the screenshot. The screenshot might be taken either of the previous frame or the next one. To be safe, if you're displaying something and then taking a screenshot of it, put a wait(1) in between.

## Debugging

trace (string)
trace
Writes string #

string

to "g_debug.txt", located in the same directory as the RPG file or game.exe. For debugging you will nearly always use tracevalue instead, which is much easier.
variable (i) i := random (1, 1000) $1 = "i = " append number (1, i) # string 1 is "i = ????" trace (1) # writes "TRACE: i = ????" to g_debug.txt
trace value (expression, ...)
trace value
Prints one or more expressions and their values to "g_debug.txt". The number of arguments to this command is variable; each is printed as source text along with its value. You can't print strings with this command; use trace instead.
variable(i) i := random (1, 1000) trace value (i) # writes "TRACE: i = ????" to g_debug.txt

# This writes something like "TRACE: hero X (me) = 14, hero Y (me) = 53" to g_debug.txt trace value (hero X (me), hero Y (me))
assert
dumpslicetree
dump slice tree (slice)
dump slice tree
Prints out a brief description of a slice and all its descendents to "g_debug.txt".

slice

is optional; if omitted the whole tree is printed out, which is the same as pressing the

Ctrl+F8

debug key.

Most of the slice data isn't printed; if you want to inspect it the easiest way to do so is either to press

Ctrl+F4

to view the slice editor/debugger, or to call scripterror at the exact moment you want to check the slice tree; you can then enter the slice debugger from the Script Error menu.
tracevalue
scripterror
script error (string id)
script error
Shows an error message, like any other script error. This allows you to open the script debugger. The optional

string id

argument gives the error message to display.
if (x < 0 || x >= map width || y < 0 || y >= map height) then ( $0="Coordinates went off the edge of the map" script error(0) )
assert
tracevalue
debugmenu
debug menu
debug menu
Opens the debug menu, which you can open by pressing F8 if debug keys are enabled; this is useful if debug keys are disabled, or on handhelds/consoles without an F8 key.
scripterror
showminimap
assert (expression)
assert
If

expression

is false, then writes the script filename, line number and

expression

into the string given by the constant or global variable named

assert expression string

, and then calls the script named

assert failure

. You can use this to detect bugs in your scripts, by checking that your assumptions about the state of the game are correct.
# The following... assert (check tag (tag:initialised) == OFF) # ...is equivalent to something like if (not (check tag (tag:initialised) == OFF)) then ( $assert expression string="myscripts.hss:123: check tag (tag:initialised) == OFF" assert failure )
# Suggested usage: define constant(31, assert expression string) script, assert failure, begin script error(assert expression string) end

# later... assert (check tag (tag:initialised) == OFF) # something ought to be true at this moment
scripterror
tracevalue
get script name (string id, script id)
get script name
Fetches the name of a script given its scriptid number and places it in a string. It's an error to pass an invalid script ID. You can get the ID number of a script by writing @scriptname.
get calling script id (depth)
get calling script id
Returns the ID number of the script which called this one. The optional

depth

argument, which defaults to 1, allows returning the ID of a deeper ancestor script instead: 1 is the parent, 2 is the grandparent, etc. If there is no calling script (the script was triggered instead), then the return value is 0. You can get the ID number of a script by writing @scriptname.
getscriptname
send email (save slot, subject string id, message string id)
send email
As of Callipygous, this command is only implemented on Android! Calling it on other platforms does nothing.
This asks the player if they want to send an email to you, optionally with a save file attached. The purpose is to make it easy for players to send bug reports or feedback, especially on Android, where it might otherwise be a nuisance to send saved games.

When called on Android, a standard system menu is brought up asking the player which email client they want to use. If they don't cancel, that client is opened with an email already filled out, which they can edit as usual: The email is sent to the address set in the Distribute Game->Distribution Info menu.

subject string id

is optional; it is the id of a string containing the email subject line. If you leave it out or set it to -1 then the default subject line is "[Name of the game] feedback".

message string id

is optional; it is the id of a string containing the email body text. If you leave it out or set it to -1 then it defaults to "(Please include a helpful description of the problem here)". The

save slot

argument is optional, and is either an existing save slot number, or

false

(the default) to not attach a save. You can use saveinslot with a large slot number to create a temporary save of the current game. If you attach an save file two other files are also attached: g_debug.txt and g_debug_archive.txt. g_debug.txt is useful for tracking down OHRRPGCE engine bugs, but you can also write to it using trace and tracevalue. You can also check it for error messages, such as script errors (errors will start with a

!

at the beginning of the line). g_debug_archive.txt contains backups of g_debug.txt from previous times the game was played. To load the .rsav file, rename it if necessary (e.g. 0.rsav for the first save slot), and put it in the 'gamename.saves' folder.

# Platform Specific

running on desktop
running on desktop
This command returns true if the game is currently running on any Windows/Mac/Linux desktop computer. You should avoid using this command unless you really need it. Most games will never need this command.
running on Windows
running on Windows
This command returns true if the game is currently running on a Windows computer. You should avoid using this command unless you really need it. Most games will never need this command.
running on Mac
running on Mac
This command returns true if the game is currently running on a Macintosh computer. You should avoid using this command unless you really need it. Most games will never need this command.
running on Linux
running on Linux
This command returns true if the game is currently running on a GNU/Linux desktop computer (not including Android or other non-PC Linux-based OS). You should avoid using this command unless you really need it. Most games will never need this command.
running on mobile
running on mobile
This command returns true if the game is currently running on a mobile device such as an Android phone or tablet. You should avoid using this command unless you really need it. Most games can support mobile devices without ever using this command. See the "Platform-Specific Options" menu under "Edit General Game Data".
running on console
running on console
This command returns true if the game is currently running on an console. Currently supported consoles include OUYA, MOJO, GameStick, and FireTV. You should avoid using this command unless you really need it. Most games can support the consoles without ever using this command. See the "Platform-Specific Options" menu under "Edit General Game Data".
running on ouya
running on ouya
This command returns true if the game is currently running on an OUYA console. You should avoid using this command unless you really need it. Most games can support the OUYA console without ever using this command, and even if you do need to do special scripting just for ouya, you should consider using runningonconsole instead, since the only thing different about OUYA is its button names and in-app-purchase support. See the "Platform-Specific Options" menu under "Edit General Game Data".
hide virtual gamepad
hide virtual gamepad
If the game is running on a platform that supports a touchscreen virtual gamepad (such as Android) this command forces the virtual gamepad to become hidden, even if it would normally be visible. On other platforms, this command does nothing. The effects of this command can be cancelled by using the autovirtualgamepad command.
show virtual gamepad
show virtual gamepad
If the game is running on a platform that supports a touchscreen virtual gamepad (such as Android) this command forces the virtual gamepad to become visible, even if it would normally be hidden. On other platforms, this command does nothing. The effects of this command can be cancelled by using the autovirtualgamepad command.
auto virtual gamepad
auto virtual gamepad
If the game is running on a platform that supports a touchscreen virtual gamepad (such as Android) this command cancels a previous showvirtualgamepad or hidevirtualgamepad command. The virtual gamepad will once again automatically show or hide itself automatically based on various factors such as textboxes, menus, battles, or suspendplayer. On other platforms, this command does nothing.

# Types and Handles

This section documents many of the different types of values that are used by various script commands, such as NPC references. Note that in HamsterSpeak everything is a number, so there are no types as in other programming languages; instead identifiers are used for everything. Values of different ID numbers and handles overlap: there's no way to tell if a number refers to an NPC or a slice or a map.

- An

  ID number

  normally refers to something which is defined in an editor, such as an NPC definition or map ID number, or something which is fixed supply, like global and string ID numbers. ID numbers always count upwards from 0 or sometimes 1. Many IDs have constants automatically defined, for example if there's a map named Overworld, there's a constant named

  map:Overworld

  with its ID number.
- A

  handle

  or a

  reference

  is an identifier for something that can be created during play, like slice handles, menu handles and NPC references. It can change from game to game, and it becomes invalid if the thing it refers to is deleted. After becoming invalid, the value can generally even be reassigned to a new thing of that type, so be careful about handles you've stored in variables when deleting things!
- A

  constant

  (or "enum") is a fixed value, used for things that don't change, like different available NPC movement types, or map numbers. Many constants in HamsterSpeak start with a prefix like

  key:

  . There's nothing special about these prefixes or names, and

  :

  is treated like any letter which you can use freely.

NPC IDs
NPC ID
An NPC ID refers to an NPC definition, as defined in the Edit NPCs menu. NPC IDs count from 0 upwards. A copy of an NPC is referred to using an npcref.
NPC references
NPC reference
NPC references are handles for NPC instances on the map, that is, a copy of an NPC definition. NPC references are always negative values counting from -1 down, while NPC IDs count from 0 up. An npcid can always be used with any command that expects an NPC reference, in which case it refers to the first instance/copy of that NPC, not to the NPC definition itself. So wait for NPC(5) is equivalent to wait for NPC(npc reference(5, 0)).
Slice handles
slice handle
Slices are referred to with

slice handles

. A slice handle is just a value that you can store in a

variable

, just like an npcref or a textbox ID number. A handle is

valid

if it currently refers to an existing slice. false (zero) is never a valid slice handle, so slice commands return 0 to indicate "no slice found" or similar failures.

lookupcodes like "sl:map layer 0" or "sli:quit button" are NOT slice handles; they can only be used by the lookupslice command.

Slice lookup codes
slice lookup code
Slice lookup codes are used to search for a particular slice using lookupslice. There are two types. User defined slice lookup codes are defined (named) in the slice collection editor. You will find them as constants in your .hsi file with sli: prefixes, and they count up from 1. You can also use any non-negative value, even if you haven't named it in the editor. There are also many special slice lookup codes with names that start with sl: prefixes. See lookupslice for the list. They are always negative.
Menu handles
menu handle
A handle for a currently open menu, for example, the one returned by openmenu or createmenu or topmenu. Menu handle

0

(

false

) means none/invalid. Not the same thing as a menu ID (which is a menu defined in the menu editor). There can be multiple open copies of a single menu ID.
Menu item handles
menu item handle
A handle to one of the items in a currently open menu, for example, the one returned by selectedmenuitem. Menu items in different menus are always different, so it's possible to lookup which menu its in with parentmenu, and menu handles are never reused.
Script IDs
script ID
Script IDs are used to refer to scripts, for example for setdeathscript. Get the ID of a script by writing

@name of the script

, which is a constant. You can call a script using its ID instead of the normal way with runscriptbyid. You used to have to manually assign IDs to scripts using define script, but that's now obsolete and IDs are automatically assigned. The ID number of a script will remain the same as long as it isn't renamed, so they're safe to store in saved games. The ID

0

means no script (e.g. no death script).
getscriptname
Color codes
color code
A number indicating a color in the master palette. A value from 1-255 is specifies the master palette index directly. The meaning of 0 depends on the particular script command: it might mean either 'transparent' or 'the default color' or 'color 0 in the palette'. Negative valeus indicate colors defined in the User-Interface Colors editor.
Scancodes
scancode
A scancode is a constant referring to a keyboard key, a joystick button, or is a virtual scancode like usekey (see keyconstants for the full list) which is an action that can be attached to multiple keys/buttons. The scancodes are also listed in the scancode.hsi file included with the engine. key:Esc key:F1 key:F2 key:F3 ... key:F15 key:Num Lock key:Scroll Lock key:Caps Lock key:Print Screen key:Pause key:1 key:Exclamation key:2 key:At Sign key:3 key:Hash key:4 key:Dollar Sign key:5 key:6 key:Circumflex key:7 key:Ampersand key:8 key:Asterisk key:9 key:Left Parenthesis key:0 key:Right Parenthesis key:Minus key:Underscore key:Equals key:Plus key:Backspace key:A key:B key:C ... key:Z key:Left Bracket # [ key:Left Brace # { key:Right Bracket # ] key:Right Brace # } key:Semicolon # ; key:Colon # : key:Quote # ' key:Doublequote # " key:Apostrophe # ' key:Backquote # ` key:Tilde # ~ key:Backslash # \ key:Pipe # | key:Comma # , key:Left Caret # < key:Period # . key:Right Caret # > key:Slash # / key:Question Mark # ? key:Enter key:Space key:Tab key:Home key:End key:Page Up key:Page Down key:Insert key:Delete key:Up key:Left key:Right key:Down key:Meta # Either Command/Windows key key:Win Logo # equal to key:Meta key:Command # equal to key:Meta key:Left Meta # Left Command/Windows key key:Right Meta # Right Command/Windows key key:Left Win Logo # equal to key:Left Meta key:Right Win Logo # equal to key:Right Meta key:Left Command # Macintosh, equal to key:Left Meta key:Right Command # Macintosh, equal to key:Right Meta key:Context # Context Menu key, next to right Windows key on PC keyboards key:Alt # either Alt key pressed key:Left Alt key:Right Alt key:Filtered Alt # either Alt key pressed, unless a key combinations like Alt+Tab is # pressed, however key presses are delayed until key release. key:Ctrl # either Ctrl key pressed key:Left Ctrl key:Right Ctrl key:Shift # either Shift key pressed key:Left Shift key:Right Shift key:Any Enter # either Enter or Numpad Enter key pressed key:Numpad 0 key:Numpad 1 key:Numpad 2 key:Numpad 3 key:Numpad 4 key:Numpad 5 key:Numpad 6 key:Numpad 7 key:Numpad 8 key:Numpad 9 key:Numpad Period key:Numpad Asterisk key:Numpad Slash key:Numpad Plus key:Numpad Minus key:Numpad Enter # Joystick scan codes: joy:button 1 joy:button 2 joy:button 3 ... joy:button 16 joy:button 17 # Warning: joy:button17 is not joy:button16+1! All other button codes are consecutive ... joy:button 32 joy:x left joy:x right joy:y up joy:y down joy:left # aka joy:x left joy:right # aka joy:x right joy:up # aka joy:y up joy:down # aka joy:y down # Virtual scancodes: any key # Any keyboard key or joystick button (including joystick left/right/up/down) up key # Up key on the keyboard, or on any joystick down key # ...ditto left key right key use key # Space, Ctrl or Enter, or Use button on any joystick cancel key # Alt or Esc, or Cancel button on any joystick menu key # Alt or Esc, or Menu button on any joystick run key # Esc or Tab, or Run button on any joystick (Hold to run from battle)

Previously it was necessary to include, scancode.hsi to use the key: constants, but no longer.

If the "Map joystick controls to keyboard keys for scripts" general preference bitset is ON (which it is by default), then checking the key:up, key:down, key:left, key:right, key:esc, key:enter keys will report true if the corresponding button on any joystick is pressed.

Since Zenzizenzic, keyboard support has been improved: some keys (such as key:down and key:numpad 2) which were previously the same scancode are now distinct (read scancode.hsi for the complete list). However for backwards compatibility, the old behaviour is emulated (so you won't be able to tell the two keys apart even if recompile and use the new, distinct scancodes) unless you turn off "Disable better scancodes for scripts" in the Backwards-Compatibility settings menu (in the General Game Settings menu).

extendedscancodesenabled
Key constants
key constants
A constant specifying a keyboard key or joystick button by its function. They can be passed to keyispressed, keyval, waitforkey, keypress, newkeypress and waitforscancode. Previously these could only be used with the waitforkey command, but that's changed! Possible values:

any key

,

up key

,

down key

,

left key

,

right key

,

use key

,

menu key

,

cancel key

,

run key

. (

menu key

and

cancel key

are identical).

# Predefined Constants

This section isn't complete; there are zillions of other builtin constants!
Numeric Constants
Numeric Constants
There are pre-defined constants for the numbers from 0 to 10. You can use these constants to make your scripts look friendly :)zero, one, two, three, four, five, six, seven, eight, nine, ten
keyconstants
any key
keyconstants
up key
keyconstants
down key
keyconstants
left key
keyconstants
right key
keyconstants
use key
keyconstants
menu key
keyconstants
cancel key
keyconstants
run key
Boolean Constants
Boolean Constants
There are constants are named true and false, and for ON and OFF. These are useful for checking and setting the values of tags, and in conditional statements. true/on are equal to 1, false/off are equal to 0.true, false, on, off
booleanconstants
true
booleanconstants
false
booleanconstants
on
booleanconstants
off
Direction Constants
Direction Constants
There are constants for each of the four directions. These constants are useful for commands such as walkhero and walknpc, which take a direction as an argument.north, south, east, west, up, down, right, left
directionconstants
north
directionconstants
south
directionconstants
east
directionconstants
west
directionconstants
up
directionconstants
down
directionconstants
right
directionconstants
left
me
me
me is a constant that can be used to refer to the first hero in your party (hero zero) in any command that takes a hero number as an argument. It is equal to zero.
none
none
none is a constant that means the same as zero.
autonumber
autonumber
ubersetzung
autonumber is an obsolete constant that is used as the ID number in old-style define script commands. This is not needed anymore. Use script instead.
current stat
current stat
A constant for use with the getherostat, setherostat, setcappedherostat and getlevelmp commands. The current value of a stat is what is normally used. The current value of stats other than HP or MP is usually equal to the maximum value, except due to temporary buffs or debuffs in-battle (which wear off after the end of the battle) or if modified with setherostat. Both maximum and current values of a stat are normally limited to the stat cap.
maximum stat
maximum stat
A constant for use with the getherostat, setherostat, setcappedherostat and getlevelmp commands. The maximum value of a stat is used for limiting it (such as for curing items) and for resetting it, such as on levelup or at an inn (if enabled by the game's general bitsets). See currentstat for more information. Both maximum and current values of a stat are normally limited to the stat cap.
base stat
base stat
A constant for use with the getherostat, setherostat and setcappedherostat commands. The base value of a stat is not displayed anywhere in-game, but tracks the value of a hero's stat without their equipment or stat caps taken into account. In other words the base value of a stat can continue to grow as a hero levels even if the current and max values have hit the cap. Hint: you can press F4 in the Status menu to display the base values of each stat in brackets.
inside battle
inside battle
A constant used in the getheropicture, setheropicture, getheropalette, setheropalette, resetheropicture and resetheropalette commands to represent the battle graphics.
outside battle
outside battle
A constant used in the getheropicture, setheropicture, getheropalette, setheropalette, resetheropicture and resetheropalette commands to represent the walkabout graphics.
hero portrait
hero portrait
A constant used in the getheropicture, setheropicture, getheropalette, setheropalette, resetheropicture and resetheropalette commands to represent the hero's portrait graphics.
Color Constants
Color Constants
Constants for each of the three primary colors are used in commands like readcolor or writecolorcolor:red, color:green, color:blue
colorconstants
color:red
colorconstants
color:green
colorconstants
color:blue
Mouse Constants
Mouse Constants
The following constants are for use with the mouse functions such as mousebutton. left button, middle button, right button
mouseconstants
left button
mouseconstants
middle button
mouseconstants
right button
get count
get count
When passed to npcatpixel, npcatspot, sliceatpixel, findcollidingslice or zoneatspot they return the number of NPCs, slices or zones at that spot. With spellslearned returns the number of spells a hero learnt. With findenemyinformation, returns the number of enemies, or the number of some kind of enemy in the formation.
Tile Constants
Tile Constants
The following constants are for use with functions like readpassblock or writepassblock.north wall, east wall, south wall, west wall, vehicle A, vehicle B, harm tile, overhead tile
tileconstants
north wall
tileconstants
east wall
tileconstants
west wall
tileconstants
south wall
tileconstants
vehicle A
tileconstants
vehicle B
tileconstants
harm tile
tileconstants
overhead tile
crop
crop
A constant used in setmapedgemode which makes the edges of the map impassible and prevents the camera from scrolling off them.
wrap
wrap
A constant used in setmapedgemode which lets the player walk over the edge of the map around to the opposite side.
default tile
default tile
A constant used in setmapedgemode which makes the edges of the map impassible and displays a specified tile everywhere off the edge of the map.
party
party
Pass as first argument to giveexperience to divide the experience between all the live heroes in the battle (active) party.
x axis
x axis
Pass to joystickaxis to specify the X axis (left and right).
y axis
y axis
Pass to joystickaxis to specify the Y axis (up and down).
timer: default
timer: default
Pass to settimer to leave one of the parameters at its default setting. Valid for any parameter except

id

timer: game over
timer: game over
Pass to settimer in the

trigger

field to have the game end when the timer runs out.
timer flag: critical
timer flag: critical
Pass to settimer in the

flags

field to indicate that if the timer runs out during a battle, it should end the battle immediately.
timer flag: battle
timer flag: battle
Pass to settimer in the

flags

field to indicate that the timer should run during battle. Otherwise, the timer will be paused during battle.
timer flag: menu
timer flag: menu
Pass to settimer in the

flags

field to indicate that the timer should run while the player is in the menu. Otherwise, it will be paused while the player is in the main menu.
song: silence
song: silence
Used with setformationsong and getformationsong to indicate an enemy formation without music. Used by setambientmusic and getambientmusic for a silent map.
song: same as last map
song: same as last map
Used with setformationsong and getformationsong to indicate an enemy formation which uses the same music as the map. Used by setambientmusic and getambientmusic for a map that continues with the last map's music.
song:sameaslastmap
song: same as map