Dictionary of Plotscripting Commands

This is the documentation for all plotscripting commands. In addition to reading this document, we also recommend you check out the Plotscripting Tutorial and the Plotscripting article on the wiki.

If you're reading this on the OHRRPGCE website then make sure you're looking at the page for the correct stable release or latest nightly version. This documentation is also included as an HTML file with downloads of the engine.

Commands by Category

Alphabetical Index

Declarations

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 with default values. 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 events in your game, or by name within other scripts.

# 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 declared for you in plotscr.hsd (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

Math, Comparison, and Logic Operators

Working with Variables

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.

See also:

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.

See also:

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.

See also:

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 number 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 (new seed)

Reseeds the random number generator. If called with no argument, this will reseed the random number generator to a new random sequence. If you pass in a number (other than 0), the random number generator will be seeded with that number, allowing for repeatable random sequences.

See also:

random

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)

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)

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)

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.

See also:

write global

write global (id,value)

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

See also:

read global

Flow Control

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

end

See begin

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

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 == 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. There are several examples of if statements in the HamsterSpeak Specification, and throughout this document. 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.

See also:

else if

... 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, 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!"
)

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 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 it is a check tag command.

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

See also:

while,
for,
switch

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

See also:

exit returning

exit returning(value)

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 exit script. 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.

See also:

return,
exit script

exit script

Causes the script to end immediately

See also:

exit returning

break

Breaks out of a for or while loop or switch and continues the script after the end of the do block.

continue

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)

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)

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 wait for NPC 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)

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.

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 (for example, the one returned by open menu), 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. You can use the following constants: any key, up key, down key, left key, right key, use key, cancel key, or menu key. If you do not specify key, then any key will be used. These are not scancodes (as used by key is pressed), and can not be mixed with scancodes! Use wait for scancode if you want to use scancodes or wait for other keys. 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 key that was pressed, which might be a joystick scancode like joy:x up.

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

wait for scancode (key)

Waits for the player to press a specific key. You can use any of the constants from key is pressed to specify the key.

show text box(624) # "press P!"
wait for scancode(key:P)

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

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 if suspend NPCs is active, waits for all NPCs to stop walking. Warning! In all versions older than July 6 2010, wait for all did not correctly wait for NPC movement. It was effectively broken, since it did not actually wait for all movement. Also be aware that wait for all does NOT wait for text boxes.

# do a bunch of things all at once
wait for all # wait until everything is done

Suspend and Resume

suspend player

Blocks the player from controlling the game, so the plotscript can have exclusive control. The one exception to this is text boxes. The player can advance text boxes no matter what, unless you use suspend box advance.

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. When suspend NPCs is run, all NPCs stop in their tracks once they've finished their current move, ready for you to control them with the walk NPC command. You can use wait for all to wait for all NPCs to stop moving. Use set NPC moves(who, false) instead to prevent a single NPC from moving.

suspend NPCs
# do stuff
resume NPCs

See also:

wait for NPC,
wait for all,
set NPC moves

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

See also:

set NPC obstructs

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

See suspend caterpillar

resume catapillar

See resume caterpillar

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

See suspend random enemies

resume random enemys

See resume random enemies

suspend box advance

Prevents the player from advancing or clearing text boxes by pressing keys. While this is active, the only way to make a text box advance is with the advance text box command (or show text box). 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.

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 # "hit spacebar"
resume box advance # go back to normal

resume box advance

Undoes the suspend box advance command and allows the player to advance and clear text boxes by pressing keys as normal.

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 # "hit spacebar"
resume box advance # go back to normal

box advance is suspended

Returns true if suspend box advance 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)

See also:

set ambient music,
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.

Moving Heroes

walk hero (who, direction, distance)

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

Defined in the Wait Commands section.

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

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

See also:

hero frame

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.

See also:

hero X,
hero Y,
hero pixel X,
hero pixel Y

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.

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.

See also:

set hero z

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) unless they are riding a vehicle which rises.

See also:

hero Z

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.

See also:

set hero speed

set hero speed (who, speed)

Changes the walking speed of the specified hero. If you do not specify a speed, the hero's speed will return to the default, 4. Be careful with using speeds that do not divide evenly into 20, because tiles are 20 pixels in size, and an irregular walking speed may cause your hero to become misaligned with the tiles.

See also:

get hero speed

teleport to map (map, x, y)

An alternative to use door, 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.

dismount vehicle

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

Moving NPCs

NPC reference (ID, copy)

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 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. If the NPC ID/copy which you asked for is not found on the map then NPC reference will return false.
If you plan on using the same NPC reference many times in a script you can store it in a variable.

NPCs hidden due to tag conditions are never returned by this command.

include,plotscr.hsd

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

See also:

NPC at spot,
NPC at pixel,
create NPC,
NPC copy count,
next 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 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. 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.

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

See also:

NPC reference,
NPC at spot,
NPC at pixel

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.

See also:

NPC reference

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.

See also:

NPC reference

walk NPC (who, direction, distance)

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 NPC reference 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 wait for NPC command. You should normally use the suspend NPCs command before moving NPCs to prevent their automatic movements from interfering with your scripted movements.

wait for NPC (who)

Defined in the Wait Commands section.

set NPC direction (who, 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 NPC reference or the NPC's ID number to specify which NPC will turn.

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

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 NPC reference 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, and 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 cancel NPC walk command.

See also:

NPC chases NPC,
cancel NPC walk,
wait for NPC

NPC chases NPC (who, other who, stop when reached, stuck ticks)

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 NPC reference 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 ommitted 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, and 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 cancel NPC walk command.

See also:

pathfind NPC to,
cancel NPC walk,
wait for NPC

cancel NPC walk (who)

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

See also:

pathfind NPC to,
NPC chases NPC,
walk NPC,
cancel NPC walk

NPC direction (who)

Returns the specified NPC's direction.

set NPC frame (who, frame)

Sets the walking frame of the specified NPC to 0 or 1. You can use either an NPC reference or the NPC's ID number to specify which NPC will change.

See also:

NPC frame

NPC frame (who)

Returns the walking frame (0 or 1) of the specified NPC.

set NPC position (who, X, Y)

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 NPC reference or the NPC's ID number to specify which NPC will be moved.

put npc (who,x,y)

Moves an NPC to a location on the map in pixels. The first argument is and NPC reference 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 set NPC position command.

NPC X (who)

Returns the specified NPC's X position in tiles. Note that an NPC's tile is the tile its top left corner is on.

See also:

NPC at spot

NPC Y (who)

Returns the specified NPC's Y position in tiles. Note that an NPC's tile is the tile its top left corner is on.

See also:

NPC at spot

NPC pixel X (who)

Returns the NPC's X position on the map in pixels. The argument is an NPC reference or an NPC ID number. To find the NPC's position in tiles, use the NPC X function instead.

NPC pixel Y (who)

Returns the NPC's Y position on the map in pixels. The argument is an NPC reference or an NPC ID number. To find the NPC's position in tiles, use the NPC Y function instead.

npc Z (who)

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.

See also:

set npc z

set npc z (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.

See also:

npc Z

walk NPC to X (who, X)

Makes the specified NPC walk to a given X coordinate on the map. You can use either an NPC reference or the NPC's ID number to specify which NPC will move.

walk NPC to Y (who, Y)

Makes the specified NPC walk to a given Y coordinate on the map. You can use either an NPC reference or the NPC's ID number to specify which NPC will move.

check NPC wall (who, direction)

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

get NPC speed (who)

Returns the walking speed of the specified NPC (either NPC reference or ID number) in pixels per tick.

set NPC speed (who, speed)

Changes the walking speed of the specified NPC. If you do not specify a speed, the NPC's speed will return to the default, 4. Be careful with using speeds that do not divide evenly into 20, because tiles are 20 pixels in size, and an irregular walking speed may cause the NPC to become misaligned with the tiles.
Normally you would only give an NPC ID number to set NPC speed, but if you want to use an NPC reference 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.

NPC is walking (who)

Returns true if the specified NPC is currently walking. Returns false if the NPC is standing still. You can use either an NPC reference or the NPC's ID number to specify which NPC will be checked.

NPC extra (who, which)

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.

See also:

set NPC extra

set NPC extra (who, which, value)

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 save map state)

See also:

NPC extra

get NPC ID (reference)

This command is the opposite of NPC reference. If you give get NPC ID a reference to an NPC it will return the NPC's ID. If the NPC ID is not valid then get NPC ID will return -1.

NPC copy count (ID)

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.

include, plotscr.hsd

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

This command takes an NPC reference 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)

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

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)

See destroy NPC

NPC is disabled (reference)

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

The Party → Inspecting the Party

leader

Returns the hero ID number (as given in the Edit Hero Stats menu) of the current caterpillar party leader.

find hero (who)

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 hero by slot.

See also:

rank in caterpillar

hero by slot (where)

This command is the reverse of find hero. 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)

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.

See also:

find hero

hero by rank (where)

This command is the reverse of rank in caterpillar. 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

A function that returns the number of available spaces in your active party. It will return zero or false if there is no room.

The Party → Changing the Party

add hero (who)

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)

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)

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)

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)

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 swap in hero or swap out hero. Use the constants defined in your HSI file. They are in the form of hero:name

unlock hero (who)

Reverses lock hero, 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)

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)

Swaps two heroes in your party by their positions in the party (ie, by party slot).

Items → Inventory

get item (item,number)

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)

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)

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 get inventory size-1.

See also:

set item in slot,
item count in slot,
set item count in slot,
get inventory size

set item in slot (slot, item)

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 get inventory size-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.

See also:

item in slot,
item count in slot,
set item count in slot,
get inventory size,
get item maximum stack size

item count in slot (slot)

Return a the count of items at a specific slot in your inventory, or 0 if that slot is empty. Slots are numbered from 0 to get inventory size-1.

See also:

item in slot,
set item in slot,
set item count in slot,
get inventory size,
get item maximum stack size

set item count in slot (slot, count)

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 get item maximum stack size), 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.

See also:

item in slot,
set item in slot,
set item count in slot,
get inventory size,
get item maximum stack size

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

See also:

use item

inventory (item)

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

Returns the number of inventory slots.

See also:

set inventory size

set inventory size (new 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.

See also:

get inventory size

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.

See also:

item count in slot,
get inventory size

Items → Equipment

unequip (hero,slot)

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 find hero 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 gain hero stat:

gain hero stat(who, stat:hp, 0)
gain hero stat(who, stat:mp, 0)

See also:

force equip,
check equipment

force equip (hero,slot,item)

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 find hero 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.

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

See also:

unequip,
equip where,
check equipment

equip where (hero,item)

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 find hero 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.

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

See also:

unequip,
check equipment

check equipment (hero,slot)

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 find hero 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.

See also:

force equip,
unequip,
equip where

get default weapon (hero)

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 find hero if you want to refer to the hero by name).

set default weapon (hero,item)

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

Plays the specified song. Use the constants defined in your HSI file. They appear in the form of song:name

current song

Returns the number of the currently playing song, or -1 if none.

stop song

Stops whatever music is currently playing.

set victory music (song)

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

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)

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 save map state 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: same as last map for song, the default is silence.

See also:

play song

get ambient music

Returns the song number of the map's ambient music, either a song ID or the constants song: silence or song: same as last map.

See also:

current song

set music volume (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

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.

Effects → Master Palette

fade screen out (red,green,blue)

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 fade screen in, fight a battle, or use a door.

fade screen in

Fades the screen back to normal after a fade screen out command, or applies the changes made with other palette commands such as greyscale palette, tweak palette, reset palette, and write color.

load palette (palette number)

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 update palette or fade screen in, however the UI colors are changed immediately.

update palette

Instantly returns from fade screen out, and applies changes made by other palette command such as greyscale palette, tweak palette, reset palette, and write color.

greyscale palette (first, last)

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 update palette or fade screen in. 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)

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 update palette or fade screen in. 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

Reloads the default master palette and its user interface colors, undoing any changes you have made with other palette-altering commands such as tweak palette or greyscale palette. Changes to the palette do not take effect until you call update palette or fade screen in. 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)

Returns a color value from the master palette. 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 color:red, color:green, and color:blue. The counterpart to this is write color.

This command operates on values from 0-63. For operation on full color values (0-255), used get color.

See also:

get color

write color (index, element, value)

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 color:red, color:green, and color:blue. 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 set color if you want to set color values in the 0-255 range. Changes do not take effect until you call update palette or fade screen in. 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.

See also:

set color,
read color

get color (index)

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.

See also:

set color,
extract color

set color (index, value)

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 get color. Changes do not take effect until you call update palette or fade screen in. 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.

See also:

get color,
RGB

RGB (red, green, blue)

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.

See also:

extract color

extract color (color, component)

Takes a 32-bit color value (as returned by get color), and extracts the red, green or blue component, based on the component parameter. You may use the color:red, color:green and color:blue parameters to choose which one.

See also:

Effects → Sound Effects

play sound (num,loop,preempt)

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, this command will do nothing.

See also:

stop sound

stop sound (num)

Stops a sound effect. If the sound is not playing, nothing will happen.

See also:

play sound

pause sound (num)

Temporarily stops a sound effect. It can be resumed with play sound, wherein it will continue from whence it left off.

See also:

play sound

sound is playing (num)

Checks to see whether a sound effect is playing or not. Useful for synchronization, etc.

See also:

play sound,
stop sound,
wait for sound

wait for sound (num)

Waits until a sound effect has finished playing. Useful for synchronization, etc.

See also:

sound is playing

Hero Data → Hero Graphics

set hero picture (who,picture,type)

Permanently changes a hero's picture. The first argument is the hero's position in the party. (Use find hero 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 inside battle or outside battle or hero portrait, 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, outside battle is assumed.

See also:

reset hero picture

set hero palette (who,palette,type)

Permanently changes a hero's 16-color palette. The first argument is the hero's position in the party. (Use find hero 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 inside battle or outside battle or hero portrait, 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, outside battle is assumed.

See also:

reset hero palette

get hero picture (who,type)

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 find hero. The second argument is a constant inside battle or outside battle or hero portrait, 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, outside battle is assumed.

get hero palette (who,type)

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 find hero. The second argument is a constant inside battle or outside battle or hero portrait, 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, outside battle is assumed.

reset hero picture (who,type)

Resets a hero's picture that was previously changed with set hero picture back to the default picture. The first argument is the hero's position in the party. (Use find hero if you want refer to the hero by name). The second argument is a constant inside battle or outside battle or hero portrait, 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, outside battle is assumed.

See also:

set hero picture

reset hero palette (who,type)

Resets a hero's palette that was previously changed with set hero palette back to the default palette. The first argument is the hero's position in the party. (Use find hero if you want refer to the hero by name.) The second argument is a constant inside battle or outside battle or hero portrait, 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, outside battle is assumed.

See also:

set hero picture

Hero Data → Hero Hand Position

get hero hand x (who,frame)

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

See also:

get hero hand x,
get hero hand y,
set hero hand x,
set hero hand y,
get default hero hand x,
get default hero hand y

get hero hand y (who,frame)

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

See also:

get hero hand x,
get hero hand y,
set hero hand x,
set hero hand y,
get default hero hand x,
get default hero hand y

set hero hand x (who, frame, new 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.

See also:

get hero hand x,
get hero hand y,
set hero hand x,
set hero hand y,
get default hero hand x,
get default hero hand y

set hero hand y (who, frame, new 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.

See also:

get hero hand x,
get hero hand y,
set hero hand x,
set hero hand y,
get default hero hand x,
get default hero hand y

get default hero hand x (who,frame)

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

See also:

get hero hand x,
get hero hand y,
set hero hand x,
set hero hand y,
get default hero hand x,
get default hero hand y

get default hero hand y (who,frame)

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

See also:

get hero hand x,
get hero hand y,
set hero hand x,
set hero hand y,
get default hero hand x,
get default hero hand y

Hero Data → Hero Stats

Experience and Levels

get hero stat (who,stat,type)

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 find hero. 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 current stat or maximum stat or base stat. Follow those links for explanations. If you leave out the type, current stat will be assumed.

See also:

set hero stat,
gain hero stat,
get level MP,
get hero level,
total experience,
hero total elemental resist as int,
set enemy stat,
get enemy stat

set hero stat (who,stat,value,type)

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 current stat or maximum stat or base stat. Follow those links for explanations. If you leave the last argument blank, current stat 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 set capped hero stat 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 set hero stat cap. 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 gain hero stat.

# 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

See also:

gain hero stat,
get hero stat,
set capped hero stat,
set hero stat cap,
set enemy stat,
get enemy stat

gain hero stat (who, stat, amount, reset to max)

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

See also:

get hero stat,
set hero stat,
set capped hero stat,
set hero stat cap

set capped hero stat (who,stat,value,type)

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 set hero stat, 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 current stat or maximum stat (base stat will also work but will not be capped). If you leave the last argument out, current stat will be assumed.

See also:

set hero stat,
get hero stat cap,
set hero stat cap,
gain hero stat

get hero stat cap (stat)

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.

See also:

set capped hero stat,
set hero stat cap

set hero stat cap (stat, value)

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.

See also:

get hero stat cap

get level MP (who, mp level slot, type)

Returns a hero's level MP (FF1-style MP). The argument who is the hero's position in the party, as returned by find hero. 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 optional third argument is either current stat or maximum stat. If you leave out the type current stat will be assumed. Pass maximum stat 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)

Changes a hero's level MP (FF1-style MP). The argument who is the hero's position in the party, as returned by find hero. 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 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)

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 find hero. 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.

See also:

set hero base elemental resist,
hero total elemental resist as int

set hero base elemental resist (who, element, percent)

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 find hero. 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.

See also:

hero base elemental resist as int

hero total elemental resist as int (who, element)

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 find hero. 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.

See also:

hero base elemental resist as int

Hero Data → Hero Stats → Experience and Levels

get hero level (who)

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 find hero. The return value with be your current level, from 0 to 99

See also:

set hero level,
total experience

set hero level (who, level, forgetspells)

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 find hero. 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.

See also:

get hero level,
hero levelled,
spells learnt,
set experience

set experience (who, experience, allowforget)

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 find hero. 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 set level cap to get around this.

See also:

set hero level,
total experience,
hero levelled,
spells learned

update level up learning(who, allowforget)

Defined in the Hero's Spells section.

hero levelled (who)

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 find hero. This command only applies to the most recent battle or give experience, set hero level or set experience 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
)

spells learned (hero,number)

Defined in the Hero's Spells section.

total experience (who)

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 find hero.

See also:

set experience

experience to next level (who)

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 find hero.

experience to level (level, hero slot)

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)

Gives experience to either a hero by position in party (use result returned by find hero 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 hero levelled and spells learned for dealing with this. This command can give negative experience, but it will never cause a hero to delevel. You should use set experience 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 set level cap to get around this.

Hero Data → Hero's Spells

teach spell (hero,attack)

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 find hero). 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 write spell to add a spell to a spell list without restriction.

forget spell (hero,attack)

Causes a hero to forget a spell. The first argument is the hero's position in the party (as returned by find hero). 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)

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

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)

Checks to see if a hero already knows a spell. The first argument is the hero's position in the party (as returned by find hero). 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)

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

This is deprecated, do not use it. It is identical to spells learned 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)

Returns the id numbers (+1) of spells the hero learned from the last battle or give experience, set hero level or set experience command that targeted either this hero or the whole party. If the second argument is get count 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 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 set hero level 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.

Hero Data → Out-of-battle Attacks

outside battle cure (attack minus 1, target, attacker)

Obsolete, replaced by map cure. This is identical to mapcure except for the attack argument differing by one.

map cure (attack, target, attacker)

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

See also:

use item,
set hero stat,
set death script

NPC Data

alter NPC (who,NPCstat,value)

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
- NPCmovetype:chaseyoumeandering
- NPCmovetype:chaseyoudirect
- NPCmovetype:avoidyou
- NPCmovetype:avoidyoumeandering
- NPCmovetype:avoidyoudirect
- NPCmovetype:walkinplace
- NPCmovetype:followwallsright
- NPCmovetype:followwallsleft
- NPCmovetype:followwallsrightstopsforothers
- NPCmovetype:followwallsleftstopsforothers
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 check onetime) 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 set NPC ignores walls command.

Normally you would only give an NPC ID number to alter NPC, but if you want to use an NPC reference 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 alterNPC 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

See also:

set NPC usable,
set NPC moves,
set NPC ignores walls,
set NPC obstructs

read NPC (who, NPCstat)

Returns data such as picture, palette, walking speed, text box, etc. for an NPC. Use the same constants as alter NPC.

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

See also:

alter NPC

set NPC ignores walls (who, value)

Given an NPC reference or NPC ID (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 set NPC obstructs for that.
This command is just like suspend NPC walls/resume NPC walls, but only affects a single npc.

Don't confuse this with alter NPC(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.

See also:

get NPC ignores walls,
suspend NPC walls,
set NPC obstructs,
alter NPC

get NPC ignores walls (who)

Given an NPC reference or NPC ID (in which case the first NPC with that ID is used), returns whether that NPC can walk through walls.

Don't confuse this with read NPC(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.

See also:

set NPC ignores walls,
read NPC

set NPC moves (who, value)

Given an NPC reference or NPC ID (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 walk NPC.
value should be true or false.
This command is just like suspend NPCs/resume NPCs, 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.

See also:

get NPC moves,
suspend NPCs,
alter NPC

get NPC moves (who)

Given an NPC reference or NPC ID (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 set NPC moves has been used.

See also:

set NPC moves,
read NPC

set NPC obstructs (who, value)

Given an NPC reference or NPC ID (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 suspend obstruction/resume obstruction, 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 set NPC ignores walls command.

See also:

get NPC obstructs,
suspend obstruction

get NPC obstructs (who)

Given an NPC reference or NPC ID (in which case the first NPC with that ID is used), returns false if that NPC's obstruction has been suspended with set NPC obstructs (and is always true otherwise).

See also:

set NPC obstructs

set NPC usable (who, value)

Given an NPC reference or NPC ID (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). use NPC will still work on the NPC. value should be true or false.

See also:

get NPC usable,
alter NPC

get NPC usable (who)

Given an NPC reference or NPC ID (in which case the first NPC with that ID is used), returns false if normal activation of that NPC has been suspended with set NPC usable. This is always true otherwise, even for NPC types which are not activatable.

See also:

set NPC usable

Enemy and Formation Functions

Formations

get enemy stat(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.

See also:

set enemy stat,
enemy elemental resist as int,
get hero stat,
set hero stat

set enemy stat(enemy, stat, value)

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.

See also:

get enemy stat,
get hero stat,
set hero stat

enemy elemental resist as int (enemy, element)

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.

See also:

get enemy stat,
hero total elemental resist as int

get enemy name (enemyid, stringid)

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.

See also:

set enemy name

set enemy name (enemyid, stringid)

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.

See also:

get enemy name

get enemy appearance (enemyid, 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.

See also:

set enemy appearance

set enemy appearance (enemyid, appearance,value)

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 get enemy appearance. 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.

See also:

get enemy appearance

read enemy data (enemyid, 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

See also:

write enemy data

write enemy data (enemyid, data, value)

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 read enemy data.

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

See also:

read enemy data

Enemy and Formation Functions → Formations

add enemy to formation (formation, enemy id, x, y, slot)

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.

See also:

delete enemy from formation

delete enemy from formation (formation, slot)

Deletes an enemy in the given slot (as returned by find enemy in formation for example) in the formation.

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

See also:

add enemy to formation

find enemy in formation (formation, enemy id, copy number)

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

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

See also:

delete enemy from formation,
formation slot enemy,
formation slot x,
formation slot y

formation slot enemy (formation, slot)

Returns the ID number of the enemy in the specified formation slot (0 to 7), or -1 if the slot is empty.

See also:

find enemy in formation

formation slot x (formation, slot)

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.

See also:

find enemy in formation

formation slot y (formation, slot)

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.

See also:

find enemy in formation

set formation background (formation, background, animation frames, animation ticks)

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.

See also:

get formation background

get formation background (formation)

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

See also:

set formation background

set formation song (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: same as map

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

See also:

get formation song

get formation song (formation)

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: same as map.

See also:

set formation song

reset formation (formation)

Reset any scripted changes to formation. This script erases changes made with add enemy to formation, delete enemy from formation, set formation background, and set formation song and changes the formation back to the way it was defined in the Formation Editor in custom.

See also:

reset formation slot

reset formation slot (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 add enemy to formation or delete enemy from formation and changes the formation slot back to the way it was defined in the Formation Editor in custom.

See also:

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

Picks a formation randomly from the given formation set (1 to 255), returning the formation number.

See also:

formation probability

formation set frequency (formation set)

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 get battle countdown).

See also:

random formation,
get battle countdown,
set 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.

See also:

formation set frequency,
get battle countdown,
set battle countdown

set battle countdown (value)

Sets the random battle countdown value (see get battle countdown). 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 teleport to map, or dismounting a vehicle.

See also:

formation set frequency,
get battle countdown,
set battle countdown

formation probability (formation set, formation)

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.

See also:

random formation,
random

Getting Player Input → Keyboard Input

key is pressed (scancode)

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 argument is a scancode, NOT the up key, down key, etc used with wait for key.

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 on the "Enable better scancodes for scripts" Preference Bitset in the General Game Settings menu.

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.

You can NOT wait for the player to press a key by continually polling key is pressed unless you stick a wait in your while loop. That's because key is pressed does not return real time data, but the state of the keyboard at the beginning of the current game tick.

Keyboard scan codes:

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:Left Win Logo # equal to key:Left Command
key:Right Win Logo # equal to key:Right Command
key:Context
key:Left Command # Macintosh, equal to key:Left Win Logo
key:Right Command # Macintosh, equal to key:Right Win Logo

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: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 (for the first joystick only):

joy:button 1
joy:button 2
joy:button 3
...
joy:button 16
joy:x left
joy:x right
joy:y up
joy:y down

Previously it was necessary to include, scancode.hsi to use the key: constants, but no longer.

See also:

keyval

keyval (scancode)

Returns a bitmask for the state of the specified key. The argument is a scancode, see key is pressed. The first (least significant) bit is whether the key was depressed at the beginning of the current tick. The second bit is whether the key was pushed down by the player since the start of the previous tick (or when the key starts to repeatedly trigger after being held down for a while). 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)

Just like key is pressed, this command does not return real time data, but the situation at the beginning of the current game tick.

The joystick scancodes described in key is pressed aren't fully supported for keyval: the return value will be 3 if the key is down, or 0 if it isn't. In other words, no additional information over key is pressed.

Don't 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 (e.g. keyval(key:X)>1) 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!

See also:

key is pressed

last ascii

This command is obsolete. Use get input text 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)

This command needs to be called before get input text can be used. If the optional argument is true or not given then get input text is enabled, otherwise it is disabled. Enabling get input text may cause some of the keys on international keyboards ("combining" keys, which are usually punctuation keys) to go "dead" --- that is, commands such as key is pressed and wait for key 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 input string.

See also:

get input text

get input text (string id)

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 enable input text before this command can be used! See that command for details. You will normally call this every tick in a loop and use concatenate strings to read the player's complete input. However it is much easier to call the input string function instead, which does this for you.

See also:

input string

input string (ID, maxlength, use current, center, position x, position y)

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 set to 40 (max visible onscreen length). 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 center string at 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.

See also:

get input text

input string with virtual keyboard (ID, maxlength, onlyplayer)

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.

See also:

input string,
input string with mouse keyboard

show virtual gamepad

Defined in the Platform Specific section.

hide virtual gamepad

Defined in the Platform Specific section.

auto virtual gamepad

Defined in the Platform Specific section.

Getting Player Input → Joystick Input

joystick button (button, joystick)

Returns true or false depending on whether button #button on joystick #joystick is pressed. button can be from 1-16 (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.

joystick axis (axis, multiplier, joystick)

Returns the position of the joystick along the X or Y axis on joystick #joystick. axis can be one of the constants x axis or y axis. 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.

Getting Player Input → Mouse Input

Helpful Related Commands

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 show value, show string at, 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

Returns the X coordinate in pixels of the mouse on the screen.

mouse pixel Y

Returns the Y coordinate in pixels of the mouse on the screen.

mouse button (which)

Returns true if the specified mouse button is currently pressed down. You can use the constants left button and right button to specify the button.

Just like keyboard commands such as key is pressed, 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 one per frame.

See also:

mouse click,
mouse release

mouse click (which)

Returns true if the specified mouse button has been 'clicked' down in the last tick. You can use the constants left button and right button to specify the button.

See also:

mouse button,
mouse release

mouse release (which)

Returns true if the specified mouse button has been released since the last tick. You can use the constants left button and right button to specify the button.

See also:

mouse button,
mouse click

put mouse (X, Y)

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. init mouse should be called before this command is used.

mouse region (x min, x max, y min, y max)

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. init mouse should be called before this command is used.

input string with mouse keyboard (ID, maxlength)

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

See also:

input string,
input string with virtual keyboard

unhide mouse cursor

Causes the normal OS mouse cursor to be displayed. You may want to run this command right after init mouse 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

Causes the normal OS mouse cursor to be hidden. This command is seldom needed, because the cursor is hidden by default when you run init mouse.

show mouse cursor

See unhidemousecursor

Getting Player Input → Mouse Input → Helpful Related Commands

camera pixel X

Defined in the The Camera section.

camera pixel Y

Defined in the The Camera section.

slice at pixel (parent, x, y, number, check descendants, visible only)

Defined in the Slice Collision Testing section.

slice collide point (handle, x, y)

Defined in the Slice Collision Testing section.

NPC at pixel (x, y, number)

Defined in the Moving NPCs section.

menu item at pixel(x, y)

Defined in the Menu Items section.

String Functions → Basic String Commands

$id="some text"

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 $id+"..." 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:
\\ turns into a single \
\" turns into a single " without signalling the end of the literal
\n is a new line character, which is useful in a textslice but doesn't cause a new line in textboxes or on-screen strings.
\t is a tab character (which isn't useful at all as it doesn't actually cause a tab)
\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 "A quote" in the corner of the screen
showstring($1="\"A quote\"")

$id+"some text"

Appends a string literal to a string variable. This is the same as $id="...", except that the existing contents of the string are preserved and appended to.

clear string(ID)

Erases the string buffer #ID to the empty string (""). That's all.

append ascii (ID, char)

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.

See also:

string sprintf,
append number

append number (ID, number)

Appends the textual representation of number to the string with ID #ID. For example, append number(1,65) will append "65", not "A".

See also:

append ascii,
string sprintf

string sprintf (dest string ID, format string ID, arguments...)

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.

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

See also:

append ascii,
append number

number from string (ID, default)

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)

See also:

append number

copy string (dest, source)

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)

Copies the text from string #source to string #dest. However, unlike copy string, 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)

Returns the length of string #ID.

string compare (ID1, ID2)

Returns true if the two strings #ID1 and #ID2 are identical, case sensitive.

replace char (ID, position, 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 string length.

delete char (ID, position)

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 string length.

ascii from string (ID, position)

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 string length. If you pass 0 as the position or a position past the end of the string, 0 will be returned.

String Functions → 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 get menu item caption live elsewhere, in more sensible sections!

get hero name (ID, hero)

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 hero by rank and find hero

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

This command changes the name of the hero in party slot #hero (as returned by find hero) to the contents of string #ID. The length is not limited by the hero's Max Name Length setting.

get enemy name (enemyid, stringid)

Defined in the Enemy and Formation Functions section.

set enemy name (enemyid, stringid)

Defined in the Enemy and Formation Functions section.

get map name (ID, map)

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

get attack name

See read attack name

read attack name (ID, attack)

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)

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)

Gets the name of song #song and puts it in string #ID.

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

Defined in the Text Boxes section.

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

Defined in the Text Boxes section.

String Functions → 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 show string command is yet another separate way to display a string.

show string at (ID, x, y)

Displays string #ID on the screen, positioning its top left corner at the given (x,y) coordinates. Unlike show string, changes to the string will be displayed in real-time.

center string at (ID, x, y)

Displays string #ID on the screen, positioning its top-middle at the given (x,y) coordinates. Unlike show string, changes to the string will be displayed in real-time.

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 topleft corner will stay fixed.

hide string (ID)

Makes a string previously displayed with show string at or center string at disappear. Has no effect on strings displayed with show string

string is visible (ID)

Returns true if a string is being displayed by show string at or center string at. Otherwise, returns false. Is not effected by show string

string style (ID, style)

Changes the appearance of a string. Use this in conjunction with (before or after) show string at or center string at. 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)

Changes the color of a string. Use this in conjunction with (before or after) show string at or center string at. 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)

Positions the top left corner of string #ID at the given x,y coordinates. Unlike show string at, this command will not affect the visibility of a string.

string X (ID)

Returns the horizontal X position of the top left corner of string #ID

string Y (ID)

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

Menu Functions → Menu Items

Menu Item Data

add menu item(menu handle)

Given a menu handle (for example, the one returned by create menu), 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 set menu item caption or set menu item type.

delete menu item(menu item handle)

Given a menu item handle (for example, the one returned by add menu item or selected menu item), 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)

Given two menu item handles (for example, the ones returned by selected menu item and next menu item) 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)

Given a menu item handle (for example, the one returned by add menu item), move the menu selection cursor to point to that menu item.

selected menu item(menu handle)

Returns the handle for the selected menu item in the topmost menu, false if no menus are open, or, when given an optional menu handle (for example, the one returned by open menu) returns the selected item in that menu.

use menu item(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu handle (for example, the one returned by open menu), return a menu item handle for the menu item at the top of the menu.

next menu item(menu item handle, visible only)

Given a menu item handle (for example, the one returned by selected menu item), 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. Note that invisible menu items are always at the end of the menu, after the last visible menu item. See menu item by true slot if that's undesirable.

variable(mi)
mi := first menu item
while(mi) do, begin
  # do things to each menu item
  mi := next menu item(mi)
end

previous menu item(menu item handle, visible only)

Given a menu item handle (for example, the one returned by selected menu item), 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 menu item by true slot if that's undesirable.

variable(m)
m := previous menu item(selected menu item)

menu item by true slot(menu handle, slot)

Given a menu handle (for example, the one returned by open menu), 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 menu item slot.

See also:

menu item by slot

menu item true slot(menu item handle)

Given a menu item handle (for example, the one returned by add menu item), 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 menu item slot.

See also:

menu item slot,
menu item by true slot

menu item by slot(menu handle, slot, visible only)

Given a menu handle (for example, the one returned by open menu), 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 menu item by true slot if you want to use the order shown in the Menu Editor.

See also:

menu item slot,
menu item by true slot

menu item slot(menu item handle)

Given a menu item handle (for example, the one returned by add menu item), 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 menu item true slot if you want to know the slot number as it appears in the Menu Editor.

See also:

menu item by slot,
menu item true slot

find menu item caption(menu handle, string ID, search after handle, visible only)

Given a menu handle (for example, the one returned by open menu), 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)

Given a position on the screen (for example menu item at pixel(mouse pixel X, mouse pixel Y)), 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 parent menu.

See also:

selected menu item

Menu Functions → Menu Items → Menu Item Data

get menu item caption(menu item handle, string ID)

Given a menu item handle (for example, the one returned by selected menu item), take the caption and copy it into the string identified by string ID.

set menu item caption(menu item handle, string ID)

Given a menu item handle (for example, the one returned by selected menu item), replace the caption with the string identified by string ID.

get menu item type(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), return the type of the menu item.

set menu item type(menu item handle, new type)

Given a menu item handle (for example, the one returned by selected menu item), change the type of the menu item to new type. Available constants are: menutype:label,menutype:special, menutype:menu, menutype:textbox, and menutype:script

get menu item subtype(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), return the subtype of the menu item. The meaning of the subtype varies depending on the type.

See also:

set menu item subtype

set menu item subtype(menu item handle, new subtype)

Given a menu item handle (for example, the one returned by selected menu item), change the subtype of the menu item to new subtype. The meaning of the subtype varies depending on the type of the menu item. For menutype:special you can use constants like: menuspecial:items, menuspecial:spells, menuspecial:status, menuspecial:equip, menuspecial:order, menuspecial:team, menuspecial:orderteam, menuspecial:map, menuspecial:save, menuspecial:load, menuspecial:quit, and menuspecial:volume. For menutype:textbox you can use the textbox's ID number. For menutype:menu you can use the menu's ID number or a menu:name constant from your HSI file. For menutype:script you can use script references in the form @scriptname

get menu item tag(menu item handle, whichtag)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), and bit number bit, Return true if the bitset is ON, and false if the bitset is OFF. You can use constants for the bit bit number in the form of menu item bit:Hide when disabled, menu item bit:Close menu when selected and menu item bit:skip close script.

set menu item bit(menu item handle, bit, value)

Given a menu item handle (for example, the one returned by selected menu item), and bit number bit, Set the bitset is ON or OFF depending on value. You can use constants for the bit bit number in the form of menu item bit:Hide when disabled, menu item bit:Close menu when selected and menu item bit:skip close script.

get menu item extra(menu item handle, extra)

Given a menu item handle (for example, the one returned by selected menu item), 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)

Given a menu item handle (for example, the one returned by selected menu item), 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.

Menu Functions → Menu Data

get menu bit(menu handle, bit)

Given a menu handle (for example, the one returned by top menu), 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

set menu bit(menu handle, bit, value)

Given a menu handle (for example, the one returned by top menu), 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 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

get menu boxstyle(menu handle)

Given a menu handle (for example, the one returned by open menu), return a the boxstyle of the menu. This will be a number from 0 to 15.

set menu boxstyle(menu handle, new box style)

Given a menu handle (for example, the one returned by open menu), change the boxstyle of the menu. new box style will be a number from 0 to 15.

get menu textcolor(menu handle)

Given a menu handle (for example, the one returned by open menu), return a the text color of the menu. This will be a number from 0 to 255.

set menu textcolor(menu handle, new textcolor)

Given a menu handle (for example, the one returned by open menu), change the text color of the menu. new textcolor will be a number from 0 to 255. 0 is the default color.

get menu max rows(menu handle)

Given a menu handle (for example, the one returned by open menu), 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)

Given a menu handle (for example, the one returned by open menu), 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)

Given a menu handle (for example, the one returned by open menu), return the x offset position of the menu's anchor point in pixels relative to the center of the screen.

See also:

get menu offset y,
set menu offset x,
set menu offset y

get menu offset y(menu handle)

Given a menu handle (for example, the one returned by open menu), return the y offset position of the menu's anchor point in pixels relative to the center of the screen.

See also:

get menu offset x,
set menu offset x,
set menu offset y

set menu offset x(menu handle, new x)

Given a menu handle (for example, the one returned by open menu), change the x offset position of the menu's anchor point in pixels relative to the center of the screen.

See also:

get menu offset x,
get menu offset y,
set menu offset y

set menu offset y(menu handle, new y)

Given a menu handle (for example, the one returned by open menu), change the y offset position of the menu's anchor point in pixels relative to the center of the screen.

See also:

get menu offset x,
get menu offset y,
set menu offset x

get menu anchor x(menu handle)

Given a menu handle (for example, the one returned by open menu), 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!)

See also:

get menu anchor y,
set menu anchor x,
set menu anchor y

get menu anchor y(menu handle)

Given a menu handle (for example, the one returned by open menu), 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!)

See also:

get menu anchor x,
set menu anchor x,
set menu anchor y

set menu anchor x(menu handle, new anchor)

Given a menu handle (for example, the one returned by open menu), change the horizontal x anchor position of the menu. The new anchor can be align:center, align:left or align:right.

See also:

get menu anchor x,
get menu anchor y,
set menu anchor y

set menu anchor y(menu handle, new anchor)

Given a menu handle (for example, the one returned by open menu), 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!)

See also:

get menu anchor x,
get menu anchor y,
set menu anchor x

get menu text align(menu handle)

Given a menu handle (for example, the one returned by open menu), 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!)

See also:

set menu text align

set menu text align(menu handle, new align)

Given a menu handle (for example, the one returned by open menu), 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!)

See also:

get menu text align

get menu min chars(menu handle)

Given a menu handle (for example, the one returned by open menu), return the minimum width of the menu in chars, or 0 for menus that have their width autodetected.

See also:

set menu min chars

set menu min chars(menu handle, new min)

Given a menu handle (for example, the one returned by open menu), change the minimum width of the menu in chars, or use 0 to make the menu width autodetected.

See also:

get menu min chars

get menu max chars(menu handle)

Given a menu handle (for example, the one returned by open menu), return the maximum width of the menu in chars, or 0 for menus that do not have a maximum.

See also:

set menu max chars

set menu max chars(menu handle, new max)

Given a menu handle (for example, the one returned by open menu), change the maximum width of the menu in chars, or use 0 for no maximum.

See also:

get menu max chars

get menu border(menu handle)

Given a menu handle (for example, the one returned by open menu), return the border thickness of the menu in pixels. Positive numbers indicate a thicker border. Negative numbers indicate a thinner border.

See also:

set menu border

set menu border(menu handle, new border)

Given a menu handle (for example, the one returned by open menu), 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.

See also:

get menu border

get menu on close script(menu handle)

Given a menu handle (for example, the one returned by open menu), return a script id 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)

See also:

run script by ID,
set menu on close script

set menu on close script(menu handle, script id)

Given a menu handle (for example, the one returned by open menu), assign script id 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)

See also:

run script by ID,
set menu on close script

Slices

Getting Slices
Slice Sizing
Positioning Slices
Visibility and Clipping
Alignment and Anchor Points
Padding
Moving Slices
Moving Around the Slice Tree
- Type-specific iteration commands
Reordering Slices
Slice Types
Slice Collision Testing

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 load slice collection.
Slices are referred to with slice handles. A slice handle is just a value that you can store in a variable, just like an NPC reference 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.

Slice lookup codes like "sl:map layer 0" or "sli:quit button" are NOT slice handles; they can only be used by the lookup slice command.

set parent (handle, parent handle)

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.

See also:

parent slice,
check parentage,
slice child

slice is valid (id)

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

dump slice tree (slice)

Defined in the Debugging section.

free slice (handle)

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

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

See also:

free sprite,
free slice children

free slice children (handle)

Frees all the children of a slice, but not the slice itself. See free slice for more details.

See also:

free slice

clone slice (handle, recurse)

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

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.

See also:

get slice extra

get slice extra (handle, extra)

Retrieve an extra data value previously set on a slice handle with set slice extra. extra is a number from 0 to 2 which indicates which extra data field to read.

reparent to npc (handle, 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 set parent(handle, get npc slice(npc)) instead.

reparent to hero (handle, 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 set parent(handle, get hero slice(hero)) instead.

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

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)

Search for an important slice using a lookup code, and return a handle to it, or 0 if it is not found. User defined slice lookup codes are defined in the slice collection editor. You will find them as constants in your .hsi file with sli: prefixes. There are also some special slice lookup codes with names that start with sl: prefixes. 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.

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! You may parent your own slices to these special slices, but moving special slices around is definitely a bad idea.

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 get slice lookup.

You may set parent 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:pathfind dest display)

See also:

set slice lookup,
get slice lookup

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 load hero sprite and create rect. You can move slices elsewhere in the slice tree with set parent. You can use spritelayer together with first child if you want to loop through all your slices without knowing their handles. Another way to get this slice is to use lookup slice: 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)

Returns the lookup code 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 lookup values in plotscr.hsd

See also:

lookup slice,
set slice lookup

set slice lookup (handle, code)

Changes the lookup code of a slice. The first argument is the slice handle, the second is the new lookup code. You can pass false as the second argument to remove a slice's lookup code. This command works with the sli: slice lookup values in your hsi file. It does not work with the sl: special lookup values in plotscr.hsd, nor can it 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.

See also:

lookup slice,
get slice lookup

get hero slice (rank)

Get the slice for a hero walkabout, which is a container slice. The argument is the hero's rank in the walkabout caterpillar. You will not be able to manually reposition this slice (e.g. put slice does not work). The main purpose of getting this slice is so you can access the sprite slice attached to it (use lookup slice(sl:walkabout sprite component, get hero slice(rank)) to get it), or if you want to attach other slices to a hero walkabout.

See also:

hero rank from slice,
get npc slice

hero rank from slice (handle)

The opposite of get hero slice: Given a slice handle, check whether it's the walkabout 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 npc reference from slice 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 find colliding slice), 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.

See also:

get hero slice,
npc reference from slice

get npc slice (npc)

Get the slice for an NPC walkabout, which is a container slice. The argument is the NPC id or an NPC reference. You will not be able to manually reposition this slice (e.g. put slice does not work). The main purpose of getting this slice is so you can access the sprite slice attached to it (use lookup slice(sl:walkabout sprite component, get npc slice(npc)) to get it), or if you want to attach other slices to an NPC.

See also:

npc reference from slice,
get hero slice

npc reference from slice (handle)

The opposite of get npc slice: Given a slice handle, check whether it's the walkabout slice of some NPC, and if so, returns the NPC reference 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 find colliding slice), such as a projectile and another slice, and you want to check whether the projectile hit an NPC, and which one.

See also:

hero rank from slice,
get npc slice

Slices → Slice Sizing

slice width (handle)

Returns the width of any slice, for example a sprite.

See also:

slice height,
set slice width

slice height (handle)

Returns the height of any slice, for example a sprite.

See also:

slice width,
set slice height

set slice width (handle, 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.

See also:

slice width,
set slice height,
set slice size

set slice height (handle, 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.

See also:

slice height,
set slice width,
set slice size

set slice size (handle, width, height)

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.

See also:

set slice width,
set slice height

clamp slice (handle1, handle2)

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.

See also:

slice contains

fill parent (handle, true_or_false)

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.

See also:

is filling parent

is filling parent (handle)

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.

See also:

fill parent

Slices → Positioning Slices

slice x (handle)

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.

See also:

slice y,
set slice x,
slice screen x

slice y (handle)

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.

See also:

slice x,
set slice y,
slice screen y

put slice (handle, X, Y)

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.

See also:

put sprite,
put slice screen,
move slice to

set slice x (handle, 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.

See also:

put slice,
slice x,
set slice y

set slice y (handle, 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.

See also:

put slice,
slice y,
set slice x

slice screen x (handle)

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.

See also:

slice screen y,
slice x

slice screen y (handle)

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.

See also:

slice screen x,
slice y

put slice screen (handle, x, y)

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.

See also:

put slice,
slice screen x,
set slice screen y

set slice screen x (handle, 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.

See also:

put slice screen,
slice screen x,
set slice screen y

set slice screen y (handle, 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.

See also:

put slice screen,
slice screen y,
set slice screen x

Slices → Visibility and Clipping

set slice visible (handle, vis)

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.

set sprite visible

See set slice visible

get slice visible (handle)

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)

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)

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.

Slices → Alignment and Anchor Points

slice edge x (handle, edge)

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

See also:

slice edge y,
set slice edge x,
set slice edge y

slice edge y (handle, edge)

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

See also:

slice edge x,
set slice edge x,
set slice edge y

set slice edge x (handle, edge, value)

Changes the X position of a specific edge of a slice. This is like set slice x, 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!)

See also:

slice edge x,
slice edge y,
set slice edge y

set slice edge y (handle, edge, value)

Changes the Y position of a specific edge of a slice. This is like set slice y, 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!)

See also:

slice edge x,
slice edge y,
set slice edge x

set horiz align (handle, edge)

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.

See also:

set vert align,
set horiz anchor,
set vert anchor,
get horiz align

set vert align (handle, edge)

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.

See also:

set horiz align,
set horiz anchor,
set vert anchor,
get vert align

set horiz anchor (handle, edge)

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.

See also:

set vert align,
set horiz align,
set vert anchor,
get horiz anchor

set vert anchor (handle, edge)

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.

See also:

set vert align,
set horiz align,
set horiz anchor,
get vert anchor

get horiz align (handle)

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

See also:

get vert align,
get horiz anchor,
get vert anchor,
set horiz align

get vert align (handle)

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

See also:

get horiz align,
get horiz anchor,
get vert anchor,
set vert align

get horiz anchor (handle)

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

See also:

get vert anchor,
get horiz align,
get vert align,
set horiz anchor

get vert anchor (handle)

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

See also:

get horiz anchor,
get horiz align,
get vert align,
set vert anchor

realign slice (handle, horiz align, vert align, horiz anchor, vert anchor)

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.

See also:

set horiz align,
set vert align,
set horiz anchor,
set vert anchor

center slice (handle)

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

See also:

realign slice,
set horiz align,
set vert align,
set horiz anchor,
set vert anchor

Slices → Padding

set padding (handle, pixels)

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.

See also:

set top padding,
set left padding,
set right padding,
set bottom padding

get top padding (handle)

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.

See also:

set top padding,
get left padding,
get right padding,
get bottom padding

set top padding (handle, pixels)

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.

See also:

get top padding,
set left padding,
set right padding,
set bottom padding

get left padding (handle)

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.

See also:

set left padding,
get top padding,
get right padding,
get bottom padding

set left padding (handle, pixels)

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.

See also:

get left padding,
set top padding,
set right padding,
set bottom padding

get right padding (handle)

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.

See also:

set right padding,
get top padding,
get left padding,
get bottom padding

set right padding (handle, pixels)

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.

See also:

get right padding,
set top padding,
set left padding,
set bottom padding

get bottom padding (handle)

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.

See also:

set bottom padding,
get top padding,
get left padding,
get right padding

set bottom padding (handle, pixels)

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.

See also:

get bottom padding,
set top padding,
set left padding,
set right padding

Slices → Moving Slices

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

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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

set slice velocity y (handle, pixels per tick, ticks)

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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

get slice velocity x (handle)

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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

get slice velocity y (handle)

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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

set slice velocity (handle, horiz pixels per tick, vert pixels per tick, ticks)

Cause slice handle to start moving. This is similar to using both set slice velocity x and set slice velocity y 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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

stop slice (handle)

Cause slice handle to stop moving. This cancels any previous slice velocity and move slice commands.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

move slice to (handle, x, y, ticks)

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 put slice), it'll continue to move towards the original target in a straight line. Use set slice velocity instead if you don't want this.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

move slice by (handle, relative x, relative y, ticks)

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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

wait for slice (handle)

Cause the script to wait until slice handle has stopped moving. This only applies to commands that operate over time like set slice velocity x or set slice velocity or move slice to or move slice by. There is no reason to use this command for instantaneous slice moving commands like put slice or set slice x or set slice y.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

slice is moving (handle)

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.

See also:

set slice velocity x,
set slice velocity y,
get slice velocity x,
get slice velocity y,
set slice velocity,
stop slice,
move slice to,
move slice by,
wait for slice,
slice is moving

move slice with wallchecking (sl, relative x, relative y, friction%)

Defined in the Wall checking section.

Slices → Moving Around the Slice Tree

Type-specific iteration commands

slice child (handle, number)

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 first child and next sibling to iterate over the children of a slice, rather than this command, when you are moving the children around.

See also:

child count,
parent slice,
first child,
last child

child count (handle)

Returns the number of children that slice handle has.

See also:

slice child,
first child

slice child index (handle)

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

See also:

slice child

first child(handle)

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

See also:

slice child,
first sprite child,
first rect child,
first container child,
last child,
child count

last child(handle)

Returns a slice handle for the last child of a given slice handle. Returns false if the slice has no children.

See also:

slice child,
first child,
child count

next sibling(handle)

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

See also:

previous sibling,
next sprite sibling,
next rect sibling,
next container sibling,
slice child,
free slice,
slice to front,
slice to back,
move slice above,
move slice below

previous sibling(handle)

Returns a slice handle for the previous sibling of a given slice handle, the inverse of next sibling . Returns false if the given slice is the first sibling of its parent. This is useful when looping through slices.

See also:

next sibling,
slice child,
free slice,
slice to front,
slice to back,
move slice above,
move slice below

slice parent

See parent slice

parent slice (handle)

Returns a slice handle for the parent of slice handle, or 0 if handle is the root slice.

See also:

set parent,
check parentage,
slice child

check parentage (handle, parent handle)

Checks to see if handle is a child (or grandchild, or great-grandchild, etc...) of parent handle. Returns true or false.

See also:

parent slice,
set parent

Slices → Moving Around the Slice Tree → Type-specific iteration commands

first child of type(handle, 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 slice type 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.

See also:

first child

next sibling of type(handle, 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 slice type 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.

See also:

next sibling

first container child(handle)

An alias for first child of type(handle, slicetype:container).

next container sibling(handle)

An alias for next sibling of type(handle, slicetype:container).

first rect child(handle)

An alias for first child of type(handle, slicetype:rect).

next rect sibling(handle)

An alias for next sibling of type(handle, slicetype:rect).

first sprite child(handle)

An alias for first child of type(handle, slicetype:sprite).

next sprite sibling(handle)

An alias for next sibling of type(handle, slicetype:sprite).

first text child(handle)

An alias for first child of type(handle, slicetype:text).

next text sibling(handle)

An alias for next sibling of type(handle, slicetype:text).

first ellipse child(handle)

An alias for first child of type(handle, slicetype:ellipse).

next ellipse sibling(handle)

An alias for next sibling of type(handle, slicetype:ellipse).

first grid child(handle)

An alias for first child of type(handle, slicetype:grid).

next grid sibling(handle)

An alias for next sibling of type(handle, slicetype:grid).

first scroll child(handle)

An alias for first child of type(handle, slicetype:scroll).

next scroll sibling(handle)

An alias for next sibling of type(handle, slicetype:scroll).

first select child(handle)

An alias for first child of type(handle, slicetype:select).

next select sibling(handle)

An alias for next sibling of type(handle, slicetype:select).

first panel child(handle)

An alias for first child of type(handle, slicetype:panel).

next panel sibling(handle)

An alias for next sibling of type(handle, slicetype:panel).

Slices → Reordering Slices

slice to front (handle)

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 next sibling 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

See also:

slice to back,
move slice above

slice to back (handle)

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

See also:

slice to front,
move slice below

move slice above (handle, above what handle)

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.

See also:

move slice below,
slice to front,
slice to back,
next sibling

move slice below (handle, below what handle)

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.

See also:

move slice above,
slice to front,
slice to back,
previous sibling

Y sort children (handle)

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.

See also:

sort children

set sort order (handle, 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 sort children 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.

See also:

get sort order

get sort order (handle)

Retrieve the sort order value previously set on a slice handle with get sort order. Note that calling sort children by default resets all the sort order values to zero, unless false is passed as wipe.

sort children (handle, wipe)

Given a slice handle, sort all of its children according to the sort order that you previously set with the set sort order 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 slice to front and slice to back).

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

See also:

set sort order,
get sort order,
Y sort children

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 (like sprite layer), and 'map' slices (which are map layers). However you can use lookup slice 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.

Slices → Slice Types → Checking Slice Type

slice type (handle)

Returns the type of the given slice handle, one of the constants: slicetype:Special, slicetype:Container, slicetype:Rect, slicetype:Sprite, slicetype:Text, slicetype:Map, slicetype:Grid, slicetype:Ellipse, slicetype:Scroll, slicetype:Select, slicetype:Panel, slicetype:Layout.

slice is container (handle)

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)

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)

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 ellipse (handle)

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)

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)

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)

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)

Returns true if the given slice handle is a scroll slcie, or false for any other type. It's an error to provide an invalid handle.

slice is panel (handle)

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)

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.

Slices → Slice Types → Container Slices

create container (width, height)

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.

slice is container (handle)

Defined in the Checking Slice Type section.

Slices → Slice Types → 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.

slice is sprite (handle)

Defined in the Checking Slice Type section.

load sprite (sprite type, num, palette)

Creates a sprite slice by loading a sprite of the given sprite type (use a constant like spritetype:walkabout; see get sprite type 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 free sprite when you are done.

See also:

replace sprite,
load hero sprite,
load small enemy sprite,
load medium enemy sprite,
load large enemy sprite,
load walkabout sprite,
load attack sprite,
load border sprite,
load portrait sprite,
load backdrop sprite,
get sprite type,
get sprite set number,
free sprite

replace sprite (slice, sprite type, num, palette)

Change an existing sprite slice into a different sprite, loading a sprite of the given sprite type (use a constant like spritetype:walkabout; see get sprite type 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 free sprite when you are done.

See also:

load sprite,
replace hero sprite,
replace small enemy sprite,
replace medium enemy sprite,
replace large enemy sprite,
replace walkabout sprite,
replace attack sprite,
replace border sprite,
replace portrait sprite,
replace backdrop sprite,
get sprite type,
get sprite set number,
free sprite

load hero sprite (num, palette)

Loads hero battle sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace hero sprite!

See also:

replace hero sprite,
free sprite

replace hero sprite (handle, num, palette)

Given an existing sprite handle, changes it to hero battle sprite #num with palette palette. As with load hero sprite, 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 free sprite when you are done.

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

See also:

load hero sprite,
free sprite

load walkabout sprite (num, palette)

Loads walkabout sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace walkabout sprite!

See also:

replace walkabout sprite,
free sprite

replace walkabout sprite (handle, num, palette)

Given an existing sprite handle, changes it to walkabout sprite #num with palette palette. As with load walkabout sprite, 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 free sprite when you are done.

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

See also:

load walkabout sprite,
free sprite

load small enemy sprite (num, palette)

Loads small enemy sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace small enemy sprite!

See also:

replace small enemy sprite,
free sprite

replace small enemy sprite (handle, num, palette)

Given an existing sprite handle, changes it to small enemy sprite #num with palette palette. As with load small enemy sprite, 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 free sprite when you are done.

You may use this on any sprite, not just ones loaded with load small enemy sprite.

See also:

load small enemy sprite,
free sprite

load medium enemy sprite (num, palette)

Loads medium enemy sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace medium enemy sprite!

See also:

replace medium enemy sprite,
free sprite

replace medium enemy sprite (handle, num, palette)

Given an existing sprite handle, changes it to medium enemy sprite #num with palette palette. As with load medium enemy sprite, 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 free sprite when you are done.

You may use this on any sprite, not just ones loaded with load medium enemy sprite.

See also:

load medium enemy sprite,
free sprite

load large enemy sprite (num, palette)

Loads large enemy sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace large enemy sprite!

See also:

replace large enemy sprite,
free sprite

replace large enemy sprite (handle, num, palette)

Given an existing sprite handle, changes it to large enemy sprite #num with palette palette. As with load large enemy sprite, 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 free sprite when you are done.

You may use this on any sprite, not just ones loaded with load large enemy sprite.

See also:

load large enemy sprite,
free sprite

load attack sprite (num, palette)

Loads attack battle sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace attack sprite!

See also:

replace attack sprite,
free sprite

replace attack sprite (handle, num, palette)

Given an existing sprite handle, changes it to attack battle sprite #num with palette palette. As with load attack sprite, 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 free sprite when you are done.

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

See also:

load attack sprite,
free sprite

load weapon sprite (num, palette)

Loads weapon battle sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace weapon sprite!

See also:

replace weapon sprite,
free sprite

replace weapon sprite (handle, num, palette)

Given an existing sprite handle, changes it to weapon battle sprite #num with palette palette. As with load weapon sprite, 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 free sprite when you are done.

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

See also:

load weapon sprite,
free sprite

load border sprite (num, palette)

Loads border battle sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace border sprite!

See also:

replace border sprite,
free sprite

replace border sprite (handle, num, palette)

Given an existing sprite handle, changes it to border battle sprite #num with palette palette. As with load border sprite, 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 free sprite when you are done.

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

See also:

load border sprite,
free sprite

load portrait sprite (num, palette)

Loads portrait battle sprite #num with palette palette, and returns a handle. You may omit palette, in which case the default palette for that sprite will be loaded. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace portrait sprite!

See also:

replace portrait sprite,
free sprite

replace portrait sprite (handle, num, palette)

Given an existing sprite handle, changes it to portrait battle sprite #num with palette palette. As with load portrait sprite, 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 free sprite when you are done.

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

See also:

load portrait sprite,
free sprite

load backdrop sprite (num)

Loads backdrop #num as a sprite, and returns a handle. You must free it with free sprite when you are done.

If you want to replace an existing sprite (or other slice) either use free sprite first, or use replace backdrop sprite!

See also:

show backdrop,
replace backdrop sprite,
free sprite

replace backdrop sprite (handle, num)

Given an existing sprite handle, changes it to backdrop #num. You must free it with free sprite 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 free sprite when you are done.

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

See also:

load backdrop sprite,
free sprite

free sprite (handle)

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 free slice, 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.

See also:

free slice,
load hero sprite

clone sprite (handle)

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 sprite layer 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 free sprite 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 clone slice command instead.

See also:

free sprite,
clone slice

put sprite (handle, x, y)

Moves sprite handle to position (x, y). This can only be used on sprites, use put slice in general.

place sprite

See put sprite

get sprite type (handle)

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

See also:

get sprite set number,
get sprite palette,
get sprite frame

set sprite set number (handle, record)

Changes the record number of the spriteset of a sprite slice handle.

See also:

get sprite set number,
set sprite palette,
set sprite frame

get sprite set number (handle)

Gets the record number of the spriteset of a sprite slice handle.

See also:

get sprite type,
get sprite palette,
get sprite frame

set sprite palette (handle, num)

Changes the palette of sprite slice handle to be num. If num is -1 or omitted, the default palette for that sprite is loaded.

See also:

get sprite palette

get sprite palette (handle)

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

See also:

get sprite type,
get sprite set number,
get sprite frame

get sprite default pal (handle)

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.

See also:

get sprite palette,
set sprite palette

set sprite frame (handle, num)

Changes the frame of sprite slice handle to be num.

See also:

get sprite frame

get sprite frame (handle)

Returns the current frame number of sprite slice handle.

See also:

get sprite type,
get sprite palette,
get sprite set number

sprite frame count (handle)

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)

Flips a sprite slice handle horizontally. You can also unflip a previously flipped sprite using horiz flip sprite(handle, false)

See also:

vert flip sprite,
sprite is horiz flipped

vert flip sprite (handle, flip)

Flips a sprite slice handle vertically. You can also unflip a previously flipped sprite using vert flip sprite(handle, false)

See also:

horiz flip sprite,
sprite is vert flipped

sprite is horiz flipped (handle)

Returns true if a sprite slice handle is flipped horizontally, or false if it is not.

See also:

horiz flip sprite,
sprite is vert flipped

sprite is vert flipped (handle)

Returns true if a sprite slice handle is flipped vertically, or false if it is not.

See also:

vert flip sprite,
sprite is horiz flipped

get sprite trans (handle)

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.

See also:

set sprite trans

set sprite trans (handle, drawtransparent)

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.

See also:

get sprite trans

dissolve sprite (handle, dissolve type, total ticks, start tick, backwards, automatic)

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

See also:

cancel dissolve,
sprite is dissolving,
wait for dissolve

cancel dissolve (handle)

If a sprite slice handle is currently dissolving, cancel the dissolve animation, restoring the sprite to normal.

See also:

dissolve sprite,
sprite is dissolving,
wait for dissolve

sprite is dissolving (handle)

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.

See also:

cancel dissolve,
sprite is dissolving,
wait for dissolve

wait for dissolve (handle)

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.

See also:

cancel dissolve,
sprite is dissolving,
wait for dissolve

Slices → Slice Types → Rect Slices

create rect (width, height, style)

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 set parent

slice is rect (handle)

Defined in the Checking Slice Type section.

get rect style (handle)

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 set rect fgcol, set rect bgcol, set rect border or set rect raw border commands causes this command to return -1.

See also:

set rect style

set rect style (handle, 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.

See also:

get rect style,
set rect fgcol,
set rect bgcol,
set rect border

get rect bgcol (handle)

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.

See also:

set rect bgcol,
get rect fgcol

set rect bgcol (handle, color)

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.

See also:

get rect bgcol,
set rect fgcol

get rect fgcol (handle)

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.

See also:

set rect fgcol,
get rect bgcol

set rect fgcol (handle, color)

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.

See also:

get rect fgcol,
set rect bgcol

get rect border (handle)

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 get rect raw border to find out which it is).

See also:

set rect border,
get rect raw border

get rect raw border (handle)

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 set rect style or set rect border), then this command returns the actual box border spriteset instead of the box style number.

See also:

set rect raw border,
get rect border

set rect border (handle, 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 set rect style and set rect raw border.

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 set rect raw border.

See also:

get rect border,
set rect raw border

set rect raw border (handle, 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 set rect style and set rect border.

See also:

get rect raw border,
set rect border

get rect trans (handle)

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 get rect fuzziness), trans:hollow if it is fully transparent, or trans:solid (equal to false) if it is drawn solid.

See also:

set rect trans,
get rect fuzziness

set rect trans (handle, transparency setting)

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 set rect fuzziness, which provides much finer control of rectangle slice transparency/translucency.

See also:

get rect trans,
set rect fuzziness

get rect fuzziness (handle)

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 set rect trans default to 50% translucency.

See also:

set rect trans,
get rect trans,
set rect fuzziness

set rect fuzziness (handle, percent)

Sets the percentage translucency of a rect slice handle to percent. A percent of 0 is equivalent to set rect trans(handle, trans:hollow), a percent of 100 is equivalent to set rect trans(handle, trans:opaque), and anything in between 1 and 99 implicitly does set rect trans(handle, trans:fuzzy) as well as setting the percentage.

See also:

set rect trans,
get rect trans,
get rect fuzziness

Slices → Slice Types → Ellipse Slices

create ellipse (width, height, border color, fill color)

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 set parent

slice is ellipse (handle)

Defined in the Checking Slice Type section.

get ellipse border col (handle)

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.

See also:

set ellipse border col,
get ellipse border col,
set ellipse fill col,
get ellipse fill col

set ellipse border col (handle, color)

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.

See also:

set ellipse border col,
get ellipse border col,
set ellipse fill col,
get ellipse fill col

get ellipse fill col (handle)

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

See also:

set ellipse border col,
get ellipse border col,
set ellipse fill col,
get ellipse fill col

set ellipse fill col (handle, color)

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

See also:

set ellipse border col,
get ellipse border col,
set ellipse fill col,
get ellipse fill col

Slices → Slice Types → Text Slices

create text

Creates a new blank text slice and returns a handle to it. A text slice holds a string of text, but it can be positioned and handled just like any other slice. Use the set slice text command to copy a string into the text slice.

See also:

set slice text

slice is text (handle)

Defined in the Checking Slice Type section.

set slice text(handle, string id)

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.

See also:

create text,
get slice text

get slice text(string id, slice handle)

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.

See also:

create text,
set slice text

get text color(handle)

Given a text slice handle, returns the current color of the text.

See also:

set text color

set text color(handle, color)

Given a text slice handle, change color used to display the text.

See also:

get text color

get text bg(handle)

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.

See also:

get text color,
set text bg

set text bg(handle, color)

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.

See also:

get text bg,
set text color

get outline(handle)

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.

See also:

set outline

set outline(handle, 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.

See also:

get outline

get wrap(handle)

Given a text slice handle, true if the text slice is configured to wrap, or false if it is configured not to wrap.

See also:

set wrap

set wrap(handle, 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.

See also:

get wrap

Slices → Slice Types → Grid Slices

create grid (width, height, rows, columns)

Creates a new grid slice, and returns an handle 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.

slice is grid (handle)

Defined in the Checking Slice Type section.

set grid columns (handle, 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.

See also:

get grid columns,
set grid rows,
get grid rows

get grid columns (handle)

Returns the number of columns in a grid slice.

See also:

set grid columns,
set grid rows,
get grid rows

set grid rows (handle, 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.

See also:

set grid columns,
get grid columns,
get grid rows

get grid rows (handle)

Returns the number of rows in a grid slice.

See also:

set grid columns,
get grid columns,
set grid rows

show grid (handle, shown)

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 set slice visible.

See also:

grid is shown

grid is shown (handle)

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 get slice visible.

See also:

show grid

Slices → Slice Types → Select Slices

create select (width, height)

Creates a new select slice, and returns an handle 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.

slice is select (handle)

Defined in the Checking Slice Type section.

set select slice index (handle, 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.

See also:

get select slice index

get select slice index (handle)

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.

See also:

set select slice index

Slices → Slice Types → Scroll Slices

create scroll (width, height)

Creates a new scroll slice, and returns an handle 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.

slice is scroll (handle)

Defined in the Checking Slice Type section.

set scroll bar style (handle, 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.

See also:

get scroll bar style

get scroll bar style (handle)

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.

See also:

set scroll bar style

set scroll check depth (handle, 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.

See also:

get scroll check depth

get scroll check depth (handle)

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.

See also:

set scroll check depth

scroll to child (parent, child)

Causes all the children of the parent slice to be scrolled until the screen position of the child slice fits inside the parent.

This is mainly intended for scroll slices, such as those created with the create scroll 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 may be unaffected.)

Slices → Slice Types → 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)

Creates a new panel slice, and returns an handle 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.

slice is panel (handle)

Defined in the Checking Slice Type section.

get panel is vertical (handle)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Given a panel slice handle, changes the number of pixels of padding that the panel will leave between the primary and secondary children.

Slices → Slice Types → 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 lookup slice 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 is map layer (handle)

Defined in the Checking Slice Type section.

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

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 mouse pixel X and mouse pixel Y (but can also be off the screen).

Unlike slice at pixel, this command ignores slice clipping.

See also:

slice collide

slice collide (handle1, handle2)

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.

See also:

slice collide point,
slice contains

slice contains (handle1, handle2)

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.

See also:

slice collide

slice at pixel (parent, x, y, number, check descendants, visible only)

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

See also:

slice collide point,
find colliding slice,
menu item at pixel

find colliding slice (parent, slice, number, check descendants, visible only)

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 sprite layer 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 get count 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).
This command never returns Special slices, such as the sprite layer 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.

See also:

slice at pixel,
slice collide

move slice with wallchecking (sl, relative x, relative y, friction%)

Defined in the Wall checking section.

Tweaking Maps → Tilemap and Wallmap

Tile Animations
Wall checking

read map block (x,y,layer)

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.

See also:

current display tile

write map block (x,y,value,layer)

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 pass block (x,y)

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 = north wall
bit 2 = east wall
bit 4 = south wall
bit 8 = west wall
bit 16 = vehicle A
bit 32 = vehicle B
bit 64 = harm tile
bit 128 = overhead tile

To check the value of a specific bit, use the and operator. For example:

  variable (pass)
  pass := read pass block(hero X(me),hero Y(me))
  if (pass,and,harm tile) then (
    # this checks if the hero is standing
    # on a harm tile
  )

See also:

check wall collision x/y

write pass block (x,y,value)

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 = north wall
bit 2 = east wall
bit 4 = south wall
bit 8 = west wall
bit 16 = vehicle A
bit 32 = vehicle B
bit 64 = harm tile
bit 128 = overhead tile

You can add the constants together. 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

Tweaking Maps → Tilemap and Wallmap → Tile Animations

current display tile (tile number, layer)

Returns the tile number from the tileset, in the range 0-159, that a given tile (read with read map block, 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)

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 read map block. 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.

See also:

current display tile

get tile animation offset (animation pattern, layer)

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.

See also:

read map block,
animation start tile

set tile animation offset (animation pattern, offset, layer)

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.

Tweaking Maps → Tilemap and Wallmap → Wall checking

read pass block (x,y)

Defined in the Tilemap and Wallmap section.

check hero wall (who,direction)

Defined in the Moving Heroes section.

check NPC wall (who, direction)

Defined in the Moving NPCs section.

check wall collision x (x, y, width, height, relative x, relative y, friction%)

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 move slice with wallchecking 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 check hero wall 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.

move slice with wallchecking 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.

See also:

move slice with wallchecking,
find colliding slice

move slice with wallchecking (sl, relative x, relative y, friction%)

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 (slice screen x, 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 north wall, south wall, east wall, west wall 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 north wall, south wall, east wall, west wall. That's because the slice isn't actually resting against any walls, although it stopped! Use ==, not and, to check for these values.
You can check for walls without needing a slice using the alternative check wall collision x/y 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

See also:

check wall collision x/y,
find colliding slice

Tweaking Maps → Zonemaps

write zone (zone id, x, y, value)

Sets whether the tile at (x,y) is part of the specified zone. zone id is a valid ID number (see read zone), 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).

See also:

read zone

read zone (zone id, x, y)

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.

See also:

write zone,
zone at spot

zone at spot (x, y, count)

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

See also:

read zone

get zone name (string id, zone id)

Places in the string with id number string id the name of zone zone id.

get zone extra (zone id, extra num)

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)

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)

Given a zone id (from 1 to 9999 or a special id), returns the number of tiles that the zone contains.

Tweaking Maps → General Map Settings

allow minimap (setting)

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.

See also:

show mini map

allow save anywhere (setting)

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.

See also:

save menu

set harm tile damage (amount)

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)

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)

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

Returns the map's foot offset.

draw NPCs above heroes (setting)

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)

Sets the behaviour at the edge of the map. Use the constants crop, wrap and default tile. 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

Returns the map's edge mode. Use the constants crop, wrap and default tile to compare with the value returned.

Tweaking Maps → Map State

save map state (whichdata, customid)

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 load map state. 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 temporary map state data previously saved either by save map state 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 save map state 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)

Reloads original unaltered map data from the RPG file. whichdata is a set of bits in the save map state 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 delete map state to remove them if wanted.

delete map state (whichdata)

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 save map state format to determine what exactly to delete. The default is mapstate:all.

General Game Settings → 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 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

Returns true if active-time battles are configured to pause on all menus.

See also:

set active battle pause on all menus

set active battle pause on all menus (value)

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.

See also:

get active battle pause on all menus

hide battle ready meter (state)

Sets whether or not the ready meter appears in battle. If the argument is off then the ready meter appears. If the argument is on then the ready meter will be hidden.

hide battle health meter (state)

Sets whether or not the health meter appears in battle. If the argument is off then the health meter appears. If the argument is on then the health meter will be hidden.

set dead heroes gain experience (state)

Sets whether or not dead heroes gain experience from battles. If the argument is off then only living heroes gain experience. If the argument is on then dead heroes get it too.

General Game Settings → Caps

get damage cap

Returns the current damage cap, or 0 if there is none.

set damage cap (cap)

Sets the current damage cap to cap. Use 0 for no cap.

get level cap

Returns the current level cap.

set level cap (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, give experience, or set experience, and the status screen doesn't show their experience to next level. You however can use set hero level 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

load menu (reallyload, show new game)

Defined in the Opening Built-in Menus section.

autosave

Transparently saves the game to the last save slot saved to in the save menu, or if the game has not been saved yet, calls save menu. Returns the number of the last save slot, or if the user cancelled the save menu, returns false.

See also:

last save slot

save in slot (slot)

Saves in the specified save slot (1 to 32, 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 save slot used. To display the save game menu instead, use save menu.

load from slot (slot, args...)

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 32, (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

See also:

load menu,
save in slot,
save slot used,
last save slot,
reset game

delete save (slot)

Deletes a saved game in the specified save slot (1 to 32, 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 load from slot. However, import globals can still be used to read globals out of the slot.

See also:

save in slot

last save slot

Returns the last save slot saved to using the save menu, if the player hasn't saved the game since starting/loading the game. Otherwise, returns the save slot the game was loaded from, or false if this is an unsaved new game. Save slots are numbered starting at 1. save in slot does not change the value returned by this command! If you need it to, you need to track it with a global variable.

See also:

save in slot,
save menu

save slot used (slot)

Returns whether a game has been saved in the save slot. Use if you, for example, don't want to overwrite a saved game with save in slot. This returns false if the slot has never been saved to normally, but has been written to using export globals (which will create a nearly-empty .rsav file containing just globals, if it doesn't already exist).

send email (save slot, subject string id, message string id)

Defined in the Debugging section.

get load script

Defined in the Script Triggers section.

set load script (id)

Defined in the Script Triggers section.

import globals (slot, first, last)

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 32. 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. 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 export globals 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, 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

See also:

export globals,
read global

export globals (slot, first, last)

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 32, 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 16383. 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, however you will still be able to read them with import globals.

Unlike importglobals, 'export globals (slot, first)' does NOT export a single global variable!

See also:

import globals,
write global

Advanced Functions → Debugging

trace (string)

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 trace value 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, ...)

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

See also:

assert,
dump slice tree

dump slice tree (slice)

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 script error at the exact moment you want to check the slice tree; you can then enter the slice debugger from the Script Error menu.

See also:

trace value,
script error

script error (string id)

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

See also:

assert,
trace value,
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.

See also:

script error,
show mini map

assert (expression)

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

See also:

script error,
trace value

get script name (string id, script id)

Fetches the name of a script given its ID 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)

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.

See also:

get script name

send email (save slot, subject string id, message string id)

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 save in slot 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 trace value. 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.

Predefined Constants

Numeric Constants

PLOTSCR.HSD defines 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

zero

See Numeric Constants

one

See Numeric Constants

two

See Numeric Constants

three

See Numeric Constants

four

See Numeric Constants

five

See Numeric Constants

six

See Numeric Constants

seven

See Numeric Constants

eight

See Numeric Constants

nine

See Numeric Constants

ten

See Numeric Constants

Key Constants

PLOTSCR.HSD defines constants that correspond to each of the usable keys (or joystick buttons) that the player can press while playing. These are useful with the wait for key command.
any key, up key, down key, left key, right key, use key, menu key, cancel key

any key

See Key Constants

up key

See Key Constants

down key

See Key Constants

left key

See Key Constants

right key

See Key Constants

use key

See Key Constants

menu key

See Key Constants

cancel key

See Key Constants

Boolean Constants

PLOTSCR.HSD defines constants for 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

true

See Boolean Constants

false

See Boolean Constants

on

See Boolean Constants

off

See Boolean Constants

Direction Constants

PLOTSCR.HSD defines constants for each of the four directions. These constants are useful for commands such as walk hero and walk NPC, which take a direction as an argument.
north, south, east, west, up, down, right, left

north

See Direction Constants

south

See Direction Constants

east

See Direction Constants

west

See Direction Constants

up

See Direction Constants

down

See Direction Constants

right

See Direction Constants

left

See Direction Constants

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 is a constant that means the same as zero.

autonumber

autonumber is a constant that is used as the ID number in old-style define script commands. This is not needed anymore. Use script instead.

current stat

A constant for use with the get hero stat, set hero stat, set capped hero stat and get level MP 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 set hero stat. Both maximum and current values of a stat are normally limited to the stat cap.

maximum stat

A constant for use with the get hero stat, set hero stat, set capped hero stat and get level MP 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 current stat for more information. Both maximum and current values of a stat are normally limited to the stat cap.

base stat

A constant for use with the get hero stat, set hero stat and set capped hero stat 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

A constant used in the get hero picture, set hero picture, get hero palette, set hero palette, reset hero picture and reset hero palette commands to represent the battle graphics.

outside battle

A constant used in the get hero picture, set hero picture, get hero palette, set hero palette, reset hero picture and reset hero palette commands to represent the walkabout graphics.

hero portrait

A constant used in the get hero picture, set hero picture, get hero palette, set hero palette, reset hero picture and reset hero palette commands to represent the hero's portrait graphics.

Color Constants

PLOTSCR.HSD defines constants for each of the three primary colors. These are used in commands like read color or write color
color:red, color:green, color:blue

color:red

See Color Constants

color:green

See Color Constants

color:blue

See Color Constants

Mouse Constants

PLOTSCR.HSD defines constants for use with the mouse functions. They're used the mouse button command.
left button, right button

left button

See Mouse Constants

right button

See Mouse Constants

get count

When passed to NPC at pixel, NPC at spot, slice at pixel, find colliding slice or zone at spot they return the number of NPCs, slices or zones at that spot. With spells learned returns the number of spells a hero learnt. With find enemy in formation, returns the number of enemies, or the number of some kind of enemy in the formation.

Tile Constants

PLOTSCR.HSD defines constants for use with functions like read pass block or write pass block.
north wall, east wall, south wall, west wall, vehicle A, vehicle B, harm tile, overhead tile

north wall

See Tile Constants

east wall

See Tile Constants

west wall

See Tile Constants

south wall

See Tile Constants

vehicle A

See Tile Constants

vehicle B

See Tile Constants

harm tile

See Tile Constants

overhead tile

See Tile Constants

crop

A constant used in set map edge mode which makes the edges of the map impassible and prevents the camera from scrolling off them.

wrap

A constant used in set map edge mode which lets the player walk over the edge of the map around to the opposite side.

default tile

A constant used in set map edge mode which makes the edges of the map impassible and displays a specified tile everywhere off the edge of the map.

party

Pass as first argument to give experience to divide the experience between all the live heroes in the battle (active) party.

x axis

Pass to joystick axis to specify the X axis (left and right).

y axis

Pass to joystick axis to specify the Y axis (up and down).

timer: default

Pass to set timer to leave one of the parameters at its default setting. Valid for any parameter except id

timer: game over

Pass to set timer in the trigger field to have the game end when the timer runs out.

timer flag: critical

Pass to set timer in the flags field to indicate that if the timer runs out during a battle, it should end the battle immediately.

timer flag: battle

Pass to set timer in the flags field to indicate that the timer should run during battle. Otherwise, the timer will be paused during battle.

timer flag: menu

Pass to set timer 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

Used with set formation song and get formation song to indicate an enemy formation without music. Used by set ambient music and get ambient music for a silent map.

song: same as last map

Used with set formation song and get formation song to indicate an enemy formation which uses the same music as the map. Used by set ambient music and get ambient music for a map that continues with the last map's music.

song: same as map

See song: same as last map

Stats: There are 825 commands and 75 constants in this file, of which 58 are only references to other entries.

This file was generated from an XML file. The contents were painstakingly transcribed by Mike Caron from the original Plotscripting Dictionary, which was created by James Paige.

Plotscripting Dictionary

For OHRRPGCE version etheldreme

Commands by Category

Alphabetical Index

Declarations

plotscript, name, argumentnames (statements)

script, name, argumentnames (statements)

subscript, name, argumentnames (statements)

global variable (id,name)

variable (name)

define constant (number,name)

include, filename

Math, Comparison, and Logic Operators

number + number

number -- number

number * number

number / number

number,mod,number

number ^ power

abs (number)

sign (number)

sqrt (number)

number == number

number <> number

number < number

number > number

number <= number

number >= number

value,and,value

value,or,value

value,xor,value

value && value

value || value

value ^^ value

not (value)

random (lownumber, highnumber)

seed random (new seed)

Math, Comparison, and Logic Operators → Working with Variables

variable := value

increment (variable,amount)

decrement (variable,amount)

read global (id)

write global (id,value)

Flow Control

begin,other commands,end

end

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

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

then

else

while(condition) do(commands)

do

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

return(value)

exit returning(value)

exit script

break

continue

switch(expression)

case(value)

Wait Commands

wait (ticks)

wait for text box

wait for menu (menu handle)

wait for hero (who)

wait for key (key)

wait for scancode (key)

wait for NPC (who)

wait for camera

wait for all

wait for slice (handle)

wait for dissolve (handle)

wait for sound (num)

Working with Tags

set tag (tag,value)

check tag (tag)

set onetime (onetime,value)

check onetime (onetime)

Suspend and Resume

suspend player