Dictionary of Plotscripting Commands

plotscript, name, argumentnames (statements)

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 set death script.)

# 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)

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 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)

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)

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 global variable instead.

variable(points) # make a new variable
variable+=1 # add one to it

define constant (number,name)

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

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 define constant 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

number + number

Adds two values together and returns the result. This can also be written as add(number,number)

number -- number

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

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

number / number

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

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)

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)

Returns -1 if number is negative, 0 if it is 0, and 1 if number is positive.

sqrt (number)

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

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.

value,or,value

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.

value,xor,value

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.

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)

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)

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

random choice (values...)

Returns one of its arguments, randomly. Up to 32 different values can be provided. Returns 0 if it has no arguments.

# Move an npc randomly to either (5,10), (5,14), or (5,18)
set npc position(npc, 5, random choice (10, 14, 18))

seed random (seed)

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.

multdiv (a, b, c)

Computes (a * b) / c with rounding, and without overflowing. The intermediate result is performed in floating point so that it won't overflow, and the final result is clamped to the range of a 32-bit integer.
This is equivalent to min(2^31 - 1, max(-2^31, round(1.0 * a * b / c))) in other languages.

dir X (direction)

Simpler helper function to convert a direction into a relative X value. Returns -1 for left, 1 for right, and otherwise 0. It's often useful to multiply the return value, e.g. to get an increment of 20 pixels rather than 1 tile.

# To find the tile in front of the hero:
variable (x, y, dir)
dir := hero direction(me)
x := hero X(me) + dir X(dir)
y := hero Y(me) + dir Y(dir

# To find the point 20 pixels in front of the hero (the hero has a 20x20 hitbox, but "hero pixel X/Y"
# return the top-left corner, so add 10 pixels to start at the center of the hero):
x := hero pixel X(me) + 10 + 20 * dir X(dir)
y := hero pixel Y(me) + 10 + 20 * dir Y(dir)

dir Y (direction)

Simpler helper function to convert a direction into a relative Y value. Returns -1 for up, 1 for down, and otherwise 0. See dir X.

begin, other commands, end

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. But using one or the other is a matter of taste.
For example, the following:

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

end

See begin.

if(condition) then(commands) else(commands)

The if statement checks the value of its condition, and if the value is true (actually, any value other than false (which is zero) also counts as true), 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 == or <>, or a command which returns either true or false, such as check tag. The else is optional as long as you have a then, and the then is optional as long as you have an else. You can also place one or more else ifs after the then (or immediately after the if if you skip the then) instead of nesting multiple if statements.

... else if(condition) then(commands) ...

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 around the else, as this example shows:

# "inventory" returns the number you own. Remember that any number other than 0 counts as true
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!"
)

then

See if.

else

See if.

while(condition) do(commands)

The while command checks the value of its condition, and if the value is true (or any value other than 0/false) 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 == or <>, or something else that returns true/false such as checktag.

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.)

for(counter,start,finish,step) do(commands)

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 put hero for examples.

return(value)

return in HamsterSpeak is very different from return in nearly all other programming languages, which is equivalent to exit in HamsterSpeak!

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. (Compare with the example for "exit returning".)
  variable(i)
  for(i, 1, ticks) do, begin
    wait(1)
    if(key is pressed(use key)) then(return(true))
    if(key is pressed(menu key)) 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

exit

exit(value)

With no argument, is equivalent to exit script. With one argument is equivalent to exit returning.

This is the same as the return statement in most other programming languages.

exit returning(value)

exit(value)

Sets the value to be returned by the script, and exits the script. Can be written as either exit returning(value) or the new style exit(value). 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(use key)) then(exit returning(true))
    if(key is pressed(menu key)) then(exit returning(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

exit script

exit

Causes the script to end immediately, and return the value set by the most recent return statement. Can be written as either exit script or the new style exit.

break (levels)

Breaks out of a for or while loop or switch (or even an isolated do block) and continues the script after the end of the do block. If breaking out of a for loop, the loop's variable isn't modified.
levels is optional (defaulting to 1), and is almost never used (see below).
For example:

plotscript, search for gemstones, begin
  variable (gems)
  # A minimum payout of 1 gem, a maximum of 15
  for (gems, 1, 15) do (
    wait(20)
    $1 = "Found "
    append number(1, gems)
    center string at(1)   # Show "Found 1", etc, in the center of the screen (the position is optional)
    if (random(1, 6) == 1) then (break)  # Roll a die and stop on a 1
  )
  # Remove the text from the screen
  hide string(1)
  # "${S1} shiny rocks in the river", displays as "Found 2 shiny rocks in the river", etc
  show textbox(17)
end

# Randomly pick one of the flowers on the map that hasn't bloomed yet and make it bloom
plotscript, a flower blooms, begin
  variable (x, y, found)
  for (x, 0, map width -- 1) do (
    for (y, 0, map height -- 1) do (
      # Look for a flower tile (on map layer 0), suppose it's tile 10
      if (read block(x, y) == 10) then (
        if (random(1, 10) == 1) then (   # 10% chance of picking this one
	  found := true
	  break (2)  # Exit both 'for' loops. The x and y variables will remain the same
      )
    )
  )
  # The break(2) jumps to here

  if (found) then (
    # Do a little animation
    write block(x, y, 11)
    wait(20)
    write block(x, y, 12)
  )
end

continue (levels)

When used inside the do block of a for or while command (or in an isolated do block), continue skips the rest of the do block and continues on to the next loop, if any. That's equivalent to jumping to the bottom of the loop, so its effect is like enclosing the rest of the loop in an if (except for isolated do blocks, in which case it jumps straight to the top of the loop because there's no condition to check).
When used inside a switch statement, continue causes a jump into the next case's do() block, even if the case doesn't match, or into the else() (aka case(else) do()) block if that follows the current case.

levels is optional (defaulting to 1), and is almost never used. When inside several nested loops/blocks it tells which one to continue. It must be at least 1. For example if there are 3 nested for loops, continue(3) continues the outermost one, in the process breaking out of the inner two. For example:

plotscript, update shadow tiles, begin
  for (x, 0, map width -- 1) do (
    for (y, 0, map height -- 1) do (

      for (layer, 4, 7) do (
        # Suppose tiles on any of the layers 4 to 7 are overhead tiles which cast shadows
        if (read map block(x, y, layer) <> 0) then (
          # Found a non-empty tile. Put a shadow tile (42) on the ground (layer 1)
          write map block(x, y, 42, 1)
	  # We don't need to check the other layers. Skipping them speeds up the script
          continue(2)
        )
      )
      # This part is reached only if the continue(2) didn't happen
      # Remove any shadow tile on layer 1, no shadow here
      write map block(x, y, 0, 1)

      # The continue(2) jumps to here (immediately before the 'for' loops back)
    )
  )
end

switch(expression)

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
)

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
  )
)

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
)

case(value)

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 (ticks)

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

Makes the script wait until there is no text box displaying on the screen. Useful to know when to move on after using a show text box command.

wait for text box doesn't wait if suspend box advance 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)

Given a menu handle, causes the script to wait until that menu has been closed.

wait for hero (who)

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

wait for key (key)

Waits for the player to press a key. (Specially, (possibly repeated) keypresses or mouse button release.) 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 use key. If you do not specify key, then any key will be used.
any key waits for any keyboard or joystick button, (except Numlock, Capslock and Scrolllock, or any joystick buttons that have no builtin meaning e.g. X/Y/L1/L2/R1/R2) and also waits for a mouse click if "'any key', etc, include mouse clicks" is turned on in the Mouse Controls menu. usekey will wait for Space, Ctrl or Enter, joystick use key, and optionally left click; and cancelkey and menukey both wait for Alt or Esc, joystick cancel, and optionally right click.
If and only if anykey is used, then waitforkey(anykey) will return the scancode of the keyboard or joystick key that was pressed, but won't ever be a constant like usekey. It returns a value >= 180 if a mouse button was released (see scancode.hsi).

Previously you couldn't use scancodes like key:x, and there was a separate wait for scancode 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 key is pressed.

While wait for key waits, on-keypress scripts will not be triggered.

show text box(623) # "press cancel!"
wait for key(cancel key)

wait for scancode (key)

Identical to wait for key.

wait for NPC (who)

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

wait for camera

Wait for the camera to stop panning after a pan camera, focus camera or pixel focus camera command.

pan camera (left,10) # show the villain 10 tiles off screen
wait for camera # wait until he's on screen

wait for all

Waits for any camera motion due to pan camera, focus camera, etc. to stop, waits for all heroes to stop walking and pathfinding, and waits for NPCs to stop scripted pathfinding (e.g. pathfind NPC to). If suspend NPCs has been used then wait for all also waits for all NPCs to come to a halt. Beware that without suspend NPCs, automatic NPC walking such as wandering, pacing, avoiding, or pathfinding, as well as movement due to walk NPC/walk NPC to X/walk NPC to Y 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

wait for slice (handle)

Documented in the Moving Slices section.

wait for dissolve (handle)

Documented in the Sprite Slices section.

wait for sound (num)

Documented in the Sound Effects section.

set tag (tag,value)

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)

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)

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)

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 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 still advance text boxes unless you use suspend box advance.
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 cancel key. (You can change that with set menu bit(menu handle, menubit:no controls, true) where menu handle might for example be top menu.)

suspend player
# do stuff
resume player

resume player

Restores normal control after a suspend player command. This is very important. If you use suspend player, but forget resume player, the game will be stuck after the script ends.

suspend player
# do stuff
resume player

player is suspended

Returns true if suspend player is active.

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 walk NPC and pathfind NPC to. You should use a wait command like wait for NPC to ensure an NPC has finished its current movement before getting it to start a new one (which could cause tile misalignment).
Use set NPC moves(who, false) instead to prevent a single NPC from moving.

If you want NPCs to stop immediately without finishing their current steps, consider suspend walkabouts instead.

suspend NPCs
# do stuff
resume NPCs

resume NPCs

Restores automatic NPC movement after a suspend NPCs command. This does not resume NPCs suspended with set NPC moves.

suspend NPCs
# do stuff
resume NPCs

npcs are suspended

Returns true if suspend NPCs is active.

suspend walkabouts

Suspends (pauses) all NPC and hero movement immediately and completely, as well as NPC AI, player movement controls, NPC activation, Walk In Place animations, and vehicle mounting/dismounting/rising/falling animations. Unlike suspend NPCs, NPCs stop moving immediately rather than finishing their step.
This doesn't suspend updating of the hero/NPCs slices. For example, put hero, put NPC, set hero z, set hero frame, etc. still cause the hero/NPC slices to move, change frame, etc.
Although player movement is suspended, this doesn't suspend everything suspend player does: the player can still open the menu (or the vehicle's menu setting or Instead-of-menu script) and advance text boxes. They can't activate NPCs or dismount vehicles.

While walkabouts are suspended, wait for hero and wait for NPC commands will freeze forever, and commands like walk hero and walk NPC won't cause any movement until you resume walkabouts.

This is one of the main effects of menus set to "Suspend gameplay & scripts", along with suspend player, suspend timers, suspend box advance, suspend text box controls, pausing scripts and script triggers, and suspending slice movement.

resume walkabouts

Undoes suspend walkabouts. Has no effect if walkabout movement is actually suspended by a menu set to "Suspend gameplay & scripts".

walkabouts are suspended

Returns true if suspend walkabouts is active.

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 resume obstruction to restore normal obstruction behavior. Use set NPC obstructs(who, false) instead to allow a single NPC to move through heroes and NPCs, and vice-versa.

suspend obstruction
# walk through things
resume obstruction

resume obstruction

Restores normal obstruction after a suspend obstruction command. This doesn't undo the effect of set NPC obstructs.

suspend obstruction
# walk through things
resume obstruction

obstruction is suspended

Returns true if suspend obstruction is active.

suspend hero walls

Allows heroes to walk through walls, and to walk off the edge of the map. Use resume hero walls 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

Restores normal wall behavior after a suspend hero walls command

suspend hero walls # hero is now a ghost
# walk through things
resume hero walls # back to mortality...

hero walls are suspended

Returns true if suspend hero walls is active.

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 resume NPC walls to restore normal wall behavior. Use set NPC ignores walls(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 suspend NPCs first, otherwise NPCs will start walking into walls and get stuck there when you call resume NPC walls!
Usually it is better to use set NPC ignores walls 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 suspend obstruction to allow that.

suspend NPC walls # npc is now a ghost
# walk through things
resume NPC walls # back to mortality...

resume NPC walls

Restores normal wall behavior after a suspend NPC walls command. This doesn't undo the effect of set NPC ignores walls.

suspend NPC walls # npc is now a ghost
# walk through things
resume NPC walls # back to mortality...

npc walls are suspended

Returns true if suspend NPC walls is active.

suspend caterpillar

Stops your other heroes from following the leader. This is useful when you want to control them individually with walk hero 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 set caterpillar mode.

suspend caterpillar # cutscene
# move heroes, probably fight a battle or two...
resume caterpillar # normal game again.

resume caterpillar

Reverses the suspend caterpillar 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.

suspend caterpillar # cutscene
# move heroes, probably fight a battle or two...
resume caterpillar # normal game again.

caterpillar is suspended

Returns true if suspend caterpillar is active.

suspend catapillar

resume catapillar

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 door at spot, etc. While doors are suspended use door still works.

resume doors

Restores normal door triggering after a suspend doors command. If the lead hero is already standing on a door, it will not be triggered.

doors are suspended

Returns true if suspend doors is active.

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

Undoes the suspend random enemies 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.

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

random enemies are suspended

Returns true if suspend random enemies is active.

suspend random enemys

resume random enemys

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 advance text box command (or show text box) 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 resume box advance.
Note that the player can still move the cursor in choiceboxes while this is active, use suspend text box controls to disable that.

wait for text box 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

Undoes the suspend box advance command, allowing the player to advance text boxes by pressing the use key, as normal.

box advance is suspended

Returns true if suspend box advance is active.

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 suspend box advance for that. Undo with resume text box controls.

resume text box controls

Undoes the suspend text box controls command, allowing the player to control choice boxes, as normal.

textbox controls are suspended

Returns true if suspend text box controls is active.

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 resume overlay.

resume overlay

Undoes the suspend overlay command, causing overhead tiles to be drawn over heroes and NPCs as normal.

overlay is suspended

Returns true if suspend overlay is active.

suspend map music

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)

resume map music

Causes ambient music to automatically start playing when you enter a map again after a suspend map music command.

map music is suspended

Returns true if suspend map music is active.

suspend timers

Causes all plot timers started with set timer to be paused. It does not cancel them. Undo with resume timers

resume timers

Undoes suspend timers. All previously paused plot timers will become active again.

timers are suspended

Returns true if suspend timers is active.

walk hero (who, direction, distance)

Makes a hero move the specified number of tiles in some direction. The first argument tells who to move, it is a caterpillar rank. Use me or numbers 0-3. (If the catepillar party is disabled then there will only be one hero, me.) The second argument is the direction, such as north. 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 wait for hero command. You should normally use the suspend player command before moving heroes, and if you want to move heroes other than the leader, you should use the suspend caterpillar command.

suspend player # stop player
walk hero(me,up,3) # move him up 3 tiles
resume player # OK, done

wait for hero (who)

Documented in the Wait Commands section.

pathfind hero to (who, x, y, stuck ticks)

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 suspend caterpillar 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 cancel hero walk command. Be careful if you are using wait for hero to wait for pathfind hero to when no stuck ticks timeout is used, since wait for hero might wait forever if the hero has no way to get to its destination.

hero chases npc (who, npc, stop when reached, stuck ticks)

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 suspend caterpillar 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 NPC reference or NPC ID. 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 cancel hero walk command. Be careful if you are using wait for hero to wait for hero chases NPC when no stuck ticks timeout is used, since wait for hero might wait forever if the hero has no way to get to its destination.

cancel hero walk (who)

If the specified hero is walking with a command like walk hero or pathfinding (due to a command like pathfind hero to 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 walk hero 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.

hero is chasing (who)

If the specified hero is currently chasing an NPC, such as by clicking on the hero with mouse/touch controls, or a previous hero chases NPC command then return an NPC reference. If the hero is not currently chasing an NPC, returns false.

set hero direction (who, direction)

Makes the specified hero face in the specified direction (e.g. down). The hero is specified by their rank in the walkabout caterpillar, 0-3. Use me to affect the leader.

set hero direction (me,right) # face right

hero direction (who)

Returns the specified hero's direction. The hero is specified by their rank in the walkabout caterpillar, 0-3

set hero frame (who, 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

hero frame (who)

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)

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 put hero command.

put hero (who, x, y)

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 set hero position 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)

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)

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)

Returns the hero's X position on the map in pixels. To find the hero's position in tiles, use the hero X function instead.

hero pixel Y (who)

Returns the hero's Y position on the map in pixels. To find the hero's position in tiles, use the hero Y function instead.

forward X (who)

Returns the X position of the tile immediately in front of the specified hero. who is optional, defaulting to 0 (me), the leader.
Wraps over the edge of wrapping maps.

forward Y (who)

Returns the Y position of the tile immediately in front of the specified hero. who is optional, defaulting to 0 (me), the leader.
Wraps over the edge of wrapping maps.

# This will check if npc 1 is in front of the leading hero, and if so show a textbox,
# as if you spoke to the npc. "use npc (1)" instead would actually activate it.
if (npc X (1) == forward X && npc Y (1) == forward Y) then(
   show text box (2)
)

hero Z (who)

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.

set hero z (who, 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.

walk hero to x (who,x)

Makes the specified hero walk to a given X coordinate on the map

walk hero to y (who,x)

Makes the specified hero walk to a given Y coordinate on the map

check hero wall (who,direction)

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 check wall collision x/y commands for much more flexible wall-checking, which works from any starting position on the map.

get hero speed (who)

Returns the walking speed of the specified hero, in pixels per tick.

set hero speed (who, 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 suspend caterpillar, 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 hero is walking. (You probably shouldn't use speed 0 at all.)

teleport to map (map, x, y)

An alternative to use door, teleport to map moves you to a given x,y position (in tiles) 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.

gracefully dismount vehicle

Documented in the Triggering Stuff section.

hero is walking (who)

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

teleport to map (map, x, y)

Documented in the Moving Heroes section.

use door (number, fade screen)

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 fade screen out immediately after use door, then the screen won't automatically fade back in afterwards. That's intentional, so that you can cancel the fade. (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)

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)

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.

get door y (number, map)

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.

get door destination id (number, map)

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 get door x and get door y. 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.

get door destination map (number, 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)

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 get door destination id to check if a door is active. If you want to script your own map transitions, you will find suspend doors helpful.

NPC reference (ID, copy, allow disabled?, pool)

(See NPC reference for an explanation of NPC references.)
Returns a reference to one of the NPCs on the map, or false/0 if the NPC you asked for is not found on the map.
ID is the NPC ID of the NPC to look up. The ID is the same number that appears in CUSTOM when you are editing NPCs or placing NPCs on the map. (Unlike other NPC commands, this one does not accept an NPC reference in place of the NPC ID.)
copy is optional. It specifies which copy (instance) of the NPC you want, in case there are more than one on the map. If you don't specify it, you will just get a reference to the first copy. Copies are counted starting from zero. You can see the copy number of NPCs in the Map Editor, at the bottom of the NPC, and using the F6 NPC debugger, by hoving the mouse over an NPC.
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.
pool is an optional NPC pool. If you don't specify which pool, then the ID is assumed to refer to the local pool for the current map. See also the global NPC reference command.
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

global NPC reference (ID, copy, allow disabled?)

global NPC (ID, copy, allow disabled?)

This command is the same as NPC reference except that it takes a global NPC ID number instead of a local NPC ID number. If there is no copy of the global NPC ID on the current map, it will return false. This command cannot get references to NPCs located on different maps, and the NPC reference it returns is only valid on the current map.
global NPC is an alias for global NPC reference.

next NPC reference (npcref)

This command is for looping over all the npcs on the map, in the same way that first child and next sibling can be used to iterate over all the children of a slice. When called with no argument or 0, it returns an NPC reference to the first NPC on the map. When npcref is 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 next sibling!), but creating NPCs at the same time might result in them getting skipped.

Tag-disabled NPCs are 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)
)

NPC at spot (x, y, number)

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 get count 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.

NPC at pixel (x, y, number)

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 get count for the third argument to return the total number of NPCs on that tile.

get NPC ID (reference)

This command (along with NPC copy number and get NPC pool) is the inverse of NPC reference. Returns an NPC's ID. If you give get NPC ID an NPC reference 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.

Some cheeky users use this command to check whether any instances of a local NPC ID exists, since like nearly all commands you can give it an NPC ID instead of a reference. E.g. get NPC ID(4) == 4 is true only if there's at least one copy of NPC 4.

get NPC pool (reference)

This command (along with get NPC ID and NPC copy number) is the inverse of NPC reference. This command takes an NPC reference and returns the ID of the NPC pool that this NPC belongs to: either pool:local or pool:global. reference can't be an NPC ID.

NPC copy number (reference)

This command is the inverse of NPC reference (along with get NPC ID). That is, it returns the copy number that you need to pass to NPC reference 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, pool)

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 NPC reference command.
The pool argument is optional (defaulting to pool:local), and tells which NPC pool ID refers to.

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, pool)

This command takes an NPC reference and lets you change the ID number of the NPC it points to, and change between local and global NPC pools. This means that the NPC will now use a different picture, palette, walking speed, text box, everything. This change is not permanent. It only lasts until the next time a map gets loaded. The pool argument is an optional NPC pool. If you don't specify a pool, then the NPC ID will be assumed to be the same pool that the NPC was previously part of.
If reference is an NPC ID then this command acts on the first NPC instance of that ID/pool, and the pool is not changed.

create NPC (ID, X, Y, direction, pool)

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). The pool argument is an optional NPC pool defaulting to pool:local (NPC definitions local to the current map).
create NPC returns an NPC reference that you can use to refer to the new NPC in other commands like walk NPC. 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.

create global NPC (ID, X, Y, direction)

This command works the same as the create NPC command, except that the ID number always refers to the global pool of NPCs, instead of the local pool. The instance of this global NPC will be created on the current map, and only lasts until you leave the map. It is not global in the sense of moving from map to map.

destroy NPC (reference)

This command will erase the specified NPC. You can use either an NPC reference or the NPC's ID number. The deletion is not permanent. Unless this is an NPC that you created with create NPC, 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.

delete NPC (reference)

NPC is disabled (reference)

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

camera pixel X

Returns the X position of the top left corner of the screen in pixels.

camera pixel Y

Returns the Y position of the top left corner of the screen in pixels.

camera follows hero (who)

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)

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 camera follows hero.

camera follows slice (slice)

With this command, you can make the camera follow a slice instead of the hero. The slice's anchor point will be centered on the screen. To revert the camera to normal, use camera follows hero. Note that this command usually only makes sense for slices that are parented to a map layer, or parented to something attached to a map layer like a hero or NPC.

pan camera (direction,distance,pixelstep)

This command causes the camera to stop following your leader and pan in the specified direction. The first argument is a direction, e.g. north. 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 wait for camera. To revert the camera to normal, use camera follows hero.

focus camera (x,y,speed)

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 wait for camera. To revert the camera to normal, use camera follows hero.

pixel focus camera (x,y,speed)

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 wait for camera. To revert the camera to normal, use camera follows hero.

put camera (x,y)

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 camera follows hero.

wait for camera

Documented in the Wait Commands section.

show text box (number)

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 wait for text box command.

show text box(2) # Show a text box
wait for text box # wait until the player continues

advance text box

Advances a text box just as if the player had pressed a key. For use 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

wait for text box

Documented in the Wait Commands section.

current text box

Returns the number of the currently displayed text box, or -1 if there's none.

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.

If you try to use this in a script called either AFTER or INSTEAD of a textbox, the textbox has closed by the time the script starts, so the NPC is no longer speaking and this will return false.
Likewise, if an NPC calls a script directly without showing a textbox this will just return false. But you don't need speaking NPC for scripts triggered directly from NPCs, because the script is given the NPC reference as its second argument (if any). (The first argument is customisable in the NPC editor.)

string from textbox (ID, textbox, line, ignored)

Loads one of the lines 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 textbox line. The fourth argument does nothing.

textbox line (string ID, textbox, line, expand, strip)

Loads one of the lines 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.

textbox text (string ID, textbox, expand, strip)

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.

show text box (number)

Documented in the Text Boxes section.

fight formation (number)

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

• 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 timer flag: critical runs out and ends the battle
• The end-battle-instantly debug key is used

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

use NPC (who)

Remotely trigger an NPC. You can use either an NPC reference or an NPC ID. 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 set NPC usable 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 door (number, fade screen)

Documented in the Doors section.

use shop (shop)

Takes you directly to a shop. You can specify the shop's ID number or its name in the form shop:name

teleport to map (map, x, y)

Documented in the Moving Heroes section.

force mount vehicle (npc)

Makes you mount the vehicle specified by NPC ID or NPC reference. Unlike use NPC, 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

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

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

gracefully dismount vehicle

Attempts to dismount whatever vehicle you are riding. If you are not riding a vehicle, nothing will happen. If the vehicle is not in a location where you are allowed to dismount, then nothing will happen.

dismount vehicle

Forces you to instantly dismount whatever vehicle you are riding without advancing the hero or allowing an airship to land. This will work even if the vehicle is located in a place where it would not normally allow dismounting. If you are not riding a vehicle, nothing will happen.
If you want normal dismounting behavior, as if the player had pressed the key to dismount a vehicle, use the gracefully dismount vehicle command instead.

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 reset game, 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 reset game 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 fade screen out beforehand.

By using reset game or load from slot instead, you can pass arguments to the newgame and loadgame scripts.

reset game(args...)

Resets and starts a new game, skipping both title and load game screens. It can be necessary to use this instead of game over 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 load from slot, 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 game over, the screen will always automatically fade out to black when calling reset game.

run game(file string id)

Documented in the Advanced Functions section.

show value (number, ...)

show values (number, ...)

Displays one or more numbers at the bottom left corner of the screen, which remains there until overwritten or show no value is used. Useful for count-down timers, and for debugging complicated scripts. The number of arguments to this command is variable. See show value of and trace value for similar debugging tools. You can't print strings with this command; use show string instead.

At most one of show value, show string, and show value of can show at once.

				show value(hero X(me), hero Y(me))   # Shows something like "  3   14" at the bottom of the screen
			

show value of (expression, ...)

Displays one or more expressions and their values at the bottom left corner of the screen, which remains there until overwritten or show no value is used. Useful for debugging complicated scripts. 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 show string instead.

At most one of show value, show string, and show value of can show at once.

# Shows something like "coins=0, hero X(me)=3, hero Y(me)=14" at the bottom of the screen
show value of(coins, hero X(me), hero Y(me))

show string (ID)

Displays string #ID in the bottom left corner of the screen, as with the show value command. Use show no value 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 show string at or center string at instead.

show no value

Gets rid of the number in the bottom left corner of the screen after a show value or show string command.

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)

Displays the specified full screen backdrop on the screen. This allows you to show full screen pictures without attaching them to text boxes. Use show map 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 load backdrop sprite.

show map

shows the map again after a show backdrop command. Don't confuse this with show mini map

main menu

Opens the main menu; exactly equivalent to open menu(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.
This isn't affected by anything that prevents the player from opening the main menu in the normal ways.

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

Displays the mini-map

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 show text box 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)

Takes you directly to a hero's status screen. Specify the hero using its position in the party 0-3. Use find hero if you want to specify the hero by name. The pick hero command can also be useful.

spells menu (who)

Takes you directly to a hero's spells menu. Specify the hero using its position in the party 0-3. Use find hero if you want to specify the hero by name. The pick hero 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)

Takes you directly to a hero's equip menu. Specify the hero using its position in the party 0-3. Use find hero if you want to specify the hero by name. The pick hero 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)

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.

load menu (reallyload, show new game)

Displays the load game menu (unless there are no saved games, in which case it's skipped). The player can pick a saved game to load or Exit/Cancel or New Game. New Game only appears if show new game is true, which is the default, together with the Exit button. (If show new game is false the button is labelled Cancel instead of Exit.) If there are no saved games, it's equivalent to selecting New Game, even if show new game is false.
The reallyload argument is optional, and defaults to true. When true, if the player picks a save it's loaded, if they pick New Game (or there are no saves) then the calling script continues, and if they select Exit/Cancel the game quits to the titlescreen if there is one or completely if not.
If you pass false as reallyload argument the menu only displays (or is skipped) without actually loading or quiting. 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/menu skipped and -1 is Quit or cancelled (pressed ESC).

If you want the New Game option to actually reset the game, call reset game afterwards:

load menu
reset game

If you don't want the player to be able to quit the game, only load a game or continue, then write:

variable (slot)
slot := load menu (false)
if (slot > 0) then (load from slot (slot))

order menu

Takes you directly to the order menu, where you can change the order of the heroes in your active party.

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.

inn screen (price, skip fade)

Opens an Inn screen with a specific price. The optional skip fade argument defaults to false. If you set it to true, no fade effect will happen when sleeping at the inn. This command returns true if the player slept in the inn, and false if they cancelled.

debug menu

Documented in the Debugging section.

party money

Returns how much money your party has.

get money (amount)

Adds the specified amount to your party's money

lose money (amount)

Subtracts the specified amount from your party's money.

set money (amount)

Changes the amount of money your party has.

pay money (amount)

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

use item (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).

get item name (ID, item)

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)

This command will take the description of item #item and stick it in string #ID, overwriting its contents.

get item maximum stack size (item)

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.

equip where (hero, item)

Documented in the Equipment section.

get ui color (color, autotoggle)

Look up which color a UI color is. color should normally be a ui: constant such as ui:menu item. See color code for a list of constants. Also, if color is a palette index (0 - 255) then it is returned unchanged.
autotoggle is optional, and defaults to false. If true, when you get certain UI colors that normally flash (for example, ui:selected item), the return value will change every tick according to the flashing, rather than just returning the value seen in the Edit User-Interface Colors menu.

set ui color (color, palette index)

Change a UI color. color should be a ui: constant such as ui:menu item. See color code for a list of constants. palette index should be a value 0-255, an index in the current master palette.

The change will be lost if you call load palette, reset palette, quit the game, or load a game.

get box style color (box style)

Returns the background/fill color (0-255 master palette index) of box style, which should be 0 to 14.

get box style edge color (box style)

Returns the edge color (0-255 master palette index) of box style, which should be 0 to 14.
This is the color of the simple line border; if the box style uses a box border spriteset (see get box style border) then the line border is usually not visible.

get box style border (box style)

Returns either border:line (which is -1) if a box style use a simple line border rather than a box border spriteset, or the spriteset ID of the border for box style, which should be 0 to 14.

rename hero (who)

Pops up a name-editing box that allows you to change the name of a hero in the party. The game and scripts are paused while this menu is up.
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)

Pops up a name-editing box that allows you to change the name of a hero in the party. The game and scripts are paused while this menu is up.
The argument is the hero's position in the party as returned by find hero. The return value is true if the player the hero renamed, or false if they cancelled.

get attack name

read attack name (str ID, attack)

This command will take the name of attack and stick it in the str ID string, 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 (str ID, attack)

This command will take the caption of attack and stick it in the str ID string, overwriting its contents. Use the atk:name constants from your HSI file as the attack.

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

get attack extra (attack, extra num)

Returns the value in one of an attack's "extra data" fields, which you can set in the Misc submenu. Use the atk:name constants from your HSI file as the attack ID. extra num is an extra array index.

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