<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="htmlplot.xsl"?>

<!DOCTYPE plotscript [
	<!ELEMENT plotscript (title,introduction?,section+)>
	<!ATTLIST plotscript version CDATA "wip" datecode CDATA "???">
	<!ATTLIST plotscript show-alias CDATA "yes">
	<!ELEMENT title         (#PCDATA)>
	<!ELEMENT introduction  ANY>
	<!ELEMENT section (description?,(command|reference|gloss|section)+)>
	<!ATTLIST section title CDATA #REQUIRED constants (yes|no) #IMPLIED topics (yes|no) #IMPLIED>
	<!ELEMENT reference EMPTY>
	<!ATTLIST reference ref IDREF #REQUIRED>
	<!ELEMENT command ((canon+,shortname,altcommand*,added?,deprecated?,description,altcommand*,example*,seealso?) |
					   (alias,shortname,added?,deprecated?))>
	<!ATTLIST command id ID #REQUIRED>
	<!ELEMENT gloss ((canon,shortname?,description) |
					   (alias,shortname))>
	<!ATTLIST gloss id ID #REQUIRED>
	<!ELEMENT altcommand (canon*,shortname)>
	<!ATTLIST altcommand id ID #IMPLIED show-alias CDATA "yes"  alias (show|hide) "show">
	<!ELEMENT canon      (#PCDATA)>
	<!ELEMENT shortname   (#PCDATA)>
	<!ELEMENT added     (#PCDATA)>
	<!ELEMENT deprecated     (#PCDATA)>
	<!ELEMENT description ANY>
	<!ELEMENT example     (#PCDATA)>
	<!ATTLIST example c IDREF #IMPLIED>
	<!ELEMENT alias       (#PCDATA)>
	<!ELEMENT seealso (ref+)>

	<!ELEMENT note         ANY>
	<!ELEMENT warn         ANY>
	<!ELEMENT danger       ANY>
	<!ELEMENT ref          (#PCDATA)>
	<!ELEMENT secref       (#PCDATA)>
	<!ELEMENT ul           (li*)>
	<!ELEMENT li           ANY>
	<!ELEMENT a            ANY>
	<!ATTLIST a            href CDATA #IMPLIED>
	<!ELEMENT lb           (#PCDATA)>
	<!ELEMENT p            (#PCDATA)>
	<!ELEMENT tt           ANY>
	<!ELEMENT b            (#PCDATA)>
]>
<!--

DOCUMENTATION FOR THIS XML FILE:

This markup (hereby refered to as PDL (Plotscript Dictionary Language)) is
designed to reduce the time spent maintaining the Plotscripting Dictionary, and
to enable easier porting to other formats.

The root element is the <plotscript> element. It has 'version' and 'datecode'
attributes telling the engine version it applies to. These are set automatically
by docs/update-html.sh (which is called by release/release-docs.sh).

In <plotscript>, there is a series of <section> elements, each with a title
attribute. These are to group the plotscripting commands into logical groups,
such as <section title="Wait Commands"> or <section title="Math Operators">.
Sections can be nested inside each other. And commands that appear after
a subsection will be reorderd in front of all subsections.

The heart of the PDL are the <command> elements inside the <section>s. It has a
single attribute, id. This is essentially the whitespace stripped version of the
command (the "wait for text box" command would have an id of "waitfortextbox").
This is used to uniquely identify each command for linking or cross-linking.
Similiar to <command> is <gloss>, for glossary items.

Inside the <command> element are subelements, in this order:
Case 1: Full command definition
  <canon>*      - This is the "canonical" form of the command: the fully spaced
                  command with parameter prototypes. Can appear multiple times to
		  show alternative arg lists; only the first is shown in command
		  indexes. (Use <altcommand> instead for aliases). Example:
		  <canon>import globals (slot, first, last)</canon>
                  <canon>import globals (slot, id)</canon>
  <shortname>   - This is the short version of the command, used for crosslinking,
                  indexes, etc. It is the <canon> element, minus the parameters.
                  Example: import globals
  <altcommand>* - This defines an alias to the command which is documented
                  together with it, but which appears separately in command
		  indexes (if it contains a <canon>) and can be linked to
		  separately. Must have an id="..." attribute and <shortname>
		  subelement, and usually has one or more <canon>s. If there's no
		  canon then <shortname> is used for links but no 'canon' line
		  appears in the command definition.
		  "Alias:" is displayed before the command, unless you add
		  alias="hide".
  <added>       - Version this was added in. Not used!
  <deprecated>  - Version this was deprecated in. Not used!
  <description> - This is a paragraph (or more) of text describing what the
                  command does, and how to use it. Use <lb/> to put paragraphs
                  in, and <p></p> when referring to a parameter (to avoid user
                  confusion). No HTML is allowed (at this time).
                  You can also embed <example> blocks inside <description> blocks
                  instead of having them trail afterwards. Example: Well, it
                  would be pretty long...
  <example>*    - Finally, commands may  have some sort of example usage of the
                  the command. You can put this inside <description> instead;
		  that way you can put more text after/between the example(s).
                  It will be displayed in a mono-space font suitable for code.
                  But, be sure to format it properly:
                  Example:
                  <example># first example line has no line-break
# the second (and more) lines should have no indentation
# and so forth</example>
                  The <example> tag can have a c="..." attribute to reuse an
		  example from another command.


As an alternative to <altcommand> you can also define aliases which have
separate entries. This is probably mainly useful for obsolete aliases which
you want to hide in a different section:

Case 2: Alias command definition
  <alias>       - If a command is an alias to another command (or is so closely
                  related that they're in the same entry, use the <alias> element. Put
                  the ID of the real command in here. Example: begin
  <shortname>   - Aliases also need a short name, since they are technically
                  different from their alias. Example: end

Additionally, if you want a command to appear in multiple sections,
define it once and place references to it elsewhere.
  <reference>   - Has a single attribute, 'ref', and no contents.

A <gloss> is like a <command> but styled differently, and not supporting most of the
same subelements. It can be placed in any section, if there's a reason to not put it
in the dedicated Glossary section. It can be an alias to another <gloss>
Case 1: Normal <gloss> subelements:
  <canon>       - The title of the glossary entry.
  <shortname>?  - Optional, this is text to use in cross-links. The canon is used
                  by default.
  <description> - Defines the term. See <command> above for available subelemnts.

Case 2: Alias <gloss> subelements:
  <alias>       - If two term are synonymous, use the <alias> element. Put
                  the ID of the real gloss entry in here.
  <shortname>   - The name/title of the term.

Basically, you should be able to examine the entries that already exist. It's
fairly self evident what everything does.

If you have xmllint installed you can run update-html.sh and it'll tell you
about all kinds of critical errors that your web browser will probably silently
ignore by throwing away what it doesn't understand.


These are cut-and-paste copies of <command> elements, so you don't have to type
everything out 10000000000 times. They are also indented properly for this file.

#===== Full description

		<command id="">
			<canon></canon>
			<shortname></shortname>
			<description></description>
			<example></example>
		</command>

#===== Full description with borrowed example

		<command id="">
			<canon></canon>
			<shortname></shortname>
			<description></description>
			<example c="">
		</command>

#===== Alias

		<command id="">
			<alias></alias>
			<shortname></shortname>
		</command>

#===== Reference

		<reference ref="" />

#=====

Which reminds me: Indentation. For each "level" you go down in the hierarchy,
you indent once. Many code specific editors will maintain this indentation level
for until you explicitly change it, so it isn't difficult. Notepad users will
have to do it manually, but you MUST do it. Remember: 1 indent = 1 tab.
(However, subsections are not indented, in order to keep all commands at the
same level.)

"Mono means 'one'. Rail means 'rail'. And that concludes our training."
	~ Monorail guy, Simpsons

-->
<plotscript version="wip" datecode="2026-02-16">
	<title>
		Dictionary of Plotscripting Commands
	</title>
	<introduction>
		This is the documentation for all <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Plotscripting">plotscripting</a> commands.
		In addition to reading this document, we also recommend you check out the
		<a href="https://rpg.hamsterrepublic.com/ohrrpgce/Plotscripting_Tutorial">Plotscripting Tutorial</a>
		and the <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Plotscripting">Plotscripting</a>
		article on the wiki.
		<lb/>
		If you're reading this on the <a href="https://rpg.hamsterrepublic.com/ohrrpgce/">OHRRPGCE website</a>
		then make sure you're looking at the page for the latest stable release
		(<a href="http://hamsterrepublic.com/ohrrpgce/docs/plotdictionary.html">here</a>)
		or latest nightly version
		(<a href="http://hamsterrepublic.com/ohrrpgce/nightly/docs/plotdictionary.html">here</a>).
		This documentation is also included as an HTML file with downloads of the engine.
	</introduction>

	<section title="Declarations">
		<command id="plotscript">
			<canon>plotscript, name, argumentnames (statements)</canon>
			<shortname>plotscript</shortname>
			<description>
				The plotscript command contains a list of commands that can be triggered directly by an event in your game.
				<lb/>
				Plotscript starts with the keyword plotscript, a comma, and then the name of the plotscript.
				If there are any arguments to the script, you list their names separated by commas after the name of
				the script, optionally with default values declared like <tt>arg = defaultvalue</tt>.
				<lb/>
				Then comes the text of the script.
				It is enclosed in <ref>begin</ref> and <ref>end</ref> statements.
				Scripts that are defined as plotscripts can be called directly from "trigger" events in your game,
				or by name within other scripts.
				<note>
					What's the difference between <p>plotscript</p> and <ref>script</ref>?
					<lb/>
					The only difference is that plotscripts are listed in the game editor,
					allowing them to be attached to triggers
					(such as the new-game script),
					while plain <tt>script</tt>s are hidden and can't be selected.
					(Technically you can use a <tt>script</tt> as a trigger,
					but only by using a command like <ref>setdeathscript</ref>.)
				</note>
			</description>
			<example># example of a simple script
plotscript, my first script, begin
	# commands go here
end</example>
			<example># Example of a plotscript with arguments.
# Attach this to an NPC script to run when the player activates the NPC
plotscript, walk npc north, npc, scriptarg, begin
	# Commands go here, and they can use the arguments npc (an NPC
	# reference) and scriptarg (set in the NPC editor).

	# E.g. walk north by "scriptarg" tiles.
	walk npc (npc, north, scriptarg)
end</example>
		</command>
		<command id="script">
			<canon>script, name, arguments (statements)</canon>
			<shortname>script</shortname>
			<description>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 <ref>begin</ref> and <ref>end</ref> 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 <ref>plotscript</ref>.</description>
			<example># example of a simple script
script, my first script, begin
	# commands go here
end</example>
			<example># Example of a script with arguments: one required and two with defaults.
# It can called with 1, 2, or 3 arguments (just fe, fe and fi, or all three).
script, my fancy script, fe, fi=0, fo=0, begin
	# Commands go here,
	# and they can use the arguments fe, fi, and fo
	# that where passed to the script.
end</example>
		</command>
		<command id="subscript">
                  
			<canon>subscript, name, argumentnames (statements)</canon>
			<shortname>subscript</shortname>
			<description><p>subscript</p> is just like <ref>script</ref> except that it must placed inside another script (or even inside another subscript). See <ref>script</ref> 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.</description>
			<example># 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</example>
		</command>
		<command id="globalvariable">
			<canon>global variable (id,name)</canon>
			<shortname>global variable</shortname>
			<description>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 <ref>variable</ref></description>
			<example># any script can read and set the value of a global
global variable(1,mini game score)</example>
		</command>
		<command id="variable">
			<canon>variable (name)</canon>
			<shortname>variable</shortname>
			<description>
				Creates a local variable that can only be used inside the script where it was created (and any <ref>subscript</ref>s).
				The value of this variable is lost when the script ends.
				If you need a variable whose value persists between calls to a script,
				or that is automatically saved when the player saves their game,
				you will need to use a <ref>globalvariable</ref> instead.
			</description>
			<example>variable(points) # Make a new variable
points := 10  # Set its starting value
points += 1   # Add one to it</example>
		</command>
		<command id="defineconstant">
			<canon>define constant (number,name)</canon>
			<shortname>define constant</shortname>
			<description>
				Creates a global constant.
				The first argument is the number that the constant will represent, and the second argument is the name of the constant.
				Use constants to replace commonly used numbers with friendly names.
				The following are some general purpose constants have been defined for you
				(there are hundreds more intended for specific commands):
				<lb />
				<tt>zero</tt> <tt>one</tt> <tt>two</tt> <tt>three</tt> <tt>four</tt> <tt>five</tt> <tt>six</tt> <tt>seven</tt> <tt>eight</tt> <tt>nine</tt> <tt>ten</tt>
				<ref>false</ref> <ref>true</ref> <ref>off</ref> <ref>on</ref>
				<ref>north</ref> <ref>east</ref> <ref>south</ref> <ref>west</ref>
				<ref>up</ref> <ref>down</ref> <ref>left</ref> <ref>right</ref>
				<ref>me</ref>
				<ref>none</ref>
			</description>
		</command>
		<command id="include">
			<canon>include, filename</canon>
			<shortname>include</shortname>
			<description>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 <ref>defineconstant</ref> into multiple files. The filename can include a path, for example <p>include, ..\utility scripts\math.hss</p>. You can optionally include quote marks around the filename, e.g. <p>include, "misc.hss"</p>, which causes normal string parsing (for example, allowing a # character in a filename). <lb/>Previously every plotscript file had to start with <p>include, plotscr.hsd</p> but this is now optional. <p>plotscr.hsd</p>, <p>scancode.hsi</p>, and the exported <p>your game name.hsi</p> file are all automatically included.</description>
			<example>include, cutscenes.hss  # All scripts for cutscenes
include, ..\utility scripts\math.hss  # A few useful scripts shared between multiple games</example>
		</command>
	</section>

	<section title="Math, Comparison, and Logic Operators">

		<section title="Working with Variables">
		<command id="setvariable">
			<canon>variable := value</canon>
			<shortname>:=</shortname>
			<description>
				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.
				<lb/>
				The <tt>:=</tt> operation actually returns <p>value</p>, so you can use it
				as an <ref>expression</ref>, for example in <tt>temp1 := (temp2 := 1)</tt>.
			</description>
		</command>
		<command id="increment">
			<canon>increment (variable,amount)</canon>
			<shortname>increment</shortname>
			<description>
				or<lb/><p>variable += amount</p>
				<lb/>
				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.
				<lb/>
				The <tt>+=</tt> operation actually returns the new value of <p>variable</p>,
				so you can use it as an <ref>expression</ref>, for example in <tt>while ((index += 1) &lt; 10)</tt>.
			</description>
		</command>
		<command id="decrement">
			<canon>decrement (variable,amount)</canon>
			<shortname>decrement</shortname>
			<description>
				or<lb/><p>variable -= amount</p>
				<lb/>
				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.
				<lb/>
				The <tt>-=</tt> operation actually returns the new value of <p>variable</p>,
				so you can use it as an <ref>expression</ref>, for example in <tt>while (index -= 1)</tt>.
			</description>
		</command>
		<command id="readglobal">
			<canon>read global (id)</canon>
			<shortname>read global</shortname>
			<description>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.</description>
			<seealso>
				<ref>writeglobal</ref>
			</seealso>
		</command>
		<command id="writeglobal">
			<canon>write global (id,value)</canon>
			<shortname>write global</shortname>
			<description>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</description>
			<seealso>
				<ref>readglobal</ref>
			</seealso>
		</command>
		</section>		<!--Working with variables-->

		<command id="add">
			<canon>number + number</canon>
			<shortname>add</shortname>
			<description>Adds two values together and returns the result. This can also be written as <p>add(number,number)</p></description>
		</command>
		<command id="subtract">
			<canon>number -- number</canon>
			<shortname>subtract</shortname>
			<description>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 <p>subtract(number,number)</p></description>
		</command>
		<command id="multiply">
			<canon>number * number</canon>
			<shortname>multiply</shortname>
			<description>Multiplies two values together and returns the result. This can also be written as <p>multiply(number,number)</p></description>
		</command>
		<command id="divide">
			<canon>number / number</canon>
			<shortname>divide</shortname>
			<description>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 <p>divide(number,number)</p></description>
		</command>
		<command id="modulus">
			<canon>number,mod,number</canon>
			<shortname>mod</shortname>
			<description>Divides the second number into the first number and returns the remainder. This can also be written as <p>modulus(number,number)</p></description>
		</command>
		<command id="exponent">
			<canon>number ^ power</canon>
			<shortname>^</shortname>
			<description>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 <p>exponent(number,power)</p></description>
		</command>
		<command id="min">
			<canon>min (number, number, ...)</canon>
			<shortname>min</shortname>
			<description>Returns the smallest value from two or more arguments.</description>
		</command>
		<command id="max">
			<canon>max (number, number, ...)</canon>
			<shortname>max</shortname>
			<description>Returns the largest value from two or more arguments.</description>
		</command>
		<command id="abs">
			<canon>abs (number)</canon>
			<shortname>abs</shortname>
			<description>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.</description>
		</command>
		<command id="sign">
			<canon>sign (number)</canon>
			<shortname>sign</shortname>
			<description>Returns -1 if <p>number</p> is negative, 0 if it is 0, and 1 if <p>number</p> is positive.</description>
		</command>
		<command id="sqrt">
			<canon>sqrt (number)</canon>
			<shortname>sqrt</shortname>
			<description>Returns the squareroot of a number, rounded to the nearest integer.</description>
		</command>
		<command id="equal">
			<canon>number == number</canon>
			<shortname>==</shortname>
			<description>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 <p>equal(number,number)</p></description>
		</command>
		<command id="notequal">
			<canon>number &lt;> number</canon>
			<shortname>&lt;></shortname>
			<description>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 <p>not equal(number,number)</p></description>
		</command>
		<command id="lessthan">
			<canon>number &lt; number</canon>
			<shortname>&lt;</shortname>
			<description>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 <p>less than(number,number)</p> and as <p>number &lt;&lt; number</p></description>
		</command>
		<command id="greaterthan">
			<canon>number &gt; number</canon>
			<shortname>&gt;</shortname>
			<description>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 <p>greater than(number,number)</p> and as <p>number &gt;&gt; number</p></description>
		</command>
		<command id="lessthanorequalto">
			<canon>number &lt;= number</canon>
			<shortname>&lt;=</shortname>
			<description>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 <p>less than or equal to(number,number)</p></description>
		</command>
		<command id="greaterthanorequalto">
			<canon>number >= number</canon>
			<shortname>&gt;=</shortname>
			<description>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 <p>greater than or equal to(number,number)</p></description>
		</command>
		<command id="and">
			<canon>value,and,value</canon>
			<shortname>and</shortname>
			<description>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.</description>
			<seealso><ref>logicaland</ref></seealso>
		</command>
		<command id="or">
			<canon>value,or,value</canon>
			<shortname>or</shortname>
			<description>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.</description>
			<seealso><ref>logicalor</ref></seealso>
		</command>
		<command id="xor">
			<canon>value,xor,value</canon>
			<shortname>xor</shortname>
			<description>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.</description>
			<seealso><ref>logicalxor</ref></seealso>
		</command>
		<command id="logicaland">
			<canon>value &amp;&amp; value</canon>
			<shortname>&amp;&amp;</shortname>
			<description>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.</description>
		</command>
		<command id="logicalor">
			<canon>value || value</canon>
			<shortname>||</shortname>
			<description>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.</description>
		</command>
		<command id="logicalxor">
			<canon>value ^^ value</canon>
			<shortname>^^</shortname>
			<description>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.</description>
		</command>
		<command id="not">
			<canon>not (value)</canon>
			<shortname>not</shortname>
			<description>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).</description>
		</command>
		<command id="random">
			<canon>random (lownumber, highnumber)</canon>
			<shortname>random</shortname>
			<description>Returns a random integer in the range of the two numbers. The returned value will be greater than or equal to the first number, and less than or equal to the second number</description>
		</command>
		<command id="randomchoice">
			<canon>random choice (values...)</canon>
			<shortname>random choice</shortname>
			<description>
				Returns one of its arguments, randomly.
				Up to 32 different <p>values</p> can be provided.
				Returns 0 if it has no arguments.
			</description>
			<example># Move an npc randomly to either (5,10), (5,14), or (5,18)
set npc position(npc, 5, random choice (10, 14, 18))</example>
		</command>
		<command id="seedrandom">
			<canon>seed random (seed)</canon>
			<shortname>seedrandom</shortname>
			<description>
				Reseeds the random number generator.
				If you pass in a <p>seed</p> (number) other than 0, the random number generator will be seeded with that number,
				allowing for repeatable random sequences - <ref>random</ref> will always return the same sequence
				of random numbers afterwards. Each seed causes a completely different sequence.
				<lb/>
				If called with no argument (or <p>seed</p> = 0), this will reseed the random number generator to a new random sequence
				(which is useful only if you've previously called <tt>seed random(...)</tt> to put it into
				a predictable sequence.)
				<note>
					You don't need to call this command before using <ref>random</ref>.
					In fact, this command is useful only if you <b>don't</b> want completely random numbers.
				</note>
			</description>
			<seealso>
				<ref>random</ref>
			</seealso>
		</command>
		<command id="multdiv">
			<canon>multdiv (a, b, c)</canon>
			<shortname>multdiv</shortname>
			<description>
				Computes <tt>(a * b) / c</tt> with rounding, and without overflowing.
				The intermediate result is performed in floating point so that it won't overflow,
				and the final result is clamped to the range of a 32-bit integer.
				<lb/>
				This is equivalent to <tt>min(2^31 - 1, max(-2^31, round(1.0 * a * b / c)))</tt> in other languages.
			</description>
		</command>

		<command id="dirx">
			<canon>dir X (direction)</canon>
			<shortname>dir X</shortname>
			<description>
				Simpler helper function to convert a <ref>direction</ref> into a relative X value. Returns -1 for left, 1 for right, and otherwise 0.
				It's often useful to multiply the return value, e.g. to get an increment of 20 pixels rather than 1 tile.
				<example># To find the tile in front of the hero:
variable (x, y, dir)
dir := hero direction(me)
x := hero X(me) + dir X(dir)
y := hero Y(me) + dir Y(dir

# To find the point 20 pixels in front of the hero (the hero has a 20x20 hitbox, but "hero pixel X/Y"
# return the top-left corner, so add 10 pixels to start at the center of the hero):
x := hero pixel X(me) + 10 + 20 * dir X(dir)
y := hero pixel Y(me) + 10 + 20 * dir Y(dir)</example>
			</description>
			<seealso><ref>diry</ref></seealso>
		</command>
		<command id="diry">
			<canon>dir Y (direction)</canon>
			<shortname>dir Y</shortname>
			<description>
				Simpler helper function to convert a <ref>direction</ref> into a relative Y value. Returns -1 for up, 1 for down, and otherwise 0.
				See <ref>dirx</ref>.
			</description>
			<seealso><ref>dirx</ref></seealso>
		</command>

	</section>   <!-- Math, Comparison, and Logic Operators" -->

	<section title="Flow Control">
		<command id="begin">
			<canon>begin, other commands, end</canon>
			<shortname>begin</shortname>
			<description>
				<tt>begin</tt> is a synonym for <tt>(</tt> and <tt>end</tt> is a synonym for <tt>)</tt>.
				Parentheses are normally used for bracketing things that all fit on the same line,
				and <tt>begin</tt>/<tt>end</tt> statements are often used to enclose very long things
				such as whole scripts or long flow control blocks that take up several lines.
				But using one or the other is a matter of taste.
				<lb/>
				For example, the following:
				<example>if (check tag(tag:have rusty sword)) then (show text box (5), wait for text box)</example>
				is equivalent to:
				<example>if (check tag(tag:have rusty sword)) then, begin
	show text box (5)
	wait for text box
end</example>
			</description>
		</command>
		<command id="end">
			<canon>end</canon>
			<shortname>end</shortname>
			<description>See <ref>begin</ref>.</description>
		</command>
		<command id="if">
			<canon>if(condition) then(commands) else(commands)</canon>
			<shortname>if</shortname>
			<description>
				The <p>if</p> statement checks the value of its <p>condition</p>, and if the value is <ref>true</ref>
				(actually, any value other than <ref>false</ref> (which is zero) also counts as true),
				it runs the commands in the <p>then</p> block.
				If the value is <ref>false</ref>, it runs the commands in its <p>else</p> block.
				The conditional is usually a comparison operator such as <ref>equal</ref> or <ref>notequal</ref>,
				or a command which returns either true or false, such as <ref>checktag</ref>.
				The <p>else</p> is optional as long as you have a <p>then</p>, and the <p>then</p>
				is optional as long as you have an <p>else</p>.
				You can also place one or more <ref>elseif</ref>s after the <p>then</p>
				(or immediately after the <p>if</p> if you skip the <p>then</p>) instead of nesting multiple <p>if</p> statements.
			</description>
			<seealso><ref>elseif</ref></seealso>
		</command>
		<command id="elseif">
			<canon>... else if(condition) then(commands) ...</canon>
			<shortname>else if</shortname>
			<description>This can appear after an <ref>if</ref> or <ref>then</ref> block. It is a shortcut for <ref>else</ref> followed by <ref>if</ref> which lets you omit a pairs of brackets/<ref>begin</ref> and <ref>end</ref> around the <tt>else</tt>, as this example shows:
			<example># "inventory" returns the number you own. Remember that any number other than 0 counts as true
if (inventory (item:apple)) then (
  show text box (10)  # "Apples! My favourite!"
) else if (inventory (item:orange)) then (
  show text box (11)  # "My, what a tasty looking orange..."
) else if (inventory (item:pear)) then (
  show text box (12)  # "Perhaps if you gave me that pear..."
) else (
  show text box (13)  # "Come back when you have something tasty for me!"
)</example>
			</description>
		</command>
		<command id="then">
			<canon>then</canon>
			<shortname>then</shortname>
			<description>See <ref>if</ref>.</description>
		</command>
		<command id="else">
			<canon>else</canon>
			<shortname>else</shortname>
			<description>See <ref>if</ref>.</description>
		</command>

		<command id="while">
			<canon>while(condition) do(commands)</canon>
			<shortname>while</shortname>
			<description>
				The while command checks the value of its condition, and if the value is <ref>true</ref>
				(or any value other than 0/false) it runs the commands in the <ref>do</ref> block.
				It keeps checking the conditional and runs the do block over and over
				again until the conditional returns <ref>false</ref>.
				The conditional is usually an equality operator such as <ref>equal</ref> or <ref>notequal</ref>,
				or something else that returns <tt>true/false</tt> such as <tt>checktag</tt>.
</description>
		</command>
		<command id="do">
			<canon>do</canon>
			<shortname>do</shortname>
			<description>Used to group several statements together. Normally appears after a <ref>while</ref>, <ref>for</ref> or <ref>switch</ref>. However, <p>do</p> blocks can actually appear by themselves. This is useful if you want to <ref>break</ref> out of them to skip to the end. (<ref>continue</ref> inside an orphan <p>do</p> block acts just like <p>break</p>.)</description>
			<seealso>
				<ref>while</ref>
				<ref>for</ref>
				<ref>switch</ref>
			</seealso>
		</command>
		<command id="for">
			<canon>for(counter,start,finish,step) do(commands)</canon>
			<shortname>for</shortname>
			<description>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 <ref>return</ref> and <ref>puthero</ref> for examples.</description>
		</command>
		<command id="return">
			<canon>return(value)</canon>
			<shortname>return</shortname>
			<description>
				<warn>
					<p>return</p> in HamsterSpeak is very different from <p>return</p> in nearly all other programming languages,
					which is equivalent to <ref>exit</ref> in HamsterSpeak!
				</warn>
				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 <p>return</p> command, the script will return zero.
				If return is used more than once in the same script, only the last one executed matters.
<example>
script, key wait, ticks, begin
  # Returns true if a key was pressed during the wait,
  # or false (0) if the wait finished uninterrupted.
  # The wait duration is always the same. (Compare with the example for "exit returning".)
  variable(i)
  for(i, 1, ticks) do, begin
    wait(1)
    if(key is pressed(use key)) then(return(true))
    if(key is pressed(menu key)) then(return(true))
  end
end

plotscript, usage example, begin
  show text box(5) # let all volunteers take one step forward!
  if(key wait(40)) then(
    walk hero(me, north, 1)
    wait for hero(me)
    show text box(6) # You there! I saw you move! You volunteer!
  )else(
    show text box(7) # a bunch of lily livered cowards, eh?
  )
end
</example>
			</description>
			<seealso>
				<ref>exitreturning</ref>
			</seealso>
		</command>
		<command id="exit">
			<canon>exit</canon>
			<canon>exit(value)</canon>
			<shortname>exit</shortname>
			<description>
				With no argument, is equivalent to <ref>exitscript</ref>. With one argument is equivalent to <ref>exitreturning</ref>.
				<note>
					This is the same as the <p>return</p> statement in most other programming languages.
				</note>
			</description>
		</command>
		<command id="exitreturning">
			<canon>exit returning(value)</canon>
			<canon>exit(value)</canon>
			<shortname>exit returning</shortname>
			<added>ubersetzung</added>
			<description>
				Sets the value to be returned by the script, and exits the script.
				Can be written as either <p>exit returning(value)</p> or the new style <p>exit(value)</p>.
				This is only useful when the script has been called as a function from another script.
<example>
script, key wait, ticks, begin
  # Returns true if the wait was cancelled by a keypress.
  variable(i)
  for(i, 1, ticks) do, begin
    wait(1)
    if(key is pressed(use key)) then(exit returning(true))
    if(key is pressed(menu key)) then(exit returning(true))
  end
end

plotscript, usage example, begin
  show text box(5) # let all volunteers take one step forward!
  if(key wait(40)) then(
    walk hero(me, north, 1)
    wait for hero(me)
    show text box(6) # You there! I saw you move! You volunteer!
  )else(
    show text box(7) # a bunch of lily livered cowards, eh?
   )
end
</example>
				The <p>exit returning</p> command works exactly the same as the <ref>return</ref> command followed immediately by <ref>exitscript</ref>.
				Whether you decide to use <ref>return</ref> or <p>exit returning</p> to set your script's return value is often just a matter of style and taste.
			</description>
			<seealso>
				<ref>return</ref>
				<ref>exitscript</ref>
			</seealso>
		</command>
		<command id="exitscript">
			<canon>exit script</canon>
			<canon>exit</canon>
			<shortname>exit script</shortname>
			<added>ubersetzung</added>
			<description>
				Causes the script to end immediately, and return the value set by the most recent <ref>return</ref> statement.
				Can be written as either <p>exit script</p> or the new style <p>exit</p>.
			</description>
			<seealso>
				<ref>exitreturning</ref>
			</seealso>
		</command>
		<command id="break">
			<canon>break (levels)</canon>
			<shortname>break</shortname>
			<added>ubersetzung</added>
			<description>
				Breaks out of a <ref>for</ref> or <ref>while</ref> loop or <ref>switch</ref>
				(or even an isolated <ref>do</ref> block)
				and continues the script after the end of the <ref>do</ref> block.
				If breaking out of a <tt>for</tt> loop, the loop's variable isn't modified.
				<lb/>
				<p>levels</p> is optional (defaulting to 1), and is almost never used (see below).
				<lb/>
				For example:
				<example>plotscript, search for gemstones, begin
  variable (gems)
  # A minimum payout of 1 gem, a maximum of 15
  for (gems, 1, 15) do (
    wait(20)
    $1 = "Found "
    append number(1, gems)
    center string at(1)   # Show "Found 1", etc, in the center of the screen (the position is optional)
    if (random(1, 6) == 1) then (break)  # Roll a die and stop on a 1
  )
  # Remove the text from the screen
  hide string(1)
  # "${S1} shiny rocks in the river", displays as "Found 2 shiny rocks in the river", etc
  show textbox(17)
end</example>
				<p>levels</p> tells how many nested loops/blocks to break out of.
				It must be at least 1.
				Remember that other flow control blocks such as <tt>if/then/else</tt> and <tt>case() do()</tt> don't count, only those listed above.
				<example># Randomly pick one of the flowers on the map that hasn't bloomed yet and make it bloom
plotscript, a flower blooms, begin
  variable (x, y, found)
  for (x, 0, map width -- 1) do (
    for (y, 0, map height -- 1) do (
      # Look for a flower tile (on map layer 0), suppose it's tile 10
      if (read block(x, y) == 10) then (
        if (random(1, 10) == 1) then (   # 10% chance of picking this one
	  found := true
	  break (2)  # Exit both 'for' loops. The x and y variables will remain the same
      )
    )
  )
  # The break(2) jumps to here

  if (found) then (
    # Do a little animation
    write block(x, y, 11)
    wait(20)
    write block(x, y, 12)
  )
end</example>
			</description>
		</command>
		<command id="continue">
			<canon>continue (levels)</canon>
			<shortname>continue</shortname>
			<added>ubersetzung</added>
			<description>
				When used inside the <ref>do</ref> block of a <ref>for</ref> or <ref>while</ref> command
				(or in an isolated <ref>do</ref> block),
				<tt>continue</tt> skips the rest of the <tt>do</tt> block and continues on to the next loop, if any.
				That's equivalent to jumping to the bottom of the loop, so its effect is like enclosing
				the rest of the loop in an <ref>if</ref>
				(except for isolated <tt>do</tt> blocks, in which case it jumps straight to the top
				of the loop because there's no condition to check).
				<lb/>
				When used inside a <ref>switch</ref> statement, <tt>continue</tt> causes a jump into
				the next <ref>case</ref>'s <tt>do()</tt> block, even if the <tt>case</tt> doesn't match,
				or into the <tt>else()</tt> (aka <tt>case(else) do()</tt>) block if that follows the current <tt>case</tt>.
				<lb/>
				
				<lb/>
				<p>levels</p> is optional (defaulting to 1), and is almost never used.
				When inside several nested loops/blocks it tells which one to continue.
				It must be at least 1.
				For example if there are 3 nested <tt>for</tt> loops, <tt>continue(3)</tt> continues the outermost one,
				in the process  breaking out of the inner two.
				For example:
<example>plotscript, update shadow tiles, begin
  for (x, 0, map width -- 1) do (
    for (y, 0, map height -- 1) do (

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

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

			</description>
		</command>
		<command id="switch">
			<canon>switch(expression)</canon>
			<shortname>switch</shortname>
			<added>ubersetzung</added>
			<description>Select between a number of <ref>case</ref> blocks to execute based on the value of an <ref>expression</ref>. The switch command is an alternative to a big block of nested <ref>if</ref>/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:
<example>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
)</example>
This is a good candidate for using switch. The example below shows how this can be done:
<example>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
  )
)</example>
The <p>else</p> 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):
<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
)</example>
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 <ref>expression</ref> (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.
			</description>
		</command>
		<command id="case">
			<canon>case(value)</canon>
			<shortname>case</shortname>
			<added>ubersetzung</added>
			<description>The case command is used to enclose a block of commands for one possible result of a <ref>switch</ref> command. See <ref>switch</ref> for more details.</description>
		</command>
	</section>

	<section title="Wait Commands">
		<description>
			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.
			<lb/>
			<warn>
				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, <ref>wait</ref> stops counting down, and
				<ref>waitfornpc</ref> 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.
			</warn>
		</description>
		<command id="wait">
			<canon>wait (ticks)</canon>
			<shortname>wait</shortname>
			<description>
				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.
			</description>
			<example>show text box(2) # Show a text box
wait(50) # Wait about 3 seconds
advance text box # "hit spacebar"</example>
		</command>
		<command id="waitfortextbox">
			<canon>wait for text box</canon>
			<shortname>wait for text box</shortname>
			<description>
				Makes the script wait until there is no text box displaying on the screen.
				Useful to know when to move on after using a <ref>showtextbox</ref> command.
				<warn>
					<tt>wait for text box</tt> doesn't wait if <ref>suspendboxadvance</ref> has been used, because it's impossible for the player to advance the textbox!
				</warn>
			</description>
			<example>show text box(2) # Show a text box
wait for text box # wait until the player continues</example>
		</command>
		<command id="waitformenu">
			<canon>wait for menu (menu handle)</canon>
			<shortname>wait for menu</shortname>
			<description>Given a <ref>menuhandle</ref>, causes the script to wait until that menu has been closed.</description>
		</command>
		<command id="waitforhero">
			<canon>wait for hero (who)</canon>
			<shortname>wait for hero</shortname>
			<description>Waits for the specified hero stop walking. Use the constant <ref>me</ref> 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.</description>
			<example>move hero to y (me, 10) # move hero to (x, 10)
wait for hero (me) # wait until he stops</example>
			<seealso>
				<ref>walkhero</ref>
				<ref>pathfindheroto</ref>
			</seealso>
		</command>
		<command id="waitforkey">
			<canon>wait for key (key)</canon>
			<shortname>wait for key</shortname>
			<description>
				Waits for the player to press a key.
				(Specially, (possibly repeated) keypresses or mouse button release.)
				<p>key</p> is an optional <ref>scancode</ref> such as a keyboard key (e.g. <tt>key:ctrl</tt>)
				a joystick button (e.g. <tt>joy:left</tt>), or a virtual scancode such as
				<ref>usekey</ref>.
				If you do not specify <p>key</p>, then <ref>anykey</ref> will be used.
				<lb/>
				<ref>anykey</ref> waits for any keyboard or joystick button,
				(except Numlock, Capslock and Scrolllock, or any joystick buttons that have no
				builtin meaning e.g. X/Y/L1/L2/R1/R2)
				and also waits for a mouse click if "'any key', etc, include mouse clicks" is
				turned on in the Mouse Controls menu.
				<p>usekey</p> will wait for Space, Ctrl or Enter, joystick use key, and optionally left click;
				and <p>cancelkey</p> and <p>menukey</p> both wait for Alt or Esc,
				joystick cancel, and optionally right click.
				<lb/>
				If and only if <tt>anykey</tt> is used, then <p>waitforkey(anykey)</p> will return the scancode of the keyboard or joystick key that was pressed,
				but won't ever be a constant like <tt>usekey</tt>.
				It returns a value >= 180 if a mouse button was released (see scancode.hsi).
				<note>
					Previously you couldn't use scancodes like <tt>key:x</tt>,
					and there was a separate <ref>waitforscancode</ref> command for those,
					but now you can use any scancode with <tt>wait for key</tt>, and use any
					of the codes like <tt>use key</tt> with other key commands like <ref>keyispressed</ref>.
				</note>
				<warn>
					While <tt>wait for key</tt> waits, on-keypress scripts will not be triggered.
				</warn>
			</description>
			<example>show text box(623) # "press cancel!"
wait for key(cancel key)</example>
		</command>
		<command id="waitforscancode">
			<canon>wait for scancode (key)</canon>
			<shortname>wait for scancode</shortname>
			<added>ubersetzung</added>
			<description>Identical to <ref>waitforkey</ref>.</description>
		</command>
		<command id="waitfornpc">
			<canon>wait for NPC (who)</canon>
			<shortname>wait for NPC</shortname>
			<description>Waits for the specified NPC to stop walking. The argument is either an NPC reference, or an NPC ID (if more than one copy of that NPC exists on the map, it only waits for the first one). Be aware that this command has the potention to wait forever, if the NPC will continue moving forever.
			<note>
				If the NPC ceases to exist, or if you move to a different map, then <p>wait for npc</p> stops waiting (continues).
			</note>
			</description>
			<example>walk NPC (2,up,3) # make NPC 2 go up three spaces
wait for NPC (2) # wait until the NPC'S done</example>
			<seealso>
				<ref>walknpc</ref>
				<ref>pathfindnpcto</ref>
			</seealso>
		</command>
		<command id="waitforcamera">
			<canon>wait for camera</canon>
			<shortname>wait for camera</shortname>
			<description>Wait for the camera to stop panning after a <ref>pancamera</ref>, <ref>focuscamera</ref> or <ref>pixelfocuscamera</ref> command.</description>
			<example>pan camera (left,10) # show the villain 10 tiles off screen
wait for camera # wait until he's on screen</example>
		</command>
		<command id="waitforall">
			<canon>wait for all</canon>
			<shortname>wait for all</shortname>
			<description>
				Waits for any camera motion due to <ref>pancamera</ref>, <ref>focuscamera</ref>, etc. to stop,
				waits for all heroes to stop walking and pathfinding, and waits for NPCs to stop <b>scripted</b> pathfinding
				(e.g. <ref>pathfindnpcto</ref>).
				If <ref>suspendnpcs</ref> has been used then <ref>waitforall</ref> also waits for all NPCs to come to a halt.
				Beware that without <ref>suspendnpcs</ref>, automatic NPC walking such as wandering, pacing, avoiding, or pathfinding,
				as well as movement due to <ref>walknpc</ref>/<ref>walknpctox</ref>/<ref>walknpctoy</ref> are ignored!
				That means that NPCs might still be partway between tiles.
				<note>
					<p>wait for all</p> does NOT wait for text boxes.
				</note>
			</description>
			<example># do a bunch of things all at once
suspend NPCs
walk hero(me, south, 3)
pathfind NPC to(4, 30, 35, 10)
NPC chases NPC(5, 4, false, 10)
pan camera(north, 20, 1)

# wait until everything is done
wait for all 

camera follows hero(me)
resume NPCs</example>
		</command>
		<reference ref="waitforslice"/>
		<reference ref="waitfordissolve"/>
		<reference ref="waitforsound"/>
	</section>

	<section title="Working with Tags">
		<command id="settag">
			<canon>set tag (tag,value)</canon>
			<shortname>set tag</shortname>
			<description>Sets the value of a tag. The available constants are: <ref>off</ref>, <ref>on</ref>, <ref>true</ref>, or <ref>false</ref>. You can specify the number of the tag, or you can use the constants in your HSI file. These constants are in the form of tag:name.</description>
		</command>
		<command id="checktag">
			<canon>check tag (tag)</canon>
			<shortname>check tag</shortname>
			<description>A function that checks the value of a tag, and returns <ref>true</ref> if the tag is turned on, and <ref>false</ref> if the tag is turned off. It can be used in <ref>if</ref> and <ref>while</ref> statements. You can specify the number of the tag, or you can use the constants in your HSI file. These constants are in the form of tag:name.</description>
		</command>
		<command id="setonetime">
			<canon>set onetime (onetime,value)</canon>
			<shortname>set onetime</shortname>
			<description>
				Sets the value of an NPC onetime use flag.
				NPC onetime use flags behave like tags but are stored separately.
				<p>value</p> is the new setting; for clarity you can use the constants
				<ref>off</ref>, <ref>on</ref>, <ref>true</ref>, or <ref>false</ref>.
			</description>
		</command>
		<command id="checkonetime">
			<canon>check onetime (onetime)</canon>
			<shortname>check onetime</shortname>
			<description>
				A function that checks the value of an NPC onetime flag,
				and returns <ref>true</ref> if the one-time NPC has already been used,
				and <ref>false</ref> if the onetime NPC has not yet been used.
				It can be used in <ref>if</ref> and <ref>while</ref> statements.
				NPC onetime flags are similar to tags, but stored separately.
			</description>
		</command>
	</section>

	<section title="Suspend and Resume">
		<command id="suspendplayer">
			<canon>suspend player</canon>
			<shortname>suspend player</shortname>
			<description>
				Blocks the player from controlling the game, so the plotscript can have exclusive control.
				The exceptions to this are text boxes and menus.
				<lb/>
				The player can still advance text boxes unless you use <ref>suspendboxadvance</ref>.
				<lb/>
				<tt>suspend player</tt> prevents the player from opening the main menu using the menu key (ESC/etc),
				but it doesn't suspend controls on any menu or the player's ability to close menus with
				the cancel key.
				(You can change that with <ref>setmenubit</ref><tt>(menu handle, menubit:no controls, true)</tt>
				where <tt>menu handle</tt> might for example be <ref>topmenu</ref>.)
			</description>
			<example>suspend player
# Script a small cutscene...
walk hero (me, right, 10)
wait for hero (me)
wait (20)
set hero direction (me, left)
resume player</example>
		</command>
		<command id="resumeplayer">
			<canon>resume player</canon>
			<shortname>resume player</shortname>
			<description>Restores normal control after a <ref>suspendplayer</ref> command. This is very important. If you use <ref>suspendplayer</ref>, but forget resume player, the game will be stuck after the script ends.</description>
			<example c="suspendplayer" />
		</command>
		<command id="playerissuspended">
			<canon>player is suspended</canon>
			<shortname>player is suspended</shortname>
			<description>Returns true if <ref>suspendplayer</ref> is active.</description>
		</command>

		<command id="suspendnpcs">
			<canon>suspend NPCs</canon>
			<shortname>suspend NPCs</shortname>
			<description>
				Stops NPCs from walking around automatically (ie., suspends NPC AI).
				When <tt>suspend NPCs</tt> is run, all NPCs stop in their tracks once they've
				finished their current step to the next tile, ready for you to control them
				with commands like <ref>walknpc</ref> and <ref>pathfindnpcto</ref>.
				You should use a wait command like <ref>waitfornpc</ref> to ensure an NPC has
				finished its current movement before getting it to start a new one (which could
				cause tile misalignment).
				<lb/>
				Use <ref>setnpcmoves</ref>(who, false) instead to prevent a single NPC from moving.
				<note>
					If you want NPCs to stop immediately without finishing their current steps, consider <ref>suspendwalkabouts</ref> instead.
				</note>
			</description>
			<example>suspend NPCs
# do stuff
resume NPCs</example>
			<seealso>
				<ref>waitfornpc</ref>
				<ref>waitforall</ref>
				<ref>setnpcmoves</ref>
				<ref>suspendwalkabouts</ref>
			</seealso>
		</command>
		<command id="resumenpcs">
			<canon>resume NPCs</canon>
			<shortname>resume NPCs</shortname>
			<description>Restores automatic NPC movement after a <ref>suspendnpcs</ref> command. This does not resume NPCs suspended with <ref>setnpcmoves</ref>.</description>
			<example c="suspendnpcs" />
		</command>
		<command id="npcsaresuspended">
			<canon>npcs are suspended</canon>
			<shortname>npcs are suspended</shortname>
			<description>Returns true if <ref>suspendnpcs</ref> is active.</description>
		</command>

		<command id="suspendwalkabouts">
			<canon>suspend walkabouts</canon>
			<shortname>suspend walkabouts</shortname>
			<description>
				Suspends (pauses) all NPC and hero movement immediately and completely, as well as
				NPC AI, player movement controls, NPC activation, Walk In Place animations,
				and vehicle mounting/dismounting/rising/falling animations.
				Unlike <ref>suspendnpcs</ref>, NPCs stop moving immediately rather than finishing their step.
				<lb/>
				This doesn't suspend updating of the hero/NPCs slices.
				For example, <ref>puthero</ref>, <ref>putnpc</ref>, <ref>setheroz</ref>, <ref>setheroframe</ref>,
				etc. still cause the hero/NPC slices to move, change frame, etc.
				<lb/>
				Although player movement is suspended, this doesn't suspend everything <ref>suspendplayer</ref> does:
				the player can still open the menu (or the vehicle's menu setting or Instead-of-menu script)
				and advance text boxes.
				They can't activate NPCs or dismount vehicles.
				<danger>
					While walkabouts are suspended, <ref>waitforhero</ref> and <ref>waitfornpc</ref> commands will freeze forever,
					and commands like <ref>walkhero</ref> and <ref>walknpc</ref> won't cause any movement until you <ref>resumewalkabouts</ref>.

				</danger>
				<note>
					This is one of the main effects of menus set to "Suspend gameplay &amp; scripts",
					along with <ref>suspendplayer</ref>, <ref>suspendtimers</ref>, <ref>suspendboxadvance</ref>,
					<ref>suspendtextboxcontrols</ref>, pausing scripts and script triggers,
					and suspending slice movement.

				</note>
			</description>
			<seealso>
				<ref>suspendplayer</ref>
				<ref>suspendnpcs</ref>
			</seealso>
		</command>
		<command id="resumewalkabouts">
			<canon>resume walkabouts</canon>
			<shortname>resume walkabouts</shortname>
			<description>
				Undoes <ref>suspendwalkabouts</ref>.
				Has no effect if walkabout movement is actually suspended by a menu set to "Suspend gameplay &amp; scripts".
			</description>
		</command>
		<command id="walkaboutsaresuspended">
			<canon>walkabouts are suspended</canon>
			<shortname>walkabouts are suspended</shortname>
			<description>Returns true if <ref>suspendwalkabouts</ref> is active.</description>
		</command>


		<command id="suspendobstruction">
			<canon>suspend obstruction</canon>
			<shortname>suspend obstruction</shortname>
			<description>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 <ref>resumeobstruction</ref> to restore normal obstruction behavior. Use <ref>setnpcobstructs</ref>(who, false) instead to allow a single NPC to move through heroes and NPCs, and vice-versa.</description>
			<example>suspend obstruction
# walk through things
resume obstruction</example>
			<seealso>
				<ref>setnpcobstructs</ref>
			</seealso>
		</command>
		<command id="resumeobstruction">
			<canon>resume obstruction</canon>
			<shortname>resume obstruction</shortname>
			<description>Restores normal obstruction after a <ref>suspendobstruction</ref> command. This doesn't undo the effect of <ref>setnpcobstructs</ref>.</description>
			<example c="suspendobstruction" />
		</command>
		<command id="obstructionissuspended">
			<canon>obstruction is suspended</canon>
			<shortname>obstruction is suspended</shortname>
			<description>Returns true if <ref>suspendobstruction</ref> is active.</description>
		</command>
		<command id="suspendherowalls">
			<canon>suspend hero walls</canon>
			<shortname>suspend hero walls</shortname>
			<description>Allows heroes to walk through walls, and to walk off the edge of the map. Use <ref>resumeherowalls</ref> to restore normal wall behavior.</description>
			<example>suspend hero walls # hero is now a ghost
# walk through things
resume hero walls # back to mortality...</example>
		</command>
		<command id="resumeherowalls">
			<canon>resume hero walls</canon>
			<shortname>resume hero walls</shortname>
			<description>Restores normal wall behavior after a <ref>suspendherowalls</ref> command</description>
			<example c="suspendherowalls" />
		</command>
		<command id="herowallsaresuspended">
			<canon>hero walls are suspended</canon>
			<shortname>hero walls are suspended</shortname>
			<description>Returns true if <ref>suspendherowalls</ref> is active.</description>
		</command>
		<command id="suspendnpcwalls">
			<canon>suspend NPC walls</canon>
			<shortname>suspend NPC walls</shortname>
			<description>
				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 <ref>resumenpcwalls</ref> to restore normal wall behavior.
				Use <ref>setnpcignoreswalls</ref>(who, true) instead to allow a single NPC to walk through walls.
				<note>
					If you use this command on a map with NPCs walking about normally
					you should use <ref>suspendnpcs</ref> first, otherwise NPCs will
					start walking into walls and get stuck there when you call
					<ref>resumenpcwalls</ref>!
					<lb/>
					Usually it is better to use <ref>setnpcignoreswalls</ref>
					to allow just a specific NPC to walk through walls.
				</note>
				<note>
					NPCs will still be unable to walk through each other, or to walk through
					the hero.
					Use <ref>suspendobstruction</ref> to allow that.
				</note>
			</description>
			<example>suspend NPC walls # npc is now a ghost
# walk through things
resume NPC walls # back to mortality...</example>
		</command>
		<command id="resumenpcwalls">
			<canon>resume NPC walls</canon>
			<shortname>resume NPC walls</shortname>
			<description>Restores normal wall behavior after a <ref>suspendnpcwalls</ref> command. This doesn't undo the effect of <ref>setnpcignoreswalls</ref>.</description>
			<example c="suspendnpcwalls" />
		</command>
		<command id="npcwallsaresuspended">
			<canon>npc walls are suspended</canon>
			<shortname>npc walls are suspended</shortname>
			<description>Returns true if <ref>suspendnpcwalls</ref> is active.</description>
		</command>
		<command id="suspendcaterpillar">
			<canon>suspend caterpillar</canon>
			<shortname>suspend caterpillar</shortname>
			<description>Stops your other heroes from following the leader. This is useful when you want to control them individually with <ref>walkhero</ref> commands. In earlier versions this was misspelled as suspend catapillar. The old spelling still works for backwards compatibility. <note>If you want to set whether the other heroes in the party are visible, use <ref>setcaterpillarmode</ref>.</note></description>
			<example>suspend caterpillar # cutscene
# move heroes, probably fight a battle or two...
resume caterpillar # normal game again.</example>
		</command>
		<command id="resumecaterpillar">
			<canon>resume caterpillar</canon>
			<shortname>resume caterpillar</shortname>
			<description>Reverses the <ref>suspendcaterpillar</ref> 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.</description>
			<example c="suspendcaterpillar" />
		</command>
		<command id="caterpillarissuspended">
			<canon>caterpillar is suspended</canon>
			<shortname>caterpillar is suspended</shortname>
			<description>Returns true if <ref>suspendcaterpillar</ref> is active.</description>
		</command>
		<command id="suspendcatapillar">
			<alias>suspendcaterpillar</alias>
			<shortname>suspend catapillar</shortname>
			<deprecated>May 22 2001</deprecated>
		</command>
		<command id="resumecatapillar">
			<alias>resumecaterpillar</alias>
			<shortname>resume catapillar</shortname>
			<deprecated>May 22 2001</deprecated>
		</command>
		<command id="suspenddoors">
			<canon>suspend doors</canon>
			<shortname>suspend doors</shortname>
			<description>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 <ref>dooratspot</ref>, etc. While doors are suspended <ref>usedoor</ref> still works.</description>
		</command>
		<command id="resumedoors">
			<canon>resume doors</canon>
			<shortname>resume doors</shortname>
			<description>Restores normal door triggering after a <ref>suspenddoors</ref> command. If the lead hero is already standing on a door, it will not be triggered.</description>
		</command>
		<command id="doorsaresuspended">
			<canon>doors are suspended</canon>
			<shortname>doors are suspended</shortname>
			<description>Returns true if <ref>suspenddoors</ref> is active.</description>
		</command>
		<command id="suspendrandomenemies">
			<canon>suspend random enemies</canon>
			<shortname>suspend random enemies</shortname>
			<description>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.</description>
			<example>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</example>
		</command>
		<command id="resumerandomenemies">
			<canon>resume random enemies</canon>
			<shortname>resume random enemies</shortname>
			<description>Undoes the <ref>suspendrandomenemies</ref> 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.</description>
			<example c="suspendrandomenemies" />
		</command>
		<command id="randomenemiesaresuspended">
			<canon>random enemies are suspended</canon>
			<shortname>random enemies are suspended</shortname>
			<description>Returns true if <ref>suspendrandomenemies</ref> is active.</description>
		</command>
		<command id="suspendrandomenemys">
			<alias>suspendrandomenemies</alias>
			<shortname>suspend random enemys</shortname>
		</command>
		<command id="resumerandomenemys">
			<alias>resumerandomenemies</alias>
			<shortname>resume random enemys</shortname>
		</command>
		<command id="suspendboxadvance">
			<canon>suspend box advance</canon>
			<shortname>suspend box advance</shortname>
			<description>
				Prevents the player from advancing text boxes by pressing the 'use' key.
				While this is active, the only way to make a text box advance is with the
				<ref>advancetextbox</ref> command (or <ref>showtextbox</ref>)
				or using the "Advance text box when menu closes" menu bit.
				Useful for cut-scenes that play out like a movie,
				where the player just watches the dialogue unfold.
				Be very careful with this command,
				since you do not want to leave the player stuck on a text box forever.
				Undo with <ref>resumeboxadvance</ref>.
				<lb/>
				Note that the player can still move the cursor in choiceboxes while this
				is active, use <ref>suspendtextboxcontrols</ref> to disable that.
				<warn>
					<ref>waitfortextbox</ref> does't wait while <ref>suspendboxadvance</ref> is active!
				</warn>
			</description>

			<example>suspend box advance # stop players from mucking things up
show text box(2)   # Show a text box
wait(45)           # Wait about 3 seconds
advance text box   # Next text box. Maybe it ends with "Press USE key to continue"
resume box advance # go back to normal</example>
		</command>
		<command id="resumeboxadvance">
			<canon>resume box advance</canon>
			<shortname>resume box advance</shortname>
			<description>Undoes the <ref>suspendboxadvance</ref> command, allowing the player to advance text boxes by pressing the use key, as normal.</description>
		</command>
		<command id="boxadvanceissuspended">
			<canon>box advance is suspended</canon>
			<shortname>box advance is suspended</shortname>
			<description>Returns true if <ref>suspendboxadvance</ref> is active.</description>
		</command>
		<command id="suspendtextboxcontrols">
			<canon>suspend text box controls</canon>
			<shortname>suspend text box controls</shortname>
			<description>
				Prevents the player from moving the cursor in choice boxes.
				In future this will also prevent the player from skipping pauses
				and fade-in animations for text boxes, once they are implemented.
				This does not prevent the player from advancing the text box,
				use <ref>suspendboxadvance</ref> for that.
				Undo with <ref>resumetextboxcontrols</ref>.
			</description>
		</command>
		<command id="resumetextboxcontrols">
			<canon>resume text box controls</canon>
			<shortname>resume text box controls</shortname>
			<description>
				Undoes the <ref>suspendtextboxcontrols</ref> command, allowing the player to control choice boxes, as normal.
			</description>
		</command>
		<command id="textboxcontrolsaresuspended">
			<canon>textbox controls are suspended</canon>
			<shortname>textbox controls are suspended</shortname>
			<description>Returns true if <ref>suspendtextboxcontrols</ref> is active.</description>
		</command>
		<command id="suspendoverlay">
			<canon>suspend overlay</canon>
			<shortname>suspend overlay</shortname>
			<description>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 <ref>resumeoverlay</ref>.</description>
		</command>
		<command id="resumeoverlay">
			<canon>resume overlay</canon>
			<shortname>resume overlay</shortname>
			<description>Undoes the <ref>suspendoverlay</ref> command, causing overhead tiles to be drawn over heroes and NPCs as normal.</description>
		</command>
		<command id="overlayissuspended">
			<canon>overlay is suspended</canon>
			<shortname>overlay is suspended</shortname>
			<description>Returns true if <ref>suspendoverlay</ref> is active.</description>
		</command>
		<command id="suspendmapmusic">
			<canon>suspend map music</canon>
			<shortname>suspend map music</shortname>
			<added>serendipity</added>
			<description>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.</description>
			<example># 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)</example>
		<seealso><ref>setambientmusic</ref> <ref>getambientmusic</ref></seealso>
		</command>
		<command id="resumemapmusic">
			<canon>resume map music</canon>
			<shortname>resume map music</shortname>
			<added>serendipity</added>
			<description>Causes ambient music to automatically start playing when you enter a map again after a <ref>suspendmapmusic</ref> command.</description>
		</command>
		<command id="mapmusicissuspended">
			<canon>map music is suspended</canon>
			<shortname>map music is suspended</shortname>
			<description>Returns true if <ref>suspendmapmusic</ref> is active.</description>
		</command>
		<command id="suspendtimers">
			<canon>suspend timers</canon>
			<shortname>suspend timers</shortname>
			<description>Causes all plot timers started with <ref>settimer</ref> to be paused. It does not cancel them. Undo with <ref>resumetimers</ref></description>
		</command>
		<command id="resumetimers">
			<canon>resume timers</canon>
			<shortname>resume timers</shortname>
			<description>Undoes <ref>suspendtimers</ref>. All previously paused plot timers will become active again.</description>
		</command>
		<command id="timersaresuspended">
			<canon>timers are suspended</canon>
			<shortname>timers are suspended</shortname>
			<description>Returns true if <ref>suspendtimers</ref> is active.</description>
		</command>
	</section>

	<section title="Moving Heroes">
		<command id="walkhero">
			<canon>walk hero (who, direction, distance)</canon>
			<shortname>walk hero</shortname>
			<description>Makes a hero move the specified number of tiles in some direction. The first argument tells who to move, it is a caterpillar rank. Use <ref>me</ref> or numbers 0-3. (If the catepillar party is disabled then there will only be one hero, <ref>me</ref>.) The second argument is the <ref>direction</ref>, such as <ref>north</ref>. 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 <ref>waitforhero</ref> command. You should normally use the <ref>suspendplayer</ref> command before moving heroes, and if you want to move heroes other than the leader, you should use the <ref>suspendcaterpillar</ref> command.</description>
			<example>suspend player # stop player
walk hero(me,up,3) # move him up 3 tiles
resume player # OK, done</example>
		</command>
		<reference ref="waitforhero" />
		<command id="pathfindheroto">
			<canon>pathfind hero to (who, x, y, stuck ticks)</canon>
			<shortname>pathfind hero to</shortname>
			<description>Makes the specified hero walk along the shortest path to the destination position. They will go around obstacles. If the destination cannot be reached at all, they will go to the closest reachable tile. The first argument <p>who</p> is the hero's rank in the caterpillar party, or <ref>me</ref> for the leader. When the caterpillar party is enabled, this command only works on the leader, and will do nothing for other heroes. Use <ref>suspendcaterpillar</ref> if you want to make the other heroes pathfind. Non-leader heroes do not treat NPCs as obstacles when they pathfind. The second argument is the destination <p>x</p> tile coordinate. The third argument is the destination <p>y</p> tile coordinate. The fourth argument <p>stuck ticks</p> is optional. If it is included, a hero who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If <p>stop ticks</p> is omitted or zero, the hero will keep pathfinding even if it gets stuck, and will not stop until it reaches the destination, or is stopped with the <ref>cancelherowalk</ref> command. Be careful if you are using <ref>waitforhero</ref> to wait for <ref>pathfindheroto</ref> when no <p>stuck ticks</p> timeout is used, since <ref>waitforhero</ref> might wait forever if the hero has no way to get to its destination.</description>
			<seealso>
				<ref>herochasesnpc</ref>
				<ref>cancelherowalk</ref>
				<ref>waitforhero</ref>
			</seealso>
		</command>
		<command id="herochasesnpc">
			<canon>hero chases npc (who, npc, stop when reached, stuck ticks)</canon>
			<shortname>hero chases NPC</shortname>
			<description>Makes the specified hero walk along the shortest path to the destination NPC, even if the destination NPC is moving. The chasing hero will go around obstacles. If the destination NPC cannot be reached at all, the chasing hero will go to the closest reachable tile. The first argument <p>who</p> is the caterpillar rank of the hero who will be chasing, or <ref>me</ref> for the leader. When the caterpillar party is enabled, this command only works on the leader, and will do nothing for other heroes. Use <ref>suspendcaterpillar</ref> if you want to make the other heroes pathfind. Non-leader heroes do not treat NPCs as obstacles when they pathfind. The second argument <p>npc</p> is the NPC to chase. You can use an <ref>npcref</ref> or <ref>npcid</ref>. The third argument <p>stop when reached</p> can be true if you want the chasing hero to stop after the first time it reaches the destination NPC. If ommitted or false, the hero will keep chasing even after it reaches a moving destination NPC. The fourth argument <p>stuck ticks</p> is optional. If it is included, a hero who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If <p>stop ticks</p> is omitted or zero, the hero will keep pathfinding even if it gets stuck, and will not stop until it reaches the destination, or is stopped with the <ref>cancelherowalk</ref> command. Be careful if you are using <ref>waitforhero</ref> to wait for <ref>herochasesnpc</ref> when no <p>stuck ticks</p> timeout is used, since <ref>waitforhero</ref> might wait forever if the hero has no way to get to its destination.</description>
			<seealso>
				<ref>pathfindheroto</ref>
				<ref>cancelherowalk</ref>
				<ref>waitforhero</ref>
			</seealso>
		</command>
		<command id="cancelherowalk">
			<canon>cancel hero walk (who)</canon>
			<shortname>cancel hero walk</shortname>
			<description>
				If the specified hero is walking with a command like <ref>walkhero</ref>
				or pathfinding (due to a command like <ref>pathfindheroto</ref>
				or because the player clicked somewhere), they will stop.
				They are allowed to finish their current step to the next tile,
				so they will not end up misaligned with the tile grid.
				<note>
					If you want to stop a hero immediately without letting them finish their
					step, use <ref>walkhero</ref> with a distance of zero tiles, like:
					<example>cancel hero walk(who) # Cancel any pathfinding
walk hero(who, hero direction(hero), 0)</example>
					This will misalign the hero with the tile grid, breaking movement and
					wall and collision checking! You are responsible for realigning the hero
					afterwards somehow.
				</note>
			</description>
			<seealso>
				<ref>pathfindheroto</ref>
				<ref>herochasesnpc</ref>
				<ref>walkhero</ref>
				<ref>cancelnpcwalk</ref>
			</seealso>
		</command>
		<command id="heroischasing">
			<canon>hero is chasing (who)</canon>
			<shortname>hero is chasing</shortname>
			<description>If the specified hero is currently chasing an NPC, such as by clicking on the hero with mouse/touch controls, or a previous <ref>herochasesnpc</ref> command then return an <ref>npcref</ref>. If the hero is not currently chasing an NPC, returns false.</description>
			<seealso>
				<ref>herochasesnpc</ref>
				<ref>npcischasing</ref>
			</seealso>
		</command>
		<command id="setherodirection">
			<canon>set hero direction (who, direction)</canon>
			<shortname>set hero direction</shortname>
			<description>Makes the specified hero face in the specified <ref>direction</ref> (e.g. <ref>down</ref>). The hero is specified by their rank in the walkabout caterpillar, 0-3. Use <ref>me</ref> to affect the leader.</description>
			<example>set hero direction (me,right) # face right</example>
		</command>
		<command id="herodirection">
			<canon>hero direction (who)</canon>
			<shortname>hero direction</shortname>
			<description>Returns the specified hero&apos;s <ref>direction</ref>. The hero is specified by their rank in the walkabout caterpillar, 0-3</description>
		</command>
		<command id="setheroframe">
			<canon>set hero frame (who, frame)</canon>
			<shortname>set hero frame</shortname>
			<description>
				Sets the walking frame of the specified hero.
				<lb/>
				This is the number of the walkabout frame, starting from 0,
				in the group of frames for the hero's current facing direction.
				If the walkabout set has two frames per direction, this should be 0 or 1.
				<lb/>
				The hero is specified by their rank in the walkabout party, 0-3.
			</description>
			<seealso>
				<ref>heroframe</ref>
			</seealso>
		</command>
		<command id="heroframe">
			<canon>hero frame (who)</canon>
			<shortname>hero frame</shortname>
			<description>
				Returns the walking frame of the specified hero; see <ref>setheroframe</ref>.
				The hero is specified by their rank in the walkabout party, 0-3.
				<note>
					The number returned can be higher than the last valid frame,
					if you call it immediately after changing hero direction or spriteset.
				</note>
			</description>
		</command>
		<command id="setheroposition">
			<canon>set hero position (who, x, y)</canon>
			<shortname>set hero position</shortname>
			<description>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 <ref>puthero</ref> command.</description>
			<seealso>
				<ref>herox</ref>
				<ref>heroy</ref>
				<ref>heropixelx</ref>
				<ref>heropixely</ref>
			</seealso>
		</command>
		<command id="puthero">
			<canon>put hero (who, x, y)</canon>
			<shortname>put hero</shortname>
			<description>Moves a hero to a precise location on the map. The first argument is the hero&apos;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 <ref>setheroposition</ref> command. Normally you will use this command to escape the tile-based movement system.</description>
			<example># 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</example>
		</command>
		<command id="herox">
			<canon>hero X (who)</canon>
			<shortname>hero X</shortname>
			<description>Returns the specified hero&apos;s X position in tiles. Note that a hero's tile is the tile its top left corner is on.</description>
		</command>
		<command id="heroy">
			<canon>hero Y (who)</canon>
			<shortname>hero Y</shortname>
			<description>Returns the specified hero&apos;s Y position in tiles. Note that a hero's tile is the tile its top left corner is on.</description>
		</command>
		<command id="heropixelx">
			<canon>hero pixel X (who)</canon>
			<shortname>hero pixel X</shortname>
			<description>Returns the hero&apos;s X position on the map in pixels. To find the hero&apos;s position in tiles, use the <ref>herox</ref> function instead.</description>
		</command>
		<command id="heropixely">
			<canon>hero pixel Y (who)</canon>
			<shortname>hero pixel Y</shortname>
			<description>Returns the hero&apos;s Y position on the map in pixels. To find the hero&apos;s position in tiles, use the <ref>heroy</ref> function instead.</description>
		</command>
		<command id="forwardx">
			<canon>forward X (who)</canon>
			<shortname>forward X</shortname>
			<description>
				Returns the X position of the tile immediately in front of the specified hero.
				<p>who</p> is optional, defaulting to 0 (<ref>me</ref>), the leader.
				<lb/>
				Wraps over the edge of wrapping maps.
			</description>
		</command>
		<command id="forwardy">
			<canon>forward Y (who)</canon>
			<shortname>forward Y</shortname>
			<description>
				Returns the Y position of the tile immediately in front of the specified hero.
				<p>who</p> is optional, defaulting to 0 (<ref>me</ref>), the leader.
				<lb/>
				Wraps over the edge of wrapping maps.
			</description>
			<example># This will check if npc 1 is in front of the leading hero, and if so show a textbox,
# as if you spoke to the npc. "use npc (1)" instead would actually activate it.
if (npc X (1) == forward X &amp;&amp; npc Y (1) == forward Y) then(
   show text box (2)
)
</example>
		</command>
		<command id="heroz">
			<canon>hero Z (who)</canon>
			<shortname>hero Z</shortname>
			<description>Returns the specified hero&apos;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.</description>
			<seealso>
				<ref>setheroz</ref>
				<ref>npcz</ref>
			</seealso>
		</command>
		<command id="setheroz">
			<canon>set hero z (who, z)</canon>
			<shortname>set hero z</shortname>
			<description>
				Sets the Z location of the specified hero.
				The Z value is the number of pixels they are above the tile that they are 'standing' on.
				Useful for scripts where you want a hero to jump or levitate.
				All heroes normally have a Z value of 0 (even on maps with a foot offset:
				the foot offset is added to the Z value) unless they are riding a vehicle which rises.
				<note>
					Hero Z values are reset to 0 when you change map or dismount a vehicle, and aren't saved in saved games.
				</note>
			</description>
			<seealso>
				<ref>heroz</ref>
				<ref>setnpcz</ref>
			</seealso>
		</command>
		<command id="walkherotox">
			<canon>walk hero to x (who,x)</canon>
			<shortname>walk hero to x</shortname>
			<description>Makes the specified hero walk to a given X coordinate on the map</description>
		</command>
		<command id="walkherotoy">
			<canon>walk hero to y (who,x)</canon>
			<shortname>walk hero to y</shortname>
			<description>Makes the specified hero walk to a given Y coordinate on the map</description>
		</command>
		<command id="checkherowall">
			<canon>check hero wall (who,direction)</canon>
			<shortname>check hero wall</shortname>
			<description>
				Returns true if there is a wall blocking the hero from moving in the specified <ref>direction</ref>.
				No actual movement takes place.
				<note>
					This command should only be used when the hero is standing still and aligned with the tile grid.
					You can use the <ref>checkwallcollisionxy</ref> commands for much
					more flexible wall-checking, which works from any starting position on the map.
				</note>
			</description>
			<seealso>
				<ref>checknpcwall</ref>
			</seealso>
		</command>
		<command id="getherospeed">
			<canon>get hero speed (who)</canon>
			<shortname>get hero speed</shortname>
			<description>Returns the walking speed of the specified hero, in pixels per tick.</description>
			<seealso>
				<ref>setherospeed</ref>
			</seealso>
		</command>
		<command id="setherospeed">
			<canon>set hero speed (who, speed)</canon>
			<shortname>set hero speed</shortname>
			<description>
				Changes the walking speed (pixels per tick) of the specified hero, from 0 to 20.
				<p>who</p> is a caterpillar slot; use <ref>me</ref> to refer to the leader.
				Normally only the speed of the leader matters,
				unless you use <ref>suspendcaterpillar</ref>,
				because the whole party moves at the leader's speed.
				<p>speed</p> defaults to 4.
				Tiles are 20 pixels in size, and speeds that do not divide evenly or nearly
				evenly into 20 will result in jerky movement.
				So only use speeds 0, 1, 2, 3, 4, 5, 7, 10, or 20.
				<note>
					Changes to hero speed aren't saved in saved games!
				</note>
				<note>
					Hero speed is weird.
					It isn't actually a property of the hero, but of the caterpillar slot.
					So if you change the leader's speed and then a different hero is swapped
					into the leader position, the leader (and party) speed doesn't change.
					That's usually a good thing!
				</note>
				<danger>
					Don't set speed to zero while a hero is moving,
					it will cause the hero to stop mid-step and become misaligned with the grid
					and stuck.
					Wait for the hero to stop first or check with <ref>heroiswalking</ref>.
					(You probably shouldn't use speed 0 at all.)
				</danger>
			</description>
			<seealso>
				<ref>getherospeed</ref>
			</seealso>
		</command>
		<command id="teleporttomap">
			<canon>teleport to map (map, x, y)</canon>
			<shortname>teleport to map</shortname>
			<description>
				An alternative to <ref>usedoor</ref>, teleport to map moves you to a given x,y position (in tiles)
				on the specified map without the need to create a door-link on the map.
				Teleport to map does not fade to black.
				<note>
					An automatic <ref>wait</ref>(1) occurs immediately after this command.
				</note>
			</description>
		</command>
		<reference ref="gracefullydismountvehicle" />
		<command id="heroiswalking">
			<canon>hero is walking (who)</canon>
			<shortname>hero is walking</shortname>
			<description>Returns <ref>true</ref> if the specified hero (by position in the caterpillar) is currently walking. Returns <ref>false</ref> if the hero is standing still.</description>
		</command>
	</section>

	<section title="Doors">
		<reference ref="teleporttomap" />
		<command id="usedoor">
			<canon>use door (number, fade screen)</canon>
			<shortname>use door</shortname>
			<description>
				Instantly uses door <p>number</p>, just as if you had stepped into it.
				<p>fade screen</p> is an optional argument, defaulting to <tt>true</tt>.
				If true, the screen will fade out before using the door (even if it leads
				to the same map), and fade back in one tick later.
				Otherwise, there are no automatic screen fades.
				<note>
					An automatic <ref>wait</ref>(1) occurs immediately after this command.
				</note>
				<note>
					If you call <ref>fadescreenout</ref> immediately after <tt>use door</tt>,
					then the screen won't automatically fade back in afterwards.
					That's intentional, so that you can cancel the fade.
					(But you might have to do this in the map autorun script, if there is one,
					since it will suspend the script that called <tt>use door</tt>!)
				</note>
			</description>
		</command>
		<command id="doorexists">
			<canon>door exists (number, map)</canon>
			<shortname>door exists</shortname>
			<description>Returns <ref>true</ref> if there is a door with ID <p>number</p> on the specified <p>map</p>. If you leave out the map number, the current map will be assumed. This command is useful for avoiding script errors due to invalid door IDs.</description>
		</command>
		<command id="getdoorx">
			<canon>get door x (number, map)</canon>
			<shortname>get door x</shortname>
			<description>Returns the x coordinate (in tiles) of the door with ID <p>number</p> on the specified <p>map</p>. If you leave out the map number, the current map will be assumed.</description>
			<seealso>
				<ref>dooratspot</ref>
			</seealso>
		</command>
		<command id="getdoory">
			<canon>get door y (number, map)</canon>
			<shortname>get door y</shortname>
			<description>Returns the y coordinate (in tiles) of the door with ID <p>number</p> on the specified <p>map</p>. If you leave out the map number, the current map will be assumed.</description>
			<seealso>
				<ref>dooratspot</ref>
			</seealso>
		</command>
		<command id="getdoordestinationid">
			<canon>get door destination id (number, map)</canon>
			<shortname>get door destination id</shortname>
			<description>Returns the door ID of the door currently linked to by the door with ID <p>number</p> on the specified <p>map</p>. If you leave out the map number, the current map will be assumed. To get the door's location, use <ref>getdoorx</ref> and <ref>getdoory</ref>. If door <p>number</p> does not exist, or is not currently linked to any other door, then -1 is returned. <note>A door's destination can vary depending on tags. Check your doorlinks if you get unexpected results! There's no script command to get information about doorlinks currently inactive due to tags.</note></description>
			<seealso>
				<ref>getdoorx</ref>
				<ref>getdoory</ref>
				<ref>getdoordestinationmap</ref>
			</seealso>
		</command>
		<command id="getdoordestinationmap">
			<canon>get door destination map (number, map)</canon>
			<shortname>get door destination map</shortname>
			<description>Returns the map ID of the destination door currently linked to by the door with ID <p>number</p> on the specified <p>map</p>. If you leave out the map number, the current map will be assumed. If door <p>number</p> does not exist, or is not currently linked to any other door, then -1 is returned. <note>A door's destination can vary depending on tags. Check your doorlinks if you get unexpected results! There's no script command to get information about doorlinks currently inactive due to tags.</note></description>
		</command>
		<command id="dooratspot">
			<canon>door at spot (x, y)</canon>
			<shortname>door at spot</shortname>
			<description>Checks whether there is a door on the position given by <p>x</p>, <p>y</p> in tiles and if so returns its ID; otherwise returns -1. Note that the door might not have any active doorlink, or no door links at all. You can use <ref>getdoordestinationid</ref> to check if a door is active. If you want to script your own map transitions, you will find <ref>suspenddoors</ref> helpful.</description>
			<seealso>
				<ref>getdoorx</ref>
				<ref>getdoory</ref>
			</seealso>
		</command>
	</section>		<!-- Doors-->


	<section title="NPCs">
		<command id="npcreference">
			<canon>NPC reference (ID, copy, allow disabled?, pool)</canon>
			<shortname>NPC reference</shortname>
			<description>
				(See <ref>npcref</ref> for an explanation of NPC references.)
				<lb/>
				Returns a reference to one of the NPCs on the map, or <tt>false</tt>/<tt>0</tt>
				if the NPC you asked for is not found on the map.
				<lb/>
				<p>ID</p> is the <ref>npcid</ref> of the NPC to look up.
				The ID is the same number that appears in CUSTOM when you are editing NPCs or placing NPCs on the map.
				(Unlike other NPC commands, this one does not accept an NPC reference in place of the NPC ID.)
				<lb/>
				<p>copy</p> is optional.
				It specifies which copy (instance) of the NPC you want, in case there are more than one on the map.
				If you don't specify it, you will just get a reference to the first copy.
				Copies are counted starting from zero.
				You can see the copy number of NPCs in the Map Editor, at the bottom of the NPC,
				and using the F6 NPC debugger, by hoving the mouse over an NPC.
				<lb/>
				<p>allow disabled?</p> is optional, and defaults to <tt>false</tt>.
				If <tt>true</tt>, when used on a copy of an NPC hidden due to tag conditions,
				<tt>NPC reference</tt> will return a reference instead of returning <tt>false</tt>.
				<lb/>
				<p>pool</p> is an optional <ref>npcpool</ref>.
				If you don't specify which pool, then the ID is assumed to refer to the local pool for the current map.
				See also the <ref>globalnpcreference</ref> command.
				<lb/>
				If you plan on using the same NPC reference many times in a script you can store it in a <ref>variable</ref>.
			</description>
			<example>#---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</example>
			<seealso>
				<ref>npcatspot</ref>
				<ref>npcatpixel</ref>
				<ref>createnpc</ref>
				<ref>getnpcid</ref>
				<ref>npccopynumber</ref>
				<ref>npccopycount</ref>
				<ref>nextnpcreference</ref>
				<ref>globalnpcreference</ref>
			</seealso>
		</command>
		<command id="globalnpcreference">
			<canon>global NPC reference (ID, copy, allow disabled?)</canon>
			<shortname>global NPC reference</shortname>
			<altcommand id="globalnpc">
				<canon>global NPC (ID, copy, allow disabled?)</canon>
				<shortname>global NPC</shortname>
			</altcommand>
			<description>
				This command is the same as <ref>npcreference</ref> except that it takes a global NPC ID number instead of a local NPC ID number. If there is no copy of the global NPC ID on the current map, it will return false. This command cannot get references to NPCs located on different maps, and the NPC reference it returns is only valid on the current map.<lb/>
				<tt>global NPC</tt> is an alias for <tt>global NPC reference</tt>.
			</description>
			<seealso>
				<ref>npcreference</ref>
			</seealso>
		</command>
		<command id="nextnpcreference">
			<canon>next NPC reference (npcref)</canon>
			<shortname>next NPC reference</shortname>
			<description>This command is for looping over all the npcs on the map, in the same way that <ref>firstchild</ref> and <ref>nextsibling</ref> can be used to iterate over all the children of a slice. When called with no argument or <tt>0</tt>, it returns an <ref>npcref</ref> to the first NPC on the map. When <p>npcref</p> is an NPC reference it returns a reference to the next NPC. It returns 0 when there are no more NPCs, and skips over NPCs that are disabled by a tag condition (including used one-time-use NPCs). It's safe to delete NPCs while you're iterating over them (unlike <ref>nextsibling</ref>!), but creating NPCs at the same time might result in them getting skipped.
				<note>
					Tag-disabled NPCs are skipped.
				</note>
			</description>
			<example># 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)
)</example>
			<seealso>
				<ref>npcreference</ref>
				<ref>npcatspot</ref>
				<ref>npcatpixel</ref>
			</seealso>
		</command>
		<command id="npcatspot">
			<canon>NPC at spot (x, y, number)</canon>
			<shortname>NPC at spot</shortname>
			<description>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). <ref>false</ref> is returned if there is no NPC there, or <p>number</p> is too large (greater than or equal to the number of NPCs). You can also pass the constant <ref>getcount</ref> for the third argument to return the total number of NPCs on that tile. <note>An NPC's tile is the tile its top left corner is on.</note></description>
			<seealso>
				<ref>npcreference</ref>
			</seealso>
		</command>
		<command id="npcatpixel">
			<canon>NPC at pixel (x, y, number)</canon>
			<shortname>NPC at pixel</shortname>
			<description>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). <ref>false</ref> is returned if there is no NPC there, or <p>number</p> is too large (greater than or equal to the number of NPCs). You can also pass the constant <ref>getcount</ref> for the third argument to return the total number of NPCs on that tile.</description>
			<seealso>
				<ref>npcreference</ref>
			</seealso>
		</command>

		<section title="Moving and Positioning NPCs">

		<command id="walknpc">
			<canon>walk NPC (who, direction, distance)</canon>
			<shortname>walk NPC</shortname>
			<description>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 <ref>npcref</ref> or <ref>npcid</ref>. The second argument is a <ref>direction</ref>, e.g. <ref>north</ref>. 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 <ref>waitfornpc</ref> command. You should normally use the <ref>suspendnpcs</ref> command before moving NPCs to prevent their automatic movements from interfering with your scripted movements.</description>
		</command>
		<command id="walknpctox">
			<canon>walk NPC to X (who, X)</canon>
			<shortname>walk NPC to X</shortname>
			<description>Makes the specified NPC walk to a given X coordinate on the map. You can use either an <ref>npcref</ref> or <ref>npcid</ref> to specify which NPC will move.</description>
		</command>
		<command id="walknpctoy">
			<canon>walk NPC to Y (who, Y)</canon>
			<shortname>walk NPC to Y</shortname>
			<description>Makes the specified NPC walk to a given Y coordinate on the map. You can use either an <ref>npcref</ref> or <ref>npcid</ref> to specify which NPC will move.</description>
		</command>

		<reference ref="waitfornpc" />

		<command id="setnpcdirection">
			<canon>set NPC direction (who, direction)</canon>
			<shortname>set NPC direction</shortname>
			<description>Makes the specified NPC face in the specified <ref>direction</ref>, e.g. <ref>north</ref>. You can use either an <ref>npcref</ref> or <ref>npcid</ref> to specify which NPC will turn.</description>
		</command>
		<command id="npcdirection">
			<canon>NPC direction (who)</canon>
			<shortname>NPC direction</shortname>
			<description>Returns the specified NPC&apos;s <ref>direction</ref>.</description>
		</command>


		<command id="pathfindnpcto">
			<canon>pathfind NPC to (who, x, y, stuck ticks)</canon>
			<shortname>pathfind NPC to</shortname>
			<description>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 <p>who</p> is the NPC. You can use an <ref>npcref</ref> or <ref>npcid</ref>. The second argument is the destination <p>x</p> tile coordinate. The third argument is the destination <p>y</p> tile coordinate. The fourth argument <p>stuck ticks</p> is optional. If it is included, an NPC who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If <p>stop ticks</p> 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 <ref>cancelnpcwalk</ref> command. Be careful if you are using <ref>waitfornpc</ref> to wait for <ref>pathfindnpcto</ref> when no <p>stuck ticks</p> timeout is used, since <ref>waitfornpc</ref> might wait forever if the NPC has no way to get to its destination.</description>
			<seealso>
				<ref>npcchasesnpc</ref>
				<ref>cancelnpcwalk</ref>
				<ref>waitfornpc</ref>
			</seealso>
		</command>
		<command id="npcchasesnpc">
			<canon>NPC chases NPC (who, other who, stop when reached, stuck ticks)</canon>
			<shortname>NPC chases NPC</shortname>
			<description>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 <p>who</p> is the NPC who will be chasing. The second argument <p>other who</p> is the NPC to chase. You can use an <ref>npcref</ref> or <ref>npcid</ref>. The third argument <p>stop when reached</p> can be true if you want the chasing NPC to stop after the first time it reaches the destination NPC. If omitted or false, the NPC will keep chasing even after it reaches a moving destination NPC. The fourth argument <p>stuck ticks</p> is optional. If it is included, an NPC who gets stuck along the way for more than the specified number of ticks will give up and stop pathfinding to the target. If <p>stop ticks</p> 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 <ref>cancelnpcwalk</ref> command. Be careful if you are using <ref>waitfornpc</ref> to wait for <ref>npcchasesnpc</ref> when no <p>stuck ticks</p> timeout is used, since <ref>waitfornpc</ref> might wait forever if the NPC has no way to get to its destination.
			<lb/>
			If the destination NPC is deleted or disappears due to a tag condition, the chasing NPC stops.
			</description>
			<seealso>
				<ref>pathfindnpcto</ref>
				<ref>cancelnpcwalk</ref>
				<ref>waitfornpc</ref>
			</seealso>
		</command>
		<command id="npcischasing">
			<canon>NPC is chasing (who)</canon>
			<shortname>NPC is chasing</shortname>
			<description>If the specified NPC is currently chasing another NPC from a previous call to <ref>npcchasesnpc</ref> then return an <ref>npcref</ref> to the target NPC. If the NPC is not currently chasing another NPC, returns false.</description>
			<seealso>
				<ref>npcchasesnpc</ref>
				<ref>heroischasing</ref>
			</seealso>
		</command>

		<command id="npciswalking">
			<canon>NPC is walking (who)</canon>
			<shortname>NPC is walking</shortname>
			<description>Returns <ref>true</ref> if the specified NPC is currently walking, or <ref>false</ref> if standing still. You can use either an <ref>npcref</ref> or <ref>npcid</ref> to specify which NPC will be checked.</description>
		</command>

		<command id="cancelnpcwalk">
			<canon>cancel NPC walk (who)</canon>
			<shortname>cancel NPC walk</shortname>
			<description>If the specified NPC is walking with a command like <ref>walknpc</ref> or pathfinding with a command like <ref>pathfindnpcto</ref>, 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.
				<note>
					If you want to stop an NPC immediately without letting them finish their
					step, use <ref>walknpc</ref> with a distance of zero tiles, like:
					<example>cancel NPC walk(npc)  # Cancel any pathfinding
walk NPC(npc, NPC direction(npc), 0)</example>
					This will misalign the NPC with the tile grid, breaking movement and
					wall and collision checking! You are responsible for realigning the NPC
					afterwards somehow.
				</note>
			</description>
			<seealso>
				<ref>pathfindnpcto</ref>
				<ref>npcchasesnpc</ref>
				<ref>walknpc</ref>
				<ref>cancelherowalk</ref>
			</seealso>
		</command>

		<command id="setnpcframe">
			<canon>set NPC frame (who, frame)</canon>
			<shortname>set NPC frame</shortname>
			<description>
				Sets the walking frame of the specified NPC to 0 or 1.
				<lb/>
				This is the number of the walkabout frame, starting from 0,
				in the group of frames for the NPC's current facing direction.
				If the walkabout set has two frames per direction, this should be 0 or 1.
				<lb/>
				You can use either an <ref>npcref</ref> or <ref>npcid</ref> to specify which NPC will change.
</description>
			<seealso>
				<ref>npcframe</ref>
			</seealso>
		</command>
		<command id="npcframe">
			<canon>NPC frame (who)</canon>
			<shortname>NPC frame</shortname>
			<description>
				Returns the walking frame of the specified NPC. See <ref>setnpcframe</ref>.
				<note>
					The number returned can be higher than the last valid frame,
					if you call it immediately after changing NPC direction or spriteset.
				</note>
			</description>
		</command>
		<command id="setnpcposition">
			<canon>set NPC position (who, X, Y)</canon>
			<shortname>set NPC position</shortname>
			<description>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 <ref>npcref</ref> or <ref>npcid</ref> to specify which NPC will be moved.</description>
		</command>
		<command id="putnpc">
			<canon>put NPC (who,x,y)</canon>
			<shortname>put NPC</shortname>
			<description>Moves an NPC to a location on the map in pixels. The first argument is and <ref>npcreference</ref> 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 <ref>setnpcposition</ref> command.</description>
		</command>
		<command id="npcx">
			<canon>NPC X (who)</canon>
			<shortname>NPC X</shortname>
			<description>Returns the specified NPC&apos;s X position in tiles. Note that an NPC's tile is the tile its top left corner is on.</description>
			<seealso>
				<ref>npcatspot</ref>
			</seealso>
		</command>
		<command id="npcy">
			<canon>NPC Y (who)</canon>
			<shortname>NPC Y</shortname>
			<description>Returns the specified NPC&apos;s Y position in tiles. Note that an NPC's tile is the tile its top left corner is on.</description>
			<seealso>
				<ref>npcatspot</ref>
			</seealso>
		</command>
		<command id="npcpixelx">
			<canon>NPC pixel X (who)</canon>
			<shortname>NPC pixel X</shortname>
			<description>Returns the NPC&apos;s X position on the map in pixels. The argument is an <ref>npcreference</ref> or an NPC ID number. To find the NPC&apos;s position in tiles, use the <ref>npcx</ref> function instead.</description>
		</command>
		<command id="npcpixely">
			<canon>NPC pixel Y (who)</canon>
			<shortname>NPC pixel Y</shortname>
			<description>Returns the NPC&apos;s Y position on the map in pixels. The argument is an <ref>npcreference</ref> or an NPC ID number. To find the NPC&apos;s position in tiles, use the <ref>npcy</ref> function instead.</description>
		</command>
                <command id="npcz">
			<canon>NPC Z (who)</canon>
			<shortname>NPC Z</shortname>
			<description>Returns the specified NPC&apos;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.</description>
			<seealso>
				<ref>setnpcz</ref>
				<ref>heroz</ref>
			</seealso>
		</command>
                <command id="setnpcz">
			<canon>set NPC z (npc, z)</canon>
			<shortname>set NPC z</shortname>
			<description>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.</description>
			<seealso>
				<ref>npcz</ref>
				<ref>setheroz</ref>
			</seealso>
		</command>
		<command id="checknpcwall">
			<canon>check NPC wall (who, direction)</canon>
			<shortname>check NPC wall</shortname>
			<description>
				Returns true if there is a wall blocking the NPC from moving in the specified <ref>direction</ref>.
				No actual movement takes place.
				It does not matter whether the NPC is set to ignore walls or ignore the passmap.
				<note>
					This command should only be used when the NPC is standing still and aligned with the tile grid.
					You can use the <ref>checkwallcollisionxy</ref> commands for much
					more flexible wall-checking, which works from any starting position on the map.
				</note>
			</description>
			<seealso>
				<ref>checkherowall</ref>
			</seealso>
		</command>

		</section>   <!-- Moving NPCs -->

		<command id="getnpcid">
			<canon>get NPC ID (reference)</canon>
			<shortname>get NPC ID</shortname>
			<description>
				This command (along with <ref>npccopynumber</ref> and <ref>getnpcpool</ref>)
				is the inverse of <ref>npcreference</ref>.
				Returns an NPC's ID.
				If you give <p>get NPC ID</p> an <ref>npcref</ref> it will return the NPC's ID.
				If the reference is not valid then <p>get NPC ID</p> will return -1.
				This command can be used on tag-disabled NPCs too, returning their ID number.
				<note>
					Some cheeky users use this command to check whether any instances of a local NPC ID exists,
					since like nearly all commands you can give it an NPC ID instead of a reference.
					E.g. <tt>get NPC ID(4) == 4</tt> is true only if there's at least one copy of NPC 4.
				</note>
			</description>
			<seealso>
				<ref>getnpcpool</ref>
				<ref>changenpcid</ref>
			</seealso>
		</command>
		<command id="getnpcpool">
			<canon>get NPC pool (reference)</canon>
			<shortname>get NPC pool</shortname>
			<description>
				This command (along with <ref>getnpcid</ref> and <ref>npccopynumber</ref>)
				is the inverse of <ref>npcreference</ref>.
				This command takes an <ref>npcref</ref> and returns the ID of the <ref>npcpool</ref> that
				this NPC belongs to: either <p>pool:local</p> or <p>pool:global</p>.
				<p>reference</p> can't be an NPC ID.
			</description>
			<seealso>
				<ref>getnpcid</ref>
				<ref>changenpcid</ref>
			</seealso>
		</command>
		<command id="npccopynumber">
			<canon>NPC copy number (reference)</canon>
			<shortname>NPC copy number</shortname>
			<description>
				This command is the inverse of <ref>npcreference</ref> (along with <ref>getnpcid</ref>).
				That is, it returns the copy number that you need to pass to <ref>npcreference</ref>
				to get this NPC.
				If you give <p>NPC copy number</p> a reference to an NPC it will return which copy
				of that NPC definition it is - 0 if it's the first NPC, 1 is the second, etc.
				This number is also shown in the map editor at the bottom of an NPC,
				and in the F6 NPC debug mode when you mouse-over an NPC.
				<lb/>
				If the reference is not valid then <p>NPC copy number</p> will return -1.
				This command also works on references to tag-disabled NPCs.
			</description>
		</command>

		<command id="npccopycount">
			<canon>NPC copy count (ID, pool)</canon>
			<shortname>NPC copy count</shortname>
			<description>
				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 <ref>npcreference</ref> command.
				<lb/>
				The <p>pool</p> argument is optional (defaulting to <tt>pool:local</tt>),
				and tells which NPC pool <p>ID</p> refers to.
				<note>
					This command does not count tag-disabled NPCs.
					So if there are four copies of NPC 2 on a map, but they only appear
					when tag 5 is on, then <tt>npc copy count(2)</tt> returns
					4 when tag 5 is on and 0 when it isn't.
				</note>
			</description>
			<example>#---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</example>
		</command>
		<command id="changenpcid">
			<canon>change NPC ID (reference, new ID, pool)</canon>
			<shortname>change NPC ID</shortname>
			<description>
				This command takes an <ref>npcref</ref> and lets you change the ID number
				of the NPC it points to, and change between local and global NPC pools.
				This means that the NPC will now use a different picture, palette,
				walking speed, text box, everything.
				This change is not permanent. It only lasts until the next time a map gets loaded.
				The <p>pool</p> argument is an optional <ref>npcpool</ref>.
				If you don't specify a pool, then the NPC ID will be assumed to be the same pool that the NPC was previously part of.
				<lb/>
				If <p>reference</p> is an NPC ID then this command acts on the first NPC instance
				of that ID/pool, and the pool is not changed.
			</description>
			<seealso>
				<ref>getnpcid</ref>
				<ref>getnpcpool</ref>
			</seealso>
		</command>
		<command id="createnpc">
			<canon>create NPC (ID, X, Y, direction, pool)</canon>
			<shortname>create NPC</shortname>
			<description>
				This command will magically create a new copy of an NPC with the given <p>ID</p> number.
				You can specify an <p>X</p> and <p>Y</p> position where it will be created, and optionally a <ref>direction</ref> too
				(if you leave out the direction, the new NPC will be facing south).
				The <p>pool</p> argument is an optional <ref>npcpool</ref> defaulting to <tt>pool:local</tt>
				(NPC definitions local to the current map).
				<lb/>
				<tt>create NPC</tt> returns an <ref>npcref</ref> that you can use to refer to the new NPC in other
				commands like <ref>walknpc</ref>. 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.
			</description>
			<seealso>
				<ref>createglobalnpc</ref>
			</seealso>
		</command>
		<command id="createglobalnpc">
			<canon>create global NPC (ID, X, Y, direction)</canon>
			<shortname>create global NPC</shortname>
			<description>
				This command works the same as the <ref>createnpc</ref> command, except that the ID number always refers to the global pool of NPCs, instead of the local pool. The instance of this global NPC will be created on the current map, and only lasts until you leave the map. It is not global in the sense of moving from map to map.
			</description>
			<seealso>
				<ref>createnpc</ref>
			</seealso>
		</command>
		<command id="destroynpc">
			<canon>destroy NPC (reference)</canon>
			<shortname>destroy NPC</shortname>
			<description>
				This command will erase the specified NPC.
				You can use either an <ref>npcref</ref> or the NPC&apos;s ID number.
				The deletion is not permanent.
				Unless this is an NPC that you created with <ref>createnpc</ref>, the NPC will be back again next time the map gets loaded.
				If you need to permanently remove an NPC, use tags.
				<note>
					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.
				</note>
				<note>
					This command can be also be written as <p>delete NPC</p>.
				</note>
			</description>
		</command>
		<command id="deletenpc">
			<alias>destroynpc</alias>
			<shortname>delete NPC (reference)</shortname>
		</command>
		<command id="npcisdisabled">
			<canon>NPC is disabled (reference)</canon>
			<shortname>NPC is disabled</shortname>
			<description>This command returns true if the <ref>npcref</ref> <p>reference</p> points to an NPC who does not exist, or has been disabled because of tags or one-time-use.</description>
		</command>

		<section title="NPC Instance Data">
		<description>
			This section contains commands for getting and setting properties of individual NPC instances.
			See <secref>NPC Definitions</secref> for inspecting or modifying NPC definitions/types.
		</description>

		<command id="setnpcignoreswalls">
			<canon>set NPC ignores walls (who, value)</canon>
			<shortname>set NPC ignores walls</shortname>
			<description>
				Given an <ref>npcref</ref> or <ref>npcid</ref> (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.
				<p>value</p> should be true or false.
				<lb/>
				Turning this on doesn't let the NPC walk through the lead hero and other NPCs;
				you need <ref>setnpcobstructs</ref> for that.
				<lb/>
				This command is just like <ref>suspendnpcwalls</ref>/<ref>resumenpcwalls</ref>,
				but only affects a single npc.
				<note>
					Don't confuse this with <ref>alternpc</ref><tt>(who, NPCstat:ignore passmap, value)</tt>,
					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.
				</note>
			</description>
			<seealso>
				<ref>getnpcignoreswalls</ref>
				<ref>suspendnpcwalls</ref>
				<ref>setnpcobstructs</ref>
				<ref>alternpc</ref>
			</seealso>
		</command>
		<command id="getnpcignoreswalls">
			<canon>get NPC ignores walls (who)</canon>
			<shortname>get NPC ignores walls</shortname>
			<description>
				Given an <ref>npcref</ref> or <ref>npcid</ref> (in which case the first NPC with that ID is used),
				returns whether that NPC can walk through walls.
				<note>
					Don't confuse this with <ref>readnpc</ref><tt>(who, NPCstat:ignore passmap)</tt>,
					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.
				</note>
			</description>
			<seealso>
				<ref>setnpcignoreswalls</ref>
				<ref>readnpc</ref>
			</seealso>
		</command>
		<command id="setnpcmoves">
			<canon>set NPC moves (who, value)</canon>
			<shortname>set NPC moves</shortname>
			<description>
				Given an <ref>npcref</ref> or <ref>npcid</ref> (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 <ref>walknpc</ref>.
				<lb/>
				<p>value</p> should be true or false.
				<lb/>
				This command is just like <ref>suspendnpcs</ref>/<ref>resumenpcs</ref>,
				but only affects a single npc.
				<note>
					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.
				</note>
			</description>
			<seealso>
				<ref>getnpcmoves</ref>
				<ref>suspendnpcs</ref>
				<ref>alternpc</ref>
			</seealso>
		</command>
		<command id="getnpcmoves">
			<canon>get NPC moves (who)</canon>
			<shortname>get NPC moves</shortname>
			<description>Given an <ref>npcref</ref> or <ref>npcid</ref> (in which case the first NPC with that ID is used), returns <ref>true</ref> or <ref>false</ref> 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 <ref>setnpcmoves</ref> has been used.</description>
			<seealso>
				<ref>setnpcmoves</ref>
				<ref>readnpc</ref>
			</seealso>
		</command>
		<command id="setnpcobstructs">
			<canon>set NPC obstructs (who, value)</canon>
			<shortname>set NPC obstructs</shortname>
			<description>
				Given an <ref>npcref</ref> or <ref>npcid</ref> (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.
				<p>value</p> should be true or false.
				<lb/>
				This command is almost like <ref>suspendobstruction</ref>/<ref>resumeobstruction</ref>,
				but it only affects a single npc and it doesn't stop activation of step-on NPCs.

				<lb/>
				If you want to allow an NPC to walk through all obstacles, you also need
				to use the <ref>setnpcignoreswalls</ref> command.
			</description>
			<seealso>
				<ref>getnpcobstructs</ref>
				<ref>suspendobstruction</ref>
			</seealso>
		</command>
		<command id="getnpcobstructs">
			<canon>get NPC obstructs (who)</canon>
			<shortname>get NPC obstructs</shortname>
			<description>Given an <ref>npcref</ref> or <ref>npcid</ref> (in which case the first NPC with that ID is used), returns false if that NPC's obstruction has been suspended with <ref>setnpcobstructs</ref> (and is always true otherwise).</description>
			<seealso>
				<ref>setnpcobstructs</ref>
			</seealso>
		</command>
		<command id="setnpcusable">
			<canon>set NPC usable (who, value)</canon>
			<shortname>set NPC usable</shortname>
			<description>Given an <ref>npcref</ref> or <ref>npcid</ref> (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). <ref>usenpc</ref> will still work on the NPC. <p>value</p> should be true or false.</description>
			<seealso>
				<ref>getnpcusable</ref>
				<ref>alternpc</ref>
			</seealso>
		</command>
		<command id="getnpcusable">
			<canon>get NPC usable (who)</canon>
			<shortname>get NPC usable</shortname>
			<description>Given an <ref>npcref</ref> or <ref>npcid</ref> (in which case the first NPC with that ID is used), returns false if normal activation of that NPC has been suspended with <ref>setnpcusable</ref>. This is always true otherwise, even for NPC types which are not activatable.</description>
			<seealso>
				<ref>setnpcusable</ref>
			</seealso>
		</command>

		<command id="npcextra">
			<canon>NPC extra (who, which)</canon>
			<shortname>NPC extra</shortname>
			<description>
				Returns an extra data value previously set on NPC instance <p>who</p> with <ref>setnpcextra</ref>.
				<lb/>
				If you use an NPC ID for <p>who</p>, the first instance's data will be used.
				<p>extra</p> is the <ref>extradataindex</ref> to read.
				<lb/>
				This command is like <ref>getextra</ref> but only works on NPCs
				and accepts NPC IDs as well as NPC references.
			</description>
			<seealso>
				<ref>setnpcextra</ref>
			</seealso>
		</command>
		<command id="setnpcextra">
			<canon>set NPC extra (who, which, value)</canon>
			<shortname>set NPC extra</shortname>
			<description>
				Sets one of the extra data variables on the NPC instance <p>who</p>.
				If you use an NPC ID for <p>who</p>, the first instance's data will be used.
				<p>extra</p> is an <ref>extradataindex</ref>.
				<lb/>
				This command is like <ref>setextra</ref> but only works on NPCs
				and accepts NPC IDs as well as NPC references.
				See <ref>appendextra</ref> and <ref>resizeextra</ref> for more ways to
				modify zone extra data.
				<note>
					Like 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 <ref>savemapstate</ref>).
				</note>
			</description>
			<seealso>
				<ref>npcextra</ref>
			</seealso>
		</command>

		</section>  <!-- NPC Data -->

		<section title="NPC Definitions">
		<description>
			These are the only commands for inspecting or modifying NPC definitions/types.
			All other commands act on single NPC instances (see <secref>NPC Instance Data</secref>).
		</description>

		<command id="alternpc">
			<canon>alter NPC (who, NPCstat, value, pool)</canon>
			<shortname>alter NPC</shortname>
			<description>
				Changes the stats of an NPC type.
				<tt>alter NPC</tt> can be used for many purposes.
				The following constants for this command are available:
				<lb/>
				<ul>
					<li>alter NPC (who,NPCstat:picture,picture number)</li>
					<li>
						alter NPC (who,NPCstat:palette,palette number)
						<lb/>
						Set the palette number to -1 to use the default palette.
					</li>
					<li>
						alter NPC (who,NPCstat:move type,move type code)
						<lb/>
						Available move types:
						<ul>
							<li>NPCmovetype:standstill</li>
							<li>NPCmovetype:wander</li>
							<li>NPCmovetype:pace</li>
							<li>NPCmovetype:rightturns</li>
							<li>NPCmovetype:leftturns</li>
							<li>NPCmovetype:randomturns</li>
							<li>NPCmovetype:chaseyou (aka NPCmovetype:chaseyoumeandering)</li>
							<li>NPCmovetype:chaseyoudirect</li>
							<li>NPCmovetype:avoidyou (aka NPCmovetype:avoidyoumeandering)</li>
							<li>NPCmovetype:avoidyoudirect</li>
							<li>NPCmovetype:walkinplace</li>
							<li>NPCmovetype:followwallsright</li>
							<li>NPCmovetype:followwallsleft</li>
							<li>NPCmovetype:followwallsrightstopsforothers</li>
							<li>NPCmovetype:followwallsleftstopsforothers</li>
							<li>NPCmovetype:chaseyoupathfinding</li>
						</ul>
					</li>
					<li>alter NPC (who,NPCstat:move speed,speed)</li>
					<li>alter NPC (who,NPCstat:display text,text box number)</li>
					<li>
						alter NPC (who,NPCstat:when activated,when activated code)
						<lb/>
						Available whenactivated codes:
						<ul>
							<li>NPCwhenactivated:changedirection</li>
							<li>NPCwhenactivated:faceplayer</li>
							<li>NPCwhenactivated:donotfaceplayer</li>
						</ul>
					</li>
					<li>
						alter NPC (who,NPCstat:give item,item number + 1)
						... Note that the item number is offset + 1. A zero means no item.
					</li>
					<li>
						alter NPC (who,NPCstat:pushability,pushability code)
						<lb/>
						Available pushability codes:
						<ul>
							<li>NPCpush:off</li>
							<li>NPCpush:full</li>
							<li>NPCpush:horizontal</li>
							<li>NPCpush:vertical</li>
							<li>NPCpush:uponly</li>
							<li>NPCpush:rightonly</li>
							<li>NPCpush:downonly</li>
							<li>NPCpush:leftonly</li>
						</ul>
					</li>
					<li>
						alter NPC (who,NPCstat:activation,activation code)
						<lb/>
						Available activation codes:
						<ul>
							<li>NPCactivation:use</li>
							<li>NPCactivation:touch</li>
							<li>NPCactivation:stepon</li>
						</ul>
					</li>
					<li>
						alter NPC (who,NPCstat:onetime use flag,onetime flag ID)
						<lb/>
						The onetime flag (see <ref>checkonetime</ref>) is zero if the
						NPC is usable repeatedly.
					</li>
					<li>
						alter NPC (who,NPCstat:tag1,tag ID)
					</li>
					<li>
						alter NPC (who,NPCstat:tag2,tag ID)
						<lb/>
						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.
					</li>
					<li>alter NPC (who,NPCstat:script,script ID)</li>
					<li>alter NPC (who,NPCstat:script argument,number)</li>
					<li>alter NPC (who,NPCstat:vehicle,vehicle ID+1)</li>
					<li>alter NPC (who,NPCstat:default movement zone,zone ID)</li>
					<li>alter NPC (who,NPCstat:default avoidance zone,zone ID)</li>
					<li>
						alter NPC (who,NPCstat:ignore passmap, true or false)
						<lb/>
						This is for the NPC editor setting, not the <ref>setnpcignoreswalls</ref> command.
					</li>
					<li>
						alter NPC (who,NPCstat:pathfinding rule,rule)
						<lb/>
						The <tt>rule</tt> (see the F1 help page for the NPC editor for more info) is one of:
						<ul>
							<li>pathfinding:default</li>
							<li>pathfinding:npcs obstruct</li>
							<li>pathfinding:npcs ignored</li>
						</ul>
					</li>
				</ul>
				Normally you would only give an NPC ID number to alter NPC,
				but if you want to use an <ref>npcref</ref> 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.
				<lb/>
				The <p>pool</p> argument is an optional <ref>npcpool</ref>.
				It cannot be used if you are specifying the NPC by reference, since then that NPC reference's
				current npc pool will be used.
				<lb/>
				Changes to global npcs in <p>pool:global</p> will persist when you move to other maps,
				regardless of whether the map is set to remember NPC data.
				Those changes will be reset if you load a saved game or start a new game.
				<lb/>
				A good way to make use of <tt>alter NPC</tt> is to wrap it in your own script. For example:
				<example># Example alter NPC wrapper for changing NPC appearance
# Palette -1 means the default palette.
plotscript, change NPC, who, picture, palette = -1, begin
  alter NPC(who, NPCstat:picture, picture)
  alter NPC(who, NPCstat:palette, palette)
end</example>
			</description>
			<seealso>
				<ref>setnpcusable</ref>
				<ref>setnpcmoves</ref>
				<ref>setnpcignoreswalls</ref>
				<ref>setnpcobstructs</ref>
			</seealso>
		</command>
		<command id="readnpc">
			<canon>read NPC (who, NPCstat, pool)</canon>
			<shortname>read NPC</shortname>
			<description>Returns data such as picture, palette, walking speed, text box, etc. for an NPC. Use the same constants as <ref>alternpc</ref>.
			<lb/>
			The <p>pool</p> argument is an optional <ref>npcpool</ref>.
			It is only allowed when you specify the NPC by ID number.
			If you specify the NPC with an <ref>npcref</ref> then the pool is determined by the reference.
			<note>If you use this command to read the give item number, the result is offset + 1. A zero means no item.</note></description>
			<seealso>
				<ref>alternpc</ref>
			</seealso>
		</command>

		<command id="getnpcspeed">
			<canon>get NPC speed (who)</canon>
			<shortname>get NPC speed</shortname>
			<description>
				Returns the walking speed of the specified NPC (either NPC reference or ID number) in pixels per tick.
				<lb/>
				(This is just an alias for <ref>readnpc</ref><tt>(who, NPCstat:movespeed)</tt>).
			</description>
		</command>
		<command id="setnpcspeed">
			<canon>set NPC speed (who, speed)</canon>
			<shortname>set NPC speed</shortname>
			<description>
				Changes the walking speed of the specified NPC.
				<p>speed</p> defaults to 4.
				Tiles are 20 pixels in size, and speeds that do not divide evenly or nearly
				evenly into 20 will result in jerky movement.
				So only use speeds 0, 1, 2, 3, 4, 5, 7, 10, or 20.
				<lb/>
				Normally you would only use an NPC ID number for <p>who</p>,
				but if you want to use an <ref>npcreference</ref> it will still work.
				Just remember that <tt>set NPC speed</tt> changes every copy of the NPC on the map,
				not just the specific one you referenced.
				<lb/>
				(This is just an alias for <ref>alternpc</ref><tt>(who, NPCstat:movespeed, speed)</tt>).
				<warn>
					Don't set speed to zero while an NPC is moving,
					it will cause the NPC to stop mid-step and become misaligned with the grid.
					Get all instances of the NPC to stop first and wait for them,
					or check with <ref>npciswalking</ref>.
				</warn>
			</description>
		</command>

		</section>		<!-- NPC Definitions-->

	</section>  <!-- NPCs -->

	<section title="The Camera">
		<command id="camerapixelx">
			<canon>camera pixel X</canon>
			<shortname>camera pixel X</shortname>
			<description>Returns the X position of the top left corner of the screen in pixels.</description>
		</command>
		<command id="camerapixely">
			<canon>camera pixel Y</canon>
			<shortname>camera pixel Y</shortname>
			<description>Returns the Y position of the top left corner of the screen in pixels.</description>
		</command>
		<command id="camerafollowshero">
			<canon>camera follows hero (who)</canon>
			<shortname>camera follows hero</shortname>
			<description>Normally, the camera follows your leader. With this command, you can make the camera follow any hero you want. If you leave out the argument, the camera will follow your leader as normal.</description>
		</command>
		<command id="camerafollowsnpc">
			<canon>camera follows NPC (who)</canon>
			<shortname>camera follows NPC</shortname>
			<description>With this command, you can make the camera follow an NPC instead of the hero. If more than one copy of the specified NPC exists, the camera will follow the first one. To revert the camera to normal, use <ref>camerafollowshero</ref>.</description>
		</command>
		<command id="camerafollowsslice">
			<canon>camera follows slice (slice)</canon>
			<shortname>camera follows slice</shortname>
			<description>With this command, you can make the camera follow a slice instead of the hero. The slice's anchor point will be centered on the screen. To revert the camera to normal, use <ref>camerafollowshero</ref>. Note that this command usually only makes sense for slices that are parented to a map layer, or parented to something attached to a map layer like a hero or NPC.</description>
		</command>
		<command id="pancamera">
			<canon>pan camera (direction,distance,pixelstep)</canon>
			<shortname>pan camera</shortname>
			<description>This command causes the camera to stop following your leader and pan in the specified direction. The first argument is a <ref>direction</ref>, e.g. <ref>north</ref>. The distance is the number of tiles you want the camera to move before it stops. You can also specify the number of pixels you want the camera to move for each tick. if you leave the last argument out, the camera will move by 2 pixels per tick. This command is normally used with <ref>waitforcamera</ref>. To revert the camera to normal, use <ref>camerafollowshero</ref>.</description>
		</command>
		<command id="focuscamera">
			<canon>focus camera (x,y,speed)</canon>
			<shortname>focus camera</shortname>
			<description>This command causes the camera to focus itself on the specified X,Y tile coordinates of the map. These coordinates are in units of tiles. The third argument, the speed, tells how fast the camera will pan. If you do not specify a speed, the camera will pan 2 pixels per tick. This command is normally used with <ref>waitforcamera</ref>. To revert the camera to normal, use <ref>camerafollowshero</ref>.</description>
		</command>
		<command id="pixelfocuscamera">
			<canon>pixel focus camera (x,y,speed)</canon>
			<shortname>pixel focus camera</shortname>
			<description>This command causes the camera to focus itself on the specified X,Y pixel coordinates of the map. These coordinates are in units of pixels. The third argument, the speed, tells how fast the camera will pan. If you do not specify a speed, the camera will pan 2 pixels per tick. This command is normally used with <ref>waitforcamera</ref>. To revert the camera to normal, use <ref>camerafollowshero</ref>.</description>
		</command>
		<command id="putcamera">
			<canon>put camera (x,y)</canon>
			<shortname>put camera</shortname>
			<description>This command causes the top left corner of the camera to instantly jump to the specified X,Y pixel coordinates of the map. These coordinates are in units of pixels, not tiles. To position the camera by tiles, just multiply the tile position by 20. To revert the camera to normal, use <ref>camerafollowshero</ref>.</description>
		</command>
		<reference ref="waitforcamera"/>
	</section>

	<section title="Text Boxes">
		<command id="showtextbox">
			<canon>show text box (number)</canon>
			<shortname>show text box</shortname>
			<description>Displays the numbered text box, just as if you had talked to an NPC. The text box will not actually pop up until the next <ref>wait</ref> command. This command is most often used with the <ref>waitfortextbox</ref> command.</description>
			<example>show text box(2) # Show a text box
wait for text box # wait until the player continues</example>
		</command>
		<command id="advancetextbox">
			<canon>advance text box</canon>
			<shortname>advance text box</shortname>
			<description>Advances a text box just as if the player had pressed a key. For use while <ref>suspendboxadvance</ref> is active.</description>
			<example c="suspendboxadvance" />
		</command>
		<reference ref="waitfortextbox"/>
		<command id="currenttextbox">
			<canon>current text box</canon>
			<shortname>current text box</shortname>
			<description>Returns the number of the currently displayed text box, or -1 if there's none.</description>
			<seealso>
				<ref>speakingnpc</ref>
				<ref>showtextbox</ref>
				<ref>advancetextbox</ref>
			</seealso>
		</command>
		<command id="speakingnpc">
			<canon>speaking NPC</canon>
			<shortname>speaking NPC</shortname>
			<description>
				If the player activated an NPC which showed a textbox
				and the hero and NPC are still "speaking" (the textbox chain isn't done),
				returns the <ref>npcref</ref> for that NPC.
				Otherwise returns <tt>false</tt>.
				<warn>
					If you try to use this in a script called either AFTER or INSTEAD of
					a textbox, the textbox has closed by the time the script starts,
					so the NPC is no longer speaking and this will return <tt>false</tt>.
					<lb/>
					Likewise, if an NPC calls a script directly without showing a textbox
					this will just return <tt>false</tt>.
					But you don't need <p>speaking NPC</p> for scripts triggered directly from NPCs,
					because the script is given the NPC reference as its second argument (if any).
					(The first argument is customisable in the NPC editor.)
				</warn>
			</description>
			<seealso>
				<ref>currenttextbox</ref>
			</seealso>
		</command>
		<command id="stringfromtextbox">
			<canon>string from textbox (ID, textbox, line, ignored)</canon>
			<shortname>string from textbox</shortname>
			<description>Loads one of the <p>line</p>s of a <p>textbox</p> into a string <p>ID</p>. Valid numbers for <p>line</p> are 0-7. Trailing and leading whitespace is stripped from the line, and embedded codes like ${H1} in the string are automatically substituted.
			<note>This command is obsolete and exists only for compatibility with old games: It has been replaced with <ref>textboxline</ref>. The fourth argument does nothing.</note></description>
			<seealso>
				<ref>expandstring</ref>
				<ref>textboxline</ref>
			</seealso>
		</command>
		<command id="textboxline">
			<canon>textbox line (string ID, textbox, line, expand, strip)</canon>
			<shortname>textbox line</shortname>
			<description>Loads one of the <p>line</p>s of a <p>textbox</p> into a <p>string ID</p>. Valid numbers for <p>line</p> are 0-7. If <p>expand</p> is true (which is the default) codes such as ${H1} in the string will be substituted automatically. If <p>strip</p> is true (which is NOT the default), white space at the beginning and end of the string are removed.</description>
			<seealso>
				<ref>expandstring</ref>
				<ref>textboxtext</ref>
			</seealso>
		</command>
		<command id="textboxtext">
			<canon>textbox text (string ID, textbox, expand, strip)</canon>
			<shortname>textbox text</shortname>
			<description>
				Loads all lines of a <p>textbox</p> into a single <p>string ID</p>.
				If <p>expand</p> is true (which is the default) codes such as ${H1} in the string will be substituted automatically.
				If <p>strip</p> is true (which is NOT the default), white space at the beginning and end of the string are removed.
			</description>
			<seealso>
				<ref>textboxline</ref>
			</seealso>
		</command>
	</section>

	<section title="Triggering Stuff">
		<reference ref="showtextbox" />
		<command id="fightformation">
			<canon>fight formation (number)</canon>
			<shortname>fight formation</shortname>
			<description>Starts a battle with the numbered enemy formation. This command returns <ref>true</ref> on victory and <ref>false</ref> if the battle ends for any other reason. However if all heroes die the game will still end as normal unless you set a death script. In that case, <ref>false</ref> is returned after the death script has finished.
				The situations which cause <ref>true</ref> to be returned are:<lb/>
				<ul>
					<li>Normal victory</li>
					<li>An attack with the "Force battle victory" bit ends the battle</li>
				</ul>
				The situations which cause <ref>false</ref> to be returned are:<lb/>
				<ul>
					<li>All heroes died</li>
					<li>Player ran from battle</li>
					<li>An attack with the "Force battle loss &amp; heroes run away" bit ends the battle</li>
					<li>An attack with the "Force battle loss &amp; exit" bit ends the battle</li>
					<li>A timer with <ref>timerflag:critical</ref> runs out and ends the battle</li>
					<li>The end-battle-instantly debug key is used</li>
				</ul>
				<note>An automatic <ref>wait</ref>(1) occurs immediately after this command.</note>
			</description>
			<seealso>
				<ref>setdeathscript</ref>
			</seealso>
		</command>
		<command id="usenpc">
			<canon>use NPC (who)</canon>
			<shortname>use NPC</shortname>
			<description>
				Remotely trigger an NPC.
				You can use either an <ref>npcref</ref> or an <ref>npcid</ref>.
				Whatever actions are associated with triggering that NPC will be taken,
				text box, script, vehicle, item, whatever.
				<lb/>
				This command works even if the NPC has been made un-usable with <ref>setnpcusable</ref>
				and regardless of any "suspend" commands.
				However you can't activate an NPC that's tag-disabled (including one-time-use flags).
				<note>
					An automatic <ref>wait</ref><tt>(1)</tt> occurs immediately after this command.
				</note>
			</description>
			<seealso>
				<ref>gracefullydismountvehicle</ref>
			</seealso>
		</command>
		<reference ref="usedoor"/>
		<command id="useshop">
			<canon>use shop (shop)</canon>
			<shortname>use shop</shortname>
			<description>Takes you directly to a shop. You can specify the shop&apos;s ID number or its name in the form shop:name</description>
		</command>
		<reference ref="teleporttomap"/>
		<command id="forcemountvehicle">
			<canon>force mount vehicle (npc)</canon>
			<shortname>force mount vehicle</shortname>
			<description>Makes you mount the vehicle specified by NPC ID or NPC reference. Unlike <ref>usenpc</ref>, <p>force mount vehicle</p> does not bother checking the tile you are currently standing on. If the NPC is not a vehicle, nothing will happen.</description>
		</command>
		<command id="currentvehicleid">
			<canon>current vehicle id</canon>
			<shortname>current vehicle id</shortname>
			<description>Returns the vehicle ID number of the vehicle your hero is currently riding. If you are not riding a vehicle, it will return -1</description>
		</command>
		<command id="currentvehiclenpc">
			<canon>current vehicle npc</canon>
			<shortname>current vehicle npc</shortname>
			<description>Returns an NPC reference to the vehicle your hero is currently riding. If you are not riding a vehicle, it will return 0 or false</description>
		</command>
		<command id="gracefullydismountvehicle">
			<canon>gracefully dismount vehicle</canon>
			<shortname>gracefully dismount vehicle</shortname>
			<description>Attempts to dismount whatever vehicle you are riding. If you are not riding a vehicle, nothing will happen. If the vehicle is not in a location where you are allowed to dismount, then nothing will happen.</description>
			<seealso>
				<ref>dismountvehicle</ref>
			</seealso>
		</command>
		<command id="dismountvehicle">
			<canon>dismount vehicle</canon>
			<shortname>dismount vehicle</shortname>
			<description>
				Forces you to instantly dismount whatever vehicle you are riding without advancing the hero or allowing
				an airship to land. This will work even if the vehicle is located in a place where it would not normally allow dismounting. If you are not riding a vehicle, nothing will happen.
				<lb/>
				If you want normal dismounting behavior, as if the player had pressed the key to dismount a vehicle, use the <ref>gracefullydismountvehicle</ref> command instead.
			</description>
			<seealso>
				<ref>gracefullydismountvehicle</ref>
			</seealso>
		</command>
		<command id="gameover">
			<canon>game over</canon>
			<shortname>game over</shortname>
			<description>
				Resets the game and returns you to the title screen.
				This command is most useful for after-you-win-the-game type scripts,
				and for death-scripts that are triggered when you lose in battle.
				(The script calling <tt>game over</tt> ends immediately.)
				This command is similar to <ref>resetgame</ref>,
				the main difference being that if the title screen and load screen have both been disabled
				(the <tt>Skip title/load screen</tt> preference bitsets),
				<tt>game over</tt> will completely exit the game (either taking you back to the game select screen,
				or exiting to the operating system),
				while <ref>resetgame</ref> starts a new game.
				<note>
					The game will instantly transition to the title screen (or load menu, if the title is disabled)
					without a screen fade.
					So you probably want to call <ref>fadescreenout</ref> beforehand.
				</note>
				<note>
					By using <ref>resetgame</ref> or <ref>loadfromslot</ref> instead,
					you can pass arguments to the newgame and loadgame scripts.
				</note>
			</description>
		</command>
		<command id="resetgame">
			<canon>reset game(args...)</canon>
			<shortname>reset game</shortname>
			<description>
				Resets and starts a new game, skipping both title and load game screens.
				It can be necessary to use this instead of <ref>gameover</ref> so that the
				program will not exit if the title screen and load screen have both been disabled.
				It always resets the game back to the beginning and runs the new-game script.
				(The script calling <tt>reset game</tt> ends immediately.)
				You can pass any number of optional <p>args</p>, which become the arguments
				to the newgame script.
				For an example, see <ref>loadfromslot</ref>, which passes its arguments
				to the loadgame script in the same way.
				<danger>
					The default arguments of a newgame script (and all other triggered scripts)
					are currently ignored.
					If you don't pass enough <p>args</p>, then the remaining arguments default to zero.
				</danger>
				<note>
					Unlike <ref>gameover</ref>, the screen will always automatically
					fade out to black when calling <tt>reset game</tt>.
				</note>
			</description>
			<seealso>
				<ref>gameover</ref>
				<ref>loadfromslot</ref>
			</seealso>
		</command>
		<reference ref="rungame"/>
	</section>		<!-- Triggering Stuff-->

	<section title="Basic Display Commands">
		<command id="showvalue">
			<canon>show value (number, ...)</canon>
			<canon>show values (number, ...)</canon>
			<shortname>show value</shortname>
			<description>
				Displays one or more numbers at the bottom left corner of the screen,
				which remains there until overwritten or <ref>shownovalue</ref> is used.
				Useful for count-down timers, and for debugging complicated scripts.
				The number of arguments to this command is variable.
				See <ref>showvalueof</ref> and <ref>tracevalue</ref> for similar debugging tools.
				You can't print strings with this command; use <ref>showstring</ref> instead.
				<note>
					At most one of <ref>showvalue</ref>, <ref>showstring</ref>, and
					<ref>showvalueof</ref> can show at once.
				</note>
			</description>
			<example>
				show value(hero X(me), hero Y(me))   # Shows something like "  3   14" at the bottom of the screen
			</example>
		</command>
		<command id="showvalueof">
			<canon>show value of (expression, ...)</canon>
			<shortname>show value of</shortname>
			<description>
				Displays one or more <ref>expression</ref>s and their values at the bottom left corner of the screen,
				which remains there until overwritten or <ref>shownovalue</ref> is used.
				Useful for debugging complicated scripts.
				The number of arguments to this command is variable;
				each is printed as source text along with its value.
				You can't print strings with this command; use <ref>showstring</ref> instead.
				<note>
					At most one of <ref>showvalue</ref>, <ref>showstring</ref>, and
					<ref>showvalueof</ref> can show at once.
				</note>
			</description>
			<example># Shows something like "coins=0, hero X(me)=3, hero Y(me)=14" at the bottom of the screen
show value of(coins, hero X(me), hero Y(me))</example>
		</command>
		<command id="showstring">
			<canon>show string (ID)</canon>
			<shortname>show string</shortname>
			<description>Displays string #ID in the bottom left corner of the screen, as with the <ref>showvalue</ref> command. Use <ref>shownovalue</ref> to remove the string from the screen. Note that this command displays the value of the string at the moment the command was run. Later changes to the value of the string will not appear unless you run show string again. If you need real-time display of changes to a string, use <ref>showstringat</ref> or <ref>centerstringat</ref> instead.</description>
			<seealso>
				<ref>showvalue</ref>
				<ref>shownovalue</ref>
				<ref>showstringat</ref>
				<ref>centerstringat</ref>
			</seealso>
		</command>
		<command id="shownovalue">
			<canon>show no value</canon>
			<shortname>show no value</shortname>
			<description>Gets rid of the number in the bottom left corner of the screen after a <ref>showvalue</ref> or <ref>showstring</ref> command.</description>
		</command>

		<command id="cancelmapnamedisplay">
			<canon>cancel map name display</canon>
			<shortname>cancel map name display</shortname>
			<description>If the map name is being displayed, this command makes it disappear. For example, this may be useful if you want the map name to appear when you enter a map normally, but not when you jump to the map for a plotscripted cutscene.</description>
		</command>
		<command id="showbackdrop">
			<canon>show backdrop (number)</canon>
			<shortname>show backdrop</shortname>
			<description>
				Displays the specified full screen backdrop on the screen.
				This allows you to show full screen pictures without attaching them to text boxes.
				Use <ref>showmap</ref> or <tt>show backdrop(-1)</tt> to hide the backdrop and
				show the map again.
				You can also do some simple animation effects by calling show backdrop many times with <ref>wait</ref> commands in between.
				<lb/>
				Whether and which backdrop is displaying is saved in save games.
				<note>It's also possible to display backdrops as sprite slices using <ref>loadbackdropsprite</ref>.</note>
			</description>
			<seealso>
				<ref>showmap</ref>
				<ref>loadbackdropsprite</ref>
			</seealso>
		</command>
		<command id="showmap">
			<canon>show map</canon>
			<shortname>show map</shortname>
			<description>shows the map again after a <ref>showbackdrop</ref> command. Don't confuse this with <ref>showminimap</ref></description>
		</command>
	</section>		<!-- Basic Display Commands-->

	<section title="Opening Built-in Menus">
		<command id="mainmenu">
			<canon>main menu</canon>
			<shortname>main menu</shortname>
			<description>
				Opens the main menu; exactly equivalent to <ref>openmenu</ref>(0).
				If menu 0 is already open, it is brought to the top.
				Returns the menu handle of the new or existing instance of menu 0.
				<lb/>
				This isn't affected by anything that prevents the player from opening
				the main menu in the normal ways.
				<warn>
					If menu 0 does NOT have the "Allow gameplay &amp; scripts" bit set,
					then your script will pause as soon as the menu opens, until either
					it's closed or another menu with that bit ON is opened.
					And once the menu has closed the menu handle is invalid!
				</warn>
			</description>
		</command>
		<command id="showminimap">
			<canon>show mini map</canon>
			<shortname>show mini map</shortname>
			<description>Displays the mini-map</description>
		</command>
		<command id="itemsmenu">
			<canon>items menu</canon>
			<shortname>items menu</shortname>
			<description>Takes you directly to the items menu. Note that if the player uses an item that calls up a text box, the items menu command will behave like a <ref>showtextbox</ref> command for that text box.
			<note>If the player uses a item which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as <ref>wait</ref>).</note></description>
		</command>
		<command id="statusscreen">
			<canon>status screen (who)</canon>
			<shortname>status screen</shortname>
			<description>Takes you directly to a hero&apos;s status screen. Specify the hero using its position in the party 0-3. Use <ref>findhero</ref> if you want to specify the hero by name. The <ref>pickhero</ref> command can also be useful.</description>
		</command>
		<command id="spellsmenu">
			<canon>spells menu (who)</canon>
			<shortname>spells menu</shortname>
			<description>Takes you directly to a hero&apos;s spells menu. Specify the hero using its position in the party 0-3. Use <ref>findhero</ref> if you want to specify the hero by name. This command does nothing if you specify a hero slot out of range, or if you specify an empty slot.
			<note>If the player uses a spell which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as <ref>wait</ref>).</note>
			<example>
variable(slot)
slot := pick hero
if(slot >= 0) then(spells screen(slot))
			</example>
			</description>
		</command>
		<command id="equipmenu">
			<canon>equip menu (who, allow switching)</canon>
			<shortname>equip menu</shortname>
			<description>
				Takes you directly to a hero's equip menu.
				Specify the hero using its position in the party 0-3.
				Use <ref>findhero</ref> if you want to specify the hero by name.
				The <ref>pickhero</ref> command can also be useful.
				If you do not specify any hero, or if you specify -1, the first hero in the party will be used.
				The optional second argument <p>allow switching</p> says whether
				to allow the player to switch to a different hero by pressing
				Left and Right keys.
				It defaults to <tt>true</tt>.
			<example>
variable(slot)
slot := pick hero
if(slot >= 0) then(equip screen(slot))
			</example>
			</description>
		</command>
		<command id="savemenu">
			<canon>save menu (reallysave)</canon>
			<shortname>save menu</shortname>
			<description>Takes you directly to the save menu. Will return the number from 1 to 1000 of the slot the player saved in, or <ref>false</ref> if the player did not save. You can optionally pass an argument of <ref>false</ref> to make the menu display without actually saving.</description>
			<seealso>
				<ref>autosave</ref>
				<ref>saveinslot</ref>
			</seealso>
		</command>
		<command id="loadmenu">
			<canon>load menu (reallyload, show new game)</canon>
			<shortname>load menu</shortname>
			<description>
				Displays the load game menu (unless there are no saved games, in which case it's skipped).
				The player can pick a saved game to load or Exit/Cancel or New Game.
				New Game only appears if <p>show new game</p> is <tt>true</tt>, which is the default,
				together with the Exit button.
				(If <p>show new game</p> is <tt>false</tt> the button is labelled Cancel instead of Exit.)
				If there are no saved games, it's equivalent to selecting
				New Game, even if <p>show new game</p> is false.
				<lb/>
				The <p>reallyload</p> argument is optional, and defaults to <tt>true</tt>.
				When true,
				if the player picks a save it's loaded,
				if they pick New Game (or there are no saves) then the calling script continues,
				and if they select Exit/Cancel
				the game quits to the titlescreen if there is one or completely if not.
				<lb/>
				If you pass <tt>false</tt> as <p>reallyload</p> argument
				the menu only displays (or is skipped) without actually loading or quiting.
				You'll need to interpret the return value to find out which option the player selected:
				positive values (1 to 1000) are save slot numbers, 0 means New Game/menu skipped and -1 is Quit or cancelled (pressed ESC).
				<note>
				If you want the New Game option to actually reset the game,
				call <ref>resetgame</ref> afterwards:
<example>load menu
reset game</example>

				</note>
				<note>
					If you don't want the player to be able to quit the game, only load a game or continue, then
					write:
					<example>variable (slot)
slot := load menu (false)
if (slot > 0) then (load from slot (slot))</example>
				</note>
			</description>
			<seealso>
				<ref>loadfromslot</ref>
			</seealso>
		</command>
		<command id="ordermenu">
			<canon>order menu</canon>
			<shortname>order menu</shortname>
			<description>Takes you directly to the order menu, where you can change the order of the heroes in your active party.</description>
		</command>
		<command id="teammenu">
			<canon>team menu</canon>
			<shortname>team menu</shortname>
			<description>Takes you directly to the team menu, where you can change the order of the heroes in your active party, and swap heroes in and out of your reserve.</description>
		</command>
		<command id="innscreen">
			<canon>inn screen (price, skip fade)</canon>
			<shortname>inn screen</shortname>
			<description>Opens an Inn screen with a specific <p>price</p>. The optional <p>skip fade</p> argument defaults to false. If you set it to true, no fade effect will happen when sleeping at the inn. This command returns true if the player slept in the inn, and false if they cancelled.</description>
			<seealso>
				<ref>healparty</ref>
			</seealso>
		</command>
		<reference ref="debugmenu" />
	</section>		<!-- Opening Built-in Menus-->

	
	<section title="The Party">
		<description>
			See also the <secref>Hero Data</secref> section for inspecting or modifying individual heroes.
			<note>
			You should definitely read <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Ways_to_refer_to_a_hero_in_a_script">
			Ways to refer to a hero in a script</a> to understand the differences between hero ID numbers
			(including <tt>hero:name</tt> constants), hero party slots, and walkabout rank!
			</note>
		</description>

		<section title="Inspecting the Party">

		<command id="leader">
			<canon>leader</canon>
			<shortname>leader</shortname>
			<description>Returns the hero ID number (as given in the Edit Heroes menu) of the current caterpillar party leader.</description>
		</command>
		<command id="findhero">
			<canon>find hero (who)</canon>
			<shortname>find hero</shortname>
			<description>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 (constants) defined in your HSI file in the format <tt>hero:name</tt> for the ID number of the hero (as it has in the Edit Heroes 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 <ref>herobyslot</ref>.</description>
			<seealso>
				<ref>rankincaterpillar</ref>
			</seealso>
		</command>
		<command id="herobyslot">
			<canon>hero by slot (where)</canon>
			<shortname>hero by slot</shortname>
			<description>This command is the reverse of <ref>findhero</ref>. 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 (constants) defined in your HSI file in the format <tt>hero:name</tt>.</description>
		</command>
		<command id="rankincaterpillar">
			<canon>rank in caterpillar (who)</canon>
			<shortname>rank in caterpillar</shortname>
			<description>Searches through your active party to see if the specified hero is there, and returns the position in the walkabout caterpillar where the hero was found, or -1 if the hero was not found. Use the names (constants) defined in your HSI file in the format <tt>hero:name</tt>. This is particularly useful if you need to use a command like <ref>walkhero</ref> but you are not sure which position the hero is in.</description>
			<seealso>
				<ref>findhero</ref>
			</seealso>
		</command>
		<command id="herobyrank">
			<canon>hero by rank (where)</canon>
			<shortname>hero by rank</shortname>
			<description>This command is the reverse of <ref>rankincaterpillar</ref>. 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 (constants) defined in your HSI file in the format <tt>hero:name</tt>.</description>
		</command>
		<command id="roominactiveparty">
			<canon>room in active party</canon>
			<shortname>room in active party</shortname>
			<description>A function that returns the number of available spaces in your active party. It will return zero or <ref>false</ref> if there is no room.</description>
		</command>
		<command id="experiencereward">
			<canon>experience reward</canon>
			<shortname>experience reward</shortname>
			<description>Returns the amount of experience given to each hero by enemies as reward in the most recent battle (or 0 if no battles have been fought so far).</description>
		</command>
		</section>		<!-- Inspecting the Party-->

		<section title="Changing the Party">
		<command id="addhero">
			<canon>add hero (who)</canon>
			<shortname>add hero</shortname>
			<description>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.</description>
		</command>
		<command id="deletehero">
			<canon>delete hero (who)</canon>
			<shortname>delete hero</shortname>
			<description>
				Permanently deletes 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.
				<lb/>
				<p>who</p> is a hero ID: use a constant of form <tt>hero:name</tt>.
				<note>
					Deleting a hero causes the "Remove hero" global script to immediately be called, if it's set.
					<lb/>
					Any equipment held by the hero is lost, so use <ref>unequip</ref> first
					if you want to keep it.
					<lb/>
					However, for backcompat reasons, for now, some script commands can continue
					to be used on a party slot that contained a deleted hero and will still
					read the old data.  It's strongly recommended you don't rely on this. You
					should instead use <ref>swapouthero</ref> and <ref>lockhero</ref> to remove
					a hero from the active party and hide them from the player
					(and make sure "Swapped out and locked heroes" receive no experience from battles, in Battle Settings).
				</note>
			</description>
			<seealso>
				<ref>deleteherobyslot</ref>
			</seealso>
		</command>
		<command id="deleteherobyslot">
			<canon>delete hero by slot (slot)</canon>
			<shortname>delete hero by slot</shortname>
			<description>
				Permanently deletes the hero in the given slot in your party.
				Returns 0 if a hero was removed, or -1 if no hero was removed because the slot was
				already empty.
				See <ref>deletehero</ref> for some notes about what happens.
			</description>
			<seealso>
				<ref>deletehero</ref>
			</seealso>
		</command>

		<command id="swapinhero">
			<canon>swap in hero (who)</canon>
			<shortname>swap in hero</shortname>
			<description>
				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.
				This command works even if the hero is locked (see <ref>lockhero</ref>).
				<lb/>
				The return value is the new party slot, or -1 on failure.
				<lb/>
				<p>who</p> is a hero ID: use a constant of form <tt>hero:name</tt>.
			</description>
			<seealso>
				<ref>swapinherobyslot</ref>
			</seealso>
		</command>
		<command id="swapouthero">
			<canon>swap out hero (who)</canon>
			<shortname>swap out hero</shortname>
			<description>
				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 <tt>hero:name</tt>.
				If there is more than one copy of the hero in the party, then the first
				<lb/>
				This command works even if the hero is locked (see <ref>lockhero</ref>).
				<lb/>
				The return value is the new party slot, or -1 on failure.
				<danger>
					If the active party contains no heroes after swapping out the hero,
					then some hero will be swapped back into the active party, possibly
					the same one, and they might go into a different slot than they were!
					You should really avoid doing that.
				</danger>
			</description>
			<seealso>
				<ref>swapoutherobyslot</ref>
			</seealso>
		</command>
		<command id="swapinherobyslot">
			<canon>swap in hero by slot (slot)</canon>
			<shortname>swap in hero by slot</shortname>
			<description>
				Identical to <ref>swapinhero</ref> except it takes a hero by their party <p>slot</p> instead their ID.
			</description>
		</command>
		<command id="swapoutherobyslot">
			<canon>swap out hero by slot (slot)</canon>
			<shortname>swap out hero by slot</shortname>
			<description>
				Identical to <ref>swapouthero</ref> except it takes a hero by their party <p>slot</p> instead their ID.
			</description>
		</command>

		<command id="lockhero">
			<canon>lock hero (who)</canon>
			<shortname>lock hero</shortname>
			<description>
				Locking a hero prevents the player from moving the hero to a different slot in the party ("Team"/"Order") menu.
				Locked heroes in the active party cannot be moved into the reserve,
				and locked heroes in the reserve are hidden in the Team menu.
				<lb/>
				<p>who</p> is a hero ID: use a constant of form <tt>hero:name</tt>.
				<note>
					Does NOT prevent a hero from being moved by <ref>swapinhero</ref> or <ref>swapouthero</ref>.
					(Previously it was incorrectly documented that <tt>lock hero</tt> did prevent scripted swapping.)
				</note>
			</description>
		</command>
		<command id="unlockhero">
			<canon>unlock hero (who)</canon>
			<shortname>unlock hero</shortname>
			<description>
				Undoes <ref>lockhero</ref>, and makes it possible to move a hero in and out of the active party again or change their slot.
				<lb/>
				<p>who</p> is a hero ID: use a constant of form <tt>hero:name</tt>.
			</description>
		</command>
		<command id="lockherobyslot">
			<canon>lock hero by slot (slot)</canon>
			<shortname>lock hero by slot</shortname>
			<description>
				Identical to <ref>lockhero</ref> except it takes a hero by their party <p>slot</p> instead their ID.
			</description>
		</command>
		<command id="unlockherobyslot">
			<canon>unlock hero by slot (slot)</canon>
			<shortname>unlock hero by slot</shortname>
			<description>
				Identical to <ref>unlockhero</ref> except it takes a hero by their party <p>slot</p> instead their ID.
			</description>
		</command>
		<command id="heroislocked">
			<canon>hero is locked (who)</canon>
			<shortname>hero is locked</shortname>
			<description>
				Returns <tt>true</tt> if the hero is locked out of the active party (see <ref>lockhero</ref>).
				<lb/>
				<p>who</p> is a hero ID: use a constant of form <tt>hero:name</tt>.
			</description>
		</command>

		<command id="swapbyname">
			<canon>swap by name (name,name)</canon>
			<shortname>swap by name</shortname>
			<description>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</description>
		</command>
		<command id="swapbyposition">
			<canon>swap by position (slot1, slot2)</canon>
			<shortname>swap by position</shortname>
			<altcommand id="swapbyslot">
				<canon>swap by slot (slot1, slot2)</canon>
				<shortname>swap by slot</shortname>
			</altcommand>
			<description>
				Swaps the heroes in two slots in your party by their positions (ie, by party slot).
				You can also swap slots which don't contain a hero, for example
				to swap a hero in or out of the active party.
			</description>
		</command>

		<reference ref="healparty" />

		</section>		<!--Changing the Party-->
	</section>		<!-- The Party-->

	<section title="Money">
		<command id="partymoney">
			<canon>party money</canon>
			<shortname>party money</shortname>
			<description>Returns how much money your party has.</description>
		</command>
		<command id="getmoney">
			<canon>get money (amount)</canon>
			<shortname>get money</shortname>
			<description>Adds the specified amount to your party&apos;s money</description>
		</command>
		<command id="losemoney">
			<canon>lose money (amount)</canon>
			<shortname>lose money</shortname>
			<description>Subtracts the specified amount from your party&apos;s money.</description>
		</command>
		<command id="setmoney">
			<canon>set money (amount)</canon>
			<shortname>set money</shortname>
			<description>Changes the amount of money your party has.</description>
		</command>
		<command id="paymoney">
			<canon>pay money (amount)</canon>
			<shortname>pay money</shortname>
			<description>A function that checks to see if you have enough money to pay the amount specified. If you do, it subtracts it, and returns <ref>true</ref>. If you do not have enough, it subtracts nothing, but returns <ref>false</ref>. Intended for use in <ref>if</ref> statements.</description>
			<example>if(pay money(1000)) then, begin
	get item(item:uber sword)
end, else, begin
	show text box(61) # ha ha, no uber sword for you!
	wait for text box
end</example>
		</command>
		<command id = "moneyreward">
			<canon>money reward</canon>
			<shortname>money reward</shortname>
			<description>Returns how much money the party gained in the most recent battle (0 if there have been no battles so far).</description>
		</command>
	</section>

	<section title="Items">
		<description>Currently there are almost no script commands to get or set any item data, except for the name and description of an item.</description>

		<command id="useitem">
			<canon>use item (item)</canon>
			<shortname>use item</shortname>
			<description>Attempts to use an item as if you had selected it in the items menu. The argument is the item's ID number, or one of the <p>item:name</p> constants in your .hsi file. This command will only work if the item can be used outside of battle, either as a cure attack, or to teach a hero a spell, or to trigger a text box. This command does not care if you actually have any of the item in your inventory, and if it is a consumable item, you will not lose any. The return value is true if you successfully used the item, or false if the item was unusable or the user cancelled.
			<note>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 <ref>wait</ref>).</note></description>
			<seealso>
				<ref>useiteminslot</ref>
			</seealso>
		</command>
		<command id="getitemname">
			<canon>get item name (ID, item)</canon>
			<shortname>get item name</shortname>
			<description>This command will take the name of item #<p>item</p> and stick it in string #<p>ID</p>, overwriting its contents. This can be useful for "You got &lt;item&gt;!" type messages.</description>
		</command>
		<command id="getitemdescription">
			<canon>get item description (ID, item)</canon>
			<shortname>get item description</shortname>
			<description>This command will take the description of item #<p>item</p> and stick it in string #<p>ID</p>, overwriting its contents.</description>
		</command>
		<command id="getitemmaximumstacksize">
			<canon>get item maximum stack size (item)</canon>
			<shortname>get item maximum stack size</shortname>
			<description>Returns the maximum allowed size of a stack of items in the inventory. The <p>item</p> 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.</description>
			<seealso>
				<ref>itemcountinslot</ref>
				<ref>getinventorysize</ref>
			</seealso>
		</command>
		<reference ref="equipwhere" />
		<command id="equippableinslot">
			<canon>equippable in slot (item, slot)</canon>
			<shortname>equippable in slot</shortname>
			<description>
				Returns true if the item can be equipped in the specified slot
				(a constant of the form <tt>slot:weapon</tt>, etc, in your .hsi file),
				or false if it can't be equipped in that slot.
				If you need to know if the item is equippable by a specific hero, see <ref>equipwhere</ref> instead.
				<lb/>
				The <p>item</p> argument is the item to check the equipability of.
				You can use the item's ID number or a constant of the form <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>checkequipment</ref>
				<ref>equipwhere</ref>
			</seealso>
		</command>
		<command id="getitemvalue">
			<canon>get item value (item)</canon>
			<shortname>get item value</shortname>
			<description>
				Returns the value of an item. This is the default price for shops that don't override it.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
		</command>
		<command id="getitemteachspell">
			<canon>get item teach spell (item)</canon>
			<shortname>get item teach spell</shortname>
			<description>
				If this item teaches a spell, return the attack ID+1 or <tt>none</tt> (0) if it does not.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number,
				or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>teachspell</ref>
			</seealso>
		</command>
		<command id="getitemattackoutsidebattle">
			<canon>get item attack outside battle (item)</canon>
			<shortname>get item attack outside battle</shortname>
			<description>
				If this item does an attack when used outside of battle, return the attack ID + 1 or <tt>none</tt> (0) if it does not.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>mapcure</ref>
				<ref>useitem</ref>
				<ref>getitemattackinbattle</ref>
				<ref>getitemattackasweapon</ref>
			</seealso>
		</command>
		<command id="getitemattackinbattle">
			<canon>get item attack in battle (item)</canon>
			<shortname>get item attack in battle</shortname>
			<description>
				If this item does an attack when used from the item menu in battle, return the attack ID + 1 or <tt>none</tt> (0) if it does not.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>getitemattackoutsidebattle</ref>
				<ref>getitemattackasweapon</ref>
			</seealso>
		</command>
		<command id="getitemattackasweapon">
			<canon>get item attack as weapon (item)</canon>
			<shortname>get item attack as weapon</shortname>
			<description>
				Returns the attack ID+1 of the attack that this item will do if it is equipped as a weapon.
				For non-weapons it will return 1 meaning attack ID 0.
				If you wish to check whether or not an item is equippable as a wepon,
				use <ref>equippableinslot</ref> instead.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>getitemattackoutsidebattle</ref>
				<ref>getitemattackinbattle</ref>
				<ref>equippableinslot</ref>
			</seealso>
		</command>
		<command id="getitemtextbox">
			<canon>get item text box (item)</canon>
			<shortname>get item text box</shortname>
			<description>
				If this item shows a text box, return the text box ID or -1 if it does not.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>showtextbox</ref>
			</seealso>
		</command>
		<command id="getitemequipstatbonus">
			<canon>get item equip stat bonus (item, stat)</canon>
			<shortname>get item equip stat bonus</shortname>
			<description>
				Return the stat bonus that you would get if you equipped this item.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
				<lb/>
				The <p>stat</p> argument is the stat name constant in the form <tt>stat:name</tt>
				(for example, <tt>stat:hp</tt> or <tt>stat:attack</tt>).
			</description>
			<seealso>
				<ref>equipwhere</ref>
				<ref>equippableinslot</ref>
			</seealso>
		</command>
		<command id="getitemweaponpic">
			<canon>get item weapon pic (item)</canon>
			<shortname>get item weapon pic</shortname>
			<description>
				Returns the sprite id of the weapon picture used for this sprite.
				If you wish to check whether or not an item is equippable as a wepon,
				use <ref>equippableinslot</ref> instead.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>getitemweaponpal</ref>
				<ref>equippableinslot</ref>
			</seealso>
		</command>
		<command id="getitemweaponpal">
			<canon>get item weapon pal (item)</canon>
			<shortname>get item weapon pal</shortname>
			<description>
				Returns the palette id of the weapon picture used for this sprite. If the weapon sprite uses the default palette, returns -1.
				If you wish to check whether or not an item is equippable as a wepon,
				use <ref>equippableinslot</ref> instead.
				<lb/>
				The <p>item</p> argument is an item ID; you can refer to the item by number, or you can use the constants in the form of <tt>item:name</tt>.
			</description>
			<seealso>
				<ref>getitemweaponpic</ref>
				<ref>equippableinslot</ref>
			</seealso>
		</command>


		<section title="Inventory">
		<command id="getitem">
			<canon>get item (item, number)</canon>
			<shortname>get item</shortname>
			<description>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. This command returns the number of items actually added, which could be different from the number requested if the inventory is full.</description>
		</command>
		<command id="deleteitem">
			<canon>delete item (item, number)</canon>
			<shortname>delete item</shortname>
			<description>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</description>
		</command>
		<command id="iteminslot">
			<canon>item in slot (slot)</canon>
			<shortname>item in slot</shortname>
			<description>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 <ref>getinventorysize</ref>-1.</description>
			<seealso>
				<ref>setiteminslot</ref>
				<ref>itemcountinslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</ref>
			</seealso>
		</command>
		<command id="setiteminslot">
			<canon>set item in slot (slot, item)</canon>
			<shortname>set item in slot</shortname>
			<description>Change the item ID number at a specific slot in your inventory. The <p>slot</p> argument is the position in your inventory screen (slots are numbered from 0 to <ref>getinventorysize</ref>-1), and the <p>item</p> argument is the item ID number, or one of the <p>item:name</p> 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.</description>
			<seealso>
				<ref>iteminslot</ref>
				<ref>itemcountinslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</ref>
				<ref>getitemmaximumstacksize</ref>
			</seealso>
		</command>
		<command id="itemcountinslot">
			<canon>item count in slot (slot)</canon>
			<shortname>item count in slot</shortname>
			<description>Return the count of items at a specific slot in your inventory, or 0 if that slot is empty. Slots are numbered from 0 to <ref>getinventorysize</ref>-1.</description>
			<seealso>
				<ref>iteminslot</ref>
				<ref>setiteminslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</ref>
				<ref>getitemmaximumstacksize</ref>
			</seealso>
		</command>
		<command id="setitemcountinslot">
			<canon>set item count in slot (slot, count)</canon>
			<shortname>set item count in slot</shortname>
			<description>Change the count of items at a specific slot in your inventory. The <p>count</p> 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 <ref>getitemmaximumstacksize</ref>), 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.</description>
			<seealso>
				<ref>iteminslot</ref>
				<ref>setiteminslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</ref>
				<ref>getitemmaximumstacksize</ref>
			</seealso>
		</command>
		<reference ref="getitemmaximumstacksize" />
		<command id="useiteminslot">
			<canon>use item in slot (slot)</canon>
			<shortname>use item in slot</shortname>
			<description>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.
			<note>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 <ref>wait</ref>).</note></description>
			<seealso>
				<ref>useitem</ref>
			</seealso>
		</command>
		<command id="inventory">
			<canon>inventory (item)</canon>
			<shortname>inventory</shortname>
			<description>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 <ref>false</ref>. 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</description>
		</command>
		<command id="roomforitem">
			<canon>room for item (item)</canon>
			<shortname>room for item</shortname>
			<description>
				Returns the maximum number of the specified item that can be added to your inventory, taking into account the item's max stack size and existing stacks of the item in the inventory. (<ref>getitem</ref><tt>(item, 999999)</tt> would return the same number.)
				<lb/>
				<p>item</p> is an ID number; you can use constants of the form of <tt>item:itemname</tt>.
				<note>
					<ref>sortinventory</ref> will combine partial stacks of items, which might create some empty slots to allow
					fitting in more of other items.
				</note>
			</description>
			<seealso>
				<ref>getitemmaximumstacksize</ref>
			</seealso>
		</command>
		<command id="getinventorysize">
			<canon>get inventory size</canon>
			<shortname>get inventory size</shortname>
			<description>Returns the number of inventory slots.</description>
			<seealso>
				<ref>setinventorysize</ref>
			</seealso>
		</command>
		<command id="setinventorysize">
			<canon>set inventory size (new size)</canon>
			<shortname>set inventory size</shortname>
			<description>Changes the number of inventory slots that are available. Use the constant <p>inv:max</p> to restore the maximum value. The number you give will be rounded up to the nearest multiple of 3.</description>
			<seealso>
				<ref>getinventorysize</ref>
			</seealso>
		</command>
		<command id="sortinventory">
			<canon>sort inventory</canon>
			<shortname>sort inventory</shortname>
			<description>
				Sorts all inventory items, like the SORT menu item in the Inventory menu.
				Moves all items to the top of the inventory and reorders them according to the
				"Inventory autosort" setting in General Game Settings.
			</description>
		</command>
		<command id="itemsreward">
			<canon>items reward (number)</canon>
			<shortname>items reward</shortname>
			<description>
				Returns the ID numbers of the items dropped by enemies in the last battle
				(-1 if item reward <p>number</p> is not present).
				<p>number</p> counts from 0 up, where <tt>items reward(0)</tt> is the ID of
				the first gained item, etc.
				If the argument is <ref>getcount</ref>, then it returns the number of distinct
				item types acquired at the end of the battle.
				You can use it in a loop in order to display all item rewards (for example, in
				an after battle script), usually in tandem with <ref>itemsquantityreward</ref>.
				<example>plotscript, print items gained, begin
  # assume text box 123 contains text "Got ${S0} x ${S1}."
  variable (idx)
  for (idx, 0, items reward (get count) -- 1) do (
    clear string (0)
    append number (0, items quantity reward (idx))
    get item name (1, items reward (idx))
    show text box (123) # this should display e.g. "Got 2 x Herb."
    wait for text box
  )
end</example>
			</description>
			<seealso>
				<ref>itemsquantityreward</ref>
			</seealso>
		</command>
		<command id="itemsquantityreward">
			<canon>items quantity reward (number)</canon>
			<shortname>items quantity reward</shortname>
			<description>
				Similar to (and used together with) <ref>itemsreward</ref>, except it returns the quantities of corresponding
				items dropped in the last battle.
				<note>
					This commands returns the number of items that were dropped by enemies
					(the number stated in the victory display at the end of battle),
					which is less than the number the player actually gained
					(<ref>itemsgainedreward</ref> tells that) if there wasn't enough
					room for them in the inventory.
				</note>
			</description>
			<seealso>
				<ref>itemsreward</ref>
			</seealso>
		</command>
		<command id="itemsgainedreward">
			<canon>items gained reward (number)</canon>
			<shortname>items gained reward</shortname>
			<description>
				Similar to (and used together with) <ref>itemsreward</ref>, except it returns the quantities of corresponding
				items actually gained in the last battle, which is less than the number dropped
				(as told by <ref>itemsquantityreward</ref>) if the items didn't all fit.
				<example># Set this as the after-battle script. If there was an overflow it opens the
# Items menu to give the player the ability to drop something else to make room
#tplotscript, handle battle item overflow, begin
  # Assume text box 123 contains text "Found ${S0}x ${S1} but could only pickup ${S2}. Make some room."
  variable (idx, item, dropped, gained)
  for (idx, 0, items reward (get count) -- 1) do (
    item := items reward (idx)
    dropped := items quantity reward (idx)
    gained := items gained reward (idx)
    clear string (0)
    append number (0, dropped)
    get item name (1, item)
    clear string (2)
    append number (2, gained)

    show text box (123) # Displays e.g. "Found 3x Herb but could only pickup 1. ..."
    wait for text box

    items menu

    # You can check the return value to see whether it fitted
    get item (item, dropped -- gained)
  )
end</example>
			</description>
		</command>

		</section>		<!--Inventory-->

		<section title="Equipment">
		<command id="unequip">
			<canon>unequip (hero, slot)</canon>
			<shortname>unequip</shortname>
			<description>
				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 <ref>findhero</ref> 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.
				<note>
					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 <ref>gainherostat</ref>:
					<example>gain hero stat(who, stat:hp, 0)
gain hero stat(who, stat:mp, 0)</example>
				</note>
			</description>
			<seealso>
				<ref>forceequip</ref>
				<ref>checkequipment</ref>
			</seealso>
		</command>
		<command id="forceequip">
			<canon>force equip (hero, slot, item)</canon>
			<shortname>force equip</shortname>
			<description>
				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 <ref>findhero</ref> if you want to refer to the hero by name).
				The second argument is the slot to equip. Use the <tt>slot:weapon</tt>, <tt>slot:armor</tt>,
				etc. constants (or whatever you've named the slots).
				(These constants can been seen in the autogenerated .hsi file.)
				The third argument is the item to equip.
				You can use the item's ID number or the <tt>item:name</tt> constants from your .hsi file.
				The item equipped will be deducted from your inventory,
				but if you <p>force equip</p> an item that you do not already have then a free copy of it will be created.
				Returns true for success, or false for failure.
				Can fail if there is no room in the inventory to put the item that has to
				be unequipped to make room for the one you are force equipping.
				<note>
					When a hero's equipment changes, their current HP and MP stats aren't updated.
					See the Note at <ref>unequip</ref> for more information.
				</note>
			</description>
			<seealso>
				<ref>unequip</ref>
				<ref>equipwhere</ref>
				<ref>checkequipment</ref>
			</seealso>
		</command>
		<command id="equipwhere">
			<canon>equip where (hero, item)</canon>
			<shortname>equip where</shortname>
			<description>
				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 <ref>false</ref> 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 <ref>findhero</ref> 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.
				<lb/>
				If the item can be equipped in more than one different slot, this command only returns the first valid slot. Use the <ref>equippableinslot</ref> command if you need to check multiple slots.
				<note>
					When a hero's equipment changes, their current HP and MP stats aren't updated.
					See the Note at <ref>unequip</ref> for more information.
				</note>
			</description>
			<seealso>
				<ref>unequip</ref>
				<ref>checkequipment</ref>
				<ref>equippableinslot</ref>
			</seealso>
		</command>
		<command id="checkequipment">
			<canon>check equipment (hero, slot)</canon>
			<shortname>check equipment</shortname>
			<description>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 <ref>findhero</ref> 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.</description>
			<seealso>
				<ref>forceequip</ref>
				<ref>unequip</ref>
				<ref>equipwhere</ref>
			</seealso>
		</command>
		<command id="getdefaultweapon">
			<canon>get default weapon (hero)</canon>
			<shortname>get default weapon</shortname>
			<description>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 <ref>findhero</ref> if you want to refer to the hero by name).</description>
		</command>
		<command id="setdefaultweapon">
			<canon>set default weapon (hero, item)</canon>
			<shortname>set default weapon</shortname>
			<description>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 <ref>findhero</ref> 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&apos;s number or the item:name constants from your .HSI file.</description>
		</command>

		</section>		<!--Equipment-->

	</section>

	<section title="Effects">

                <section title="Music">
		<command id="playsong">
			<canon>play song (song)</canon>
			<shortname>play song</shortname>
			<description>Plays the specified song. Use the constants defined in your HSI file. They appear in the form of song:name</description>
		</command>
		<command id="playmusic">
			<alias>playsong</alias>
			<shortname>play music</shortname>
		</command>
		<command id="currentsong">
			<canon>current song</canon>
			<shortname>current song</shortname>
			<description>Returns the number of the currently playing song, or -1 if none.</description>
		</command>
		<command id="currentmusic">
			<alias>currentsong</alias>
			<shortname>current music</shortname>
		</command>
		<command id="stopsong">
			<canon>stop song</canon>
			<shortname>stop song</shortname>
			<description>Stops whatever music is currently playing.</description>
		</command>
		<command id="stopmusic">
			<alias>stopsong</alias>
			<shortname>stop music</shortname>
		</command>

		<command id="getmusictimems">
			<canon>get music time ms</canon>
			<shortname>get music time ms</shortname>
			<altcommand id="getsongtimems">
				<canon>get song time ms</canon>
				<shortname>get song time ms</shortname>
			</altcommand>
			<description>
				Returns the current position of the song in milliseconds, or -1 if this is not supported for the current audio format by the music backend.
				<warn>
					Whether a song is seekable may vary by engine build and operating system,
					but generally you should expect that seeking in a MIDI file is not supported.
				</warn>
			</description>
		</command>
		<command id="setmusictimems">
			<canon>set music time ms (pos)</canon>
			<shortname>set music time ms</shortname>
			<altcommand id="setsongtimems">
				<canon>set song time (pos)</canon>
				<shortname>set song time</shortname>
			</altcommand>
			<description>
				Seeks to/sets the position in milliseconds of the currently playing song.
				Returns <ref>true</ref> on success, or <ref>false</ref> on failure.
				<warn>
					Whether a song is seekable will vary by engine build and platform (operating system),
					for example, you can expect that seeking in a MIDI file is not supported on Windows.
				</warn>
				<note>
					Getting and setting the song time won't be accurate to the millisecond,
					e.g. because of buffering.
					For module music (with libxmp specifically, the current default playback library),
					you'll probably find that the song skips to the beginning of a pattern
					(a section of music), or does nothing if that pattern is already playing.
				</note>
			</description>
		</command>
		<command id="musicisseekable">
			<canon>music is seekable</canon>
			<shortname>music is seekable</shortname>
			<altcommand id="songisseekable">
				<canon>song is seekable</canon>
				<shortname>song is seekable</shortname>
			</altcommand>
			<description>
				Returns true if the currently playing song is capable of seeking with <ref>setmusictimems</ref>.
				This depends on the audio format of the song, the engine build and the platform.
			</description>
		</command>
		<command id="getmusiclengthms">
			<canon>get music length ms</canon>
			<shortname>get music length ms</shortname>
			<altcommand id="getsonglengthms">
				<canon>get song length ms</canon>
				<shortname>get song length ms</shortname>
			</altcommand>
			<description>
				Returns the duration of the currently playing song in milliseconds, or -1 if querying this is not supported for the current audio format/engine build/music library.
				<note>
					Most likely to work for OGG music (but still fails for all audio formats wth music_sdl, used on Android),
					least likely to work for MIDI music (fails on Windows).
				</note>
			</description>
		</command>

		<command id="setvictorymusic">
			<canon>set victory music (song)</canon>
			<shortname>set victory music</shortname>
			<description>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</description>
		</command>
		<command id="getvictorymusic">
			<canon>get victory music</canon>
			<shortname>get victory music</shortname>
			<description>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</description>
		</command>
		<command id="setambientmusic">
			<canon>set ambient music (song)</canon>
			<shortname>set ambient music</shortname>
			<description>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 <ref>savemapstate</ref> 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 <ref>song:silence</ref> and <ref>song:sameaslastmap</ref> for <p>song</p>, the default is silence.</description>
			<seealso>
				<ref>playsong</ref>
			</seealso>
		</command>
		<command id="getambientmusic">
			<canon>get ambient music</canon>
			<shortname>get ambient music</shortname>
			<description>Returns the song number of the map's ambient music, either a song ID or the constants <ref>song:silence</ref> or <ref>song:sameaslastmap</ref>.</description>
			<seealso>
				<ref>currentsong</ref>
			</seealso>
		</command>

		<command id="setmusicvolume">
			<canon>set music volume (volume)</canon>
			<shortname>set music volume</shortname>
			<description>
				Sets the volume at which music is played,
				<p>volume</p> being a number on the scale of 0 to 255, 0 being silent, 255 loudest.
				This is the same as the Music setting in the in-game Volume 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 usually not the maximum 255, so you should not hardcode fades to begin at volume 255.
				<note>
					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.
				</note>
			</description>
		</command>
		<command id="getmusicvolume">
			<canon>get music volume</canon>
			<shortname>get music volume</shortname>
			<description>
				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 Music setting in the in-game Volume menu.
			</description>
		</command>

		<command id="setglobalsoundvolume">
			<canon>set global sound volume (volume)</canon>
			<shortname>set global sound volume</shortname>
			<description>
				Sets the volume at which sound effects (sfx) are played,
				<p>volume</p> being a number on the scale of 0 to 255, 0 being silent, 255 loudest.
				This is the same as the Sound setting in the in-game Volume menu.
				Any currently playing sounds are affected, so this can be used for fading.
				If you want to temporarily change the volume
				you should record the original volume that the player has set and return to this later.
				The default volume is usually not the maximum 255, so you should not hardcode fades to begin at volume 255.
			</description>
		</command>
		<command id="getglobalsoundvolume">
			<canon>get global sound volume</canon>
			<shortname>get global sound volume</shortname>
			<description>
				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 Sound setting in the in-game Volume menu.
			</description>
		</command>

		</section>

		<section title="Master Palette and Screen Fades">
		<description>
			Everything displayed on-screen uses colors from a 256-color master palette.
			Screen fading works by momentarily changing the colors in the palette,
			for example shifting them all to black.
			The screen fade commands are a very common source of confusion because they pause
			the engine during the fade, and don't redraw the screen at all.
			Instead, what is already on-screen (which was drawn in the <b>previous</b> game tick)
			is re-displayed with a new palette. So
			<example>fade screen out
show backdrop (1)
fade screen out</example>
			will <b>not</b> work as expected: the screen fades out, then it fades back in,
			then the backdrop appears instantly.
			You need to add a <ref>wait</ref><tt>(1)</tt> immediately after the <ref>showbackdrop</ref>
			so that the engine repaints the screen (still entirely black) with the backdrop
			before it fades the backdrop into view.
			<lb/>
			This works because there's both a 'visible' master palette and a 'loaded' one.
			<ref>fadescreenout</ref> smoothly changes the visible one to be all the same color
			but doesn't modified the loaded one.
			<ref>fadescreenin</ref> changes the visible one smoothly back to the loaded one.
			<ref>loadpalette</ref>, <ref>tweakpalette</ref>, <ref>writecolor</ref>, etc
			modify the loaded palette but not the visible one.
			You need to call either <ref>fadescreenin</ref> or <ref>updatepalette</ref>
			to copy the loaded palette to the visible one to make your changes visible.
			<ref>updatepalette</ref> instantly changes the visible palette to the loaded one.
			<lb/>
			For example, this means you can fade between two different master palettes like so:
			<example>load palette(2)
fade screen in</example>
		</description>

		<command id="fadescreenout">
			<canon>fade screen out (red, green, blue)</canon>
			<shortname>fade screen out</shortname>
			<description>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 <ref>fadescreenin</ref>, fight a battle, or use a door.</description>
		</command>
		<command id="fadescreenin">
			<canon>fade screen in</canon>
			<shortname>fade screen in</shortname>
			<description>
				Fades the screen back to normal after a <ref>fadescreenout</ref> command,
				or smoothly applies the changes made with other palette commands such as <ref>greyscalepalette</ref>,
				<ref>tweakpalette</ref>,  <ref>loadpalette</ref>, <ref>resetpalette</ref>, and <ref>writecolor</ref>.
				<lb/>
				(You can also make palette changes take effect immediately without a fade using <ref>updatepalette</ref>.)
				<warn>
					Switching a game to 24-bit mode causes this command (but no others)
					to behave slightly differently when used after modifying the master palette
					(<ref>tweakpalette</ref>,, etc): it does an extra (implicit) <tt>wait(1)</tt>.
				</warn>
			</description>
		</command>
		<command id="loadpalette">
			<canon>load palette (palette number)</canon>
			<shortname>load palette</shortname>
			<description>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 <ref>updatepalette</ref> or <ref>fadescreenin</ref>, however the UI colors are changed immediately.</description>
		</command>
		<command id="updatepalette">
			<canon>update palette</canon>
			<shortname>update palette</shortname>
			<description>Instantly returns from fade screen out, and applies changes made by other palette command such as <ref>greyscalepalette</ref>, <ref>tweakpalette</ref>, <ref>resetpalette</ref>, and <ref>writecolor</ref>.</description>
		</command>
		<command id="greyscalepalette">
			<canon>greyscale palette (first, last)</canon>
			<shortname>greyscale palette</shortname>
			<description>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 <ref>updatepalette</ref> or <ref>fadescreenin</ref>. 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.</description>
		</command>
		<command id="tweakpalette">
			<canon>tweak palette (red, green, blue, first, last)</canon>
			<shortname>tweak palette</shortname>
			<description>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 <ref>updatepalette</ref> or <ref>fadescreenin</ref>. 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.</description>
		</command>
		<command id="resetpalette">
			<canon>reset palette</canon>
			<shortname>reset palette</shortname>
			<description>Reloads the default master palette and its user interface colors, undoing any changes you have made with other palette-altering commands such as <ref>tweakpalette</ref>, <ref>greyscalepalette</ref>, or <ref>loadpalette</ref>. Changes to the palette do not take effect until you call <ref>updatepalette</ref> or <ref>fadescreenin</ref>. 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).</description>
		</command>
		<command id="readcolor">
			<canon>read color (index, element)</canon>
			<shortname>read color</shortname>
			<description>Returns a color value from the master palette, in the range 0 to 63. The first argument is the index in the palette to read from, 0 to 255. The second argument is the color value to read, red, green, or blue. You can use 0,1, and 2, or you can use the predefined constants <ref>colorred</ref>, <ref>colorgreen</ref>, and <ref>colorblue</ref>. The counterpart to this is <ref>writecolor</ref>.
			<note>
				This command converts color components from the usual 0-255 down to 0-63,
				for compatibility with old OHRRPGCE versions which ran on DOS!
				For operation on full color values (0-255), use <ref>getcolor</ref>.
			</note>
			</description>
			<seealso>
				<ref>getcolor</ref>
			</seealso>
		</command>
		<command id="writecolor">
			<canon>write color (index, element, value)</canon>
			<shortname>write color</shortname>
			<description>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 <ref>colorred</ref>, <ref>colorgreen</ref>, and <ref>colorblue</ref>. 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 <ref>setcolor</ref> if you want to set color values in the 0-255 range. Changes do not take effect until you call <ref>updatepalette</ref> or <ref>fadescreenin</ref>. 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.</description>
			<seealso>
				<ref>setcolor</ref>
				<ref>readcolor</ref>
			</seealso>
		</command>
		<command id="getcolor">
			<canon>get color (index)</canon>
			<shortname>get color</shortname>
			<description>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 <ref>rgb</ref> for more details on its format.</description>
			<seealso>
				<ref>setcolor</ref>
				<ref>extractcolor</ref>
			</seealso>
		</command>
		<command id="setcolor">
			<canon>set color (index, value)</canon>
			<shortname>set color</shortname>
			<description>Updates the master palette with a new 32-bit color. The <p>value</p>, a 32-bit number representing the red, green and blue components of the color, can come from <ref>rgb</ref> or <ref>getcolor</ref>. Changes do not take effect until you call <ref>updatepalette</ref> or <ref>fadescreenin</ref>. 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.</description>
			<seealso>
				<ref>getcolor</ref>
				<ref>rgb</ref>
			</seealso>
		</command>
		<command id="findcolor">
			<canon>find color (r, g, b, searchstart)</canon>
			<shortname>find color</shortname>
			<description>
				Searches the master palette for the color most similar to the given <p>r</p>, <p>g</p>, <p>b</p>
				triple and returns its index, from 0 to 255.
				The color is selected using an approximate perceptual distance function.
				<lb/>
				<p>r</p>, <p>g</p>, <p>b</p> should be in the range 0-255
				(but out-of-bounds values are allowed, which weights those colors even more heavily).
				The <p>searchstart</p> argument is optional, and defaults to 0.
				It says how many colors at the beginning of the palette to ignore.
				For example, if <p>searchstart</p> is 1, then color 0 will never be returned,
				which is useful because 0 is often used as the transparent color.
			</description>
		</command>
		<command id="rgb">
			<canon>RGB (red, green, blue)</canon>
			<shortname>RGB</shortname>
			<description>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.</description>
			<seealso>
				<ref>extractcolor</ref>
			</seealso>
		</command>
		<command id="extractcolor">
			<canon>extract color (color, component)</canon>
			<shortname>extract color</shortname>
			<description>Takes a 32-bit color value (as returned by <ref>getcolor</ref>), and extracts the red, green or blue component, based on the <p>component</p> parameter. You may use the <ref>colorred</ref>, <ref>colorgreen</ref> and <ref>colorblue</ref> parameters to choose which one.</description>
			<seealso><ref>rgb</ref></seealso>
		</command>

		<reference ref="getuicolor" />
		<reference ref="setuicolor" />

		</section>

		<section title="Sound Effects">
		<command id="playsound">
			<canon>play sound (num, loop, preempt)</canon>
			<shortname>play sound</shortname>
			<description>
				Plays or resumes a sound effect.
				Pass <ref>true</ref> to <p>loop</p> if you want the sound effect to start over when it finishes
				instead of stopping (it defaults to false).
				Pass <ref>true</ref> to <p>preempt</p> if you want to automatically stop the sound before playing it.
				If <p>preempt</p> is <ref>false</ref> (which is the default), and the sound is already playing
				(and not paused) then this command will do nothing.
				<note>
					There isn't yet a way to play a sound effect twice at the same time.
				</note>
			</description>
			<seealso>
				<ref>stopsound</ref>
			</seealso>
		</command>
		<command id="stopsound">
			<canon>stop sound (num)</canon>
			<shortname>stop sound</shortname>
			<description>Stops a sound effect. If the sound is not playing, nothing will happen.</description>
			<seealso>
				<ref>playsound</ref>
			</seealso>
		</command>
		<command id="pausesound">
			<canon>pause sound (num)</canon>
			<shortname>pause sound</shortname>
			<description>Temporarily stops a sound effect. It can be resumed with <ref>playsound</ref>, which causes it to continue from whence it left off.</description>
			<seealso>
				<ref>playsound</ref>
			</seealso>
		</command>
		<command id="soundisplaying">
			<canon>sound is playing (num)</canon>
			<shortname>sound is playing</shortname>
			<description>Checks to see whether a sound effect is playing or not. Useful for synchronization, etc. Returns true if the sound is paused but not stopped.</description>
			<seealso>
				<ref>playsound</ref>
				<ref>stopsound</ref>
				<ref>waitforsound</ref>
			</seealso>
		</command>
		<command id="waitforsound">
			<canon>wait for sound (num)</canon>
			<shortname>wait for sound</shortname>
			<description>Waits until a sound effect has finished playing. Useful for synchronization, etc.</description>
			<seealso>
				<ref>soundisplaying</ref>
			</seealso>
		</command>

		<reference ref="getglobalsoundvolume" />
		<reference ref="setglobalsoundvolume" />

		</section>		<!-- Sound Effects-->
	</section>


	<section title="User Interface Colors and Box Styles">

		<command id="getuicolor">
			<canon>get ui color (color, autotoggle)</canon>
			<shortname>get ui color</shortname>
			<description>
				Look up which color a UI color is.
				<p>color</p> should normally be a <tt>ui:</tt> constant such as <tt>ui:menu item</tt>.
				See <ref>colorcode</ref> for a list of constants.
				Also, if <p>color</p> is a palette index (0 - 255) then it is returned unchanged.
				<lb/>
				<p>autotoggle</p> is optional, and defaults to false.
				If <tt>true</tt>, when you get certain UI colors that normally flash
				(for example, <tt>ui:selected item</tt>), the return value will change
				every tick according to the flashing, rather than just returning the value seen
				in the Edit User-Interface Colors menu.
			</description>
			<seealso>
				<ref>setuicolor</ref>
			</seealso>
		</command>
		<command id="setuicolor">
			<canon>set ui color (color, palette index)</canon>
			<shortname>set ui color</shortname>
			<description>
				Change a UI color.
				<p>color</p> should be a <tt>ui:</tt> constant such as <tt>ui:menu item</tt>.
				See <ref>colorcode</ref> for a list of constants.
				<p>palette index</p> should be a value 0-255, an index in the current master palette.
				<note>
					The change will be lost if you call <ref>loadpalette</ref>, <ref>resetpalette</ref>, quit the game, or load a game.
				</note>
			</description>
			<seealso>
				<ref>getuicolor</ref>
			</seealso>
		</command>

		<command id="getboxstylecolor">
			<canon>get box style color (box style)</canon>
			<shortname>get box style color</shortname>
			<description>
				Returns the background/fill color (0-255 master palette index) of <p>box style</p>,
				which should be 0 to 14.
			</description>
		</command>
		<command id="getboxstyleedgecolor">
			<canon>get box style edge color (box style)</canon>
			<shortname>get box style edge color</shortname>
			<description>
				Returns the edge color (0-255 master palette index) of <p>box style</p>,
				which should be 0 to 14.
				<lb/>
				This is the color of the simple line border;
				if the box style uses a box border spriteset (see <ref>getboxstyleborder</ref>)
				then the line border is usually not visible.
			</description>
		</command>
		<command id="getboxstyleborder">
			<canon>get box style border (box style)</canon>
			<shortname>get box style border</shortname>
			<description>
				Returns either <tt>border:line</tt> (which is -1) if a box style use a simple line
				border rather than a box border spriteset,
				or the spriteset ID of the border for <p>box style</p>,
				which should be 0 to 14.
			</description>
		</command>

	</section>


	<section title="Hero Data">

		<description>
			See also <secref>The Party</secref> section for commands for finding, adding, removing or swapping
			heroes in the party.
			<note>
			You should definitely read <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Ways_to_refer_to_a_hero_in_a_script">
			Ways to refer to a hero in a script</a> to understand the differences between hero ID numbers
			(including <tt>hero:name</tt> constants), hero party slots, and walkabout rank!
			</note>
		</description>


		<command id="renamehero">
			<canon>rename hero (heroid)</canon>
			<shortname>rename hero</shortname>
			<description>
				Pops up a name-editing box that allows you to change the name of a hero in the party.
				The game and scripts are paused while this menu is up.
				<lb/>
				The <tt>heroid</tt> argument is the hero&apos;s ID number, for example a constant in the format <tt>hero:name</tt>, unlike most hero commands!
				Use <ref>renameherobyslot</ref> to use a "who" argument.
				<lb/>
				The return value is true if the player renamed the hero, or false if they cancelled.
			</description>
		</command>
		<command id="renameherobyslot">
			<canon>rename hero by slot (who)</canon>
			<shortname>rename hero by slot</shortname>
			<description>
				Pops up a name-editing box that allows you to change the name of a hero in the party.
				The game and scripts are paused while this menu is up.
				<lb/>
				The <tt>who</tt> argument is the hero&apos;s position in the party as returned by <ref>findhero</ref>.
				<lb/>
				The return value is true if the player renamed the hero, or false if they cancelled.
			</description>
		</command>

		<section title="Hero Graphics">
		<command id="setheropicture">
			<canon>set hero picture (who, picture, type)</canon>
			<shortname>set hero picture</shortname>
			<description>
				Permanently changes a hero&apos;s picture.
				The first argument is the hero's position in the party.
				(Use <ref>findhero</ref> if you want refer to the hero by name.)
				The second argument is the index number of the picture to use (the sprite set of the appropriate type),
				and the last argument is a constant <ref>insidebattle</ref> or <ref>outsidebattle</ref> or <ref>heroportrait</ref>,
				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, <ref>outsidebattle</ref> is assumed.
				<lb/>
				The palette is not modified (but if the palette is "default" it will of course update to the spriteset's default).
			</description>
			<seealso>
				<ref>resetheropicture</ref>
			</seealso>
		</command>
		<command id="setheropalette">
			<canon>set hero palette (who, palette, type)</canon>
			<shortname>set hero palette</shortname>
			<description>Permanently changes a hero&apos;s 16-color palette. The first argument is the hero's position in the party. (Use <ref>findhero</ref> 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 <ref>insidebattle</ref> or <ref>outsidebattle</ref> or <ref>heroportrait</ref>, 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, <ref>outsidebattle</ref> is assumed.</description>
			<seealso>
				<ref>resetheropalette</ref>
			</seealso>
		</command>
		<command id="getheropicture">
			<canon>get hero picture (who, type)</canon>
			<shortname>get hero picture</shortname>
			<description>A function that returns the index number of a hero&apos;s picture. The first argument is the hero's position in the party as returned by <ref>findhero</ref>. The second argument is a constant <ref>insidebattle</ref> or <ref>outsidebattle</ref> or <ref>heroportrait</ref>, 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, <ref>outsidebattle</ref> is assumed.</description>
		</command>
		<command id="getheropalette">
			<canon>get hero palette (who, type)</canon>
			<shortname>get hero palette</shortname>
			<description>A function that returns the index number of a hero&apos;s 16-color palette. The first argument is the hero's position in the party as returned by <ref>findhero</ref>. The second argument is a constant <ref>insidebattle</ref> or <ref>outsidebattle</ref> or <ref>heroportrait</ref>, 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, <ref>outsidebattle</ref> is assumed.</description>
		</command>
		<command id="resetheropicture">
			<canon>reset hero picture (who, type)</canon>
			<shortname>reset hero picture</shortname>
			<description>
				Resets a hero&apos;s picture that was previously changed with <ref>setheropicture</ref> back to the default picture.
				The first argument is the hero's position in the party.
				(Use <ref>findhero</ref> if you want refer to the hero by name).
				The second argument is a constant <ref>insidebattle</ref> or <ref>outsidebattle</ref> or <ref>heroportrait</ref>,
				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, <ref>outsidebattle</ref> is assumed.
				<lb/>
				The palette is not modified (but if the palette is "default" it will of course update to the spriteset's default).
			</description>
			<seealso>
				<ref>setheropicture</ref>
				<ref>resetheropalette</ref>
			</seealso>
		</command>
		<command id="resetheropalette">
			<canon>reset hero palette (who, type)</canon>
			<shortname>reset hero palette</shortname>
			<description>Resets a hero&apos;s palette that was previously changed with <ref>setheropalette</ref> back to the default palette. The first argument is the hero's position in the party. (Use <ref>findhero</ref> if you want refer to the hero by name.) The second argument is a constant <ref>insidebattle</ref> or <ref>outsidebattle</ref> or <ref>heroportrait</ref>, 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, <ref>outsidebattle</ref> is assumed.</description>
			<seealso>
				<ref>setheropicture</ref>
			</seealso>
		</command>
		</section>		<!-- Hero Graphics-->

		<section title="Hero Battle Settings">
		<command id="getheroautobattle">
			<canon>get hero auto battle (who)</canon>
			<shortname>get hero auto battle</shortname>
			<description>Returns <tt>true</tt> if the hero is set to fight automatically in battles, or <tt>false</tt> if the hero will be under normal player control. <tt>who</tt> should be the hero's position in the party as returned by <ref>findhero</ref>.</description>
			<seealso>
				<ref>setheroautobattle</ref>
			</seealso>
		</command>
		<command id="setheroautobattle">
			<canon>set hero auto battle (who, bool)</canon>
			<shortname>set hero auto battle</shortname>
			<description>Changes whether or not the hero should fight automatically in battles (<tt>true</tt>), or if the hero will be under normal player control (<tt>false</tt>). <tt>who</tt> should be the hero's position in the party as returned by <ref>findhero</ref>.</description>
			<seealso>
				<ref>getheroautobattle</ref>
			</seealso>
		</command>
		</section>		<!-- Hero Battle Settings -->

		<section title="Hero Hand Position">
		<command id="getherohandx">
			<canon>get hero hand x (who, frame)</canon>
			<shortname>get hero hand x</shortname>
			<description>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 <p>hand:Attack A</p> and <p>hand:Attack B</p></description>
			<seealso>
				<ref>getherohandx</ref>
				<ref>getherohandy</ref>
				<ref>setherohandx</ref>
				<ref>setherohandy</ref>
				<ref>getdefaultherohandx</ref>
				<ref>getdefaultherohandy</ref>
			</seealso>
		</command>
		<command id="getherohandy">
			<canon>get hero hand y (who, frame)</canon>
			<shortname>get hero hand y</shortname>
			<description>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 <p>hand:Attack A</p> and <p>hand:Attack B</p></description>
			<seealso>
				<ref>getherohandx</ref>
				<ref>getherohandy</ref>
				<ref>setherohandx</ref>
				<ref>setherohandy</ref>
				<ref>getdefaultherohandx</ref>
				<ref>getdefaultherohandy</ref>
			</seealso>
		</command>
		<command id="setherohandx">
			<canon>set hero hand x (who, frame, new x)</canon>
			<shortname>set hero hand x</shortname>
			<description>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 <p>hand:Attack A</p> and <p>hand:Attack B</p> The third argument is the new x position.</description>
			<seealso>
				<ref>getherohandx</ref>
				<ref>getherohandy</ref>
				<ref>setherohandx</ref>
				<ref>setherohandy</ref>
				<ref>getdefaultherohandx</ref>
				<ref>getdefaultherohandy</ref>
			</seealso>
		</command>
		<command id="setherohandy">
			<canon>set hero hand y (who, frame, new y)</canon>
			<shortname>set hero hand y</shortname>
			<description>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 <p>hand:Attack A</p> and <p>hand:Attack B</p> The third argument is the new y position.</description>
			<seealso>
				<ref>getherohandx</ref>
				<ref>getherohandy</ref>
				<ref>setherohandx</ref>
				<ref>setherohandy</ref>
				<ref>getdefaultherohandx</ref>
				<ref>getdefaultherohandy</ref>
			</seealso>
		</command>
		<command id="getdefaultherohandx">
			<canon>get default hero hand x (who, frame)</canon>
			<shortname>get default hero hand x</shortname>
			<description>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 <p>hand:Attack A</p> and <p>hand:Attack B</p></description>
			<seealso>
				<ref>getherohandx</ref>
				<ref>getherohandy</ref>
				<ref>setherohandx</ref>
				<ref>setherohandy</ref>
				<ref>getdefaultherohandx</ref>
				<ref>getdefaultherohandy</ref>
			</seealso>
		</command>
		<command id="getdefaultherohandy">
			<canon>get default hero hand y (who, frame)</canon>
			<shortname>get default hero hand y</shortname>
			<description>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 <p>hand:Attack A</p> and <p>hand:Attack B</p></description>
			<seealso>
				<ref>getherohandx</ref>
				<ref>getherohandy</ref>
				<ref>setherohandx</ref>
				<ref>setherohandy</ref>
				<ref>getdefaultherohandx</ref>
				<ref>getdefaultherohandy</ref>
			</seealso>
		</command>
		</section>		<!-- Hero Hand Position-->

		<section title="Hero Stats">
		<command id="getherostat">
			<canon>get hero stat (who, stat, type)</canon>
			<shortname>get hero stat</shortname>
			<description>A function that returns one of a hero&apos;s stats. The first argument is the position of the hero you want to check in your party as as returned by <ref>findhero</ref>. 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 <ref>currentstat</ref> or <ref>maximumstat</ref> or <ref>basestat</ref>. Follow those links for explanations. If you leave out the type, <ref>currentstat</ref> will be assumed.</description>
			<seealso>
				<ref>setherostat</ref>
				<ref>gainherostat</ref>
				<ref>getlevelmp</ref>
				<ref>getherolevel</ref>
				<ref>totalexperience</ref>
				<ref>herototalelementalresistasint</ref>
				<ref>setenemystat</ref>
				<ref>getenemystat</ref>
			</seealso>
		</command>
		<command id="setherostat">
			<canon>set hero stat (who, stat, value, type)</canon>
			<shortname>set hero stat</shortname>
			<description>A command that changes one of a hero&apos;s stats. The first argument is the position of the hero you want to change in your party as returned by <ref>findhero</ref>. 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 <ref>currentstat</ref> or <ref>maximumstat</ref> or <ref>basestat</ref>. Follow those links for explanations. If you leave the last argument blank, <ref>currentstat</ref> 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.
				<note>
					Cap stats are ignored by this command.
					Use <ref>setcappedherostat</ref> 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 <ref>setherostatcap</ref>. Caps don't apply to base stats.
				</note>
				<note>
					The maximum and base values of a stat are tied together.
					Modifying the max will always modify the other by the same amount.
				</note>
				<note>
					Modifying a hero's HP will turn on or off the hero's Is Alive tag as needed,
					but will not trigger a game over if all the heroes have zero HP.
				</note>
				<note>
					If you want to permanently increase or decrease the max and base of a stat just use <ref>gainherostat</ref>.
				</note>
			</description>
			<example># 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</example>
			<example># Increase (or decrease, if amount is negative) the current value
# of a stat (so, make a temporary change) without violating stat caps or going below zero.
# You can use the "gain hero stat" command instead to make a permanent change.
script, adjust stat, hero slot, stat, amount, begin 
  variable (value)
  value := get hero stat(hero slot, stat, current stat) + amount
  if (value &lt; 0) then (value := 0)
  set capped hero stat(hero slot, stat, value, current stat)
end</example>
			<seealso>
				<ref>gainherostat</ref>
				<ref>getherostat</ref>
				<ref>setcappedherostat</ref>
				<ref>setherostatcap</ref>
				<ref>setenemystat</ref>
				<ref>getenemystat</ref>
			</seealso>
		</command>
		<command id="gainherostat">
			<canon>gain hero stat (who, stat, amount, reset to max)</canon>
			<shortname>gain hero stat</shortname>
			<description>
				Permanently increase or decrease one of a hero's stats.
				The base, maximum and current value of the stat are all changed, consistently.
				<lb/>
				The first argument <tt>who</tt> is the position in your party of the hero you want
				to change, as returned by <ref>findhero</ref>.
				<lb/>
				The second argument is the name of the <tt>stat</tt> that you want to change.
				The names of the stats are defined in your HSI file in the form <tt>stat:name</tt>,
				such as <tt>stat:hp</tt>.
				<lb/>
				The third argument is the <tt>amount</tt> to change the stat;
				it will be added to the base value and maximum value of the stat.
				<lb/>
				The optional fourth argument <tt>reset to max</tt> says how the current value of
				the stat should be updated.
				If <tt>false</tt> (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 <tt>reset to max</tt> is <tt>true</tt>, then the current value is set equal to the max.
				<lb/>
				The maximum and current stat values are capped to the stat cap, if any.
				(Base stats are by definition not capped.)
			</description>
			<seealso>
				<ref>getherostat</ref>
				<ref>setherostat</ref>
				<ref>setcappedherostat</ref>
				<ref>setherostatcap</ref>
			</seealso>
		</command>
		<command id="setcappedherostat">
			<canon>set capped hero stat (who, stat, value, type)</canon>
			<shortname>set capped hero stat</shortname>
			<description>A command that changes one of a hero&apos;s stats. The first argument is the position of the hero you want to change in your party as returned by <ref>findhero</ref>. 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 <tt>stat:name</tt>. The third argument is the new value of the stat. Unlike <ref>setherostat</ref>, 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 <ref>currentstat</ref> or <ref>maximumstat</ref> (<ref>basestat</ref> will also work but will not be capped). If you leave the last argument out, <ref>currentstat</ref> will be assumed.</description>
			<seealso>
				<ref>setherostat</ref>
				<ref>getherostatcap</ref>
				<ref>setherostatcap</ref>
				<ref>gainherostat</ref>
			</seealso>
		</command>
		<command id="getherostatcap">
			<canon>get hero stat cap (stat)</canon>
			<shortname>get hero stat cap</shortname>
			<description>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.</description>
			<seealso>
				<ref>setcappedherostat</ref>
				<ref>setherostatcap</ref>
			</seealso>
		</command>
		<command id="setherostatcap">
			<canon>set hero stat cap (stat, value)</canon>
			<shortname>set hero stat cap</shortname>
			<description>Set the maximum allowed value for a hero stat. The <p>stat</p> argument is the stat to affect; one of the stat:name constants defined in your HSI file. The <p>value</p> argument should be either greater than zero to set a cap, or 0/false to remove the cap for that stat.
<note>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.</note></description>
			<seealso>
				<ref>getherostatcap</ref>
			</seealso>
		</command>
		<command id="getlevelmp">
			<canon>get level MP (who, mp level slot, type)</canon>
			<shortname>get level MP</shortname>
			<description>Returns a hero's level MP (FF1-style MP). The argument <p>who</p> is the hero's position in the party, as returned by <ref>findhero</ref>. The argument <p>mp level slot</p> is a number from 0 to 7 that represents a row of spells in the hero's spell list (the level is NOT counted from 1 to 8, as it's displayed in-game and in the spell-list editor!) The optional third argument is either <ref>currentstat</ref> or <ref>maximumstat</ref>. If you leave out the type <ref>currentstat</ref> will be assumed. Pass <ref>maximumstat</ref> instead to get the hero's maximum amount of level MP for that slot. The maximum depends only on the hero's experience level.</description>
		</command>
		<command id="setlevelmp">
			<canon>set level MP (who, mp level slot, new value)</canon>
			<shortname>get level MP</shortname>
			<description>
				Changes one of a hero's level MP (FF1-style MP) numbers.
				The argument <p>who</p> is the hero's position in the party,
as returned by <ref>findhero</ref>.
				The argument <p>mp level slot</p> is a number from 0 to 7 that represents a row of spells in the hero's spell list
				(the level is NOT counted from 1 to 8, as it's displayed in-game and in the spell-list editor!)
				The argument <p>new value</p> is the new number of level MP points.
				Each point lets the player cast one spell from that row.
				<lb/>
				This changes the current value of a Level MP stat, therefore changes
				will be erased if the hero levels up or otherwise has their MP restored
				(e.g. by an inn).
				There's not yet any command to make a permanent change (to maximum level MP).
			</description>
		</command>
		<command id="herouseslevelmp">
			<canon>hero uses level MP (who)</canon>
			<shortname>hero uses level MP</shortname>
			<description>Returns true if a hero makes use of level MP (FF1-style MP). The argument <p>who</p> is the hero's position in the party, as returned by <ref>findhero</ref>. This will be true if the hero has at least one named spell list set to use level MP, and that spell list is included in their battle menu. This is the same logic that is used internall to decide if Level MP will be displayed on the Status screen.</description>
		</command>
		<command id="herobasestatatlevel">
			<canon>hero base stat at level (hero id, stat name, level)</canon>
			<shortname>hero base stat at level</shortname>
			<description>
				Returns what a hero's <ref>basestat</ref> (raw stat with no equipment bonuses) would be at a given level.<lb/>
				<p>hero id</p> is the hero ID number or a hero constant in the form of <tt>hero:name</tt>.<lb/>
				<p>stat name</p> is a constant in the form of <tt>stat:name</tt> such as <tt>stat:hp</tt>.<lb/>
				<p>level</p> is the level number to look up the stat for.<lb/>
				<note>This command takes hero ID. If you need to use the hero position in the party, use <ref>herobyslot</ref>. If you need to use the hero caterpillar rank, use <ref>herobyrank</ref></note>
				<note>This command ignores stat caps. You will need to also use the <ref>getherostatcap</ref> command if you need to check that.</note>
			</description>
			<example>
# Show what the base HP of the leader would be at level 99
variable(hero id)
hero id := hero by rank(me)
show value(hero base stat at level(hero id, stat:hp, 99))
</example>
			<seealso>
				<ref>getherostat</ref>
				<ref>resetherobasestat</ref>
			</seealso>
		</command>
		<command id="resetherobasestat">
			<canon>reset hero base stat (who, stat name)</canon>
			<shortname>reset hero base stat</shortname>
			<description>
				Reset the <ref>basestat</ref> (raw stat with no equipment bonuses) for a hero to whatever it should be for their current experience level. This discards any base stat or max stat changes that were done by <ref>setherostat</ref> or by out-of-battle item attacks that target max hp<lb/>
				<p>who</p> is the hero slot in the part.  in a party slot (use <ref>findhero</ref> if you want to refer to the hero by <tt>hero:name</tt> constants).<lb/>
				<p>stat name</p> is a constant in the form of <tt>stat:name</tt> such as <tt>stat:hp</tt>.<lb/>
				<note>This command respects stat caps. Stat caps will be re-applied after the base stat is reset.</note>
			</description>
			<seealso>
				<ref>setherostat</ref>
				<ref>herobasestatatlevel</ref>
			</seealso>
		</command>

		<command id="healparty">
			<canon>heal party (revive dead heroes)</canon>
			<shortname>heal party</shortname>
			<description>
				Restores the HP, MP and level MP of the active party heroes to 100%,
				just like inns or the textbox "Restore HP &amp; MP" conditional do.
				<lb/>
				The optional <p>revive dead heroes</p> argument tells whether
				heroes with 0 HP should be healed. If omitted, the General Preference
				Bitset "Inns Don't Revive Dead Heroes" determines the default.
			</description>
		</command>

		<command id="herobaseelementalresistasint">
			<canon>hero base elemental resist as int (who, element)</canon>
			<shortname>hero base elemental resist as int</shortname>
			<description>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 <p>who</p> is the hero's position in the party, as returned by <ref>findhero</ref>. The argument <p>element</p> 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.<note>When floating point support is added to HamsterSpeak, an alternative to this command will be added.</note></description>
			<seealso>
				<ref>setherobaseelementalresist</ref>
				<ref>herototalelementalresistasint</ref>
			</seealso>
		</command>
		<command id="setherobaseelementalresist">
			<canon>set hero base elemental resist (who, element, percent)</canon>
			<shortname>set hero base elemental resist</shortname>
			<description>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 <p>who</p> is the hero's position in the party, as returned by <ref>findhero</ref>. The argument <p>element</p> is a number from 0 to whatever the highest enabled element is. The argument <p>percent</p> 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.<note>Unlike the elemental resist editors in Custom, you can't use fractions of a percent here.</note></description>
			<seealso>
				<ref>herobaseelementalresistasint</ref>
			</seealso>
		</command>
		<command id="herototalelementalresistasint">
			<canon>hero total elemental resist as int (who, element)</canon>
			<shortname>hero total elemental resist as int</shortname>
			<description>Gets the amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. The argument <p>who</p> is the hero's position in the party, as returned by <ref>findhero</ref>. The argument <p>element</p> 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.<note>When floating point support is added to HamsterSpeak, an alternative to this command will be added.</note></description>
			<seealso>
				<ref>herobaseelementalresistasint</ref>
			</seealso>
		</command>

		<section title="Experience and Levels">
		<command id="getherolevel">
			<canon>get hero level (who)</canon>
			<shortname>get hero level</shortname>
			<description>A function that returns a hero&apos;s current level. The argument is the position of the hero you want to check in your party as as returned by <ref>findhero</ref>. The return value with be your current level, from 0 to 99</description>
			<seealso>
				<ref>setherolevel</ref>
				<ref>totalexperience</ref>
			</seealso>
		</command>
		<command id="setherolevel">
			<canon>set hero level (who, level, forgetspells)</canon>
			<shortname>set hero level</shortname>
			<description>A command that sets a hero&apos;s current level. The first argument is the position of the hero you want to change in your party as as returned by <ref>findhero</ref>. 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&apos;s level, which will cause spells to be forgotten, unless the optional 3rd argument (defaulting to true) is set as false.</description>
			<seealso>
				<ref>getherolevel</ref>
				<ref>herolevelled</ref>
				<ref>spellslearnt</ref>
				<ref>setexperience</ref>
			</seealso>
		</command>
		<command id="setexperience">
			<canon>set experience (who, experience, allowforget)</canon>
			<shortname>set experience</shortname>
			<description>Sets a hero&apos;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 <ref>findhero</ref>. To decrease a hero&apos;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 <ref>setlevelcap</ref> to get around this.</description>
			<seealso>
				<ref>setherolevel</ref>
				<ref>totalexperience</ref>
				<ref>herolevelled</ref>
				<ref>spellslearned</ref>
			</seealso>
		</command>
		<reference ref="updateleveluplearning" />
		<command id="herolevelled">
			<canon>hero levelled (who)</canon>
			<shortname>hero levelled</shortname>
			<description>Returns the number of levels the specified hero gained. <p>who</p> is the hero's position in the battle party. If you want to use <p>hero:Name</p> you should use <ref>findhero</ref>. This command only applies to the most recent battle or <ref>giveexperience</ref>, <ref>setherolevel</ref> or <ref>setexperience</ref> 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:</description>
			<example>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
)</example>
		</command>
		<reference ref="spellslearned" />
		<command id="totalexperience">
			<canon>total experience (who)</canon>
			<shortname>total experience</shortname>
			<description>Returns a hero&apos;s total experience. The argument is the position of the hero you want to check in your party as as returned by <ref>findhero</ref>.</description>
			<seealso>
				<ref>setexperience</ref>
			</seealso>
		</command>
		<command id="experiencetonextlevel">
			<canon>experience to next level (who)</canon>
			<shortname>experience to next level</shortname>
			<description>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 <ref>findhero</ref>.</description>
		</command>
		<command id="experiencetolevel">
			<canon>experience to level (level, hero slot)</canon>
			<shortname>experience to level</shortname>
			<description>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 <p>hero slot</p> argument is left out, then the default experience curve will be used.</description>
		</command>
		<command id="giveexperience">
			<canon>give experience (hero, amount)</canon>
			<shortname>give experience</shortname>
			<description>Gives experience to either a hero by position in party (use result returned by <ref>findhero</ref> command if you want to give experience by name or ID) or the whole party, if the constant <ref>party</ref> 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 <ref>herolevelled</ref> and <ref>spellslearned</ref> for dealing with this. This command can give negative experience, but it will never cause a hero to delevel. You should use <ref>setexperience</ref> 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 <ref>setlevelcap</ref> to get around this.</description>
		</command>
		</section>		<!-- Experience and Levels-->

		</section>		<!--Hero Stats-->


		<section title="Hero&apos;s Spells">

		<command id="teachspell">
			<canon>teach spell (hero, attack)</canon>
			<shortname>teach spell</shortname>
			<description>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&apos;s position in the party (as returned by <ref>findhero</ref>). 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&apos;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 <ref>true</ref>, or if the hero cannot learn the spell (perhaps because they already know it) it will return <ref>false</ref>. Use <ref>writespell</ref> to add a spell to a spell list without restriction.</description>
		</command>
		<command id="forgetspell">
			<canon>forget spell (hero, attack)</canon>
			<shortname>forget spell</shortname>
			<description>
				Causes a hero to forget a spell, by deleting all occurrences of it in their spell lists, regardless of how the spell was learnt.
				If the hero doesn't know the spell, nothing happens.
				(This doesn't affect attacks which are options directly in the hero's battle menu.)
				Returns <ref>true</ref> if the hero knew the spell, <ref>false</ref> if not.
				<lb/>
				The first argument is the hero&apos;s position in the party (as returned by <ref>findhero</ref>).
				<lb/>
				The second argument is the attack to forget.
				You can use the constants (defined in your .hsi file) in the form <tt>atk:attackname</tt>.
				(You may also use the attack&apos;s ID number. This is the number you see in the attack editor + 1).
			</description>
		</command>
		<command id="readspell">
			<canon>read spell (hero, list, slot)</canon>
			<shortname>read spell</shortname>
			<description>
				Checks what spell (attack) is in a certain slot of a hero spell list.
				Returns 0 (<ref>false</ref>) if the slot is empty,
				otherwise the attack ID (i.e. one of the <tt>atk:attackname</tt> constants),
				which is the ID shown in the attack editor + 1.
				The first argument is the hero&apos;s position in the party (as returned by <ref>findhero</ref>).
				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.
			</description>
		</command>
		<command id="writespell">
			<canon>write spell (hero, list, slot, attack)</canon>
			<shortname>write spell</shortname>
			<description>Forces a hero to learn a particular spell. The first argument is the hero&apos;s position in the party (as returned by <ref>findhero</ref>). 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&apos;s ID number. This is the number you see in the attack editor + 1). You can also erase a spell by writing 0 or <ref>none</ref> 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)</description>
		</command>
		<command id="knowsspell">
			<canon>knows spell (hero, attack)</canon>
			<shortname>knows spell</shortname>
			<description>
				Checks whether a hero already knows a spell (whether it's in one of their spell lists - if it's an option directly in the hero's battle menu that doesn't count!)
				and returns <ref>true</ref> or <ref>false</ref>.
				<lb/>
				The first argument is the hero&apos;s position in the party (as returned by <ref>findhero</ref>).
				<lb/>
				The second argument is the attack to check for.
				You can use the constants (defined in your .hsi file) in the form <tt>atk:attackname</tt>.
				(You may also use the attack&apos;s ID number. This is the number you see in the attack editor + 1).
			</description>
		</command>
		<command id="canlearnspell">
			<canon>can learn spell (hero, attack)</canon>
			<shortname>can learn spell</shortname>
			<description>
				Checks whether a hero is capable of learning a spell from an item (and therefore also with the <ref>teachspell</ref> command) and returns <ref>true</ref> or <ref>false</ref>.
				<lb/>
				The first argument is the hero&apos;s position in the party (as returned by <ref>findhero</ref>).
				<lb/>
				The second argument is the attack to check for.
				You can use the constants (defined in your .hsi file) in the form <tt>atk:attackname</tt>.
				(You may also use the attack&apos;s ID number. This is the number you see in the attack editor + 1).
			</description>
		</command>
		<command id="spellslearnt">
			<canon>spells learnt (hero, number)</canon>
			<shortname>spells learnt</shortname>
			<deprecated>zenzizenzic</deprecated>
			<description>This is deprecated, do not use it. It is identical to <ref>spellslearned</ref> 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.</description>
		</command>
		<command id="spellslearned">
			<canon>spells learned (hero, number)</canon>
			<shortname>spells learned</shortname>
			<description>Returns the id numbers (+1) of spells the hero learned from the last battle or <ref>giveexperience</ref>, <ref>setherolevel</ref> or <ref>setexperience</ref> command that targeted either this hero or the whole party. If the second argument is <ref>getcount</ref> then the number of spells that the hero learned is returned. Pass 0 for <p>number</p> 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:
			<note>If you want to compare attacks returned by this command with attack ID numbers, you must add 1 to the ID number, unless you use <tt>atk:...</tt> constants.</note>
			</description>
			<example># The following script uses strings 0, 1, 2 for its use (they 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 key (anykey)
  )
  hide string (0)
end</example>
		</command>
		<command id="updateleveluplearning">
			<canon>update level up learning(who, allowforget)</canon>
			<shortname>update level up learning</shortname>
			<description>Update a hero to make sure they know the spells they are supposed to have learned for their current level. The <p>who</p> is the hero's position in the battle party. You can optionally pass <ref>false</ref> as the <p>allowforget</p> 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 <ref>setherolevel</ref> 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.</description>
		</command>
		</section>

		<section title="Out-of-battle Attacks">
		<command id="outsidebattlecure">
			<canon>outside battle cure (attack minus 1, target, attacker)</canon>
			<shortname>outside battle cure</shortname>
			<deprecated>zenzizenzic</deprecated>
			<description>
				Obsolete, replaced by <ref>mapcure</ref>.
				This is identical to mapcure except for the <p>attack</p> argument differing by one.
			</description>
		</command>
		<command id="mapcure">
			<canon>map cure (attack, target, attacker)</canon>
			<shortname>map cure</shortname>
			<description>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, <p>attack</p> is name of the attack from your HSI file in the form atk:name. (You may also use the attack&apos;s ID number. This is the number you see in the attack editor + 1.) The second argument, <p>target</p> is the position in the party of the hero to cure (or harm). The third optional argument, <p>attacker</p> 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 <ref>true</ref> if the cure/attack succeeded, and <ref>false</ref> if it did nothing.
			<note>The <p>map cure</p> command replaces the old command <p>outside battle cure</p> which had a bug which required you to use <p>atk:name -- 1</p> instead of <p>atk:name</p> for the <p>attack</p> argument.</note>
			<note>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 <ref>wait</ref>).</note>
			<note>
				If you want to cure a hero that has 0 HP with an attack, then the attack's Target Class
				needs to be set to something that allows targetting dead heroes.
				Otherwise the attack doesn't happen and this command returns <tt>false</tt>.
				Other Target settings, including "Spread Attack", are ignored.
			</note>
			</description>
			<seealso>
				<ref>useitem</ref>
				<ref>setherostat</ref>
				<ref>setdeathscript</ref>
			</seealso>
		</command>
		</section>		<!-- Out-of-battle Attacks-->

	</section>
	
	<section title="Attack Data">

		<command id="getattackname">
			<alias>readattackname</alias>
			<shortname>get attack name</shortname>
		</command>
		<command id="readattackname">
			<canon>read attack name (str ID, attack)</canon>
			<shortname>read attack name</shortname>
			<description>
				This command will take the name of <p>attack</p> and stick it in the <p>str ID</p> string, overwriting its contents.
				Use the <p>atk:name</p> constants from your HSI file.
				<note>
				If you want to use this command with attack ID numbers, you must add 1 to the ID number.
				</note>
				<note>
					This command replaces the old <p>get attack name</p> which required you to use <p>atk:name -- 2</p> or the attack id number <p>-- 1</p>
				</note>
			</description>
		</command>
		<command id="getattackcaption">
			<canon>get attack caption (str ID, attack)</canon>
			<shortname>get attack caption</shortname>
			<description>
				This command will take the caption of <p>attack</p> and stick it in the <p>str ID</p> string, overwriting its contents.
				Use the <p>atk:name</p> constants from your HSI file as the <p>attack</p>.
				<note>
					If you want to use this command with attack ID numbers, you must add 1 to the ID displayed in the attack editor.
				</note>
			</description>
		</command>
		<command id="getattackextra">
			<canon>get attack extra (attack, extra num)</canon>
			<shortname>get attack extra</shortname>
			<description>
				Returns the value in one of an attack's "extra data" fields, which you can set in the Misc submenu.
				Use the <tt>atk:name</tt> constants from your HSI file as the <p>attack</p> ID.
				<p>extra num</p> is an <ref>extradataindex</ref>.
				<note>
					If you want to use this command with attack ID numbers, you must add 1 to the ID displayed in the attack editor.
				</note>
			</description>
		</command>

	</section>   <!-- Attack Data -->

	<section title="Enemy and Formation Functions">
		<command id="getenemystat">
			<canon>get enemy stat(enemy, stat)</canon>
			<shortname>get enemy stat</shortname>
			<description>Returns the selected stat from the selected enemy definition. 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 <tt>stat:name</tt>.</description>
			<seealso>
				<ref>setenemystat</ref>
				<ref>enemyelementalresistasint</ref>
				<ref>getherostat</ref>
				<ref>setherostat</ref>
			</seealso>
		</command>
		<command id="setenemystat">
			<canon>set enemy stat(enemy, stat, value)</canon>
			<shortname>set enemy stat</shortname>
			<description>
				Sets the selected stat of the selected enemy definition 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 <tt>stat:name</tt>.
				The third is the new value of the stat.
				<note>
					Enemy stat changes are temporary. They are not saved in saved games.
					If you want to reset them early, use <ref>resetenemystat</ref>.
				</note>
			</description>
			<seealso>
				<ref>getenemystat</ref>
				<ref>resetenemystat</ref>
				<ref>getherostat</ref>
				<ref>setherostat</ref>
			</seealso>
		</command>
		<command id="resetenemystat">
			<canon>reset enemy stat(enemy, stat)</canon>
			<shortname>reset enemy stat</shortname>
			<description>
				Resets the selected stat of the selected enemy definition to its original value as set in the editor.
				<p>enemy</p> is an enemy ID and <p>stat</p> 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.
			</description>
		</command>

		<command id="enemyelementalresistasint">
			<canon>enemy elemental resist as int (enemy, element)</canon>
			<shortname>enemy elemental resist as int</shortname>
			<description>Gets the amount of damage that an enemy receives from attacks of a certain element, as a percentage of normal. The argument <p>enemy</p> is the enemy's ID number. The argument <p>element</p> 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.<note>When floating point support is added to HamsterSpeak, an alternative to this command will be added.</note></description>
			<seealso>
				<ref>getenemystat</ref>
				<ref>herototalelementalresistasint</ref>
			</seealso>
		</command>
		<command id="getenemyname">
			<canon>get enemy name (enemyid, stringid)</canon>
			<shortname>get enemy name</shortname>
			<description>
				Put the name of an enemy in a string.
				<p>enemyid</p> is the number of the enemy
				(you can use a constant like <tt>enemy: skeleton</tt>,
				and <p>stringid</p> is the number of the string in which to store the name of the enemy.
				<warn>
					The arguments are the opposite order to every other "get ... name" command! Whoops!
				</warn>
			</description>
			<seealso>
				<ref>setenemyname</ref>
			</seealso>
		</command>
		<command id="setenemyname">
			<canon>set enemy name (enemyid, stringid)</canon>
			<shortname>set enemy name</shortname>
			<description>
				Lets you change an enemy's name to a new name in a string.
				The string length cannot be more then 16 characters, if it is more then 16 the name will be truncated.
				<lb/>
				<p>enemyid</p> is the number of the enemy
				(you can use a constant like <tt>enemy: skeleton</tt>,
				and <p>stringid</p> is the number of the string that you supply the name of the enemy from.
				<note>
					Enemy name changes are temporary. They are not saved in saved games.
					If you want to reset them early, use <ref>resetenemyname</ref>.
				</note>
			</description>
			<seealso>
				<ref>getenemyname</ref>
				<ref>resetenemyname</ref>
			</seealso>
		</command>
		<command id="resetenemyname">
			<canon>reset enemy name (enemyid)</canon>
			<shortname>reset enemy name</shortname>
			<description>
				Resets the name of an enemy to the value originally set in the editor.
				<p>enemyid</p> is the number of the enemy.
			</description>
		</command>

		<command id="getenemyappearance">
			<canon>get enemy appearance (enemyid, appearance)</canon>
			<shortname>get enemy appearance</shortname>
			<description>
				Returns data on the appearance of a enemy.
				<p>enemyid</p> is the enemy number that you want to return the appearance of,
				<p>appearance</p> is one of the following constants:
				<ul>
					<li>enemy:picture</li>
					<li>enemy:palette</li>
					<li>enemy:picturesize</li>
				</ul>
				<lb/>
				You can compare the values returned for <tt>enemy:picturesize</tt> with the constants <tt>enemysize:small</tt>, <tt>enemysize:medium</tt> and <tt>enemysize:large</tt>.
				<lb/>
				This command is just an alias for <ref>readenemydata</ref>.
			</description>
			<seealso>
				<ref>setenemyappearance</ref>
			</seealso>
		</command>
		<command id="setenemyappearance">
			<canon>set enemy appearance (enemyid, appearance, value)</canon>
			<shortname>set enemy appearance</shortname>
			<description>
				Lets you change an enemy's appearance.
				<p>enemyid</p> is the number of the enemy's appearance that you want to change,
				<p>appearance</p> is one of the constants given in <ref>getenemyappearance</ref>.
				<p>value</p> is the value to assign:
				spriteset id for <tt>enemy:picture</tt>;
				constants <tt>enemysize:small</tt>,
				<tt>enemysize:medium</tt>, or <tt>enemysize:large</tt> when changing picture size
				(spriteset group);
				or palette number when changing palette.
				<note>
					Enemy appearance changes are temporary: they are not saved in saved games.
					If you want to reset them early, use <ref>resetenemydata</ref>,
					because <p>set enemy appearance</p> is (now) just an alias for <ref>writeenemydata</ref>.
				</note>
			</description>
			<seealso>
				<ref>getenemyappearance</ref>
			</seealso>
		</command>
		<command id="readenemydata">
			<canon>read enemy data (enemyid, data)</canon>
			<shortname>read enemy data</shortname>
			<description>
				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:
				<ul>
					<li>enemy:gold</li>
					<li>enemy:experience</li>
					<li>enemy:item</li>
					<li>enemy:itempercent</li>
					<li>enemy:rareitem</li>
					<li>enemy:rareitempercent</li>
					<li>stealability</li>
					<li>stealableitem</li>
					<li>stealableitemchance</li>
					<li>stealablerareitem</li>
					<li>stealablerareitemchance</li>
				</ul>
			</description>
			<seealso>
				<ref>writeenemydata</ref>
			</seealso>
		</command>
		<command id="writeenemydata">
			<canon>write enemy data (enemyid, data, value)</canon>
			<shortname>write enemy data</shortname>
			<description>
				Lets you set items of an enemy's data.
				<p>enemyid</p> is the number of enemy.
				<p>data</p> is a predefined constant for the data you want to change:
				use the same constants listed at <ref>readenemydata</ref>.
				<p>value</p> is the new value given to that setting.
				<note>
					Enemy data changes are temporary. They are not saved in saved games.
					If you want to reset them early, use <ref>resetenemydata</ref>.
				</note>
			</description>
			<seealso>
				<ref>readenemydata</ref>
				<ref>resetenemydata</ref>
			</seealso>
		</command>
		<command id="resetenemydata">
			<canon>reset enemy data (enemyid, data)</canon>
			<shortname>reset enemy data</shortname>
			<description>
				Undoes the effect of <ref>writeenemydata</ref>, resetting one piece of
				an enemy's data to the original value set in the enemy editor.
				<p>enemyid</p> is the number of enemy.
				<p>data</p> is a predefined constant for the data you want to change:
				use the constants listed at <ref>readenemydata</ref> or <ref>getenemyappearance</ref>.
			</description>
		</command>

		<section title="Formations">
		<command id="addenemytoformation">
			<canon>add enemy to formation (formation, enemy id, x, y, slot)</canon>
			<shortname>add enemy to formation</shortname>
			<description>
				Adds an enemy with given <p>enemy id</p>
				(use the constants of the form <p>enemy:name</p> in your exported .hsi file) to the specified <p>formation</p>.
				give the position of the center of the bottom edge of the enemy (approximately where it appears to stand),
				relative to the center 320x200 of the screen.
				Use the formation editor to get coordinates to feed into this command.
				<p>slot</p> (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 <p>slot</p> or <p>slot</p> 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.
				<note>
					Changes to enemy formations are temporary: they are not saved in save files.
				</note>
			</description>
			<seealso>
				<ref>deleteenemyfromformation</ref>
			</seealso>
		</command>
		<command id="deleteenemyfromformation">
			<canon>delete enemy from formation (formation, slot)</canon>
			<shortname>delete enemy from formation</shortname>
			<description>Deletes an enemy in the given <p>slot</p> (as returned by <ref>findenemyinformation</ref> for example) in the <p>formation</p>.<note>Changes to enemy formations are temporary: they are not saved in save files.</note></description>
			<seealso>
				<ref>addenemytoformation</ref>
			</seealso>
		</command>
		<command id="findenemyinformation">
			<canon>find enemy in formation (formation, enemy id, copy number)</canon>
			<shortname>find enemy in formation</shortname>
			<description>Searches for an enemy in a formation, returning the slot number, or -1 if not found. <p>copy number</p> is optional, use 0 or greater specify which enemy to return if there is more than one, or the constant <ref>getcount</ref>. 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. <p>enemy id</p> can be either an enemy id, or the constant <p>any enemy</p>, which searches for any enemy (the first enemy in the formation by default), or the total number of enemies with <ref>getcount</ref>.</description>
			<example>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
</example>
			<seealso>
				<ref>deleteenemyfromformation</ref>
				<ref>formationslotenemy</ref>
				<ref>formationslotx</ref>
				<ref>formationsloty</ref>
			</seealso>
		</command>
		<command id="formationslotenemy">
			<canon>formation slot enemy (formation, slot)</canon>
			<shortname>formation slot enemy</shortname>
			<description>Returns the ID number of the enemy in the specified formation slot (0 to 7), or -1 if the slot is empty.</description>
			<seealso>
				<ref>findenemyinformation</ref>
			</seealso>
		</command>
		<command id="formationslotx">
			<canon>formation slot x (formation, slot)</canon>
			<shortname>formation slot x</shortname>
			<description>
				Returns the x position of the center of the enemy in the specified formation slot (0 to 7).
				An enemy's position is the center of the bottom edge of the enemy - approximately where it appears to stand.
			</description>
			<seealso>
				<ref>findenemyinformation</ref>
			</seealso>
		</command>
		<command id="formationsloty">
			<canon>formation slot y (formation, slot)</canon>
			<shortname>formation slot y</shortname>
			<description>
				Returns the y position of the bottom edge of the enemy sprite in the specified formation slot (0 to 7).
				An enemy's position is the center of the bottom edge of the enemy - approximately where it appears to stand.
			</description>
			<seealso>
				<ref>findenemyinformation</ref>
			</seealso>
		</command>
		<command id="setformationbackground">
			<canon>set formation background (formation, background, animation frames, animation ticks)</canon>
			<shortname>set formation background</shortname>
			<description>Sets the background and the background animation for a <p>formation</p>. The animation arguments do not need to be given, producing a static background. <p>animation frames</p>, optional, is the number of frames (1 to 50) to use for the background animation. 1 is non-animating. <p>animation ticks</p>, also optional, is the number of ticks to display each backdrop for. The engine normally (but not reliably) runs at 18 ticks per second.<note>Changes to enemy formations are temporary: they are not saved in save files.</note></description>
			<seealso>
				<ref>getformationbackground</ref>
			</seealso>
		</command>
		<command id="getformationbackground">
			<canon>get formation background (formation)</canon>
			<shortname>get formation background</shortname>
			<description>Gets the background used by a <p>formation</p>. If the backdrop is animated, this returns the ID of the first backdrop (the one set in Custom).</description>
			<seealso>
				<ref>setformationbackground</ref>
			</seealso>
		</command>
		<command id="setformationsong">
			<canon>set formation song (formation, song)</canon>
			<shortname>set formation song</shortname>
			<description>Changes an enemy formation to use <p>song</p> as its music. Use the constants of the form <p>song:songname</p> from your exported .hsi file, or the special constants <ref>song:silence</ref> or <ref>song:sameasmap</ref><note>Changes to enemy formations are temporary: they are not saved in save files.</note></description>
			<seealso>
				<ref>getformationsong</ref>
			</seealso>
		</command>
		<command id="getformationsong">
			<canon>get formation song (formation)</canon>
			<shortname>get formation song</shortname>
			<description>Returns the song associated with <p>formation</p>. Compare the result with the constants of the form <p>song:songname</p> from your exported .hsi file, or the special constants <ref>song:silence</ref> or <ref>song:sameasmap</ref>.</description>
			<seealso>
				<ref>setformationsong</ref>
			</seealso>
		</command>
		<command id="resetformation">
			<canon>reset formation (formation)</canon>
			<shortname>reset formation</shortname>
			<description>Reset any scripted changes to <p>formation</p>. This script erases changes made with <ref>addenemytoformation</ref>, <ref>deleteenemyfromformation</ref>, <ref>setformationbackground</ref>, and <ref>setformationsong</ref> and changes the formation back to the way it was defined in the Formation Editor in custom.</description>
			<seealso>
				<ref>resetformationslot</ref>
			</seealso>
		</command>
		<command id="resetformationslot">
			<canon>reset formation slot (formation, slot)</canon>
			<shortname>reset formation slot</shortname>
			<description>Reset any scripted changes to a specific <p>slot</p> in a <p>formation</p>. This script erases changes to enemy id, enemy x, and enemy y made with <ref>addenemytoformation</ref> or <ref>deleteenemyfromformation</ref> and changes the formation slot back to the way it was defined in the Formation Editor in custom.</description>
			<seealso>
				<ref>resetformation</ref>
			</seealso>
		</command>
		<command id="lastformation">
			<canon>last formation</canon>
			<shortname>last formation</shortname>
			<description>Returns the last formation fought. If the player hasn't fought any formations yet (since starting or loading the game), it returns -1.</description>
			<seealso>
				<ref>readfoemap</ref>
			</seealso>
		</command>

		<command id="randomformation">
			<canon>random formation (formation set)</canon>
			<shortname>random formation</shortname>
			<description>Picks a formation randomly from the given <p>formation set</p> (1 to 255), returning the formation number.</description>
			<seealso>
				<ref>formationprobability</ref>
			</seealso>
		</command>
		<command id="formationsetfrequency">
			<canon>formation set frequency (formation set)</canon>
			<shortname>formation set frequency</shortname>
			<description>
				Returns the formation frequency (from 0 to 200) of a <p>formation set</p> (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 <ref>getbattlecountdown</ref>).
			</description>
			<seealso>
				<ref>randomformation</ref>
				<ref>getbattlecountdown</ref>
				<ref>setbattlecountdown</ref>
			</seealso>
		</command>
		<command id="getbattlecountdown">
			<canon>get battle countdown</canon>
			<shortname>get battle countdown</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>formationsetfrequency</ref>
				<ref>getbattlecountdown</ref>
				<ref>setbattlecountdown</ref>
				<ref>readfoemap</ref>
			</seealso>
		</command>
		<command id="setbattlecountdown">
			<canon>set battle countdown (value)</canon>
			<shortname>set battle countdown</shortname>
			<description>
				Sets the random battle countdown value (see <ref>getbattlecountdown</ref>).
				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 <ref>teleporttomap</ref>,
				or dismounting a vehicle.
			</description>
			<seealso>
				<ref>formationsetfrequency</ref>
				<ref>getbattlecountdown</ref>
				<ref>setbattlecountdown</ref>
			</seealso>
		</command>
		<command id="formationprobability">
			<canon>formation probability (formation set, formation)</canon>
			<shortname>formation probability</shortname>
			<description>Returns the probability of a particular <p>formation</p> in a <p>formation set</p> 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.</description>
			<seealso>
				<ref>randomformation</ref>
				<ref>random</ref>
			</seealso>
		</command>
		</section>		<!-- Formations-->

	</section>		<!--Enemy and Formation Data-->

	<section title="Getting Player Input">
		<command id="pickhero">
			<canon>pick hero (message, skip if alone)</canon>
			<shortname>pick hero</shortname>
			<description>
				Pops up a hero-picker box that lets you choose one of the heroes in your active party.
				The return value is the position in the party of the hero you picked, or -1 if the player cancelled.
				<lb/>
				Both arguments are optional.
				<lb/>
				<p>message</p> is the ID of the string to use for the prompt, which defaults to "Which Hero?".
				If you leave it out or pass -1, the default message is used,
				which is defined in the Global Text Strings menu (search it for "pick hero").
				<lb/>
				If <p>skip if alone</p> is true then if there's only one hero in the active party
				then will automatically be picked, without showing the menu.
				It defaults to <tt>false</tt>!
			</description>
		</command>
		<reference ref="renamehero" />
		<reference ref="renameherobyslot" />

		<section title="Keyboard Input">
		<description>
			There are three main commands for checking for keypresses: <ref>keypress</ref>,
			<ref>newkeypress</ref> and <ref>keyispressed</ref>.
			Use <ref>keyispressed</ref> (which checks whether a key is down) when you want the player to do something continually,
			such for moving, running, jumping, or attacking repeatedly
			each time a cooldown expires (you'll need to script your own cooldown).
			For nearly everything else you will use <ref>keypress</ref>,
			(or <ref>newkeypress</ref> instead if you don't want key repeat),
			such as when you script a menu
			(both activating menu items and moving the cursor - since the cursor moves in jumps rather than continually),
			or to use a special ability such throwing a ball.
			You should use <ref>keypress</ref> for key repeat for scripted menus.
			<note>
				You can NOT wait for the player to press a key by continually polling <ref>keyispressed</ref>, etc,
				in a <ref>while</ref> loop unless you stick a <ref>wait</ref> in your loop.
				That's because key, joystick and mouse commands don't return real time data,
				but the state of the devices at the beginning of the current game tick (after the last wait).
			</note>
		</description>

		<command id="keyispressed">
			<canon>key is pressed (scancode, player)</canon>
			<shortname>key is pressed</shortname>
			<description>
				Returns <ref>true</ref> if the keyboard or joystick key with the specified <ref>scancode</ref> is being pressed
				(either held down or pressed since last tick), or <ref>false</ref> if it is not.
				The <p>scancode</p> argument is a <ref>scancode</ref> such as a keyboard key (e.g. <tt>key:ctrl</tt>)
				a joystick button (e.g. <tt>joy:left</tt>), or a virtual scancode such as
				<ref>usekey</ref> (see <ref>controlcodes</ref>).
				<lb/>
				<p>player</p> is an optional <ref>playernumber</ref>,
				normally only used with <tt>joy:...</tt> joystick scancodes
				or <ref>controlcodes</ref>, and tells which player's controller to read.
				By default it checks for a button press on any plugged-in controller.
				<note>
					This command is an alternative to <ref>keypress</ref> or <ref>newkeypress</ref>;
					see <secref>Keyboard Input</secref> for usage hints.
					<lb/>
					You can use <ref>keypresstime</ref> to see how long a key/button has been down.
				</note>
				<note>
					Previously you couldn't use virtual scancodes like <ref>usekey</ref>,
					which could only be used with <ref>waitforkey</ref>.
					Now all key commands accept any kind of constant; what a relief!
				</note>
				<warn>
					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.
				</warn>
			</description>
			<seealso>
				<ref>keypress</ref>
				<ref>newkeypress</ref>
				<ref>keyval</ref>
				<ref>keypresstime</ref>
			</seealso>
		</command>
		<command id="keypress">
			<canon>keypress (scancode, player)</canon>
			<shortname>keypress</shortname>
			<description>
				Checks for a keypress event, and returns <tt>true</tt> or <tt>false</tt>.
				A keypress happens either when there's a new keypress (the key/button gets pressed down),
				or each time it repeats once it's been held down for a little while
				(18 times a second after it's been held half a second, by default).
				<lb/>
				The <p>scancode</p> argument is a <ref>scancode</ref> such as a keyboard key (e.g. <tt>key:ctrl</tt>)
				a joystick button (e.g. <tt>joy:left</tt>), or a virtual scancode such as
				<ref>usekey</ref> (see <ref>controlcodes</ref>).
				<lb/>
				<p>player</p> is an optional <ref>playernumber</ref>,
				normally only used with <tt>joy:...</tt> joystick scancodes
				or <ref>controlcodes</ref>, and tells which player's controller to read.
				By default it checks for a button press on any plugged-in controller.
				<note>
					This command is an alternative to <ref>newkeypress</ref> or <ref>keyispressed</ref>;
					see <secref>Keyboard Input</secref> for usage hints.
				</note>
				<warn>
					It's not a good idea to rely on the key repeat rate for things that affect gameplay such as the rate at which you can shoot bullets!
					The repeat rate is once every 55 milliseconds (18 times a second), independent of the frames per second (fps) that
					the game is running at.
					Suppose you use key repeat to shoot bullets and your game runs at 36 fps,
					then a bullet will be fired every other frame.
					But if played on a really slow computer that only ran the game at 18 fps, a bullet will be fired every frame!
				</warn>
			</description>
			<seealso>
				<ref>keyispressed</ref>
				<ref>newkeypress</ref>
				<ref>keyval</ref>
				<ref>keypresstime</ref>
			</seealso>
		</command>
		<command id="newkeypress">
			<canon>new keypress (scancode, player)</canon>
			<shortname>new keypress</shortname>
			<description>
				Checks for a new keypress (the key/button gets pressed down), and returns <tt>true</tt> or <tt>false</tt>.
				<lb/>
				The <p>scancode</p> argument is a <ref>scancode</ref> such as a keyboard key (e.g. <tt>key:ctrl</tt>)
				a joystick button (e.g. <tt>joy:left</tt>), or a virtual scancode such as
				<ref>usekey</ref> (see <ref>controlcodes</ref>).
				<lb/>
				<p>player</p> is an optional <ref>playernumber</ref>,
				normally only used with <tt>joy:...</tt> joystick scancodes
				or <ref>controlcodes</ref>, and tells which player's controller to read.
				By default it checks for a button press on any plugged-in controller.
				<note>
					This command is an alternative to <ref>keypress</ref> or <ref>keyispressed</ref>;
					see <secref>Keyboard Input</secref> for hints.
				</note>
			</description>
			<seealso>
				<ref>keyispressed</ref>
				<ref>keypress</ref>
				<ref>keyval</ref>
				<ref>keypresstime</ref>
			</seealso>
		</command>
		<command id="keyval">
			<canon>keyval (scancode, player)</canon>
			<shortname>keyval</shortname>
			<description>
			(Obsolete, you can now use simpler commands like <ref>keypress</ref> instead.)
			<lb/>
			Returns a bitmask for the state of the specified key, joystick/gamepad button, or virtual scancode.
			<lb/>
			The <p>scancode</p> argument is a <ref>scancode</ref> such as a keyboard key (e.g. <tt>key:ctrl</tt>)
			a joystick button (e.g. <tt>joy:left</tt>), or a virtual scancode such as
			<ref>usekey</ref> (see <ref>controlcodes</ref>).
			<lb/>
			<p>player</p> is an optional <ref>playernumber</ref>,
			normally only used with <tt>joy:...</tt> joystick scancodes
			or <ref>controlcodes</ref>, and tells which player's controller to read.
			By default it checks for a button press on any plugged-in controller.
			<lb/>
			The result holds the same information as given by the <ref>keyispressed</ref> and <ref>keypress</ref> commands,
			so you can use those instead.
			The first (least significant) bit is whether the key was depressed at the beginning of the current tick.
			The second bit is whether a keypress event happened (either this is a new keypress, or key repeat occurred)
			- same as <ref>keypress</ref>.
			<lb/>
			It can therefore return 0, 1, 2 or 3:
			<lb/>
			0 = not pressed<lb/>
			1 = key held down since last tick, but is not a new press<lb/>
			2 = the player pressed the key and released it, all in the same tick<lb/>
			3 = new keypress (or typematic repeat)
			<note>
				Previously you couldn't use virtual scancodes like <ref>usekey</ref>,
				which could only be used with <ref>waitforkey</ref>.
				Now all key commands accept any kind of constant; what a relief!
			</note>
			</description>
			<seealso>
				<ref>keyispressed</ref>
				<ref>keypress</ref>
				<ref>newkeypress</ref>
				<ref>keypresstime</ref>
			</seealso>
		</command>
		<command id="keypresstime">
			<canon>keypress time (scancode, player)</canon>
			<shortname>keypress time</shortname>
			<description>
				Returns how long a key or button has been held down, in milliseconds (thousandths of a second), or 0 if the key isn't pressed.
				<lb/>
				The <p>scancode</p> argument is a <ref>scancode</ref> such as a keyboard key (e.g. <tt>key:ctrl</tt>)
				a joystick button (e.g. <tt>joy:left</tt>), or a virtual scancode such as
				<ref>usekey</ref> (see <ref>controlcodes</ref>).
				If you use a scancode that refers to multiple keys/buttons
				(e.g. <tt>usekey</tt> or <tt>anykey</tt>)
				then the longest time that any of those keys has been held down is returned.
				<lb/>
				<p>player</p> is an optional <ref>playernumber</ref>,
				normally only used with <tt>joy:...</tt> joystick scancodes
				or <ref>controlcodes</ref>, and tells which player's controller to read.
				By default it checks for a button press on any plugged-in controller.
				<lb/>
				If a fast keypress happens in less than a tick and the key is already up again
				then <ref>keyispressed</ref> can return <tt>false</tt> and <p>keypress time</p>
				return <tt>0</tt> although <ref>keypress</ref> returns <tt>true</tt>.
			</description>
			<seealso>
				<ref>keyispressed</ref>
				<ref>keypress</ref>
			</seealso>
		</command>

		<command id="lastascii">
			<canon>last ascii</canon>
			<shortname>last ascii</shortname>
			<description>This command is obsolete. Use <ref>getinputtext</ref> instead, if possible.<lb/>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.</description>
			<seealso>
				<ref>getscancodename</ref>
			</seealso>
		</command>
		<command id="getscancodename">
			<canon>get scancode name(string id, scancode, long name)</canon>
			<shortname>get scancode name</shortname>
			<description>
				Get a name for a <ref>scancode</ref>, what the key does if Shift isn't pressed,
				and put it in <p>string id</p>.
				For example, "7", "Q", "Space", "Caps Lock", "Gamepad Button 1", "Gamepad Up".
				<lb/>
				<p>scancode</p> can be any <tt>key:...</tt> or <tt>joy:...</tt> scancode,
				or <ref>usekey</ref>, <ref>menukey</ref>, etc.
				<lb/>
				Normally a long name like "Left Shift" is returned, but if
				optional argument <p>long name</p> is false, then
				a one-character string for what the key inserts
				is returned if available, for example "[" instead of "Left Bracket",
				with the exception of "Space" and "Enter" and numpad keys like "Numpad Minus" which
				are always returned as long names.
			</description>
			<seealso>
				<ref>getinputtext</ref>
				<ref>lastascii</ref>
			</seealso>
		</command>
		<command id="enableinputtext">
			<canon>enable input text (enable)</canon>
			<shortname>enable input text</shortname>
			<description>This command needs to be called before <ref>getinputtext</ref> can be used. If the optional argument is <ref>true</ref> or not given then <p>get input text</p> is enabled, otherwise it is disabled. Enabling <ref>getinputtext</ref> may cause some of the keys on international keyboards ("combining" keys, which are usually punctuation keys) to go "dead" --- that is, commands such as <ref>keyispressed</ref> and <ref>waitforkey</ref> will stop showing that they are pressed. For that reason, <p>get input text</p> is disabled by default. You don't need to use this command before calling <ref>inputstring</ref>.</description>
			<seealso>
				<ref>getinputtext</ref>
			</seealso>
		</command>
		<command id="getinputtext">
			<canon>get input text (string id)</canon>
			<shortname>get input text</shortname>
			<description>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 <ref>enableinputtext</ref> before this command can be used! See that command for details. You will normally call this every tick in a loop and use <ref>concatenatestrings</ref> to read the player's complete input. However it is much easier to call the <ref>inputstring</ref> function instead, which does this for you.</description>
			<seealso>
				<ref>inputstring</ref>
			</seealso>
		</command>
		<command id="inputstring">
			<canon>input string (ID, maxlength, use current, center, position x, position y)</canon>
			<shortname>input string</shortname>
			<description>
				Allows the player to type in a string (until they press ENTER).
				Returns false if they press ESC to cancel.
				<p>ID</p> is the string you want to use.
				All other arguments are optional:
				<p>maxlen</p> is the length of input, if left blank the limit will be equal to
				the maximum length that fits on-screen (40 characters if the screen is the default 320 pixels wide).
				<p>use current</p> 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 <ref>true</ref> or <ref>false</ref>.
				The string will be centered (see <ref>centerstringat</ref> unless <p>center</p> is <ref>false</ref>.
				If the string is not visible, then it will automatically be placed onscreen
				(centered if not specified) and hidden when done.
				<p>position x</p> and <p>position y</p> 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.
			</description>
			<seealso>
				<ref>getinputtext</ref>
			</seealso>
		</command>
		<command id="inputstringwithvirtualkeyboard">
			<canon>input string with virtual keyboard (ID, maxlength, onlyplayer)</canon>
			<shortname>input string with virtual keyboard</shortname>
			<description>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. <p>ID</p> is the string you want to use. All other arguments are optional: <p>maxlen</p> is the length of input, if left blank the limit will be set to 40 (max visible onscreen length). The <p>onlyplayer</p> 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.</description>
			<seealso>
				<ref>inputstring</ref>
				<ref>inputstringwithmousekeyboard</ref>
			</seealso>
		</command>
		<reference ref="showvirtualgamepad" />
		<reference ref="hidevirtualgamepad" />
		<reference ref="autovirtualgamepad" />
		</section>		<!-- Keyboard Input-->

		<section title="Joystick/Gamepad Input">
		<description>
			Joystick buttons and up/down/left/right directions can also be read using the
			<ref>keypress</ref>, <ref>newkeypress</ref>, <ref>keyispressed</ref> and <ref>waitforkey</ref>
			commands, by using the <tt>joy:...</tt> <ref>scancode</ref> constants instead of keyboard scancodes.
			<lb/>
			But the best way to support joysticks is to use <ref>controlcodes</ref> such as <ref>usekey</ref>
			instead of keyboard scancodes, e.g. write <tt>if (keypress(use key))</tt> instead of
			<tt>if (keypress(key:space) || keypress(key:enter) || keypress(key:ctrl))</tt>.
		</description>

		<command id="joystickbutton">
			<canon>joystick button (button, player)</canon>
			<shortname>joystick button</shortname>
			<description>
				Returns <ref>true</ref> or <ref>false</ref> depending on whether button
				number <p>button</p> on the <p>player</p>'s joystick/gamepad is pressed.
				<p>button</p> can be from 1-32 (assuming the joystick has that many buttons),
				or a joystick <ref>scancode</ref> like <tt>joy:Up</tt>.
				<lb/>
				<p>player</p> is an optional <ref>playernumber</ref> telling which player's controller to read.
				By default it checks for button presses on any plugged-in controller.
				<lb/>
				This command is redundant to <ref>keyispressed</ref>.
				<note>
					If you want to check for new button presses, or want key-repeat to happen,
					use the <ref>keypress</ref> or <ref>newkeypress</ref> commands instead
					with a <tt>joy:...</tt> scancode.
				</note>
			</description>
		</command>
		<command id="joystickaxis">
			<canon>joystick axis (axis, multiplier, player)</canon>
			<shortname>joystick axis</shortname>
			<description>
				Returns the position of one of a joystick/gamepad's sticks along the X or Y axis, or of one of the trigger buttons.
				<p>axis</p> is a value 0 or higher, or one of the constants:
				<ul>
					<li>
						<tt>axis:X</tt> - the X axis of the joystick, or left thumbstick on a gamepad.
						Negative for left, positive for right.
						(You can also use the obsolete <tt>x axis</tt> alias)
					</li>
					<li>
						<tt>axis:Y</tt> - the Y axis of the joystick, or left thumbstick on a gamepad.
						Negative for up, positive for down.
						(You can also use the obsolete <tt>y axis</tt> alias)
					</li>
					<li><tt>axis:Right X</tt> - X axis of the right thumbstick</li>
					<li><tt>axis:Right Y</tt> - Y axis of the right thumbstick</li>
					<li><tt>axis:L2</tt> - the left trigger button. Never negative</li>
					<li><tt>axis:R2</tt> - the right trigger button. Never negative</li>
				</ul>
				<lb/>
				The optional <p>multiplier</p> is the range of the return value: between <tt>-multiplier ... multiplier</tt>
				(or <tt>0 ... multiplier</tt> for <tt>axis:L2</tt> or <tt>axis:R2</tt>).
				By default, the range is -100 - 100.
				<lb/>
				<p>player</p> is an optional <ref>playernumber</ref> telling which player's controller to read.
				By default it check all controllers and combines their input.
				<warn>
					All axes are meant to return 0 when the player isn't touching the stick/trigger,
					but you must NOT rely on this as joysticks/thumbsticks in general don't return to exactly 0,0!
					In fact, some of them never report exactly 0!
					Instead, you must use a "dead zone" around 0 where input is ignored.
					For example, ignore values between -50 and 50.
					Also, if you push a stick diagonally (e.g. up-right) it probably won't reach 100,-100.
					<lb/>
					If possible (if you don't need to know how far or precisely what angle the stick is pushed),
					use the <tt>joy:Up, joy:Down, joy:Left, joy:Right</tt> or
					<tt>joy:RStick Up, joy:RStick Down, joy:RStick Left, joy:RStick Right</tt>
					buttons with <ref>keyispressed</ref> instead.
					These allow 8-directional movement and have a proper circular dead zone.
				</warn>
				<note>
					Constants like <tt>axis:Right X</tt> only mean what they say if the controller
					is a gamepad and if you're using the default gfx_sdl2 backend. All the other
					backends number gamepad buttons and axes unpredictably.
					So that means <tt>axis:L2</tt> and <tt>axis:R2</tt> can actually return negatives.
				</note>
			</description>
		</command>
		</section>		<!-- Joystick/Gamepad Input-->

		<section title="Mouse Input">
		<command id="initmouse">
			<canon>init mouse</canon>
			<shortname>init mouse</shortname>
			<description>Informs the engine that you intend to use the mouse. This command should be run before any mouse functions are be used, but it's not necessary. 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.<lb/><note>Running this command does not draw a cursor onscreen. Either you can enable the default mouse cursor with <ref>unhidemousecursor</ref>, 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 <ref>showvalue</ref>, <ref>showstringat</ref>, etc., which is currently unavoidable.</note> Here is an example:</description>
			<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</example><example>#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</example>
		</command>
		<command id="mousepixelx">
			<canon>mouse pixel X</canon>
			<shortname>mouse pixel X</shortname>
			<description>
				Returns the X coordinate in pixels of the mouse on the screen (window).
				The position is clamped to the size of the window: it is always in the range <tt>0</tt> to <ref>getscreenwidth</ref><tt> -- 1</tt>.
				<note>
					Because of the clamping, currently there's no way to tell whether the mouse is actually over the window.
				</note>
			</description>
		</command>
		<command id="mousepixely">
			<canon>mouse pixel Y</canon>
			<shortname>mouse pixel Y</shortname>
			<description>
				Returns the Y coordinate in pixels of the mouse on the screen.
				The position is clamped to the size of the window: it is always in the range <tt>0</tt> to <ref>getscreenheight</ref><tt> -- 1</tt>.
			</description>
		</command>
		<command id="mousebutton">
			<canon>mouse button (which)</canon>
			<shortname>mouse button</shortname>
			<description>
				Returns <ref>true</ref> if the specified mouse button is currently pressed down.
				You can use the constants <ref>leftbutton</ref>, <ref>middlebutton</ref> or <ref>rightbutton</ref> to specify the button.
				<note>
					Just like keyboard commands such as <ref>keyispressed</ref>, you can <b>not</b>
					wait for the player to click the mouse with a while loop that doesn't contain
					a <ref>wait</ref> command, because the mouse state is only updated once per frame.
				</note>
				<warn>
					When scripting a user interface (GUI or menu) with custom mouse-based controls,
					you should almost always use <ref>mouserelease</ref> instead of <ref>mousebutton</ref>
					or <ref>mouseclick</ref>.
					(<tt>mouse button</tt> is fine for gameplay actions, like throwing projectiles.)
					<lb/>
					There are two reasons: firstly, that's how the mouse works in almost all software (try it!).
					Secondly, the engine itself uses 'mouse release' everywhere,
					so you may run into problems if you use <tt>mouse button</tt> for UI stuff.
					For example if you quit a custom menu on <tt>mouse button</tt> (ie the button is pushed down),
					but then the engine will do something like walk the hero to a tile when it sees the button goes back up,
					that'll cause an unwanted action.
				</warn>
			</description>
			<seealso>
				<ref>mouseclick</ref>
				<ref>mouserelease</ref>
			</seealso>
		</command>
		<command id="mouseclick">
			<canon>mouse click (which)</canon>
			<shortname>mouse click</shortname>
			<description>
				Returns <ref>true</ref> if the specified mouse button has been 'clicked' down in the last tick.
				You can use the constants <ref>leftbutton</ref>, <ref>middlebutton</ref> or <ref>rightbutton</ref> to specify the button.
				<note>
					Just like keyboard commands such as <ref>keyispressed</ref>, you can <b>not</b>
					wait for the player to click the mouse with a while loop that doesn't contain
					a <ref>wait</ref> command, because the mouse state is only updated once per frame.
				</note>
			</description>
			<seealso>
				<ref>mousebutton</ref>
				<ref>mouserelease</ref>
			</seealso>
		</command>
		<command id="mouserelease">
			<canon>mouse release (which)</canon>
			<shortname>mouse release</shortname>
			<description>
				Returns <ref>true</ref> if the specified mouse button has been released since the last tick.
				You can use the constants <ref>leftbutton</ref>, <ref>middlebutton</ref> and <ref>rightbutton</ref> to specify the button.
				<note>
					Just like keyboard commands such as <ref>keyispressed</ref>, you can <b>not</b>
					wait for the player to click the mouse with a while loop that doesn't contain
					a <ref>wait</ref> command, because the mouse state is only updated once per frame.
				</note>
			</description>
			<seealso>
				<ref>mousebutton</ref>
				<ref>mouseclick</ref>
			</seealso>
		</command>
		<command id="putmouse">
			<canon>put mouse (X, Y)</canon>
			<shortname>put mouse</shortname>
			<description>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 (see <ref>windowisfocused</ref>). <ref>initmouse</ref> should be called before this command is used.</description>
		</command>
		<command id="mouseregion">
			<canon>mouse region (x min, x max, y min, y max)</canon>
			<shortname>mouse region</shortname>
			<description>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. <ref>initmouse</ref> should be called before this command is used.</description>
		</command>
		<command id="inputstringwithmousekeyboard">
			<canon>input string with mouse keyboard (ID, maxlength)</canon>
			<shortname>input string with mouse keyboard</shortname>
			<description>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. <p>ID</p> is the string you want to use. All other arguments are optional: <p>maxlen</p> is the length of input, if left blank the limit will be set to 40 (max visible onscreen length).</description>
			<seealso>
				<ref>inputstring</ref>
				<ref>inputstringwithvirtualkeyboard</ref>
			</seealso>
		</command>
		<command id="unhidemousecursor">
			<canon>unhide mouse cursor</canon>
			<shortname>unhidemousecursor</shortname>
			<altcommand id="showmousecursor">
				<canon>show mouse cursor</canon>
				<shortname>show mouse cursor</shortname>
			</altcommand>
			<description>
				Causes the normal OS mouse cursor to be displayed, even when fullscreened.
				You may want to run this command right after <ref>initmouse</ref> unless you plan to use a scripted customized mouse cursor.
				<lb/>
				If you don't call <ref>initmouse</ref>, <ref>hidemousecursor</ref> or <ref>unhidemousecursor</ref> then
				the default behaviour is for the cursor to be shown when running in a window and hidden in fullscreen.
				<note>
					This command has no effect if the game is running on Android, because a mouse cursor is usually inappropriate on a touch screen.
				</note>
			</description>
		</command>
		<command id="hidemousecursor">
			<canon>hide mouse cursor</canon>
			<shortname>hidemousecursor</shortname>
			<description>Causes the normal OS mouse cursor to be hidden. This command is seldom needed, because the cursor is hidden by default when you run <ref>initmouse</ref>.</description>
		</command>

		<section title="Helpful Related Commands">
		<reference ref="camerapixelx" />
		<reference ref="camerapixely" />
		<reference ref="sliceatpixel" />
		<reference ref="slicecollidepoint" />
		<reference ref="npcatpixel" />
		<reference ref="menuitematpixel" />
		</section>		<!-- Helpful Related Commands-->

		</section>		<!-- Mouse Input-->
	</section>		<!-- Getting Player Input-->


	<section title="String Functions">
		<description>In HamsterSpeak, strings are special variables which hold pieces of text, and are referred to by their ID numbers. There are 100 string variables, with IDs 0 to 99. Strings variables can be displayed onscreen directly, or alternatively embedded in textboxes or displayed with text slices. For more information, see the <a href="rpg.hamsterrepublic.com/ohrrpgce/Strings">wiki article on strings</a>.<lb/>
You can set the value of a string directly with <ref>__setstring__</ref> and append to an existing string with <ref>__appendstring__</ref>.
There is no limit on string length.<lb/>
<note>Unlike almost all other indices in the OHRRPGCE, when referring to a position in a string, <p>position</p> is a 1-based index into the string, not a 0-based index. For example, given a string "ABCDEFG", position=3 is "C", not "D". This means that position 0 is invalid. Beware!</note>
<note>Strings are not saved in saved games by default, but this can be enabled in the Saved Game Settings menu.</note></description>

		<reference ref="showstring" />
		<reference ref="inputstring" />

		<command id="expandstring">
			<canon>expand string(ID, saveslot)</canon>
			<shortname>expand string</shortname>
			<description>
				Expands "embed" codes in string <p>ID</p> such as ${H1}, modifying the string.
				(See the textbox editor for the list of all available embed codes.)
				This does the same thing that textboxes do automatically.
				The <p>saveslot</p> argument is optional.
				If you leave it out, the string's codes will be expanded based on the currently running game state.
				If you specify a save slot number (from 1-1000) then the string will be expanded based on data
				(hero names, variables, strings, etc.) from that saved game.
			</description>
			<seealso>
				<ref>expandstringsinslices</ref>
			</seealso>
		</command>

		<section title="Basic String Commands">
		<command id="__setstring__">
			<canon>$id="some text"</canon>
			<shortname>$id="..."</shortname>
			<description>Sets the contents of a string variable given by <p>id</p>, which can be a constant like 0 or 1, a variable, or even an <ref>expression</ref> 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 <ref>__appendstring__</ref> statements instead). The value of the whole statement is equal to <p>id</p> for convenience (see the example). The text (which is called a string literal) can contain certain escape codes (see examples below):<lb/>
\\ turns into a single \<lb/>
\" turns into a single " without signalling the end of the literal<lb/>
\n is a new line character, which can be used in text slices, <ref>showstring</ref>, <ref>showstringat</ref> and <ref>trace</ref>.<lb/>
\t is a tab character (which isn't useful at all as it doesn't actually cause a tab except when printing to a file with <ref>trace</ref>).<lb/>
\x## where ## is a two digit hexidecimal number adds an ASCII character to the string. For example \x4b is the letter K.</description>
			<example># This displays Some text! in the corner of the screen
$1 = "Some text!"
showstring(1)

# This displays
# Guard:
#   "Halt!"
# near the bottom left corner of the screen (at 30,150) for a moment
show string at ($1="Guard:\n  \"Halt!\"", 30, 150)
wait (40)
hide string (1)</example>
		</command>
		<command id="__appendstring__">
			<canon>$id+"some text"</canon>
			<shortname>$id+"..."</shortname>
			<description>Appends a string literal to a string variable. This is the same as <ref>__setstring__</ref>, except that the existing contents of the string are preserved and appended to.</description>
		</command>
		<command id="clearstring">
			<canon>clear string(ID)</canon>
			<shortname>clear string</shortname>
			<description>Erases the string buffer #ID to the empty string (""). That's all.</description>
		</command>
		<command id="appendnumber">
			<canon>append number (ID, number, min length, pad with zeros)</canon>
			<shortname>append number</shortname>
			<description>
				Appends the decimal representation of <p>number</p> to the string with ID #<p>ID</p>.
				The optional <p>min length</p> argument can be used to add padding to the left or right.
				It's the minimum length of the string to append - if the number of digits
				(including the leading negative sign, if any)
				is less than this, then spaces or zeroes are added as padding:
				<ul>
					<li>
						If the optional argument <p>pad with zeros</p> (which defaults to false)
						is false, then spaces are added to the left (left of the negative
						sign, if any)
					</li>
					<li>
						If <p>pad with zeros</p> is true, then zeroes are added to the left
						(to the right of the negative sign, if any)
					</li>
					<li>
						If <p>min length</p> is negative, then the padding is added to the
						right instead.
						E.g. -4 means a minimum length of 4, padded to the right.
						<p>pad with zeros</p> is ignored.
					</li>
				</ul>
			</description>
			<example>append number(1, 65)           # Appends "65" to string 1.
append number(1, 1234, 3)      # Appends "1234" to string 1: no padding added

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

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

append number(1, 65, -4)       # Appends "65  " to string 1.
append number(1, 65, -4, true) # Appends "65  " to string 1: the 4th argument is ignored
append number(1, -65, -4)      # Appends "-65 " to string 1.</example>
			<seealso>
				<ref>appendascii</ref>
				<ref>stringsprintf</ref>
				<ref>numberfromstring</ref>
			</seealso>
		</command>
		<command id="stringsprintf">
			<canon>string sprintf (dest string ID, format string ID, arguments...)</canon>
			<shortname>string sprintf</shortname>
			<description>Builds a string from a template (given by <p>format string ID</p>) and zero or more additional arguments, and puts the result in the string <p>dest string ID</p>. 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:<lb/>
<p>%d</p>: substituted with a number, printed as a decimal.<lb/>
<p>%x</p>: substituted with a number, printed as a unsigned 32 bit hexidecimal, in lower case and without a leading 0x.<lb/>
<p>%o</p>: substituted with a number, printed as a unsigned 32 bit octal number, without a leading 0o.<lb/>
<p>%b</p>: substituted with a number, printed as a unsigned 32 bit binary number, with a space between every 8 bits, without a leading 0b.<lb/>
<p>%s</p>: substituted with a string. The argument should be a valid string ID.<lb/>
<p>%c</p>: substituted with a single character. The argument should be an ASCII code (that is, a number between 0 and 255).<lb/>
<p>%%</p>: substituted with a single %. In this case an argument is NOT used up.<lb/>
More sophisticated formatting codes like %-04d that are possible in other programming languages are not supported yet.
<note>
	Modifiers like field width and precision which are available in other programming languages,
	e.g. "%4d" or "%.2f", aren't available. But <ref>appendnumber</ref> has extra options for these.
</note>
</description>
			<example># 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)</example>
			<example># 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)
</example>
			<example># 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)</example>
			<seealso>
				<ref>appendascii</ref>
				<ref>appendnumber</ref>
			</seealso>
		</command>
		<command id="numberfromstring">
			<canon>number from string (ID, default)</canon>
			<shortname>number from string</shortname>
			<description>Try to read the string specified by <p>ID</p> 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 <p>default</p> value that will be returned if the string is not a valid number (for example, if it contains a non-numeric letter)</description>
			<seealso><ref>appendnumber</ref></seealso>
		</command>
		<command id="copystring">
			<canon>copy string (dest, source)</canon>
			<shortname>copy string</shortname>
			<description>Copies the text from string #<p>source</p> to string #<p>dest</p>, overwriting the existing string completely. <lb/>If you prefer, you can write <p>dest $= source</p> instead. You must supply string id numbers, not strings, as arguments.</description>
		</command>
		<command id="concatenatestrings">
			<canon>concatenate strings (dest, source)</canon>
			<shortname>concatenate strings</shortname>
			<description>Copies the text from string #<p>source</p> to string #<p>dest</p>. However, unlike <ref>copystring</ref>, the text is appended to the end of <p>dest</p>.  <lb/>If you prefer, you can write <p>dest $+ source</p> instead. You must supply string id numbers, not strings, as arguments.</description>
		</command>
		<command id="stringlength">
			<canon>string length (ID)</canon>
			<shortname>string length</shortname>
			<description>Returns the length of string #<p>ID</p>.</description>
		</command>
		<command id="stringequal">
			<canon>string equal (ID1, ID2)</canon>
			<shortname>string equal</shortname>
			<altcommand id="stringcompare">
				<canon>string compare (ID1, ID2)</canon>
				<shortname>string compare</shortname>
			</altcommand>
			<description>Returns true if the two strings #<p>ID1</p> and #<p>ID2</p> are identical, case sensitive.</description>
		</command>
		<command id="insensitivestringequal">
			<canon>insensitive string equal (ID1, ID2)</canon>
			<shortname>insensitive string equal</shortname>
			<altcommand id="insensitivestringcompare">
				<canon>insensitive string compare (ID1, ID2)</canon>
				<shortname>insensitive string compare</shortname>
			</altcommand>
			<description>Returns true if the two strings #<p>ID1</p> and #<p>ID2</p> are identical, case insensitive.</description>
		</command>
		<command id="stringtolower">
			<canon>string to lower (ID)</canon>
			<shortname>string to lower</shortname>
			<description>Converts the string at <p>ID</p> to lower-case. Returns the same string <p>ID</p>.</description>
		</command>
		<command id="stringtoupper">
			<canon>string to upper (ID)</canon>
			<shortname>string to upper</shortname>
			<description>Converts the string at <p>ID</p> to upper-case. Returns the same string <p>ID</p>.</description>
		</command>
		<command id="searchstring">
			<canon>search string (ID1, ID2, start)</canon>
			<shortname>search string</shortname>
			<description>Searches the string for a specified string, returns the position at which the string was found. <p>start</p> is the position at which you want to start looking, default is 1. <p>ID1</p> is the the string you want to search, <p>ID2</p> is the string you want to find. Returns <ref>false</ref> if the string wasn't found</description>
		</command>
		<command id="trimstring">
			<canon>trim string (ID, start, length)</canon>
			<canon>trim string (ID)</canon>
			<shortname>trim string</shortname>
			<description>
				Cuts a string to the specified substring (if you specify <p>start</p> and <p>length</p>),
				OR removes all whitespace (spaces, tabs and newlines) from the beginning and end of the string
				(if you only provide <p>ID</p>).
				<p>ID</p> is the string you want to trim.
				<lb/>
				<p>start</p> is the position at which you want the new string to start,
				anything to the left of this will be deleted from the string.
				Pass <tt>1</tt> if you don't want to cut anything from the start but just want to shorten the string.
				If <tt>start</tt> is past the end of the string, the string is blanked (this isn't an error).
				<lb/>
				<p>length</p> is the size of the string you want,
				anything to the right of <tt>start+length</tt> will be deleted.
				It's not an error if <tt>start+length</tt> is beyond the end of the string or if <tt>length &lt;= 0</tt>.
				<lb/>
			</description>
			<example>$1 = "  this silly example \n "
# \n is the newline character, if you remove the trimstring(1) now you'll see the text is two lines high
trim string(1)
show string(1)  # Shows "this silly example"
wait(30)
trim string(1, 3, 8)
show string(1)  # Shows "is silly"</example>
		</command>

		<command id="replacesubstring">
			<canon>replace substring (in string, replace what, with what, max replacements, case insensitive)</canon>
			<shortname>replace substring</shortname>
			<description>
				Replace occurrences in string ID <p>in string</p> of a substring (ID <p>replace what</p>)
				with a different string (ID <p>with what</p>).
				<lb/>
				By default, replaces all occurrences of <tt>replace what</tt>,
				but optionally you can limit the number of times to do the replacement by passing <p>max replacements</p>;
				there's no limit if it's &lt; 0.
				Inserted text is not eligible for further replacements (see examples).
				<lb/>
				If you pass <tt>true</tt> as the optional argument <p>case insensitive</p> (which defaults to false),
				then the search for <tt>replace what</tt> is case-insensitive.
				For example, "hi" matches "hi", "Hi", "HI" and "hI".
				<lb/>
				Returns the number of replacements done.
			</description>
			<example>$1 = "This is an example of replace substring"
# Shows '2'
show value (replace substring (1, $2="is", $3="iiss"))
wait for key
# Note that although "iiss" contains "is", it isn't replaced again with "iiisss"
show string (1)  # "Thiiss iiss an example of replace substring"
wait for key

$1 = "AaabaAaa"
replace substring (1, $2="AA", $3="CA", 2, true)  # Do only 2 replacements, case insensitively
# Again, Aaab becomes CAab but the new Aa isn't replaced, because part of it was a replacement
show string (1)  # "CAabCAaa"
</example>
		</command>

		<command id="appendascii">
			<canon>append ascii (ID, char)</canon>
			<shortname>append ascii</shortname>
			<description>
				Appends the character with ASCII code <p>char</p> to the string with ID <p>ID</p>.
				The font editor displays the character code of each character.
				For example numbers are 48 - 57, uppercase letters are 65 - 90, lowercase letters are 97 - 122.
			</description>
			<seealso>
				<ref>stringsprintf</ref>
				<ref>appendnumber</ref>
			</seealso>
		</command>
		<command id="replacechar">
			<canon>replace char (ID, position, char)</canon>
			<shortname>replace char</shortname>
			<description>Replaces the character at <p>position</p> in string #<p>ID</p> with a character with ascii code <p>char</p>. The first position of the string is 1, and the last position of the string is the same as <ref>stringlength</ref>.</description>
		</command>
		<command id="deletechar">
			<canon>delete char (ID, position)</canon>
			<shortname>delete char</shortname>
			<description>This deletes the character at <p>position</p> in string #<p>ID</p>, 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 <ref>stringlength</ref>.</description>
		</command>
		<command id="asciifromstring">
			<canon>ascii from string (ID, position)</canon>
			<shortname>ascii from string</shortname>
			<description>Returns the ascii code of the character at <p>position</p> in string #<p>ID</p>. The first position of the string is 1, and the last position of the string is the same as <ref>stringlength</ref>. If you pass 0 as the position or a position past the end of the string, 0 will be returned.</description>
		</command>
		</section>		<!-- Basic String Commands-->

                <section title="Get/Set Names of Things">
		<description>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 <ref>getmenuitemcaption</ref> live elsewhere, in more sensible sections!</description>

		<command id="getheroname">
			<canon>get hero name (ID, hero)</canon>
			<shortname>get hero name</shortname>
			<description>This command will take the name of the hero in the party slot #<p>hero</p>, and stick it in string #<p>ID</p>, overwriting its contents. <note>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 <ref>herobyrank</ref> and <ref>findhero</ref></note></description>
			<example># This example gets the name of the leader and stores it in string ID 1

get hero name (1, find hero (leader))
</example>
		</command>
		<command id="setheroname">
			<canon>set hero name (ID, hero)</canon>
			<shortname>set hero name</shortname>
			<description>This command changes the name of the hero in party slot #<p>hero</p> (as returned by <ref>findhero</ref>) to the contents of string #<p>ID</p>. The length is not limited by the hero's Max Name Length setting.</description>
		</command>
		<reference ref="getenemyname" />
		<reference ref="setenemyname" />
		<command id="getmapname">
			<canon>get map name (ID, map)</canon>
			<shortname>get map name</shortname>
			<description>This command will take the name of map #<p>map</p> and stick it in string #<p>ID</p>, overwriting its contents.</description>
		</command>
		<command id="getstatname">
			<canon>get stat name (ID, stat)</canon>
			<shortname>get stat name</shortname>
			<description>
				Gets the name of a <p>stat</p> and puts it in string #<p>ID</p>.
				The <p>stat</p> index can be a constant like <tt>stat:hp</tt> for stats 0-11 (but beware the names of these change to match the stats so are no use for portable scripts) or an in-battle register stat (stats 12-15 for poison, regen, stun and mute registers).
				<lb/>
				Safe to use with an out-of-range <p>stat</p>: returns <tt>false</tt> and sets a blank string without showing an error.
				Otherwise returns <tt>true</tt>.
			</description>
		</command>
		<reference ref="getattackname" />
		<reference ref="readattackname" />
		<reference ref="getattackcaption" />
		<command id="getsongname">
			<canon>get song name (ID, song)</canon>
			<shortname>get song name</shortname>
			<description>Gets the name of song #<p>song</p> and puts it in string #<p>ID</p>.</description>
		</command>
		<reference ref="stringfromtextbox" />
		<reference ref="textboxline" />
		</section>

                <section title="Showing Plotstrings">
		<description>These commands are an old (and largely obsolete) method of showing strings on the screen. They're completely separate to, and superceded by <secref>Text Slices</secref>. The <ref>showstring</ref> command is yet another separate way to display a string.</description>
		<reference ref="showstring" />
		<command id="showstringat">
			<canon>show string at (ID, x, y)</canon>
			<shortname>show string at</shortname>
			<description>Displays string #<p>ID</p> on the screen, positioning its top left corner at the given (<p>x</p>,<p>y</p>) coordinates. Unlike <ref>showstring</ref>, changes to the string will be displayed in real-time.
			The string will not auto-wrap at the edge of the screen, but it can contain new lines (<tt>\n</tt>). </description>
		</command>
		<command id="centerstringat">
			<canon>center string at (ID, x, y)</canon>
			<shortname>center string at</shortname>
			<description>
				Displays string #<p>ID</p> on the screen, positioning its top-middle at the
				given (<p>x</p>,<p>y</p>) coordinates.
				Unlike <ref>showstring</ref>, changes to the string will be displayed in real-time.
				<p>x</p>,<p>y</p> are optional: if they are missing then the string is centered
				in the center of the screen.
				<note>
					The string is not re-centered automatically if its length changes.
					If you change the string and want to keep it centered, call showstringat again.
					Otherwise, its top-left corner will stay fixed.
				</note>
				<warn>
					The string position will be miscalculated if it contains newlines (\n characters).
				</warn>
			</description>
		</command>
		<command id="hidestring">
			<canon>hide string (ID)</canon>
			<shortname>hide string</shortname>
			<description>Makes a string previously displayed with <ref>showstringat</ref> or <ref>centerstringat</ref> disappear. Has no effect on strings displayed with <ref>showstring</ref></description>
		</command>
		<command id="stringisvisible">
			<canon>string is visible (ID)</canon>
			<shortname>string is visible</shortname>
			<description>Returns true if a string is being displayed by <ref>showstringat</ref> or <ref>centerstringat</ref>. Otherwise, returns false. Is not effected by <ref>showstring</ref></description>
		</command>
		<command id="stringstyle">
			<canon>string style (ID, style)</canon>
			<shortname>string style</shortname>
			<description>Changes the appearance of a string. Use this in conjunction with (before or after) <ref>showstringat</ref> or <ref>centerstringat</ref>. Choice of <p>style</p> 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.</description>
		</command>
		<command id="stringcolor">
			<canon>string color (ID, foreground color, background color)</canon>
			<shortname>string color</shortname>
			<description>Changes the color of a string. Use this in conjunction with (before or after) <ref>showstringat</ref> or <ref>centerstringat</ref>. 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 <p>background color</p>, the background will be transparent. Omit <p>foreground color</p> as well to reset the color to default ('Text' User-interface color).</description>
		</command>
		<command id="positionstring">
			<canon>positionstring (ID, x, y)</canon>
			<shortname>position string</shortname>
			<description>Positions the top left corner of string #<p>ID</p> at the given <p>x</p>,<p>y</p> coordinates. Unlike <ref>showstringat</ref>, this command will not affect the visibility of a string.</description>
		</command>
		<command id="stringx">
			<canon>string X (ID)</canon>
			<shortname>string X</shortname>
			<description>Returns the horizontal X position of the top left corner of string #<p>ID</p></description>
		</command>
		<command id="stringy">
			<canon>string Y (ID)</canon>
			<shortname>string Y</shortname>
			<description>Returns the vertical Y position of the top left corner of string #<p>ID</p></description>
		</command>

		</section>   <!-- Basic string commands -->

		<section title="Obsolete Commands">

		<command id="stringtoglobals">
			<canon>string to globals (ID, starting global, length)</canon>
			<shortname>string to globals</shortname>
			<description>
				This command will fill global variables (starting with #<p>starting global</p>),
				up to <p>length</p> globals, with the ascii values of the characters in string #<p>ID</p>.
				If the string is not long enough, the rest of the globals in this "field" are padded with the value 256.
				If the string is too long, then only part of it is saved.
				<note>
					This command is deprecated.
					The Saved Game Settings menu now has an option to store strings in saved games.
					There is no reason to use this command in new games,
					unless you're using <ref>importglobals</ref>/<ref>exportglobals</ref>.
				</note>
			</description>
			<seealso><ref>globalstostring</ref></seealso>
		</command>
		<command id="globalstostring">
			<canon>globals to string(ID, starting global, length)</canon>
			<shortname>globals to string</shortname>
			<description>
				This command is the opposite of <ref>stringtoglobals</ref>.
				It will build a new string in slot #<p>ID</p>,
				using the ascii values from the global variables #<p>starting global</p>
				and <p>length</p> globals thereafter.
				Pass the same value for <p>length</p> as you did to <ref>stringtoglobals</ref>
				if you don't know the length of the string.
				If a global has a value greater than 255, the value will be ignored.
				<note>
					This command is deprecated.
					The Saved Game Settings menu now has an option to store strings in saved games.
					There is no reason to use this command in new games,
					unless you're using <ref>importglobals</ref>/<ref>exportglobals</ref>.
				</note>
			</description>
			<seealso><ref>stringtoglobals</ref></seealso>
		</command>

		</section>     <!-- Obsolete Commands -->

	</section>      <!-- String Functions -->

	<section title="Extra Data Array Functions">
		<description>
			Certain types of objects (slices, NPCs, zones, menu items) have "extra data",
			which is an array of data fields with no builtin meaning which you can use for whatever you want.
			(Menu item extra data is also passed as arguments to any script triggered by the item.)
			For example you could write a script to randomly play ambient sound effects while inside a zone,
			and store the sound effect numbers in the zone's extra data in the zone editor.
			<lb/>
			These functions can be used on any objects with a resizable "extra data" array.
			(To operate on zones you need to use <ref>getzone</ref> to get a zone handle.)
		</description>

		<command id="setextra">
			<canon>set extra (handle, extra, value)</canon>
			<shortname>set extra</shortname>
			<description>
				Sets one of the extra data variables on an object,
				which have no builtin meaning, they are only for use in your scripts.
				By default all new objects that support extra data start with a length 3 extra data array containing zeroes.
				<lb/>
				<p>handle</p> is an <ref>objecthandle</ref>.
				<p>extra</p> is an <ref>extradataindex</ref>, typically a value from 0 to 2.
				Use <ref>resizeextra</ref> if you want more than 3 extra values.
				<lb/>
				This command is a generic alternative to <ref>setsliceextra</ref>, <ref>setzoneextra</ref>, <ref>setnpcextra</ref>, and <ref>setmenuitemextra</ref>.
			</description>
			<seealso>
				<ref>getextra</ref>
				<ref>appendextra</ref>
			</seealso>
		</command>
		<command id="getextra">
			<canon>get extra (handle, extra)</canon>
			<shortname>get extra</shortname>
			<description>
				Retrieve a value of an object's extra data array (e.g. one previously stored with <ref>setextra</ref>).
				<lb/>
				<p>handle</p> is an <ref>objecthandle</ref>.
				<p>extra</p> is the <ref>extradataindex</ref> to read.
				<lb/>
				This command is a generic alternative to <ref>getsliceextra</ref>, <ref>getzoneextra</ref> (using <ref>getzone</ref> not a zone ID), <ref>npcextra</ref>, and <ref>getmenuitemextra</ref>.
				But it can't be used to replace <ref>getattackextra</ref>.
			</description>
		</command>

		<command id="appendextra">
			<canon>append extra (handle, value)</canon>
			<shortname>append extra</shortname>
			<description>
				Increases the length of an object's extra data array by 1 and puts <p>value</p> in the new slot at the end.
				<p>handle</p> is the <ref>objecthandle</ref>.
				<lb/>
				The return value is the new array length.
				<lb/>
				Equivalent to:
				<example>resize extra(handle, extra length(handle) + 1)
set extra(handle, -1, value)   # Index -1 is the last element of the array</example>
			</description>
		</command>
		<command id="insertextra">
			<canon>insert extra (handle, index, value)</canon>
			<shortname>insert extra</shortname>
			<description>
				Insert a value into a new position anywhere in an extra data array, moving up the index of all the data after it, and increasing the length by 1.
				<lb/>
				<p>handle</p> is the <ref>objecthandle</ref>.
				<lb/>
				<p>index</p> is an <ref>extradataindex</ref> where to put the new element. As usual negative indices count from the end.
				<lb/>
				<p>value</p> is the value to insert.
				<example>
# starting extra array 0,0,0
insert extra(handle, 0, 111) # 111,0,0,0
insert extra(handle, 2, 222) # 111,0,222,0,0</example>
				<note>
					Inserting an element means all the elments after it have to be moved. If you are using an extra array as a stack, and are concerned about high performance, it is better to push to the end with <tt>append extra(handle, value)</tt> rather than insert at the beginning with <tt>insert extra(handle, 0, value)</tt>
				</note>
			</description>
		</command>
		<command id="findextra">
			<canon>find extra (handle, value, start index)</canon>
			<shortname>find extra</shortname>
			<description>
				Search an object's extra data array for <p>value</p> and returns the index of the first item from the beginning
				equal to value, or -1 if not found.
				You could write a for loop instead but this command is much faster.
				<lb/>
				<p>handle</p> is the <ref>objecthandle</ref>.
				<lb/>
				<p>start index</p>, defaulting to 0, is an optional <ref>extradataindex</ref> where to start searching from;
				the search looks from there until the end of the array.
				(If it's beyond the end, the return value is always -1.)
				Use this if there might be multiple copies of the value and you want to find them all:
				set <p>start index</p> equal to the previous return value <tt>+ 1</tt>.
				<example>
# Deletes every occurrence of 'value' from an extra array.
script, remove extra, obj, value, begin
	variable (idx)
	while (true) do (
		idx := find extra (obj, value)
		if (idx == -1) then (exit)   # All deleted
		delete extra (obj, idx)
		# Normally we'd do "idx += 1" to look for the next occurrence of 'value'
		# after idx, but because we deleted it we don't need to.
	)
end</example>
			</description>
		</command>

		<command id="extralength">
			<canon>extra length (handle)</canon>
			<shortname>extra length</shortname>
			<description>
				Returns the length of an object's extra data array.
				This is 3 by default, and can be changed with <ref>resizeextra</ref>.
				<p>handle</p> is the <ref>objecthandle</ref>.
			</description>
		</command>
		<command id="resizeextra">
			<canon>resize extra (handle, length)</canon>
			<shortname>resize extra</shortname>
			<description>
				Changes the length of an object's extra data array.
				<p>handle</p> is the <ref>objecthandle</ref>.
				The new <p>length</p> can be between 0 and 5,000,000.
				For backwards compatibility it's 3 by default for all newly created slices, zones,
				NPCs and menu items.
				Values will either be removed from the end of the array, or zeroes added to the
				end to meet the new length.
				The rest of the existing contents of the array will be preserved.
			</description>
		</command>
		<command id="deleteextra">
			<canon>delete extra (handle, index)</canon>
			<shortname>delete extra</shortname>
			<description>
				Delete an element from an extra data array at a specific index, moving down the index of all the data after it, and decreasing the length of an object's extra data array by 1.
				<lb/>
				<p>handle</p> is the <ref>objecthandle</ref>.
				<lb/>
				<p>index</p> is the <ref>extradataindex</ref> of the element to delete and return.
				<lb/>
				The return value is the value that was found at the index which was removed.
				<example>
# starting extra array 11,12,13
delete extra(handle, 1) # returns 12, remaining extra data is 11,13
delete extra(handle, -1) # returns 13, remaining extra data is 11</example>
				<note>
					If you want to delete by value rather than by index, use the <tt>remove extra</tt>
					script from the example to <ref>findextra</ref>.
				</note>
				<note>
					Deleting an element means all the elments after it have to be moved. If you are using an extra array as queue, and are concerned about high performance, it is better to pop from the end with <tt>delete extra(handle, -1)</tt> rather than popping from the beginning with <tt>delete extra(handle, 0)</tt>
				</note>
			</description>
		</command>
		<command id="deleteextrarange">
			<canon>delete extra range (handle, from index, to index)</canon>
			<shortname>delete extra range</shortname>
			<description>
				Delete a range of elements from an extra data array starting from one index (inclusive) to another (exclusive).
				All the data after it will be moved down, and the length of an object's extra data array will be decreased by the same amount,
				which is <tt>to index -- from index</tt> elements (after converting negative indices to positive).
				<lb/>
				<p>handle</p> is the <ref>objecthandle</ref>.
				<lb/>
				<p>from index</p> is the <ref>extradataindex</ref> of the starting element to delete. It's the one returned. You can use negative indices as usual.
				<lb/>
				<p>to index</p> is the <ref>extradataindex</ref> of the first element <b>after</b> the deleted range: it is exclusive.
				<lb/>
				The return value is the item that was at <p>from index</p>,
				unless <tt>from index == to index</tt> (an empty range) in which case nothing
				happens and nothing is returned.
				<example>
delete extra range(handle, 2, 2) # Will not delete anything because the indices are the same
delete extra range(handle, 2, 3) # Will delete just the element at index 2, same as delete extra(handle, 2)

# starting extra array 50,51,52,53,54,55
delete extra range(handle, 2, 5) # delete elements 2, 3, and 4
# remaining extra array 50,51,55

# delete from element 1 to the end of the extra array, leaving behind only element 0
delete extra range(handle, 1, extra length(handle))</example>
				<note>
					Deleting elements means all the elments after them have to be moved. Using <tt>delete extra range</tt> to delete a bunch of elements at once is more efficient than calling <ref>deleteextra</ref> many times in a row, because the elements after only need to be moved once.
				</note>
			</description>
		</command>

	</section>  <!-- Extra Data Array Functions -->

	<section title="Shop Functions">
		<reference ref="useshop" />
		<command id="isshopbuymenuempty">
			<canon>is shop buy menu empty (shop id)</canon>
			<shortname>is shop buy menu empty</shortname>
			<description>
				Returns true if the shop specified by <p>shop id</p> has no available items. This could be because no items are defined, or they might all be out of stock or disabled by tags. You can use constants in the form of <tt>shop:Shop Name</tt>. 
			</description>
			<seealso>
				<ref>isshophiremenuempty</ref>
			</seealso>
		</command>
		<command id="isshophiremenuempty">
			<canon>is shop hire menu empty (shop id)</canon>
			<shortname>is shop hire menu empty</shortname>
			<description>
				Returns true if the shop specified by <p>shop id</p> has no available heroes for hire. This could be because no hireable heroes are defined, or they might all be out of stock or disabled by tags. You can use constants in the form of <tt>shop:Shop Name</tt>. 
			</description>
			<seealso>
				<ref>isshopbuymenuempty</ref>
			</seealso>
		</command>
		<reference ref="innscreen" />
		
	</section>  <!-- Shop Functions -->

	<section title="Menu Functions">
		<command id="openmenu">
			<canon>open menu (ID, allow duplicate)</canon>
			<shortname>open menu</shortname>
			<description>
				Opens the menu specified by <p>ID</p>.
				You can also use the constants defined in your HSI file in the form <tt>menu:name</tt>.
				The menu will be opened on top of any menus that are already open.
				<lb/>
				The optional second argument <p>allow duplicates</p> (defaulting to <tt>false</tt>)
				can be <ref>true</ref> if you want to be able to open more than one
				copy of the same menu at the same time.
				If <p>allow duplicates</p> is false and the menu is already open,
				then the existing menu (the top-most one, if there's more than one)
				is brought to the top.
				<lb/>
				The return value is a menu handle that you should store in a variable for use with
				other menu-related commands.
				(If an existing menu was brought to top, its handle is returned
				<lb/>
				If <p>ID</p> isn't a valid menu, this acts like <ref>createmenu</ref>.
				<warn>
					If menu 0 does NOT have the "Allow gameplay &amp; scripts" bit set,
					then your script will pause as soon as the menu opens, until either
					it's closed or another menu with that bit ON is opened.
					And once the menu has closed the menu handle is invalid!
				</warn>
			</description>
		</command>
		<command id="createmenu">
			<canon>create menu</canon>
			<shortname>create menu</shortname>
			<description>Create a new empty menu. You can add menu items to it with the <ref>addmenuitem</ref> command. The return value is a menu handle that you should save in a variable for use with other menu related commands. Menus created with this command have the "Allow gameplay and scripts" bitset turned on by default.</description>
		</command>
		<command id="closemenu">
			<canon>close menu(menu handle, run close script)</canon>
			<shortname>close menu</shortname>
			<description>
				Close a menu.
				The first argument is a <p>menu handle</p>
				(for example, the one returned by <ref>openmenu</ref> or <ref>topmenu</ref>).
				The second argument <p>run close script</p>, which defaults to <ref>false</ref>,
				states whether to run the menu's on-close script, if there is one.
			</description>
		</command>
		<command id="topmenu">
			<canon>top menu</canon>
			<shortname>top menu</shortname>
			<description>Return a menu handle for the topmost menu. Returns <ref>false</ref> if no menus are open.</description>
		</command>
		<command id="bottommenu">
			<canon>bottom menu</canon>
			<shortname>bottom menu</shortname>
			<description>Return a menu handle for the bottom menu (the menu underneath all other open menus). Returns <ref>false</ref> if no menus are open.</description>
		</command>
		<command id="previousmenu">
			<canon>previous menu(menu handle)</canon>
			<shortname>previous menu</shortname>
			<description>Return a menu handle for the menu beneath the one specified by <p>menu handle</p>, or false if there is no menu underneath.</description>
			<example>variable(menu)
menu := topmenu
while(menu) do, begin
 # do things to each menu
 menu := previous menu(menu)
end</example>
		</command>
		<command id="nextmenu">
			<canon>next menu(menu handle)</canon>
			<shortname>next menu</shortname>
			<description>Return a menu handle for the menu on top of the one specified by <p>menu handle</p>, or false if there is no menu on top</description>
			<example>variable(menu)
menu := bottom menu
while(menu) do, begin
 # do things to each menu
 menu := next menu(menu)
end</example>
		</command>
		<command id="bringmenuforward">
			<canon>bring menu forward(menu handle)</canon>
			<shortname>bring menu forward</shortname>
			<description>Given a <ref>menuhandle</ref>, move the menu to the top of all other open menus.</description>
		</command>
		<command id="findmenuid">
			<canon>find menu ID(menu ID)</canon>
			<shortname>find menu ID</shortname>
			<description>Given a <p>menu ID</p> number or a constant in the form of <p>menu:name</p>, check to see if it is already open, and if so return a <ref>menuhandle</ref> to it. Otherwise returns <ref>false</ref>.</description>
		</command>
		<command id="menuisopen">
			<canon>menu is open(menu handle)</canon>
			<shortname>menu is open</shortname>
			<description>Given a <ref>menuhandle</ref>, checks to see whether it is still open, and returns <ref>true</ref> if it is, or <ref>false</ref> if it has been closed.</description>
		</command>
		<command id="parentmenu">
			<canon>parent menu(menu item handle)</canon>
			<shortname>parent menu</shortname>
			<description>Given a <ref>menuitemhandle</ref>, return a menu handle for the menu that the menu item belongs to.</description>
		</command>
		<command id="getmenuid">
			<canon>get menu ID(menu handle)</canon>
			<shortname>get menu ID</shortname>
			<description>Given a <ref>menuhandle</ref>, return the ID number of the menu, or -1 if the men was created with the <ref>createmenu</ref> command.</description>
		</command>

		<section title="Menu Items">

		<command id="addmenuitem">
			<canon>add menu item(menu handle)</canon>
			<shortname>add menu item</shortname>
			<description>Given a <ref>menuhandle</ref>, 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 <ref>setmenuitemcaption</ref> or <ref>setmenuitemtype</ref>.</description>
		</command>
		<command id="deletemenuitem">
			<canon>delete menu item(menu item handle)</canon>
			<shortname>delete menu item</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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.)</description>
		</command>
		<command id="swapmenuitems">
			<canon>swap menu items(handle1, handle2)</canon>
			<shortname>swap menu items</shortname>
			<description>Given two <ref>menuitemhandle</ref>s 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.</description>
		</command>
		<command id="selectmenuitem">
			<canon>select menu item(menu item handle)</canon>
			<shortname>select menu item</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				move the menu selection cursor to point to that menu item.
				This works even if the menu item is in a menu that's not top-most/selected, but the
				menu won't become selected.
				Unselectable menu items (see <ref>menuitemselectable</ref>) can't be selected;
				if you try to select one this command silently fails and returns <tt>false</tt>;
				normally it returns <tt>true</tt>.
			</description>
		</command>
		<command id="selectedmenuitem">
			<canon>selected menu item(menu handle)</canon>
			<shortname>selected menu item</shortname>
			<description>
				Returns the handle for the selected menu item in the topmost menu
				if the optional <p>menu handle</p> is omitted, or,
				with a <ref>menuhandle</ref>
				returns the selected item in that menu.
				Returns <ref>false</ref> if no menus are open, or if the topmost or specified menu
				has no selection (which happens if it's empty, or all menu items are unselectable or hidden).
			</description>
		</command>

		<command id="menuitemdisabled">
			<canon>menu item disabled(menu item handle)</canon>
			<shortname>menu item disabled</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				returns whether that menu item is disabled (true or false).
				Menu items can be disabled for a range of reasons such as tag conditions.
			</description>
		</command>
		<command id="menuitemvisible">
			<canon>menu item visible(menu item handle)</canon>
			<shortname>menu item visible</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				returns whether that menu item is visible (true or false).
				A menu item is hidden only if it's disabled and has the "Hide if disabled" bit set.
			</description>
		</command>
		<command id="menuitemselectable">
			<canon>menu item selectable(menu item handle)</canon>
			<shortname>menu item selectable</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				returns true or false, telling whether that menu item is visible and can be selected by normal controls,
				(rather than being skipped over).
				<lb/>
				Currently only hidden menu items and Labels which "Can't be selected" return false.
			</description>
		</command>

		<command id="usemenuitem">
			<canon>use menu item(menu item handle)</canon>
			<shortname>use menu item</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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.</description>
		</command>
		<command id="firstmenuitem">
			<canon>first menu item(menu handle)</canon>
			<shortname>first menu item</shortname>
			<description>
				Given a <ref>menuhandle</ref>, return a menu item handle for the menu item at the
				top of the menu, or 0 (false) if there are no visible menu items.
				<note>
					This is NOT the handle for the first menu item defined in the menu editor.
					Use <tt><ref>menuitembytrueslot</ref>(menu, 0)</tt> to get that one.
				</note>
			</description>
		</command>
		<command id="lastmenuitem">
			<canon>last menu item(menu handle, visible only)</canon>
			<shortname>last menu item</shortname>
			<description>
				Given a <ref>menuhandle</ref>, by default returns a menu item handle for the
				last visible menu item, at the bottom of the menu.
				<p>visible only</p> defaults to <tt>true</tt>.
				If you pass <p>false</p> as the <p>visible only</p> argument,
				then returns the last visible or invisible menu item
				(last as seen by <ref>menuitembyslot</ref> or <ref>nextmenuitem</ref>).
				<note>
					<tt>last menu item(menu, false)</tt> does NOT return the handle for the
					last menu item that appears in the menu editor, because menu items are
					sorted based on visibility: all invisible items to the end.
					Use <tt><ref>menuitembytrueslot</ref>(menu, <ref>menuitemcount</ref>(menu) -- 1)</tt>
					to get that one.
				</note>
			</description>
		</command>

		<command id="nextmenuitem">
			<canon>next menu item(menu item handle, visible only)</canon>
			<shortname>next menu item</shortname>
			<description>Given a <ref>menuitemhandle</ref>, return a menu item handle for the menu item below the specified one, or <ref>false</ref> there is no next menu item. You can optionally include invisible items by using the optional argument <p>visible only</p>, which defaults to <ref>true</ref>.
				<note>
					Invisible menu items are always at the end of the menu,
					after the last visible menu item,
					not in the order in which they are defined in the menu editor!
					See <ref>menuitembytrueslot</ref> if that's undesirable.
				</note>
			</description>
			<example>variable(mi)
mi := first menu item
while(mi) do, begin
  # do things to each visible menu item
  mi := next menu item(mi)
end
</example>
		</command>
		<command id="previousmenuitem">
			<canon>previous menu item(menu item handle, visible only)</canon>
			<shortname>previous menu item</shortname>
			<description>Given a <ref>menuitemhandle</ref>, return a menu item handle for the menu item above the specified one, or <ref>false</ref> there is no previous menu item. You can optionally include invisible items by using the optional argument <p>visible only</p>, which defaults to <ref>true</ref>. Note that invisible menu items are always at the end of the menu, after the last visible menu item. See <ref>menuitembytrueslot</ref> if that's undesirable.</description>
			<example>variable(m)
m := previous menu item(selected menu item)</example>
		</command>

		<command id="menuitemcount">
			<canon>menu item count(menu handle)</canon>
			<shortname>menu item count</shortname>
			<description>
				Returns the total number of menu items in a menu,
				both visible and invisible (disabled).
			</description>
			<seealso>
				<ref>visiblemenuitemcount</ref>
			</seealso>
		</command>
		<command id="visiblemenuitemcount">
			<canon>visible menu item count(menu handle)</canon>
			<shortname>visible menu item count</shortname>
			<description>
				Returns the number of visible menu items in a menu.
			</description>
			<seealso>
				<ref>menuitemcount</ref>
			</seealso>
		</command>

		<command id="menuitembytrueslot">
			<canon>menu item by true slot(menu handle, slot)</canon>
			<shortname>menu item by true slot</shortname>
			<description>Given a <ref>menuhandle</ref>, return a menu item handle for the menu item at the position specified by <p>slot</p>. 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 <ref>menuitemslot</ref>.</description>
			<seealso>
				<ref>menuitembyslot</ref>
			</seealso>
		</command>
		<command id="menuitemtrueslot">
			<canon>menu item true slot(menu item handle)</canon>
			<shortname>menu item true slot</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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 <ref>menuitemslot</ref>.</description>
			<seealso>
				<ref>menuitemslot</ref>
				<ref>menuitembytrueslot</ref>
			</seealso>
		</command>
		<command id="menuitembyslot">
			<canon>menu item by slot(menu handle, slot, visible only)</canon>
			<shortname>menu item by slot</shortname>
			<description>Given a <ref>menuhandle</ref>, return a menu item handle for the menu item at the position specified by <p>slot</p>. The first slot in the menu is 0. You can optionally include invisible items by using the optional argument <p>visible only</p>, which defaults to <ref>true</ref>. 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 <ref>menuitembytrueslot</ref> if you want to use the order shown in the Menu Editor.</description>
			<seealso>
				<ref>menuitemslot</ref>
				<ref>menuitembytrueslot</ref>
				<ref>menuitemcount</ref>
				<ref>visiblemenuitemcount</ref>
			</seealso>
		</command>
		<command id="menuitemslot">
			<canon>menu item slot(menu item handle)</canon>
			<shortname>menu item slot</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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 <ref>menuitemtrueslot</ref> if you want to know the slot number as it appears in the Menu Editor.</description>
			<seealso>
				<ref>menuitembyslot</ref>
				<ref>menuitemtrueslot</ref>
			</seealso>
		</command>
		<command id="findmenuitemcaption">
			<canon>find menu item caption(menu handle, string ID, search after handle, visible only)</canon>
			<shortname>find menu item caption</shortname>
			<description>Given a <ref>menuhandle</ref>, and a string identified by <p>string ID</p>, 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 <p>search after handle</p> 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 <p>visible only</p> is a <ref>true</ref> or <ref>false</ref> value that determines whether or not to include hidden items. It defaults to <ref>true</ref>.</description>
			<example>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</example>
		</command>
		<command id="menuitematpixel">
			<canon>menu item at pixel(x, y)</canon>
			<shortname>menu item at pixel</shortname>
			<description>
				Given a position on the screen (for example <p>menu item at pixel</p>(<ref>mousepixelx</ref>, <ref>mousepixely</ref>)),
				returns the handle for the menu item at that position, or <p>false</p> 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 <ref>parentmenu</ref>.
				<note>
					The menu item might not actually be selectable. Check with <ref>menuitemselectable</ref>.
				</note>
			</description>
			<seealso>
				<ref>selectedmenuitem</ref>
			</seealso>
		</command>

		<section title="Menu Item Data">

		<command id="getmenuitemcaption">
			<canon>get menu item caption(menu item handle, string ID)</canon>
			<shortname>get menu item caption</shortname>
			<description>Given a <ref>menuitemhandle</ref>, take the caption and copy it into the string identified by <p>string ID</p>.</description>
		</command>
		<command id="setmenuitemcaption">
			<canon>set menu item caption(menu item handle, string ID)</canon>
			<shortname>set menu item caption</shortname>
			<description>Given a <ref>menuitemhandle</ref>, replace the caption with the string identified by <p>string ID</p>.</description>
		</command>
		<command id="getmenuitemtype">
			<canon>get menu item type(menu item handle)</canon>
			<shortname>get menu item type</shortname>
			<description>Given a <ref>menuitemhandle</ref>, return the type of the menu item.</description>
		</command>
		<command id="setmenuitemtype">
			<canon>set menu item type(menu item handle, new type)</canon>
			<shortname>set menu item type</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				change the type of the menu item to <p>new type</p>.
				Available constants are:
				<tt>menutype:label</tt> (aka <tt>menutype:caption</tt>), <tt>menutype:special</tt>, <tt>menutype:menu</tt>,
				<tt>menutype:textbox</tt>, and <tt>menutype:script</tt>.
				<lb/>
				You will also need to call
				<ref>setmenuitemsubtype</ref> to fully specify the action attached to the menu item.
				Setting just the item type does NOT change the subtype to a sensible value!
			</description>
		</command>
		<command id="getmenuitemsubtype">
			<canon>get menu item subtype(menu item handle)</canon>
			<shortname>get menu item subtype</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				return the subtype of the menu item. The meaning of the subtype varies depending on the type
				(see <ref>setmenuitemsubtype</ref>).
			</description>
			<seealso>
				<ref>setmenuitemsubtype</ref>
			</seealso>
		</command>
		<command id="setmenuitemsubtype">
			<canon>set menu item subtype(menu item handle, new subtype)</canon>
			<shortname>set menu item subtype</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				change the subtype of the menu item to <p>new subtype</p>.
				The meaning of the subtype varies depending on the type of the menu item,
				which is changed with <ref>setmenuitemtype</ref>:

				<ul>
					<li>
						For <tt>menutype:label</tt> use the constants:
						<ul>
							<li>
								<p>menulabel:selectable</p>
							</li>
							<li>
								<p>menulabel:disabled</p> -
								The menu item is always disabled, regardless of tags.
								Hence, the Set Tag and Toggle Tag options and the
								"Close menu when activated" bitset are ignored.
							</li>
							<li>
								<p>menulabel:unselectable</p> - (aka <p>menulabel:cant be selected</p>)
								Can't be selected with normal controls.
								Can still be selected using <ref>selectmenuitem</ref>
								(but can't be activated).
							</li>
						</ul>
					</li>
					<li>
						For <tt>menutype:special</tt> use the constants:
						<ul>
							<li>
								<p>menuspecial:items</p>
							</li>
							<li>
								<p>menuspecial:spells</p>
							</li>
							<li>
								<p>menuspecial:status</p>
							</li>
							<li>
								<p>menuspecial:equip</p>
							</li>
							<li>
								<p>menuspecial:order</p> - Reorder the active party
							</li>
							<li>
								<p>menuspecial:team</p> - Reorder, or swap heroes in and out of the active party 
							</li>
							<li>
								<p>menuspecial:order team</p> -
								Either the Team menu if the "Hero Swapping Always
								Available" general preference bitset is turned on,
								otherwise the Order menu.
							</li>
							<li>
								<p>menuspecial:map</p> - Minimap.
								Appears only if allowed in the Map General Settings.
							</li>
							<li>
								<p>menuspecial:save</p> -
								Appears only if allowed in the Map General Settings.
							</li>
							<li>
								<p>menuspecial:load</p>
							</li>
							<li>
								<p>menuspecial:quit</p>
							</li>
							<li>
								<p>menuspecial:volume</p> - Obsolete.
								This lets you adjust the music volume, and pressing
								Enter opens a new menu with Music and Sound Volume
								options.
							</li>
							<li>
								<p>menuspecial:map always</p> - Minimap.
								Appears even if the minimap isn't allowed in Map General Settings.
							</li>
							<li>
								<p>menuspecial:save always</p> -
								Appears even if saving isn't allowed in Map General Settings.
							</li>
							<li>
								<p>menuspecial:margins</p> -
								An option to adjust margins at the edges of the screen,
								when playing a game on a console like the Ouya which
								displays on a TV.
								(Only appears on consoles)
							</li>
							<li>
								<p>menuspecial:purchases</p> -
								Appears only if a store has been set in the
								In-App Purchases menu.
							</li>
							<li>
								<p>menuspecial:windowed</p> -
								Appears only if currently playing fullscreen, and
								switching to windowed is supported.
							</li>
							<li>
								<p>menuspecial:fullscreen</p> -
								Appears only if currently playing windowed, and
								switching to fullscreen is supported.
								<lb/>
								You must add BOTH Fullscreen and Windowed menu items
								next to each other to allow players to switch to-and-fro.
							</li>
							<li>
								<p>menuspecial:music volume</p>
							</li>
							<li>
								<p>menuspecial:sound volume</p>
							</li>
						</ul>
					</li>
					<li>
						For <tt>menutype:textbox</tt> use the textbox's ID number.
					</li>
					<li>

						For <tt>menutype:menu</tt> use the menu's ID number or a menu:name constant from your HSI file.
					</li>
					<li>
						For <tt>menutype:script</tt> use script references in the form <tt>@scriptname</tt>.
					</li>
				</ul>
			</description>
		</command>
		<command id="getmenuitemtag">
			<canon>get menu item tag(menu item handle, whichtag)</canon>
			<shortname>get menu item tag</shortname>
			<description>Given a <ref>menuitemhandle</ref>, and a tag number <p>whichtag</p> 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.</description>
		</command>
		<command id="setmenuitemtag">
			<canon>set menu item tag(menu item handle, new tag, whichtag)</canon>
			<shortname>set menu item tag</shortname>
			<description>Given a <ref>menuitemhandle</ref>, and a tag number <p>whichtag</p> which can be 1 or 2, set the tag required for the menu item to <p>new tag</p>. Use a positive number if the tag needs to be turned ON, and a negative number if the tag needs to be turned OFF.</description>
		</command>
		<command id="getmenuitemsettag">
			<canon>get menu item settag(menu item handle)</canon>
			<shortname>get menu item settag</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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.</description>
		</command>
		<command id="setmenuitemsettag">
			<canon>set menu item settag(menu item handle, new settag)</canon>
			<shortname>set menu item settag</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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.</description>
		</command>
		<command id="getmenuitemtogtag">
			<canon>get menu item togtag(menu item handle)</canon>
			<shortname>get menu item togtag</shortname>
			<description>Given a <ref>menuitemhandle</ref>, 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).</description>
		</command>
		<command id="setmenuitemtogtag">
			<canon>set menu item togtag(menu item handle, new settag)</canon>
			<shortname>set menu item togtag</shortname>
			<description>Given a <ref>menuitemhandle</ref>, change the tag that will be toggled when the menu item is selected. (The tag number will always be positive).</description>
		</command>
		<command id="getmenuitembit">
			<canon>get menu item bit(menu item handle, bit)</canon>
			<shortname>get menu item bit</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				and bit number <p>bit</p>,
				return <ref>true</ref> if the bitset is ON, and <ref>false</ref> if the bitset is OFF.
				See <ref>setmenuitembit</ref> for the constants you can pass as the value of <p>bit</p>.
			</description>
		</command>
		<command id="setmenuitembit">
			<canon>set menu item bit(menu item handle, bit, value)</canon>
			<shortname>set menu item bit</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>,
				and bit number <p>bit</p>, set the bitset is ON or OFF depending on <p>value</p>.
				You can use the following constants for <p>bit</p>:
				<ul>
					<li>
						<p>menu item bit:Hide when disabled</p>
					</li>
					<li>
						<p>menu item bit:Close menu when activated</p> (the old name, <p>menu item bit:Close menu when selected</p>, can also be used)
					</li>
					<li>
						<p>menu item bit:Skip close script</p> (ie "Don't run on-close script")
					</li>
				</ul>
			</description>
		</command>
		<command id="getmenuitemextra">
			<canon>get menu item extra(menu item handle, extra)</canon>
			<shortname>get menu item extra</shortname>
			<description>Given a <ref>menuitemhandle</ref>, and an <p>extra</p> 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.</description>
		</command>
		<command id="setmenuitemextra">
			<canon>set menu item extra(menu item handle, extra, num)</canon>
			<shortname>set menu item extra</shortname>
			<description>Given a <ref>menuitemhandle</ref>, and an <p>extra</p> data number which can be 0, 1, or 2, change the number stored in the extra data space to <p>num</p>. This extra data has no meaning of its own, and is just useful for advanced menu scripting.</description>
		</command>

		<command id="getmenuitemcolor">
			<canon>get menu item color(menu item handle)</canon>
			<shortname>get menu item color</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>, get its normal color (when it isn't disabled). This will be a <ref>colorcode</ref>.
				0 means the default for the menu is used, which is <ref>getmenutextcolor</ref>.
			</description>
			<seealso>
				<ref>getmenutextcolor</ref>
				<ref>menuitemdisabled</ref>
			</seealso>
		</command>
		<command id="setmenuitemcolor">
			<canon>set menu item color(menu item handle, colorcode)</canon>
			<shortname>set menu item color</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>, set its normal color (when it isn't disabled). This should be a <ref>colorcode</ref>.
				0 means to use the default for the menu, which is <ref>getmenutextcolor</ref>.
			</description>
			<seealso>
				<ref>setmenutextcolor</ref>
				<ref>menuitemdisabled</ref>
			</seealso>
		</command>
		<command id="getmenuitemdisabledcolor">
			<canon>get menu item disabled color(menu item handle)</canon>
			<shortname>get menu item disabled color</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>, get the color it uses when disabled. This will be a <ref>colorcode</ref>.
				0 means the default for the menu is used, which is <ref>getmenudisabledtextcolor</ref>.
			</description>
			<seealso>
				<ref>setmenudisabledtextcolor</ref>
				<ref>menuitemdisabled</ref>
			</seealso>
		</command>
		<command id="setmenuitemdisabledcolor">
			<canon>set menu item disabled color(menu item handle, colorcode)</canon>
			<shortname>set menu item disabled color</shortname>
			<description>
				Given a <ref>menuitemhandle</ref>, set its color it uses when disabled. This should be a <ref>colorcode</ref>.
				0 means to use the default for the menu, which is <ref>getmenudisabledtextcolor</ref>.
			</description>
			<seealso>
				<ref>setmenudisabledtextcolor</ref>
				<ref>menuitemdisabled</ref>
			</seealso>
		</command>

		</section>  	<!--Menu Item Data-->
		</section>	<!--Menu Items-->

		<section title="Menu Data">

		<command id="getmenubit">
			<canon>get menu bit(menu handle, bit)</canon>
			<shortname>get menu bit</shortname>
			<description>
				Given a <ref>menuhandle</ref>,
				and bit number <p>bit</p>, returns <ref>true</ref> if the bitset is ON, and <ref>false</ref> if the bitset is OFF.
				For the <p>bit</p> bit number you should use one of the constants:
				<ul>
					<li>menubit:translucent box</li>
					<li>menubit:never show scrollbar</li>
					<li>menubit:allow gameplay</li>
					<li>menubit:suspend player even if gameplay allowed</li>
					<li>menubit:no box</li>
					<li>menubit:no close</li>
					<li>menubit:no controls</li>
					<li>menubit:prevent main menu</li>
					<li>menubit:advance text box when menu closes</li>
					<li>menubit:highlight selection background</li>
					<li>menubit:remember selection</li>
					<li>menubit:clamp to screen bounds</li>
				</ul>
			</description>
		</command>
		<command id="setmenubit">
			<canon>set menu bit(menu handle, bit, value)</canon>
			<shortname>set menu bit</shortname>
			<description>
				Given a <ref>menuhandle</ref>,
				and bit number <p>bit</p>, sets the bitset is ON or OFF depending on <p>value</p>.
				For the <p>bit</p> bit number you should use one of the <p>menubit:...</p> constants.
				See <ref>getmenubit</ref> for the available constants.
				<lb/>
				Note that this command only changes an open instance of a menu, it doesn't
				change the menu definition, so if the menu is closed and reopened any
				edits are reverted.
			</description>
		</command>
		<command id="getmenuboxstyle">
			<canon>get menu boxstyle(menu handle)</canon>
			<shortname>get menu boxstyle</shortname>
			<description>Given a <ref>menuhandle</ref>, return a the boxstyle of the menu. This will be a number from 0 to 14.</description>
		</command>
		<command id="setmenuboxstyle">
			<canon>set menu boxstyle(menu handle, new box style)</canon>
			<shortname>set menu boxstyle</shortname>
			<description>Given a <ref>menuhandle</ref>, change the boxstyle of the menu. <p>new box style</p> will be a number from 0 to 14.</description>
		</command>

		<command id="getmenutextcolor">
			<canon>get menu textcolor(menu handle)</canon>
			<shortname>get menu textcolor</shortname>
			<description>Given a <ref>menuhandle</ref>, return the default text color of the menu items. This will be a <ref>colorcode</ref>. 0 means the default is used, which is the "Menu item" color (<tt>ui:menuitem</tt>) in the User Interface Colors menu.</description>
		</command>
		<command id="setmenutextcolor">
			<canon>set menu textcolor(menu handle, new textcolor)</canon>
			<shortname>set menu textcolor</shortname>
			<description>Given a <ref>menuhandle</ref>, change the default text color of its menu items. <p>new textcolor</p> should be a <ref>colorcode</ref>. 0 means the default is used, which is the "Menu item" color (<tt>ui:menuitem</tt>) in the User Interface Colors menu.</description>
		</command>
		<command id="getmenudisabledtextcolor">
			<canon>get menu disabled textcolor(menu handle)</canon>
			<shortname>get menu disabled textcolor</shortname>
			<description>Given a <ref>menuhandle</ref>, return the default text color of disabled menu items. This will be a <ref>colorcode</ref>. 0 means the default is used, which is the "Disabled menu item" color (<tt>ui:disableditem</tt>) in the User Interface Colors menu.</description>
		</command>
		<command id="setmenudisabledtextcolor">
			<canon>set menu disabled textcolor(menu handle, new textcolor)</canon>
			<shortname>set menu disabled textcolor</shortname>
			<description>Given a <ref>menuhandle</ref>, change the default text color of disabled menu items. <p>new textcolor</p> should be a <ref>colorcode</ref>. 0 means the default is used, which is the "Disabled menu item" color (<tt>ui:disableditem</tt>) in the User Interface Colors menu.</description>
		</command>

		<command id="getmenumaxrows">
			<canon>get menu max rows(menu handle)</canon>
			<shortname>get menu max rows</shortname>
			<description>Given a <ref>menuhandle</ref>, 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.</description>
		</command>
		<command id="setmenumaxrows">
			<canon>set menu max rows(menu handle, new max rows)</canon>
			<shortname>set menu max rows</shortname>
			<description>Given a <ref>menuhandle</ref>, change the max rows to display of the menu to <p>new max rows</p>. 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.</description>
		</command>
		<command id="getmenuoffsetx">
			<canon>get menu offset x(menu handle)</canon>
			<shortname>get menu offset x</shortname>
			<description>Given a <ref>menuhandle</ref>, return the x offset position of the menu's anchor point in pixels relative to the center of the screen.</description>
			<seealso>
				<ref>getmenuoffsety</ref>
				<ref>setmenuoffsetx</ref>
				<ref>setmenuoffsety</ref>
			</seealso>
		</command>
		<command id="getmenuoffsety">
			<canon>get menu offset y(menu handle)</canon>
			<shortname>get menu offset y</shortname>
			<description>Given a <ref>menuhandle</ref>, return the y offset position of the menu's anchor point in pixels relative to the center of the screen.</description>
			<seealso>
				<ref>getmenuoffsetx</ref>
				<ref>setmenuoffsetx</ref>
				<ref>setmenuoffsety</ref>
			</seealso>
		</command>
		<command id="setmenuoffsetx">
			<canon>set menu offset x(menu handle, new x)</canon>
			<shortname>set menu offset x</shortname>
			<description>Given a <ref>menuhandle</ref>, change the x offset position of the menu's anchor point in pixels relative to the center of the screen.</description>
			<seealso>
				<ref>getmenuoffsetx</ref>
				<ref>getmenuoffsety</ref>
				<ref>setmenuoffsety</ref>
			</seealso>
		</command>
		<command id="setmenuoffsety">
			<canon>set menu offset y(menu handle, new y)</canon>
			<shortname>set menu offset y</shortname>
			<description>Given a <ref>menuhandle</ref>, change the y offset position of the menu's anchor point in pixels relative to the center of the screen.</description>
			<seealso>
				<ref>getmenuoffsetx</ref>
				<ref>getmenuoffsety</ref>
				<ref>setmenuoffsetx</ref>
			</seealso>
		</command>
		<command id="getmenuanchorx">
			<canon>get menu anchor x(menu handle)</canon>
			<shortname>get menu anchor x</shortname>
			<description>Given a <ref>menuhandle</ref>, return the x anchor position of the menu. The return value will be <p>align:center</p>, <p>align:left</p> or <p>align:right</p>. (Not the <tt>edge:</tt> constants used by slices!)</description>
			<seealso>
				<ref>getmenuanchory</ref>
				<ref>setmenuanchorx</ref>
				<ref>setmenuanchory</ref>
			</seealso>
		</command>
		<command id="getmenuanchory">
			<canon>get menu anchor y(menu handle)</canon>
			<shortname>get menu anchor y</shortname>
			<description>Given a <ref>menuhandle</ref>, return the y anchor position of the menu. The return value will be <p>align:center</p>, <p>align:top</p> or <p>align:bottom</p>. (Not the <tt>edge:</tt> constants used by slices!)</description>
			<seealso>
				<ref>getmenuanchorx</ref>
				<ref>setmenuanchorx</ref>
				<ref>setmenuanchory</ref>
			</seealso>
		</command>
		<command id="setmenuanchorx">
			<canon>set menu anchor x(menu handle, new anchor)</canon>
			<shortname>set menu anchor x</shortname>
			<description>Given a <ref>menuhandle</ref>, change the horizontal x anchor position of the menu. The <p>new anchor</p> can be <p>align:center</p>, <p>align:left</p> or <p>align:right</p>.</description>
			<seealso>
				<ref>getmenuanchorx</ref>
				<ref>getmenuanchory</ref>
				<ref>setmenuanchory</ref>
			</seealso>
		</command>
		<command id="setmenuanchory">
			<canon>set menu anchor y(menu handle, new anchor)</canon>
			<shortname>set menu anchor y</shortname>
			<description>Given a <ref>menuhandle</ref>, change the vertical y anchor position of the menu. The <p>new anchor</p> can be <p>align:center</p>, <p>align:top</p> or <p>align:bottom</p>. (Not the <tt>edge:</tt> constants used by slices!)</description>
			<seealso>
				<ref>getmenuanchorx</ref>
				<ref>getmenuanchory</ref>
				<ref>setmenuanchorx</ref>
			</seealso>
		</command>
		<command id="getmenutextalign">
			<canon>get menu text align(menu handle)</canon>
			<shortname>get menu text align</shortname>
			<description>Given a <ref>menuhandle</ref>, return the text alignment of the menu. The return value will be <p>align:center</p>, <p>align:left</p> or <p>align:right</p>. (Not the <tt>edge:</tt> constants used by slices!)</description>
			<seealso>
				<ref>setmenutextalign</ref>
			</seealso>
		</command>
		<command id="setmenutextalign">
			<canon>set menu text align(menu handle, new align)</canon>
			<shortname>set menu text align</shortname>
			<description>Given a <ref>menuhandle</ref>, change the text alignment of the menu. The <p>new align</p> can be <p>align:center</p>, <p>align:left</p> or <p>align:right</p>. (Not the <tt>edge:</tt> constants used by slices!)</description>
			<seealso>
				<ref>getmenutextalign</ref>
			</seealso>
		</command>
		<command id="getmenuminchars">
			<canon>get menu min chars(menu handle)</canon>
			<shortname>get menu min chars</shortname>
			<description>Given a <ref>menuhandle</ref>, return the minimum width of the menu in chars, or 0 for menus that have their width autodetected.</description>
			<seealso>
				<ref>setmenuminchars</ref>
			</seealso>
		</command>
		<command id="setmenuminchars">
			<canon>set menu min chars(menu handle, new min)</canon>
			<shortname>set menu min chars</shortname>
			<description>Given a <ref>menuhandle</ref>, change the minimum width of the menu in chars, or use 0 to make the menu width autodetected.</description>
			<seealso>
				<ref>getmenuminchars</ref>
			</seealso>
		</command>
		<command id="getmenumaxchars">
			<canon>get menu max chars(menu handle)</canon>
			<shortname>get menu max chars</shortname>
			<description>Given a <ref>menuhandle</ref>, return the maximum width of the menu in chars, or 0 for menus that do not have a maximum.</description>
			<seealso>
				<ref>setmenumaxchars</ref>
			</seealso>
		</command>
		<command id="setmenumaxchars">
			<canon>set menu max chars(menu handle, new max)</canon>
			<shortname>set menu max chars</shortname>
			<description>Given a <ref>menuhandle</ref>, change the maximum width of the menu in chars, or use 0 for no maximum.</description>
			<seealso>
				<ref>getmenumaxchars</ref>
			</seealso>
		</command>
		<command id="getmenuborder">
			<canon>get menu border(menu handle)</canon>
			<shortname>get menu border</shortname>
			<description>Given a <ref>menuhandle</ref>, return the border thickness of the menu in pixels. Positive numbers indicate a thicker border. Negative numbers indicate a thinner border.</description>
			<seealso>
				<ref>setmenuborder</ref>
			</seealso>
		</command>
		<command id="setmenuborder">
			<canon>set menu border(menu handle, new border)</canon>
			<shortname>set menu border</shortname>
			<description>Given a <ref>menuhandle</ref>, 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.</description>
			<seealso>
				<ref>getmenuborder</ref>
			</seealso>
		</command>
		<command id="getmenuonclosescript">
			<canon>get menu on close script(menu handle)</canon>
			<shortname>get menu on close script</shortname>
			<description>Given a <ref>menuhandle</ref>, return a <ref>scriptid</ref> for the script that will be run when the menu is closed, or <p>false</p> if there is none. This command is only useful with scripts that have the <p>allow gameplay and scripts</p> bitset turned on.</description>
			<example>variable(m, s)
m := open menu(5)
s := get menu on close script(m)
run script by id(s)
			</example>
			<seealso>
				<ref>runscriptbyid</ref>
				<ref>setmenuonclosescript</ref>
			</seealso>
		</command>
		<command id="setmenuonclosescript">
			<canon>set menu on close script(menu handle, script id)</canon>
			<shortname>set menu on close script</shortname>
			<description>Given a <ref>menuhandle</ref>, assign the <ref>scriptid</ref> that will be run when the menu is closed, or <p>false</p> 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 <p>allow gameplay and scripts</p> bitset turned on.</description>
			<example>variable(m, s)
m := open menu(5)
set menu on close script(m, @my menu exit handler)
			</example>
			<seealso>
				<ref>runscriptbyid</ref>
				<ref>setmenuonclosescript</ref>
			</seealso>
		</command>
		<command id="getmenucancelbuttonmenu">
			<canon>get menu cancel button menu(menu handle)</canon>
			<shortname>get menu cancel button menu</shortname>
			<description>
				Given a <ref>menuhandle</ref>,
				returns the action that happens when the player presses a cancel button.
				-1 means the menu simply closes.
				0 or greater is a menu ID to open in its place
			</description>
			<seealso>
				<ref>setmenucancelbuttonmenu</ref>
			</seealso>
		</command>
		<command id="setmenucancelbuttonmenu">
			<canon>set menu cancel button menu(menu handle, menu)</canon>
			<shortname>set menu cancel button menu</shortname>
			<description>
				Given a <ref>menuhandle</ref>,
				sets the action that happens when the player presses a cancel button.
				<p>menu</p> can be either -1, in which the menu simply closes,
				or a menu ID to open in its place (which is 0 or greater).
			</description>
			<seealso>
				<ref>getmenucancelbuttonmenu</ref>
			</seealso>
		</command>
		<command id="getmenuitemspacing">
			<canon>get menu item spacing(menu handle)</canon>
			<shortname>get menu item spacing</shortname>
			<description>
				Given a <ref>menuhandle</ref>,
				returns the amount of extra spacing in pixels between menu items.
				0 is the default.
			</description>
			<seealso>
				<ref>setmenuitemspacing</ref>
			</seealso>
		</command>
		<command id="setmenuitemspacing">
			<canon>set menu item spacing(menu handle, spacing)</canon>
			<shortname>set menu item spacing</shortname>
			<description>
				Given a <ref>menuhandle</ref>,
				sets the amount of extra spacing in pixels between menu items.
				0 is the default.
			</description>
			<seealso>
				<ref>getmenuitemspacing</ref>
			</seealso>
		</command>

		</section>          <!-- Menu Data -->
	</section>

	<section title="Slices">
		<description>
			To learn what a slice is, read the <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Slices">Slices article</a> on the wiki,
			or one of the other tutorials you can find there.
			Although there are many commands here for manipulating slices, it's much easier to create slices
			in the Slice Collection Editor and then use <ref>loadslicecollection</ref>.
			<lb/>
			Slices are referred to with <ref>slicehandle</ref>s.
		</description>
		<command id="setparent">
			<canon>set parent (handle, parent handle)</canon>
			<shortname>set parent</shortname>
			<description>Moves a slice <p>handle</p> to a different <p>parent handle</p>. 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. Because a slice is positioned relative to its parent, using this command can cause the slice to move. If you would like to change a slice's parent without changing its screen position, see the <ref>gentlyreparent</ref> command instead.</description>
			<seealso>
				<ref>parentslice</ref>
				<ref>checkparentage</ref>
				<ref>slicechild</ref>
				<ref>gentlyreparent</ref>
			</seealso>
		</command>
		<command id="gentlyreparent">
			<canon>gently reparent (handle, parent handle)</canon>
			<shortname>gently reparent</shortname>
			<description>Moves a slice <p>handle</p> to a different <p>parent handle</p>, but preserves the slice's current screen position. This means that the slice's x and y position relative to its new parent might be changed. 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. If you would like to change a slice's parent without changing its position relative to its parent (which could change its screen position), see the <ref>setparent</ref> command instead.</description>
			<seealso>
				<ref>parentslice</ref>
				<ref>checkparentage</ref>
				<ref>slicechild</ref>
				<ref>gentlyreparent</ref>
			</seealso>
		</command>
		<command id="sliceisvalid">
			<canon>slice is valid (value)</canon>
			<shortname>slice is valid</shortname>
			<description>
				Returns true if the given <p>value</p> is a valid slice handle to some existing slice,
				or false if the value isn't a slice handle (e.g. if it's <tt>false</tt> or is any
				other type of handle such as an NPC reference or menu item handle) or if it refers
				to a slice that's been deleted.
				This command never throws an error.
				<note>
					Previously this command was considered dangerous because it could return
					<tt>true</tt> even if the slice had been deleted because its handle
					could be reused for a different slice.
					But starting in the <b>ichorescent</b> release this is mostly solved.
					Now in ichorescent slice handles won't get reused unless you create and
					delete at least a million slices.
					If you create millions of slices and want to be sure,
					set your slice handles to 0 when you delete the slice (see examples)
					rather than using this command.
				</note>
				When you want to check whether the result of a slice command is a valid slice,
				you can just test whether the handle is <p>false</p>, as this example shows:
				<example>
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.
				</example>
				The following example shows how to be safe when deleting a slice:
				<example>
global variable (1, bullet slice)

###### Suppose one script creates a 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 (
		...

		# 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 could use sliceisvalid:

	if (slice is valid (bullet slice)) then (
		# Test for collision with the player
		if (slice collide (bullet slice, get hero slice(me))) then (
			...
		)
	)

###### Or you could make sure to set the variable bulletslice to 0 in every single place you delete
###### it so there are no invalid slice handles.
###### Some of other places aren't obvious! They include leaving the map, or loading a saved game!

	if (bullet slice) then (     # &lt;--- This works only because we do the needed bookkeeping
		# 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     # &lt;---
		)
	)
				</example>
			</description>
		</command>
		<reference ref="dumpslicetree" />
		<command id="freeslice">
			<canon>free slice (handle)</canon>
			<shortname>free slice</shortname>
			<description>
				Deletes a slice and any child slices.
				This works on any type of slice.
				This removes the slice from the screen and removes it from memory.
				You should free your slices after you are completely done with them.
				<lb/>
				Freeing the same slice handle twice shows a warning
				(if slice error reporting is enabled, e.g. while testing your game).
				However, <tt>free slice (0)</tt> is fine, showing no warning.
				It's good practice to set a variable containing a slice handle to 0
				after you free it, so that the script can easily test whether the slice
				exists or not without needing to use <ref>sliceisvalid</ref>.
				<note>
					You can't delete a protected slice, which includes most
					slices created by the engine such as NPCs and heroes.
				</note>
			</description>
			<example>
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
</example>
			<seealso>
				<ref>freesprite</ref>
				<ref>freeslicechildren</ref>
			</seealso>
		</command>
		<command id="freeslicechildren">
			<canon>free slice children (handle)</canon>
			<shortname>free slice children</shortname>
			<description>Frees all the children of a slice, but not the slice itself. See <ref>freeslice</ref> for more details.</description>
			<seealso>
				<ref>freeslice</ref>
			</seealso>
		</command>
		<command id="cloneslice">
			<canon>clone slice (handle, recurse)</canon>
			<shortname>clone slice</shortname>
			<description>
				Copies (clones) a slice.
				If the optional argument <p>recurse</p> 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 <p>handle</p>.
				<lb/>
				You can copy a protected slice (such as an NPC); the result isn't protected.
				Any slices with special lookup codes (those listed in <ref>lookupslice</ref>)
				won't have their lookup codes copied; they'll be set to 0 instead.
				If the slice is a Template then the copy won't be marked as a template,
				but the copies of any descendents it has still will be.
				Passing the root slice or a Map slice as <p>handle</p> 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).
				<note>
					Ongoing slice movement (e.g. velocity) and sprite dissolves are copied into the clone too,
					so you might need to reset those.
				</note>
			</description>
		</command>

		<command id="reparenttonpc">
			<canon>reparent to npc (handle, npc)</canon>
			<shortname>reparent to npc</shortname>
			<description>Reparent a slice <p>handle</p> so that it is attached to an NPC's sprite. The <p>npc</p> 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 <ref>setparent</ref>(<p>handle</p>, <ref>getnpcslice</ref>(<p>npc</p>)) instead.</description>
		</command>
		<command id="reparenttohero">
			<canon>reparent to hero (handle, hero)</canon>
			<shortname>reparent to hero</shortname>
			<description>Reparent a slice <p>handle</p> so that it is attached to an hero's walkabout caterpillar sprite. The <p>hero</p> 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 <ref>setparent</ref>(<p>handle</p>, <ref>getheroslice</ref>(<p>hero</p>)) instead.</description>
		</command>

		<section title="Getting Slices">
		<description>This section describes commands to find existing slices or load them from a defined slice collection. Commands to create slices are in other sections.</description>
		<command id="loadslicecollection">
			<canon>load slice collection (id)</canon>
			<shortname>load slice collection</shortname>
			<description>
				Loads a collection of slices that you have defined in the slice collection editor.
				<lb/>
				The argument is the <p>id</p> number of the collection.
				<lb/>
				The return value is a handle to the container that holds the loaded collection.
				If the collection doesn't exist (it's marked as BLANK in the editor), then
				the return value is false (0).
			</description>
		</command>
		<command id="lookupslice">
			<canon>lookup slice (lookup code, root slice)</canon>
			<shortname>lookup slice</shortname>
			<description>
				Search for a slice that's tagged with a <ref>lookupcode</ref>, and return a handle to it, or 0 if it is not found.
				<lb/>
				<p>root slice</p> is optional, if you don't specify it the whole slice tree will be searched,
				otherwise only descendents of that slice (a subtree) will be searched.
				<p>root slice</p> itself will be returned if it matches.
				<note>
					You can use a number as a lookup code, but usually you use a builtin code constant, starting with <tt>sl:</tt>
					(see below), or name a code in the slice editor, in which case the constant will start with <tt>sli:</tt>.
					Don't mix them up!
				</note>
				<note>Although the user-defined slice lookup codes are always safe to use for any purpose, there is a lot of potential mischief that you can do with a handle to a special slice. If you do anything dubious, like reordering, reparenting, or god forbid freeing the special slice, don't expect your scripts to work in later versions of the engine, which are likely to impose stricter restrictions! Deleting or reparenting special slices generally won't work. You may parent your own slices to these special slices, though.</note>
				<note>
					When there is more than one slice with the same lookup code
					this command will only return the first one it finds (in depth-first search order).
					If you need to find multiple slices with the same lookup code,
					use <ref>lookupnextslice</ref>.
					<lb/>
					Also, if you want to find a slice based on something other than lookup code,
					search for it using <ref>nextsliceintree</ref>.
				</note>
				You may <ref>setparent</ref> a slice to a map layer
				(or to <tt>sl:map overlay</tt> which is above all map layers)
				to make it move with the camera just like heroes and NPCs do.
			</description>
<example>
# 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)
</example>
<example>
# 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)
)
</example>
<example>
# 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:sprite layer)  # Same as lookup slice(sl:script layer)
lookup slice(sl:textbox layer)
lookup slice(sl:string layer)
lookup slice(sl:reserve)
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:sprite)
lookup slice(sl:walkabout sprite)  # Same as lookup slice(sl:sprite)
lookup slice(sl:walkabout sprite component)  # Same as lookup slice(sl:sprite)
lookup slice(sl:shadow)
lookup slice(sl:walkabout shadow)  # Same as lookup slice(sl:shadow)
lookup slice(sl:walkabout shadow component)  # Same as lookup slice(sl:shadow)
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:pathfind dest display)
</example>
			<seealso>
				<ref>setslicelookup</ref>
				<ref>getslicelookup</ref>
				<ref>lookupnextslice</ref>
				<ref>lookupancestor</ref>
			</seealso>
		</command>

		<command id="lookupnextslice">
			<canon>lookup next slice (lookup code, current slice, root slice)</canon>
			<shortname>lookup next slice</shortname>
			<description>
				Find the next slice after <p>current slice</p> that has a certain <ref>lookupcode</ref>
				and return it, or 0 if there are no more matching slices.
				<lb/>
				The first matching slice after <p>current slice</p> (in the order that slices are shown in the slice editor/debugger, 
				called the "depth first search order"), will be returned.
				<p>current slice</p> is actually optional, if it's <tt>0</tt> then this command is equivalent to <ref>lookupslice</ref>.
				(In that case, if <p>root slice</p> has the lookup code you're searching for, it's returned first.)
				<p>current slice</p> can be any descendent of <p>root slice</p>, it doesn't have to have the lookup code.
				<lb/>
				<p>root slice</p> is optional, if you don't specify it the whole slice tree will be searched,
				otherwise only descendents of that slice (a subtree) will be searched.
				<note>
					You can delete slices while you're iterating over them,
					as long as you don't pass a handle to a deleted slice to this command.
				</note>
			</description>
			<example>
# Suppose you've scripted a slice-based GUI or menu, attached to the sprite layer,
# and every clickable thing the sli:selectable lookup code, and now you want to undo any
# highlighting of text or buttons you might have added previously due to mouse-over.
variable(sl)
sl := lookup slice (sli:selectable, sprite layer)
while (sl) do (
  if (slice is sprite (sl)) then (set sprite frame (sl, 0))  # Reset button appearances
  if (slice is text (sl)) then (set text color (sl, ui:text))  # Reset text highlighting
  sl := lookup next slice (sli:selectable, sl, sprite layer)
)</example>
			<example># An alternative way to write the above
variable(sl)
while (true) do (
  sl := lookup next slice (sli:selectable, sl, sprite layer)
  if (sl == 0) then (break)
  if (slice is sprite (sl)) then (set sprite frame (sl, 0))  # Reset button appearances
  if (slice is text (sl)) then (set text color (sl, ui:text))  # Reset text highlighting
)</example>
		</command>
		<command id="lookupancestor">
			<canon>lookup ancestor (lookup code, slice)</canon>
			<shortname>lookup ancestor</shortname>
			<description>
				Search for a slice's <ref>ancestor</ref> that's tagged with a <ref>lookupcode</ref>, and return a handle to it, or 0 if no ancestor slice has the lookup code.
				Starts by checking the parent, and goes up to the root.
			</description>
			<seealso>
				<ref>lookupslice</ref>
				<ref>setslicelookup</ref>
				<ref>getslicelookupname</ref>
			</seealso>
		</command>

		<command id="scriptlayer">
			<canon>script layer</canon>
			<shortname>script layer</shortname>
			<description>Returns a slice handle for the slice (also called the 'sprite layer') which is the default parent of all new script-created slices, such as created by <ref>loadherosprite</ref> and <ref>createrect</ref>. You can move slices elsewhere in the slice tree with <ref>setparent</ref>. You can use <tt>scriptlayer</tt> together with <ref>firstchild</ref> if you want to loop through all your slices (that you haven't reparented) without knowing their handles. Another way to get this slice is to use <ref>lookupslice</ref>: <p>lookup slice(sl:script layer)</p>.</description>
			<example>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
</example>
		</command>
		<command id="spritelayer">
			<alias>scriptlayer</alias>
			<shortname>spritelayer</shortname>
		</command>

		<command id="getslicelookup">
			<canon>get slice lookup (handle)</canon>
			<shortname>get slice lookup</shortname>
			<description>Returns the <ref>lookupcode</ref> of a slice, or <ref>false</ref> if it has none. You can compare the result with the <p>sli:</p> slice lookup values in your hsi file, or with the <p>sl:</p> special builtin lookup values</description>
			<seealso>
				<ref>lookupslice</ref>
				<ref>setslicelookup</ref>
				<ref>getslicelookupname</ref>
			</seealso>
		</command>
		<command id="setslicelookup">
			<canon>set slice lookup (handle, code)</canon>
			<shortname>set slice lookup</shortname>
			<description>
				Changes the lookup code of a slice.
				The first argument is the <ref>slicehandle</ref>, the second is the new <ref>lookupcode</ref>.
				You can pass <ref>false</ref> as the lookup code to remove it.
				The <p>code</p> can be either a lookup code you named in the slice editor,
				which is available as a constant with a <tt>sli:</tt> prefix added (e.g. "menubg" becomes <tt>sli:menubg</tt>),
				or any positive number - you don't have to give a name to a lookup code
				before using it!
				(The values of <tt>sli:</tt> codes count up from 1, so use large numbers for unnamed
				lookup codes, to avoid clashing).
				<lb/>
				You can't use <tt>sl:</tt> special builtin lookup codes,
				nor can you modify the lookup code of slices that already have special lookup codes.
				Only user-defined lookup codes can be changed. Built-in special lookup codes cannot.
			</description>
			<seealso>
				<ref>lookupslice</ref>
				<ref>getslicelookup</ref>
			</seealso>
		</command>

		<reference ref="getslicelookupname" />

		<command id="getheroslice">
			<canon>get hero slice (rank)</canon>
			<shortname>get hero slice</shortname>
			<description>
				Get a hero walkabout container slice (the parent of all slices for the hero).
				<p>rank</p> is the hero's rank in the walkabout caterpillar, from 0-3,
				e.g. <ref>me</ref> for the leader.
				Returns 0 if there is no hero in that rank in the active party,
				but still returns the slice even if the caterpillar party is disabled
				(the slice will be hidden).
				You can use <ref>getheroslicebyslot</ref> instead, which works for heroes
				in the reserve party too.
				<lb/>
				You won't be able to manually reposition this slice (e.g. <ref>putslice</ref> does not work) - use <ref>puthero</ref> instead.
				<lb/>
				Once you have this slice you can access any other slices attached to the hero, such as the sprite slice
				(e.g. <ref>lookupslice</ref><tt>(sl:walkabout sprite component, get hero slice(rank))</tt>, which is equivalent to <ref>getherosprite</ref><tt>(rank)</tt>),
				or attach other slices to a hero walkabout.
				See <ref>lookupslice</ref> for the different walkabout components.
			</description>
			<seealso>
				<ref>getheroslicebyslot</ref>
				<ref>herorankfromslice</ref>
				<ref>getnpcslice</ref>
			</seealso>
		</command>
		<command id="getheroslicebyslot">
			<canon>get hero slice by slot (slot)</canon>
			<shortname>get hero slice by slot</shortname>
			<description>
				Get a hero walkabout container slice (the parent of all slices for the hero),
				from the <p>slot</p> in the hero party.
				Returns 0 if there is no hero in that slot.
				<lb/>
				This is an alternative to <ref>getheroslice</ref>, see that command for more info.
				<lb/>
				<p>slot</p> can even be in the reserve party: all heroes have slices.
				Slices for heroes in the reserve party are parented to the special 'Reserve'
				slice (<tt>lookup slice(sl:reserve)</tt>) instead of to a walktabout layer.
			</description>
			<seealso>
				<ref>getheroslice</ref>
				<ref>heroslotfromslice</ref>
				<ref>getherospritebyslot</ref>
			</seealso>
		</command>

		<command id="getherosprite">
			<canon>get hero sprite (rank)</canon>
			<shortname>get hero sprite</shortname>
			<description>
				Get the walkabout sprite slice for a hero.
				<p>rank</p> is the hero's rank in the walkabout caterpillar (0-3),
				e.g. <ref>me</ref> for the leader.
				This is equivalent to
				<ref>lookupslice</ref><tt>(sl:walkabout sprite component, get hero slice(rank))</tt>.
			</description>
			<seealso>
				<ref>getheroslice</ref>
				<ref>getherospritebyslot</ref>
			</seealso>
		</command>
		<command id="getherospritebyslot">
			<canon>get hero sprite by slot (slot)</canon>
			<shortname>get hero sprite by slot</shortname>
			<description>
				Get the walkabout sprite slice for a hero.
				<p>slot</p> is the hero's slot in the party, including reserve party slots.
				This is equivalent to
				<ref>lookupslice</ref><tt>(sl:walkabout sprite component, get hero slice by slot(slot))</tt>.
			</description>
			<seealso>
				<ref>getherosprite</ref>
				<ref>getheroslice</ref>
			</seealso>
		</command>

		<command id="herorankfromslice">
			<canon>hero rank from slice (handle)</canon>
			<shortname>hero rank from slice</shortname>
			<description>
				The opposite of <ref>getheroslice</ref>:
				Given a slice <p>handle</p>, check whether it's the walkabout container slice of some hero,
				and if so, returns the hero rank in the party
				(always a number between 0 and 3 if the hero is in the active party).
				If it doesn't belong to any hero, returns -1, <b>not</b> 0/false, like
				<ref>npcreferencefromslice</ref> does!
				<lb/>
				This also returns -1 for slices parented to a hero slice, such as the 'walkabout
				sprite component'.
				<lb/>
				This command is useful if you've detected a collision between two slices
				(e.g. using <ref>findcollidingslice</ref>), such as a projectile and another slice,
				and you want to check whether the projectile hit a hero, and which one.
			</description>
			<seealso>
				<ref>heroslotfromslice</ref>
				<ref>getheroslice</ref>
				<ref>npcreferencefromslice</ref>
			</seealso>
		</command>
		<command id="heroslotfromslice">
			<canon>hero slot from slice (handle)</canon>
			<shortname>hero slot from slice</shortname>
			<description>
				The opposite of <ref>getheroslicebyslot</ref>:
				Given a slice <p>handle</p>, check whether it's the walkabout container slice of some hero,
				and if so, returns the hero's party slot (0 or higher).
				If it doesn't belong to any hero, returns -1, <b>not</b> 0/false, like
				<ref>npcreferencefromslice</ref> does!
				<lb/>
				See <ref>herorankfromslice</ref> for more information.
			</description>
			<seealso>
				<ref>herorankfromslice</ref>
				<ref>getheroslicebyslot</ref>
				<ref>npcreferencefromslice</ref>
			</seealso>
		</command>

		<command id="getnpcslice">
			<canon>get npc slice (npc)</canon>
			<shortname>get npc slice</shortname>
			<description>
				Get an NPC walkabout container slice (the parent of all slices for the NPC).
				The argument is an <ref>npcref</ref> or <ref>npcid</ref>.
				If the NPC is tag-disabled, it has no slice so this command returns 0/false.
				If there are no copies of an NPC ID on the map, an error is thrown.
				You will not be able to manually reposition this slice (e.g. <ref>putslice</ref> does not work) - use <ref>putnpc</ref> instead.
				<lb/>
				Once you have this slice you can access any other slices attached to the npc, such as the sprite slice
				(e.g. <ref>lookupslice</ref><tt>(sl:walkabout sprite component, get npc slice(npc))</tt>, which is equivalent to <ref>getnpcsprite</ref><tt>(npc)</tt>),
				or attach other slices to an npc walkabout.
			</description>
			<seealso>
				<ref>npcreferencefromslice</ref>
				<ref>getheroslice</ref>
			</seealso>
		</command>
		<command id="getnpcsprite">
			<canon>get npc sprite (npc)</canon>
			<shortname>get npc sprite</shortname>
			<description>
				Get the walkabout sprite slice for a npc.
				<p>npc</p> is an <ref>npcref</ref> or <ref>npcid</ref>.
				This is equivalent to
				<ref>lookupslice</ref><tt>(sl:walkabout sprite component, get npc slice(npc))</tt>.
			</description>
			<seealso>
				<ref>getnpcslice</ref>
			</seealso>
		</command>
		<command id="npcreferencefromslice">
			<canon>npc reference from slice (handle)</canon>
			<shortname>npc reference from slice</shortname>
			<description>
				The opposite of <ref>getnpcslice</ref>:
				Given a slice <p>handle</p>, check whether it's the walkabout container slice of some NPC,
				and if so, returns the <ref>npcref</ref>.
				If it doesn't belong to any NPC, returns 0.
				<lb/>
				This also returns 0 for slices parented to the NPC's slices, such as the 'walkabout
				sprite component'.
				<lb/>
				This command is useful if you've detected a collision between two slices
				(e.g. using <ref>findcollidingslice</ref>), such as a projectile and another slice,
				and you want to check whether the projectile hit an NPC, and which one.
			</description>
			<seealso>
				<ref>herorankfromslice</ref>
				<ref>getnpcslice</ref>
			</seealso>
		</command>

		</section>		<!-- Getting Slices-->

		<section title="Slice Sizing">
		<command id="slicewidth">
			<canon>slice width (handle)</canon>
			<shortname>slice width</shortname>
			<description>Returns the width of any slice, for example a sprite.</description>
			<seealso>
				<ref>sliceheight</ref>
				<ref>setslicewidth</ref>
			</seealso>
		</command>
		<command id="sliceheight">
			<canon>slice height (handle)</canon>
			<shortname>slice height</shortname>
			<description>Returns the height of any slice, for example a sprite.</description>
			<seealso>
				<ref>slicewidth</ref>
				<ref>setsliceheight</ref>
			</seealso>
		</command>
		<command id="setslicewidth">
			<canon>set slice width (handle, width)</canon>
			<shortname>set slice width</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>slicewidth</ref>
				<ref>setsliceheight</ref>
				<ref>setslicesize</ref>
			</seealso>
		</command>
		<command id="setsliceheight">
			<canon>set slice height (handle, height)</canon>
			<shortname>set slice height</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>sliceheight</ref>
				<ref>setslicewidth</ref>
				<ref>setslicesize</ref>
			</seealso>
		</command>
		<command id="setslicesize">
			<canon>set slice size (handle, width, height)</canon>
			<shortname>set slice size</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>setslicewidth</ref>
				<ref>setsliceheight</ref>
			</seealso>
		</command>
		<command id="clampslice">
			<canon>clamp slice (slice, within slice)</canon>
			<shortname>clamp slice</shortname>
			<description>
				Try to move <p>slice</p> so that its screen position will
				be inside the screen position of <p>within slice</p>.
				The size of the slices will not be changed, so if
				<p>within sl</p> isn't large enough to contain <p>slice</p> it will stick out at least one side
				(it's shifted to align with the nearest vertical and nearest horizontal edge of <p>within slice</p>).
				It does not matter whether the slices are related.
			</description>
			<seealso>
				<ref>slicecontains</ref>
			</seealso>
		</command>
		<command id="isfillingparent">
			<canon>is filling parent (handle)</canon>
			<shortname>is filling parent</shortname>
			<description>Returns true if a slice <p>handle</p> is set to automatically fill its parent, or false if it is not. This command always returns false for slice handles that cannot be resized such as sprite slices. This command doesn't care if the slice is set to fill horizontally, vertically, or both, it returns true for all of them. If you need to check those, use <ref>getfillparent</ref> instead.</description>
			<seealso>
				<ref>fillparent</ref>
				<ref>getfillparent</ref>
			</seealso>
		</command>
		<command id="getfillparent">
			<canon>get fill parent (handle)</canon>
			<shortname>get fill parent</shortname>
			<description>
				Returns the Fill Parent setting of slice <p>handle</p>: one of the constants <p>fill:none</p>, <p>fill:horiz</p>, <p>fill:vert</p>, or <p>fill:all</p>.
			</description>
			<seealso>
				<ref>isfillingparent</ref>
				<ref>setfillparent</ref>
			</seealso>
		</command>
		<command id="setfillparent">
			<canon>set fill parent (handle, fill:constant)</canon>
			<shortname>set fill parent</shortname>
			<description>
				Makes a slice <p>handle</p> fill its parent, but only if this is a type of slice that can be resized. Use the constants <p>fill:none</p>, <p>fill:horiz</p>, <p>fill:vert</p>, or <p>fill:all</p>.
				<note>
					For backwards compatability you can also use the value <p>true</p> or <p>fill:enable</p> both of which will turn on filling but will not change the fill mode, returning to the previously set one (horiz, vert or all; the default fill-mode for a new slice is <p>fill:all</p>).
				</note>
			</description>
			<seealso>
				<ref>isfillingparent</ref>
				<ref>getfillparent</ref>
			</seealso>
		</command>
		<command id="fillparent">
			<alias>setfillparent</alias>
			<shortname>fill parent</shortname>
		</command>
		<command id="getcoverchildren">
			<canon>get cover children (handle)</canon>
			<shortname>get cover children</shortname>
			<description>
				Checks a slice <p>handle</p> and returns whether or not it is configured to automatically resize to cover its children. Return values will be the constants <p>cover:none</p>, <p>cover:horiz</p>, <p>cover:vert</p>, or <p>cover:all</p>. Note that the cover children setting has no effect on a slice that is set to fill its parent in the same axis.
			</description>
			<seealso>
				<ref>setcoverchildren</ref>
				<ref>getfillparent</ref>
			</seealso>
		</command>
		<command id="setcoverchildren">
			<canon>set cover children (handle, cover:constant)</canon>
			<shortname>set cover children</shortname>
			<description>
				Makes a slice <p>handle</p> automatically resize to cover its children (if the slice type supports it). Use the constants <p>cover:none</p>, <p>cover:horiz</p>, <p>cover:vert</p>, or <p>cover:all</p>.
				<lb/>
				Covering children has no effect if the slice is set to fill its parent on the same axis.
				<note>
					This command fails (with an error) on Grid, Panel and Layout slices and on unresizable slices: Sprite, Map, and Text that's not set to wrap.
					Text slice can't cover their children vertically, because their height is fixed.
				</note>
			</description>
			<seealso>
				<ref>getcoverchildren</ref>
				<ref>setfillparent</ref>
			</seealso>
		</command>
		
		</section>		<!-- Slice Sizing-->

		<section title="Positioning Slices">
		<command id="slicex">
			<canon>slice x (handle)</canon>
			<shortname>slice x</shortname>
			<description>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.
				<note>
					If you want the global position of a slice (i.e. relative to top-left of the map),
					use the <ref>slicescreenx</ref> example script.
				</note>
			</description>
			<seealso>
				<ref>slicey</ref>
				<ref>setslicex</ref>
				<ref>slicescreenx</ref>
			</seealso>
		</command>
		<command id="slicey">
			<canon>slice y (handle)</canon>
			<shortname>slice y</shortname>
			<description>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.</description>
			<seealso>
				<ref>slicex</ref>
				<ref>setslicey</ref>
				<ref>slicescreeny</ref>
			</seealso>
		</command>
		<command id="putslice">
			<canon>put slice (handle, X, Y)</canon>
			<shortname>put slice</shortname>
			<description>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.</description>
			<seealso>
				<ref>putsprite</ref>
				<ref>putslicescreen</ref>
				<ref>movesliceto</ref>
			</seealso>
		</command>
		<command id="setslicex">
			<canon>set slice x (handle, X)</canon>
			<shortname>set slice x</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>putslice</ref>
				<ref>slicex</ref>
				<ref>setslicey</ref>
			</seealso>
		</command>
		<command id="setslicey">
			<canon>set slice y (handle, Y)</canon>
			<shortname>set slice y</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>putslice</ref>
				<ref>slicey</ref>
				<ref>setslicex</ref>
			</seealso>
		</command>
		<command id="slicescreenx">
			<canon>slice screen x (handle)</canon>
			<shortname>slice screen x</shortname>
			<description>
				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.
			</description>
			<example># slice screen x can be used to compute the position of a slice on the map, in pixels:
variable (map x, map y)
map x := slice screen x(sl) + camera pixel x
map y := slice screen y(sl) + camera pixel y</example>
			<seealso>
				<ref>slicescreeny</ref>
				<ref>slicex</ref>
			</seealso>
		</command>
		<command id="slicescreeny">
			<canon>slice screen y (handle)</canon>
			<shortname>slice screen y</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>slicescreenx</ref>
				<ref>slicey</ref>
			</seealso>
		</command>
		<command id="putslicescreen">
			<canon>put slice screen (handle, x, y)</canon>
			<shortname>put slice screen</shortname>
			<description>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.</description>
			<seealso>
				<ref>putslice</ref>
				<ref>slicescreenx</ref>
				<ref>setslicescreeny</ref>
			</seealso>
		</command>
		<command id="setslicescreenx">
			<canon>set slice screen x (handle, x)</canon>
			<shortname>set slice screen x</shortname>
			<description>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.</description>
			<seealso>
				<ref>putslicescreen</ref>
				<ref>slicescreenx</ref>
				<ref>setslicescreeny</ref>
			</seealso>
		</command>
		<command id="setslicescreeny">
			<canon>set slice screen y (handle, y)</canon>
			<shortname>set slice screen y</shortname>
			<description>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.</description>
			<seealso>
				<ref>putslicescreen</ref>
				<ref>slicescreeny</ref>
				<ref>setslicescreenx</ref>
			</seealso>
		</command>
		</section>		<!--Positioning Slices-->

		<section title="Extra Data">
			<description>
				You can use any of the <secref>Extra Data Array Functions</secref> on slices.
			</description>

		<command id="setsliceextra">
			<canon>set slice extra (handle, extra, value)</canon>
			<shortname>set slice extra</shortname>
			<description>
				Sets one of the extra data variables on the slice <p>handle</p>.
				<p>extra</p> is an <ref>extradataindex</ref>.
				<lb/>
				This command is the same as <ref>setextra</ref> but only works on slices
				and is slightly faster.
			</description>
		</command>
		<command id="getsliceextra">
			<canon>get slice extra (handle, extra)</canon>
			<shortname>get slice extra</shortname>
			<description>
				Retrieve an extra data value previously set on a slice <p>handle</p> with <ref>setsliceextra</ref>.
				<p>extra</p> is an <ref>extradataindex</ref>.
				<lb/>
				This command is the same as <ref>getextra</ref> but only works on slices
				and is slightly faster.
			</description>
		</command>

		</section>  <!-- Extra data -->

		<section title="Visibility and Clipping">
		<command id="setslicevisible">
			<canon>set slice visible (handle, vis)</canon>
			<shortname>set slice visible</shortname>
			<description>
				Makes slice <p>handle</p> invisible or visible. <p>vis</p> is a true or false value.
				Slices are automatically visible when you load them,
				but you can make them invisible with <p>set slice visible(handle, off)</p>.
				If the slice has children, they will become invisible too.
			</description>
		</command>
		<command id="setspritevisible">
			<alias>setslicevisible</alias>
			<shortname>set sprite visible</shortname>
		</command>
		<command id="getslicevisible">
			<canon>get slice visible (handle)</canon>
			<shortname>get slice visible</shortname>
			<description>Returns the visibility setting for slice <p>handle</p>.  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 <ref>descendent</ref> of an invisible slice.</description>
		</command>
		<command id="setsliceclipping">
			<canon>set slice clipping (handle, clip)</canon>
			<shortname>set slice clipping</shortname>
			<description>Changes whether or not a slice will clip its children if they overflow its edges. The first argument is a slice <p>handle</p>. 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)</description>
		</command>
		<command id="getsliceclipping">
			<canon>get slice clipping (handle)</canon>
			<shortname>set slice clipping</shortname>
			<description>Returns true if the slice <p>handle</p> is set to clip drawing its children, or false if child slices are allowed to be drawn overflowing its edges.</description>
		</command>
		</section>		<!-- Visibility and Clipping-->

		<section title="Slice Blending">
		<command id="setopacity">
			<canon>set opacity (handle, percent)</canon>
			<shortname>set opacity</shortname>
			<description>
				Set the opacity (the opposite of transparency) of a slice.
				<p>handle</p> is a <ref>blendableslicehandle</ref>.
				<p>percent</p> is normally a value from 0 to 100;
				values outside this range are clipped to 0-100 without showing an error.
				Opacity 0 is completely invisible, and 100 is fully opaque (solid) if the blending mode is 'Normal'.
				If the blending mode is 'Add' or 'Multiply', the slice is never opaque,
				due to how those work.
				<lb/>
				If <tt>percent &lt; 100</tt> then blending is automatically enabled (<ref>setblendingenabled</ref>).
				<note>
					You have to use <ref>setrectopacity</ref> instead on Rect slices.
				</note>
			</description>
			<seealso>
				<ref>getopacity</ref>
				<ref>setrectopacity</ref>
			</seealso>
		</command>

		<command id="getopacity">
			<canon>get opacity (handle)</canon>
			<shortname>get opacity</shortname>
			<description>
				Returns the opacity of any slice (from 0-100; see <ref>setopacity</ref>).
				<p>handle</p> is a <ref>slicehandle</ref>;
				if it isn't a <ref>blendableslicehandle</ref> or if blending is disabled
				for this slice, 100 is returned without showing an error.
				<note>
					You have to use <ref>getrectopacity</ref> instead on Rect slices.
				</note>
			</description>
			<seealso>
				<ref>setopacity</ref>
				<ref>getrectopacity</ref>
			</seealso>
		</command>

		<command id="setblendmode">
			<canon>set blend mode (handle, blend mode)</canon>
			<shortname>set blend mode</shortname>
			<description>
				Set the blending mode (aka blend mode) of a slice, also enables blending (<ref>setblendingenabled</ref>).
				<p>handle</p> is a <ref>blendableslicehandle</ref>.
				<p>blend mode</p> is one of:
				<ul>
					<li><tt>blend:normal</tt> -- (Default) Ordinary transparency; no effect if opacity is 100%</li>
					<li><tt>blend:add</tt> or <tt>blend:additive</tt> -- Lightens the image by adding to the RGB channels</li>
					<li><tt>blend:multiply </tt> -- Darkens the image by multiplying the RGB channels</li>
				</ul>
			</description>
			<seealso>
				<ref>getblendmode</ref>
			</seealso>
		</command>

		<command id="getblendmode">
			<canon>get blend mode (handle)</canon>
			<shortname>get blend mode</shortname>
			<description>
				Gets the blend mode of any slice (see <ref>setblendmode</ref>).
				<p>handle</p> is a <ref>slicehandle</ref>;
				if it isn't a <ref>blendableslicehandle</ref> or if blending is disabled
				for this slice, then this returns <tt>blend:normal</tt> without showing an error.
			</description>
			<seealso>
				<ref>setblendmode</ref>
			</seealso>
		</command>

		<command id="setblendingenabled">
			<canon>set blending enabled (handle, state)</canon>
			<shortname>set blending enabled</shortname>
			<description>
				Set whether blending (opacity and blend mode) is enabled for a slice.
				<p>handle</p> is a <ref>blendableslicehandle</ref>.
				<p>state</p> is a true or false value.
				<note>
					You normally don't need to use this command, because setting a slice's opacity or
					blend mode will automatically enable blending.
					This command is only useful if you want to temporarily disable blending
					and then reenable it later, because disabling it (including in the slice editor)
					preserves the other blending settings, even though they're hidden in the editor.
				</note>
			</description>
			<seealso>
				<ref>getblendingenabled</ref>
			</seealso>
		</command>

		<command id="getblendingenabled">
			<canon>get blending enabled (handle)</canon>
			<shortname>get blending enabled</shortname>
			<description>
				Tells whether any slice has its blending settings, if any, enabled;
				returns <tt>true</tt> or <tt>false</tt>.
				<p>handle</p> is a <ref>slicehandle</ref>;
				if it isn't a <ref>blendableslicehandle</ref> then this returns <tt>false</tt>
				without showing an error.
				<note>
					You normally wouldn't use this command for anything.
					Even if blending is enabled, that doesn't tell whether
					the slice is transparent/blended or appears normally.
					To check that, instead of this command, write
					<lb/>
					<tt>if (<ref>getopacity</ref>(sl) &lt; 100 || get blend mode(sl) &lt;&gt; blend:normal)</tt>
				</note>
			</description>
			<seealso>
				<ref>setblendingenabled</ref>
			</seealso>
		</command>
		</section>  <!-- Slice Blending -->

		<section title="Alignment and Anchor Points">
		<command id="sliceedgex">
			<canon>slice edge x (handle, edge)</canon>
			<shortname>slice edge x</shortname>
			<description>Returns the x position of a particular edge of a slice. Use the constants <p>edge:left</p>, <p>edge:center</p>, <p>edge:right</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>sliceedgey</ref>
				<ref>setsliceedgex</ref>
				<ref>setsliceedgey</ref>
			</seealso>
		</command>
		<command id="sliceedgey">
			<canon>slice edge y (handle, edge)</canon>
			<shortname>slice edge y</shortname>
			<description>Returns the y position of a particular edge of a slice. Use the constants <p>edge:top</p>, <p>edge:middle</p>, <p>edge:bottom</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>sliceedgex</ref>
				<ref>setsliceedgex</ref>
				<ref>setsliceedgey</ref>
			</seealso>
		</command>
		<command id="setsliceedgex">
			<canon>set slice edge x (handle, edge, value)</canon>
			<shortname>set slice edge x</shortname>
			<description>Changes the X position of a specific edge of a slice. This is like <ref>setslicex</ref>, except that you can set by any edge regardless of the slice's anchor. Use the constants <p>edge:left</p>, <p>edge:center</p>, <p>edge:right</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>sliceedgex</ref>
				<ref>sliceedgey</ref>
				<ref>setsliceedgey</ref>
			</seealso>
		</command>
		<command id="setsliceedgey">
			<canon>set slice edge y (handle, edge, value)</canon>
			<shortname>set slice edge y</shortname>
			<description>Changes the Y position of a specific edge of a slice. This is like <ref>setslicey</ref>, except that you can set by any edge regardless of the slice's anchor. Use the constants <p>edge:top</p>, <p>edge:middle</p>, <p>edge:bottom</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>sliceedgex</ref>
				<ref>sliceedgey</ref>
				<ref>setsliceedgex</ref>
			</seealso>
		</command>
		<command id="sethorizalign">
			<canon>set horiz align (handle, edge)</canon>
			<shortname>set horiz align</shortname>
			<description>Changes the horizontal alignment of any slice relative to its parent. The available edges are <p>edge:left</p>, <p>edge:center</p>, <p>edge:right</p>. (Not the <tt>align:</tt> constants used by menus!) The default value is edge:left.</description>
			<seealso>
				<ref>setvertalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</ref>
				<ref>gethorizalign</ref>
			</seealso>
		</command>
		<command id="setvertalign">
			<canon>set vert align (handle, edge)</canon>
			<shortname>set vert align</shortname>
			<description>Changes the vertical alignment of any slice relative to its parent. The available edges are <p>edge:top</p>, <p>edge:middle</p>, <p>edge:bottom</p>. (Not the <tt>align:</tt> constants used by menus!) The default value is edge:top.</description>
			<seealso>
				<ref>sethorizalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</ref>
				<ref>getvertalign</ref>
			</seealso>
		</command>
		<command id="sethorizanchor">
			<canon>set horiz anchor (handle, edge)</canon>
			<shortname>set horiz anchor</shortname>
			<description>Changes the horizontal anchor of any slice. The available anchor values are <p>edge:left</p>, <p>edge:center</p>, <p>edge:right</p>. (Not the <tt>align:</tt> constants used by menus!) The default value is edge:left.</description>
			<seealso>
				<ref>setvertalign</ref>
				<ref>sethorizalign</ref>
				<ref>setvertanchor</ref>
				<ref>gethorizanchor</ref>
			</seealso>
		</command>
		<command id="setvertanchor">
			<canon>set vert anchor (handle, edge)</canon>
			<shortname>set vert anchor</shortname>
			<description>Changes the vertical anchor of any slice. The available anchor values are <p>edge:top</p>, <p>edge:middle</p>, <p>edge:bottom</p>. (Not the <tt>align:</tt> constants used by menus!) The default value is edge:top.</description>
			<seealso>
				<ref>setvertalign</ref>
				<ref>sethorizalign</ref>
				<ref>sethorizanchor</ref>
				<ref>getvertanchor</ref>
			</seealso>
		</command>
		<command id="gethorizalign">
			<canon>get horiz align (handle)</canon>
			<shortname>get horiz align</shortname>
			<description>Returns the horizontal alignment of any slice relative to its parent. The return value will be one of <p>edge:left</p>, <p>edge:center</p>, <p>edge:right</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>getvertalign</ref>
				<ref>gethorizanchor</ref>
				<ref>getvertanchor</ref>
				<ref>sethorizalign</ref>
			</seealso>
		</command>
		<command id="getvertalign">
			<canon>get vert align (handle)</canon>
			<shortname>get vert align</shortname>
			<description>Returns the vertical alignment of any slice relative to its parent. The return value will be one of <p>edge:top</p>, <p>edge:middle</p>, <p>edge:bottom</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>gethorizalign</ref>
				<ref>gethorizanchor</ref>
				<ref>getvertanchor</ref>
				<ref>setvertalign</ref>
			</seealso>
		</command>
		<command id="gethorizanchor">
			<canon>get horiz anchor (handle)</canon>
			<shortname>get horiz anchor</shortname>
			<description>Returns the horizontal anchor that a slice uses to position itself relative to its parent. The return value will be one of <p>edge:left</p>, <p>edge:center</p>, <p>edge:right</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>getvertanchor</ref>
				<ref>gethorizalign</ref>
				<ref>getvertalign</ref>
				<ref>sethorizanchor</ref>
			</seealso>
		</command>
		<command id="getvertanchor">
			<canon>get vert anchor (handle)</canon>
			<shortname>get vert anchor</shortname>
			<description>Returns the vertical anchor that a slice uses to position itself relative to its parent. The return value will be one of <p>edge:top</p>, <p>edge:middle</p>, <p>edge:bottom</p>. (Not the <tt>align:</tt> constants used by menus!)</description>
			<seealso>
				<ref>gethorizanchor</ref>
				<ref>gethorizalign</ref>
				<ref>getvertalign</ref>
				<ref>setvertanchor</ref>
			</seealso>
		</command>
		<command id="realignslice">
			<canon>realign slice (handle, horiz align, vert align, horiz anchor, vert anchor)</canon>
			<shortname>realign slice</shortname>
			<description>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.</description>
			<seealso>
				<ref>sethorizalign</ref>
				<ref>setvertalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</ref>
				<ref>gentlyrealignslice</ref>
			</seealso>
		</command>
		<command id="centerslice">
			<canon>center slice (handle)</canon>
			<shortname>center slice</shortname>
			<description>A quick way to center the alignment and the anchor of a slice with a single command. Equivalent to <p>realign slice(handle, edge:center, edge:center, edge:middle, edge:middle)</p>.</description>
			<seealso>
				<ref>realignslice</ref>
				<ref>sethorizalign</ref>
				<ref>setvertalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</ref>
			</seealso>
		</command>
		<command id="gentlyrealignslice">
			<canon>gently realign slice (handle, horiz align, vert align, horiz anchor, vert anchor)</canon>
			<shortname>gently realign slice</shortname>
			<description>A quick way to set the alignment and optionally the anchor of a slice with a single command, but to preserve the current screen position of the slice. This will alter a slices relative position, but keep its screen position the same as the alignment and anchor change. If you leave out the arguments for the anchor then only the alignment will be changed.</description>
			<seealso>
				<ref>sethorizalign</ref>
				<ref>setvertalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</ref>
			</seealso>
		</command>
		</section>		<!--Alignment and Anchor Points-->

		<section title="Padding">
		<command id="setpadding">
			<canon>set padding (handle, pixels)</canon>
			<shortname>set padding</shortname>
			<description>Sets the padding value in pixels for all the edges of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>settoppadding</ref>
				<ref>setleftpadding</ref>
				<ref>setrightpadding</ref>
				<ref>setbottompadding</ref>
			</seealso>
		</command>
		<command id="gettoppadding">
			<canon>get top padding (handle)</canon>
			<shortname>get top padding</shortname>
			<description>Get the padding value in pixels for the top edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>settoppadding</ref>
				<ref>getleftpadding</ref>
				<ref>getrightpadding</ref>
				<ref>getbottompadding</ref>
			</seealso>
		</command>
		<command id="settoppadding">
			<canon>set top padding (handle, pixels)</canon>
			<shortname>set top padding</shortname>
			<description>Set the padding value in pixels for the top edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>gettoppadding</ref>
				<ref>setleftpadding</ref>
				<ref>setrightpadding</ref>
				<ref>setbottompadding</ref>
			</seealso>
		</command>
		<command id="getleftpadding">
			<canon>get left padding (handle)</canon>
			<shortname>get left padding</shortname>
			<description>Get the padding value in pixels for the left edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>setleftpadding</ref>
				<ref>gettoppadding</ref>
				<ref>getrightpadding</ref>
				<ref>getbottompadding</ref>
			</seealso>
		</command>
		<command id="setleftpadding">
			<canon>set left padding (handle, pixels)</canon>
			<shortname>set left padding</shortname>
			<description>Set the padding value in pixels for the left edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>getleftpadding</ref>
				<ref>settoppadding</ref>
				<ref>setrightpadding</ref>
				<ref>setbottompadding</ref>
			</seealso>
		</command>
		<command id="getrightpadding">
			<canon>get right padding (handle)</canon>
			<shortname>get right padding</shortname>
			<description>Get the padding value in pixels for the right edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>setrightpadding</ref>
				<ref>gettoppadding</ref>
				<ref>getleftpadding</ref>
				<ref>getbottompadding</ref>
			</seealso>
		</command>
		<command id="setrightpadding">
			<canon>set right padding (handle, pixels)</canon>
			<shortname>set right padding</shortname>
			<description>Set the padding value in pixels for the right edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>getrightpadding</ref>
				<ref>settoppadding</ref>
				<ref>setleftpadding</ref>
				<ref>setbottompadding</ref>
			</seealso>
		</command>
		<command id="getbottompadding">
			<canon>get bottom padding (handle)</canon>
			<shortname>get bottom padding</shortname>
			<description>Get the padding value in pixels for the bottom edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>setbottompadding</ref>
				<ref>gettoppadding</ref>
				<ref>getleftpadding</ref>
				<ref>getrightpadding</ref>
			</seealso>
		</command>
		<command id="setbottompadding">
			<canon>set bottom padding (handle, pixels)</canon>
			<shortname>set bottom padding</shortname>
			<description>Set the padding value in pixels for the bottom edge of a slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>getbottompadding</ref>
				<ref>settoppadding</ref>
				<ref>setleftpadding</ref>
				<ref>setrightpadding</ref>
			</seealso>
		</command>
		</section>		<!--Padding-->

		<section title="Moving Slices">
		<command id="setslicevelocityx">
			<canon>set slice velocity x (handle, pixels per tick, ticks)</canon>
			<shortname>set slice velocity x</shortname>
			<description>
				Cause slice <p>handle</p> to start moving horizontally.
				A negative value for <p>pixels per tick</p> moves left,
				and a positive value for <p>pixels per tick</p> moves right.
				The <p>ticks</p> 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.
				<lb/>
				Calling this command causes movement due to <ref>movesliceby</ref> or
				<ref>movesliceto</ref>
				to be cancelled.
				<note>
					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.
				</note>
			</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="setslicevelocityy">
			<canon>set slice velocity y (handle, pixels per tick, ticks)</canon>
			<shortname>set slice velocity y</shortname>
			<description>
				Cause slice <p>handle</p> to start moving vertically.
				A negative value for <p>pixels per tick</p> moves up,
				and a positive value for <p>pixels per tick</p> moves down.
				The <p>ticks</p> 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.
				<lb/>
				Calling this command causes movement due to <ref>movesliceby</ref> or
				<ref>movesliceto</ref> to be cancelled.
				<note>
					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.
				</note>
			</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="getslicevelocityx">
			<canon>get slice velocity x (handle)</canon>
			<shortname>get slice velocity x</shortname>
			<description>Returns a number representing the horizontal velocity of slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="getslicevelocityy">
			<canon>get slice velocity y (handle)</canon>
			<shortname>get slice velocity y</shortname>
			<description>Returns a number representing the vertical velocity of slice <p>handle</p>. 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.</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="setslicevelocity">
			<canon>set slice velocity (handle, horiz pixels per tick, vert pixels per tick, ticks)</canon>
			<shortname>set slice velocity</shortname>
			<description>
				Cause slice <p>handle</p> to start moving.
				This is similar to using both <ref>setslicevelocityx</ref> and
				<ref>setslicevelocityy</ref> at the same time (except that those let you use
				different <p>ticks</p> for the X and Y velocities).
				The <p>ticks</p> argument is optional.
				If you do not specify the number of ticks (or pass -1), 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.
				<lb/>
				Calling this command causes movement due to <ref>movesliceby</ref> or <ref>movesliceto</ref> to be cancelled.
			</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="stopslice">
			<canon>stop slice (handle)</canon>
			<shortname>stop slice</shortname>
			<description>Cause slice <p>handle</p> to stop moving. This cancels any previous slice velocity and move slice commands.</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="movesliceto">
			<canon>move slice to (handle, x, y, ticks)</canon>
			<shortname>move slice to</shortname>
			<description>
				Instruct slice <p>handle</p> to move in a straight line to a specific
				<p>x</p> and <p>y</p> position over a given number of <p>ticks</p>.
				(As always, the position is an offset relative to its parent. See <ref>moveslicetoscreenpos</ref> if you want to use screen coordinates instead)
				<lb/>
				If the slice had velocity set with <ref>setslicevelocity</ref>,
				<ref>setslicevelocityx</ref> or <ref>setslicevelocityy</ref> it will be cancelled.
				<note>
					If you change the slice's position manually during that time (eg. with <ref>putslice</ref>),
					it'll continue to move towards the original target in a straight line
					(but now with a different velocity), until <tt>ticks</tt> is up.
					Use <ref>setslicevelocity</ref> instead if you don't want this.
				</note>
			</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>moveslicetoscreenpos</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="moveslicetoscreenpos">
			<canon>move slice to screen pos (handle, x, y, ticks)</canon>
			<shortname>move slice to screen pos</shortname>
			<description>
				Instruct slice <p>handle</p> to move in a straight line to a specific
				<p>x</p> and <p>y</p> screen position over a given number of <p>ticks</p>.
				(Unlike <ref>movesliceto</ref> the position is relative to the screen, regardless of the slice's parentage)
				<lb/>
				If the slice had velocity set with <ref>setslicevelocity</ref>,
				<ref>setslicevelocityx</ref> or <ref>setslicevelocityy</ref> it will be cancelled.
				<note>
					If you change the slice's position manually during that time (eg. with <ref>putslice</ref>),
					it'll continue to move towards the original target in a straight line
					(but now with a different velocity), until <tt>ticks</tt> is up.
					Use <ref>setslicevelocity</ref> instead if you don't want this.
				</note>
			</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="movesliceby">
			<canon>move slice by (handle, relative x, relative y, ticks)</canon>
			<shortname>move slice by</shortname>
			<description>
				Instruct slice <p>handle</p> to move in a straight line to an <p>x</p> and <p>y</p>
				offset relative to its current position over a given number of <p>ticks</p>.
				<lb/>
				A negative <p>relative x</p> moves left.<lb/>
				A positive <p>relative x</p> moves right.<lb/>
				A negative <p>relative y</p> moves up.<lb/>
				A positive <p>relative y</p> moves down.
				<lb/>
				If the slice had velocity set with <ref>setslicevelocity</ref>,
				<ref>setslicevelocityx</ref> or <ref>setslicevelocityy</ref> it will be cancelled.
				<note>
					If you change the slice's position manually during that time (eg. with <ref>putslice</ref>),
					it'll continue to move towards the original target in a straight line
					(but now with a different velocity), until <tt>ticks</tt> is up.
					Use <ref>setslicevelocity</ref> instead if you don't want this.
				</note>
			</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>moveslicetoscreenpos</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="waitforslice">
			<canon>wait for slice (handle)</canon>
			<shortname>wait for slice</shortname>
			<description>Cause the script to wait until slice <p>handle</p> has stopped moving. This only applies to commands that operate over time like <ref>setslicevelocityx</ref> or <ref>setslicevelocity</ref> or <ref>movesliceto</ref> or <ref>movesliceby</ref>. There is no reason to use this command for instantaneous slice moving commands like <ref>putslice</ref> or <ref>setslicex</ref> or <ref>setslicey</ref>.</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<command id="sliceismoving">
			<canon>slice is moving (handle)</canon>
			<shortname>slice is moving</shortname>
			<description>Returns true if the slice <p>handle</p> is moving (has velocity or has been instructed to move to some point). Returns false if the slice is not moving.</description>
			<seealso>
				<ref>setslicevelocityx</ref>
				<ref>setslicevelocityy</ref>
				<ref>getslicevelocityx</ref>
				<ref>getslicevelocityy</ref>
				<ref>setslicevelocity</ref>
				<ref>stopslice</ref>
				<ref>movesliceto</ref>
				<ref>movesliceby</ref>
				<ref>waitforslice</ref>
				<ref>sliceismoving</ref>
			</seealso>
		</command>
		<reference ref="moveslicewithwallchecking" />
		</section>		<!--Moving Slices-->

		<section title="Moving Around the Slice Tree">
		<command id="slicechild">
			<canon>slice child (handle, number)</canon>
			<shortname>slice child</shortname>
			<description>Returns a handle for the nth child of a slice, counting from 0. Returns <p>false</p> if <p>number</p> is too large (<p>last child(handle)</p> is equivalent to <p>slice child(handle, child count(handle) -- 1)</p>). Note that you will need to use <ref>firstchild</ref> and <ref>nextsibling</ref> to iterate over the children of a slice, rather than this command, when you are moving the children around.</description>
			<seealso>
				<ref>childcount</ref>
				<ref>parentslice</ref>
				<ref>firstchild</ref>
				<ref>lastchild</ref>
			</seealso>
		</command>
		<command id="childcount">
			<canon>child count (handle)</canon>
			<shortname>child count</shortname>
			<description>Returns the number of children that slice <p>handle</p> has.</description>
			<seealso>
				<ref>slicechild</ref>
				<ref>firstchild</ref>
			</seealso>
		</command>
		<command id="slicechildindex">
			<canon>slice child index (handle)</canon>
			<shortname>slice child index</shortname>
			<description>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...</description>
			<seealso>
				<ref>slicechild</ref>
			</seealso>
		</command>
		<command id="firstchild">
			<canon>first child (handle)</canon>
			<shortname>first child</shortname>
			<description>Returns a slice handle for the first child of a given slice <p>handle</p>. Returns <p>false</p> if the slice has no children. You can use this to loop through all the children of a slice.</description>
			<example>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
</example>
			<seealso>
				<ref>slicechild</ref>
				<ref>firstspritechild</ref>
				<ref>firstrectchild</ref>
				<ref>firstcontainerchild</ref>
				<ref>lastchild</ref>
				<ref>childcount</ref>
			</seealso>
		</command>
		<command id="lastchild">
			<canon>last child (handle)</canon>
			<shortname>last child</shortname>
			<description>Returns a slice handle for the last child of a given slice <p>handle</p>. Returns <p>false</p> if the slice has no children.</description>
			<seealso>
				<ref>slicechild</ref>
				<ref>firstchild</ref>
				<ref>childcount</ref>
			</seealso>
		</command>
		<command id="nextsibling">
			<canon>next sibling (handle)</canon>
			<shortname>next sibling</shortname>
			<description>Returns a slice handle for the next sibling of a given slice <p>handle</p>. Returns <p>false</p> if the given slice is the last sibling of its parent. This is useful when looping through slices.</description>
			<example>variable(sl)
sl := first child(sprite layer)
while (sl) do, begin
 if (slice is sprite(sl)) then (
   # ...do an operation on each sprite
 )
 sl := next sibling(sl)
end

# The above loop can be written more simply as:
sl := first sprite child(sprite layer)
while (sl) do, begin
 # ...do an operation on each sprite
 sl := next sprite sibling(sl)
end
</example>
			<seealso>
				<ref>previoussibling</ref>
				<ref>parentslice</ref>
				<ref>nextsliceintree</ref>
				<ref>nextspritesibling</ref>
				<ref>nextrectsibling</ref>
				<ref>nextcontainersibling</ref>
				<ref>slicechild</ref>
				<ref>slicetofront</ref>
				<ref>slicetoback</ref>
				<ref>movesliceabove</ref>
				<ref>moveslicebelow</ref>
			</seealso>
		</command>
		<command id="previoussibling">
			<canon>previous sibling (handle)</canon>
			<shortname>previous sibling</shortname>
			<description>Returns a slice handle for the previous sibling of a given slice <p>handle</p>, the inverse of <ref>nextsibling</ref> . Returns <p>false</p> if the given slice is the first sibling of its parent. This is useful when looping through slices.</description>
			<seealso>
				<ref>nextsibling</ref>
				<ref>slicechild</ref>
			</seealso>
		</command>
		<command id="parentslice">
			<canon>parent slice (handle)</canon>
			<shortname>parent slice</shortname>
			<altcommand id="sliceparent">
				<canon>slice parent (handle)</canon>
				<shortname>slice parent</shortname>
			</altcommand>
			<description>Returns a slice handle for the parent of slice <p>handle</p>, or 0 if <p>handle</p> is the root slice.</description>
			<seealso>
				<ref>setparent</ref>
				<ref>gentlyreparent</ref>
				<ref>checkparentage</ref>
				<ref>slicechild</ref>
			</seealso>
		</command>

		<command id="nextsliceintree">
			<canon>next slice in tree (current slice, root slice, visit children)</canon>
			<shortname>next slice in tree</shortname>
			<description>
				Returns the next slice after <p>current slice</p> in the slice tree or a <ref>slicesubtree</ref>.
				This can be used for iterating over a tree of slices using a <ref>while</ref> loop, in the order that they appear
				in the slice collection editor (from top to bottom):
				first go to the first child if any, and then any other descendents and children,
				then go across to the next sibling if any,
				then finally go up and look for a sibling of the parent, then of the grandparent, etc.
				Finally, returns <p>false</p> if <p>current slice</p> is the last descendent of <p>root slice</p>.
				<lb/>
				<p>root slice</p> tells the sub-tree to iterate over: every descendent of it starting with <p>root slice</p> itself.
				<p>root slice</p> is optional, if it's omitted (or <tt>0</tt>) then iterate over the entire slice tree.
				<lb/>
				On the first iteration you can pass <tt>0</tt> or <tt>false</tt> as <p>current slice</p>,
				in which case the return value is <p>root slice</p>.
				<p>current slice</p> can actually be any slice, but
				should normally be in the subtree defined by <p>root slice</p>.
				<lb/>
				<p>visit children</p> is optional, defaulting to true.
				If false, then skip over all the children and descendents of this slice.
				<lb/>
				Unless you use <tt>visit children = false</tt> each slice in the sub-tree is visited exactly once,
				provided that you don't add, delete, or reorder slices.
				<example>variable(root, sl)
root := sprite layer
sl := root
# If you want to skip over the root slice itself, write instead:
#sl := first child(root)

while (sl) do, begin
  # Reset all text slices to default text color, e.g. to unhighlight all menu items in a slice-based menu
  if (slice is text(sl)) then (set text color(sl, ui:Text))
  sl := next slice in tree(sl, root)
end
</example>
This example shows how to delete slices while you're iterating over them:
			<example>variable(root, sl, next)
root := sprite layer
sl := root

while (sl) do, begin
  next := next slice in tree(sl, root)
  # Delete all the hidden slices
  if (get slice visible(sl) == false) then (
    free slice (sl)
  )
  sl := next
end
</example>
			</description>
			<seealso>
				<ref>nextsibling</ref>
				<ref>parentslice</ref>
				<ref>slicechild</ref>
				<ref>lookupnextslice</ref>
			</seealso>
		</command>

		<command id="checkparentage">
			<canon>check parentage (handle, ancestor handle)</canon>
			<shortname>check parentage</shortname>
			<description>
				Checks to see if <p>handle</p> is a <ref>descendent</ref> of <p>ancestor handle</p>.
				Returns <ref>true</ref> or <ref>false</ref>.
				The result is <tt>false</tt> if <tt>handle == ancestor handle</tt>.
			</description>
			<seealso>
				<ref>parentslice</ref>
				<ref>setparent</ref>
			</seealso>
		</command>

		<section title="Type-specific Iteration Commands">

		<command id="firstchildoftype">
			<canon>first child of type(handle, type)</canon>
			<shortname>first child of type</shortname>
			<description>
				Returns a slice handle for the first child of a given
				slice <p>handle</p> which has the given <p>type</p>.
				<p>type</p> is one of the <tt>slicetype:</tt>
				constants, such as <tt>slicetype:sprite</tt>.
				See <ref>slicetype</ref> for the full list.
				Returns <p>false</p> if the slice has no children of that type.
				Children of other types will be ignored.
				This is useful when looping through slices.
			</description>
			<seealso>
				<ref>firstchild</ref>
			</seealso>
		</command>
		<command id="nextsiblingoftype">
			<canon>next sibling of type (handle, type)</canon>
			<shortname>next sibling of type</shortname>
			<description>
				Returns a slice handle for the next sibling of a given
				slice <p>handle</p> which has the given <p>type</p>.
				<p>type</p> is one of the <tt>slicetype:</tt>
				constants, such as <tt>slicetype:sprite</tt>.
				See <ref>slicetype</ref> for the full list.
				Returns <p>false</p> if there are no more children of that type.
				Children of other types will be ignored.
				This is useful when looping through slices.
			</description>
			<seealso>
				<ref>nextsibling</ref>
			</seealso>
		</command>

		<command id="firstcontainerchild">
			<canon>first container child (handle)</canon>
			<shortname>first container child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:container)</tt>.
			</description>
		</command>
		<command id="nextcontainersibling">
			<canon>next container sibling (handle)</canon>
			<shortname>next container sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:container)</tt>.
			</description>
		</command>

		<command id="firstrectchild">
			<canon>first rect child (handle)</canon>
			<shortname>first rect child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:rect)</tt>.
			</description>
		</command>
		<command id="nextrectsibling">
			<canon>next rect sibling (handle)</canon>
			<shortname>next rect sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:rect)</tt>.
			</description>
		</command>

		<command id="firstspritechild">
			<canon>first sprite child (handle)</canon>
			<shortname>first sprite child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:sprite)</tt>.
			</description>
		</command>
		<command id="nextspritesibling">
			<canon>next sprite sibling (handle)</canon>
			<shortname>next sprite sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:sprite)</tt>.
			</description>
		</command>

		<command id="firsttextchild">
			<canon>first text child (handle)</canon>
			<shortname>first text child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:text)</tt>.
			</description>
		</command>
		<command id="nexttextsibling">
			<canon>next text sibling (handle)</canon>
			<shortname>next text sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:text)</tt>.
			</description>
		</command>

		<command id="firstellipsechild">
			<canon>first ellipse child (handle)</canon>
			<shortname>first ellipse child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:ellipse)</tt>.
			</description>
		</command>
		<command id="nextellipsesibling">
			<canon>next ellipse sibling (handle)</canon>
			<shortname>next ellipse sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:ellipse)</tt>.
			</description>
		</command>

		<command id="firstgridchild">
			<canon>first grid child (handle)</canon>
			<shortname>first grid child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:grid)</tt>.
			</description>
		</command>
		<command id="nextgridsibling">
			<canon>next grid sibling (handle)</canon>
			<shortname>next grid sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:grid)</tt>.
			</description>
		</command>

		<command id="firstscrollchild">
			<canon>first scroll child (handle)</canon>
			<shortname>first scroll child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:scroll)</tt>.
			</description>
		</command>
		<command id="nextscrollsibling">
			<canon>next scroll sibling (handle)</canon>
			<shortname>next scroll sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:scroll)</tt>.
			</description>
		</command>

		<command id="firstselectchild">
			<canon>first select child (handle)</canon>
			<shortname>first select child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:select)</tt>.
			</description>
		</command>
		<command id="nextselectsibling">
			<canon>next select sibling (handle)</canon>
			<shortname>next select sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:select)</tt>.
			</description>
		</command>

		<command id="firstpanelchild">
			<canon>first panel child (handle)</canon>
			<shortname>first panel child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:panel)</tt>.
			</description>
		</command>
		<command id="nextpanelsibling">
			<canon>next panel sibling (handle)</canon>
			<shortname>next panel sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:panel)</tt>.
			</description>
		</command>

		<command id="firstlinechild">
			<canon>first line child (handle)</canon>
			<shortname>first line child</shortname>
			<description>
				An alias for <ref>firstchildoftype</ref><tt>(handle, slicetype:line)</tt>.
			</description>
		</command>
		<command id="nextlinesibling">
			<canon>next line sibling (handle)</canon>
			<shortname>next line sibling</shortname>
			<description>
				An alias for <ref>nextsiblingoftype</ref><tt>(handle, slicetype:line)</tt>.
			</description>
		</command>

		</section>	        <!-- Type-specific Iteration Commands-->

		</section>		<!-- Moving Around the Slice Tree-->


		<section title="Reordering Slices">
		<command id="slicetofront">
			<canon>slice to front (handle)</canon>
			<shortname>slice to front</shortname>
			<description>Sort a slice <p>handle</p> 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 <ref>nextsibling</ref> be careful not to accidentally create an endless loop.</description>
			<example>
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 &amp;&amp; sl &lt;&gt; 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
</example>
			<seealso>
				<ref>slicetoback</ref>
				<ref>movesliceabove</ref>
			</seealso>
		</command>
		<command id="slicetoback">
			<canon>slice to back (handle)</canon>
			<shortname>slice to back</shortname>
			<description>Sort a slice <p>handle</p> 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.</description>
			<example>
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 &amp;&amp; sl &lt;&gt; 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
</example>
			<seealso>
				<ref>slicetofront</ref>
				<ref>moveslicebelow</ref>
			</seealso>
		</command>
		<command id="movesliceabove">
			<canon>move slice above (handle, above what handle)</canon>
			<shortname>move slice above</shortname>
			<description>Given a slice <p>handle</p>, move it so that it is the next sibling of another slice given by <p>above what handle</p> (changing its parent if necessary). This will cause it to be drawn immediately after that slice.</description>
			<seealso>
				<ref>moveslicebelow</ref>
				<ref>slicetofront</ref>
				<ref>slicetoback</ref>
				<ref>nextsibling</ref>
			</seealso>
		</command>
		<command id="moveslicebelow">
			<canon>move slice below (handle, below what handle)</canon>
			<shortname>move slice below</shortname>
			<description>Given a slice <p>handle</p>, move it so that it is the previous sibling of another slice given by <p>below what handle</p> (changing its parent if necessary). This will cause it to be drawn immediately before that slice.</description>
			<seealso>
				<ref>movesliceabove</ref>
				<ref>slicetofront</ref>
				<ref>slicetoback</ref>
				<ref>previoussibling</ref>
			</seealso>
		</command>

		<section title="Sorting Slices">

		<command id="ysortchildren">
			<canon>Y sort children (handle)</canon>
			<shortname>Y sort children</shortname>
			<description>Given a slice <p>handle</p>, 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.</description>
			<seealso>
				<ref>sortchildren</ref>
			</seealso>
		</command>
		<command id="setsortorder">
			<canon>set sort order (handle, order)</canon>
			<shortname>set sort order</shortname>
			<description>Assign a sort order value to a slice <p>handle</p>. This can be any arbitrary number that will be used to sort the slice relative to its sibling slices the next time that <ref>sortchildren</ref> 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.</description>
			<seealso>
				<ref>getsortorder</ref>
			</seealso>
		</command>
		<command id="getsortorder">
			<canon>get sort order (handle)</canon>
			<shortname>get sort order</shortname>
			<description>Retrieve the sort order value previously set on a slice <p>handle</p> with <ref>getsortorder</ref>. Note that calling <ref>sortchildren</ref> by default resets all the sort order values to zero, unless <ref>false</ref> is passed as <p>wipe</p>.</description>
		</command>
		<command id="sortchildren">
			<canon>sort children (handle, wipe)</canon>
			<shortname>sort children</shortname>
			<description>Given a slice <p>handle</p>, sort all of its children according to the sort order that you previously set with the <ref>setsortorder</ref> command. If no sort order values have been set then no changes will be made to the order of the slices. <p>wipe</p> is an optional argument, defaulting to <ref>true</ref>, 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 <ref>slicetofront</ref> and <ref>slicetoback</ref>).</description>
			<example>
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
</example>
			<seealso>
				<ref>setsortorder</ref>
				<ref>getsortorder</ref>
				<ref>ysortchildren</ref>
			</seealso>
		</command>

		<command id="getchildautosort">
			<canon>get child autosort (handle)</canon>
			<shortname>get child autosort</shortname>
			<description>
				Get slice <p>handle</p>'s "autosort children" setting, which is one of the following constants:
				<ul>
					<li><tt>autosort: Off</tt></li>
					<li><tt>autosort: Custom</tt> -
						sorted according to the sort order value (<ref>setsortorder</ref>),
						just like <ref>sortchildren</ref> (sort order not wiped after sorting)
					</li>
					<li><tt>autosort: Y</tt> - sorted by each child's Y (<ref>slicey</ref>). That means anchoring and alignment are ignored</li>
					<li><tt>autosort: Custom Then Y</tt> -
						sort primarily by sort order (set by <ref>setsortorder</ref>),
						breaking ties with equal sort order by each child's Y (<ref>slicey</ref>).
						So all sortorder=1 children draw above all sortorder=0 ones.
					</li>
					<li><tt>autosort: Top Y</tt> - sorted by top edge position </li>
					<li><tt>autosort: Center Y</tt> - sorted by center position</li>
					<li><tt>autosort: Bottom Y</tt> - sorted by bottom edge position</li>
				</ul>
				Every tick immediately before the screen is redrawn the children of the slice will
				be sorted according to the autosort setting in ascending order, meaning that those
				with lower values (e.g. for the "Y"-type autosorts, towards the top of the screen)
				will be the first children, drawn earlier, underneath later ones.
				The sort is "stable" meaning if any children have the same sort value
				then their relative order won't change.
				<lb/>
				This is useful for emulating 3D (or "2.5D") environments, causing slices for objects that are closer to the "view"
				(the bottom of the screen) to be drawn on top of ones further away.
			</description>
		</command>

		<command id="setchildautosort">
			<canon>set child autosort (handle, setting)</canon>
			<shortname>set child autosort</shortname>
			<description>
				Change a slice <p>handle</p>'s "autosort children" setting.
				<p>setting</p> should be one of the <tt>autosort: ...</tt> settings; see <ref>getchildautosort</ref>.
			</description>
		</command>

		</section>		<!--Sorting Slices-->

		</section>		<!--Reordering Slices-->


		<section title="Slice Types">
			<description>
				For a description of the different slice types, see the <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Slices#Slice_types">Slices</a> article on the wiki.
				<note>
					There are two types of slice used by the engine for which there are no commands:
					'special' slices (such as <ref>spritelayer</ref>),
					and 'map' slices (which are map layers).
					However you can use <ref>lookupslice</ref> 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.
				</note>
			</description>
		<section title="Checking Slice Type">
		<command id="slicetype">
			<canon>slice type (handle)</canon>
			<shortname>slice type</shortname>
			<description>
				Returns the type of the given slice <p>handle</p>, one of the constants:
				<tt>slicetype:Special</tt>,
				<tt>slicetype:Container</tt>,
				<tt>slicetype:Rect</tt>,
				<tt>slicetype:Line</tt>,
				<tt>slicetype:Ellipse</tt>,
				<tt>slicetype:Sprite</tt>,
				<tt>slicetype:Text</tt>,
				<tt>slicetype:Map</tt>,
				<tt>slicetype:Grid</tt>,
				<tt>slicetype:Scroll</tt>,
				<tt>slicetype:Select</tt>,
				<tt>slicetype:Panel</tt>,
				<tt>slicetype:Layout</tt>.
			</description>
		</command>
		<command id="sliceiscontainer">
			<canon>slice is container (handle)</canon>
			<shortname>slice is container</shortname>
			<description>Returns true if the given slice <p>handle</p> is a container, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceissprite">
			<canon>slice is sprite (handle)</canon>
			<shortname>slice is sprite</shortname>
			<description>Returns true if the given slice <p>handle</p> is a sprite, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceisrect">
			<canon>slice is rect (handle)</canon>
			<shortname>slice is rect</shortname>
			<description>Returns true if the given slice <p>handle</p> is a rect, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceisline">
			<canon>slice is line (handle)</canon>
			<shortname>slice is line</shortname>
			<description>Returns true if the given slice <p>handle</p> is a line, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceisellipse">
			<canon>slice is ellipse (handle)</canon>
			<shortname>slice is ellipse</shortname>
			<description>Returns true if the given slice <p>handle</p> is a ellipse, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceistext">
			<canon>slice is text (handle)</canon>
			<shortname>slice is text</shortname>
			<description>Returns true if the given slice <p>handle</p> is a text slice, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceisgrid">
			<canon>slice is grid (handle)</canon>
			<shortname>slice is grid</shortname>
			<description>Returns true if the given slice <p>handle</p> is a grid, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceisselect">
			<canon>slice is select (handle)</canon>
			<shortname>slice is select</shortname>
			<description>Returns true if the given slice <p>handle</p> is a select slice, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceisscroll">
			<canon>slice is scroll (handle)</canon>
			<shortname>slice is scroll</shortname>
			<description>Returns true if the given slice <p>handle</p> is a scroll slice, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceispanel">
			<canon>slice is panel (handle)</canon>
			<shortname>slice is panel</shortname>
			<description>Returns true if the given slice <p>handle</p> is a panel slice, or false for any other type. It's an error to provide an invalid <p>handle</p>.</description>
		</command>
		<command id="sliceismaplayer">
			<canon>slice is map layer (handle)</canon>
			<shortname>slice is map layer</shortname>
			<description>
				Returns true if the given slice <p>handle</p> is a map layer,
				or false for any other type. It's an error to provide an invalid <p>handle</p>.
			</description>
		</command>


		</section>		<!-- Checking Slice Type-->

		<section title="Container Slices">
		<command id="createcontainer">
			<canon>create container (width, height)</canon>
			<shortname>create container</shortname>
			<description>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 <p>width</p> and <p>height</p> for the container.
<example>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)
</example>
			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.</description>
		</command>
		<reference ref="sliceiscontainer" />
		</section>		<!-- Container Slices-->

		<section title="Sprite Slices">
		<description>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 <p>replace*sprite</p> commands.</description>
		<reference ref="sliceissprite" />
		<command id="loadsprite">
			<canon>load sprite (sprite type, num, palette)</canon>
			<shortname>load sprite</shortname>
			<description>
				Creates a sprite slice by loading a sprite of the given <p>sprite type</p>
				(use a constant like <tt>spritetype:walkabout</tt>; see <ref>getspritetype</ref> for more),
				with sprite set number <p>num</p> and with given <p>palette</p>.
				Returns a handle for the slice.
				You may omit <p>palette</p>,
				in which case the default palette for that sprite will be loaded.
				<p>palette</p> is ignored for <tt>spritetype:backdrop</tt>.
				You must free it with <ref>freesprite</ref> when you are done.
			</description>
			<seealso>
				<ref>replacesprite</ref>
				<ref>loadherosprite</ref>
				<ref>loadsmallenemysprite</ref>
				<ref>loadmediumenemysprite</ref>
				<ref>loadlargeenemysprite</ref>
				<ref>loadwalkaboutsprite</ref>
				<ref>loadattacksprite</ref>
				<ref>loadbordersprite</ref>
				<ref>loadportraitsprite</ref>
				<ref>loadbackdropsprite</ref>
				<ref>getspritetype</ref>
				<ref>getspritesetnumber</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="createsprite">
			<alias>loadsprite</alias>
			<shortname>create sprite</shortname>
		</command>
		<command id="replacesprite">
			<canon>replace sprite (slice, sprite type, num, palette)</canon>
			<shortname>replace sprite</shortname>
			<description>
				Change an existing sprite <p>slice</p> into a different sprite,
				loading a sprite of the given <p>sprite type</p>
				(use a constant like <tt>spritetype:walkabout</tt>; see <ref>getspritetype</ref> for more),
				with sprite set number <p>num</p> and with given <p>palette</p>.
				You may omit <p>palette</p>,
				in which case the default palette for that sprite will be loaded.
				<p>palette</p> is ignored for <tt>spritetype:backdrop</tt>.
				The handle for the slice doesn't change,
				and everything except the size of the slice stays the same.
				You must free it with <ref>freesprite</ref> when you are done.
			</description>
			<seealso>
				<ref>loadsprite</ref>
				<ref>replaceherosprite</ref>
				<ref>replacesmallenemysprite</ref>
				<ref>replacemediumenemysprite</ref>
				<ref>replacelargeenemysprite</ref>
				<ref>replacewalkaboutsprite</ref>
				<ref>replaceattacksprite</ref>
				<ref>replacebordersprite</ref>
				<ref>replaceportraitsprite</ref>
				<ref>replacebackdropsprite</ref>
				<ref>getspritetype</ref>
				<ref>getspritesetnumber</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadherosprite">
			<canon>load hero sprite (num, palette)</canon>
			<shortname>load hero sprite</shortname>
			<description>Loads hero battle sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replaceherosprite</ref>!</warn></description>
			<seealso>
				<ref>replaceherosprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replaceherosprite">
			<canon>replace hero sprite (handle, num, palette)</canon>
			<shortname>replace hero sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to hero battle sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadherosprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadherosprite</ref>.</note></description>
			<seealso>
				<ref>loadherosprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadwalkaboutsprite">
			<canon>load walkabout sprite (num, palette)</canon>
			<shortname>load walkabout sprite</shortname>
			<description>Loads walkabout sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replacewalkaboutsprite</ref>!</warn></description>
			<seealso>
				<ref>replacewalkaboutsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replacewalkaboutsprite">
			<canon>replace walkabout sprite (handle, num, palette)</canon>
			<shortname>replace walkabout sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to walkabout sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadwalkaboutsprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadwalkaboutsprite</ref>.</note></description>
			<seealso>
				<ref>loadwalkaboutsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadsmallenemysprite">
			<canon>load small enemy sprite (num, palette)</canon>
			<shortname>load small enemy sprite</shortname>
			<description>Loads small enemy sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replacesmallenemysprite</ref>!</warn></description>
			<seealso>
				<ref>replacesmallenemysprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replacesmallenemysprite">
			<canon>replace small enemy sprite (handle, num, palette)</canon>
			<shortname>replace small enemy sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to small enemy sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadsmallenemysprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadsmallenemysprite</ref>.</note></description>
			<seealso>
				<ref>loadsmallenemysprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadmediumenemysprite">
			<canon>load medium enemy sprite (num, palette)</canon>
			<shortname>load medium enemy sprite</shortname>
			<description>Loads medium enemy sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replacemediumenemysprite</ref>!</warn></description>
			<seealso>
				<ref>replacemediumenemysprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replacemediumenemysprite">
			<canon>replace medium enemy sprite (handle, num, palette)</canon>
			<shortname>replace medium enemy sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to medium enemy sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadmediumenemysprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadmediumenemysprite</ref>.</note></description>
			<seealso>
				<ref>loadmediumenemysprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadlargeenemysprite">
			<canon>load large enemy sprite (num, palette)</canon>
			<shortname>load large enemy sprite</shortname>
			<description>Loads large enemy sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replacelargeenemysprite</ref>!</warn></description>
			<seealso>
				<ref>replacelargeenemysprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replacelargeenemysprite">
			<canon>replace large enemy sprite (handle, num, palette)</canon>
			<shortname>replace large enemy sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to large enemy sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadlargeenemysprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadlargeenemysprite</ref>.</note></description>
			<seealso>
				<ref>loadlargeenemysprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadattacksprite">
			<canon>load attack sprite (num, palette)</canon>
			<shortname>load attack sprite</shortname>
			<description>Loads attack battle sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replaceattacksprite</ref>!</warn></description>
			<seealso>
				<ref>replaceattacksprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replaceattacksprite">
			<canon>replace attack sprite (handle, num, palette)</canon>
			<shortname>replace attack sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to attack battle sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadattacksprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadattacksprite</ref>.</note></description>
			<seealso>
				<ref>loadattacksprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadweaponsprite">
			<canon>load weapon sprite (num, palette)</canon>
			<shortname>load weapon sprite</shortname>
			<description>Loads weapon battle sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replaceweaponsprite</ref>!</warn></description>
			<seealso>
				<ref>replaceweaponsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replaceweaponsprite">
			<canon>replace weapon sprite (handle, num, palette)</canon>
			<shortname>replace weapon sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to weapon battle sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadweaponsprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadweaponsprite</ref>.</note></description>
			<seealso>
				<ref>loadweaponsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadbordersprite">
			<canon>load border sprite (num, palette)</canon>
			<shortname>load border sprite</shortname>
			<description>Loads border battle sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replacebordersprite</ref>!</warn></description>
			<seealso>
				<ref>replacebordersprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replacebordersprite">
			<canon>replace border sprite (handle, num, palette)</canon>
			<shortname>replace border sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to border battle sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadbordersprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadbordersprite</ref>.</note></description>
			<seealso>
				<ref>loadbordersprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadportraitsprite">
			<canon>load portrait sprite (num, palette)</canon>
			<shortname>load portrait sprite</shortname>
			<description>Loads portrait battle sprite #<p>num</p> with palette <p>palette</p>, and returns a <ref>slicehandle</ref>.. You may omit <p>palette</p>, in which case the default palette for that sprite will be loaded. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replaceportraitsprite</ref>!</warn></description>
			<seealso>
				<ref>replaceportraitsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replaceportraitsprite">
			<canon>replace portrait sprite (handle, num, palette)</canon>
			<shortname>replace portrait sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to portrait battle sprite #<p>num</p> with palette <p>palette</p>. As with <ref>loadportraitsprite</ref>, you may omit <p>palette</p>, 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadportraitsprite</ref>.</note></description>
			<seealso>
				<ref>loadportraitsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="loadbackdropsprite">
			<canon>load backdrop sprite (num)</canon>
			<shortname>load backdrop sprite</shortname>
			<description>Loads backdrop #<p>num</p> as a sprite, and returns a <ref>slicehandle</ref>.. You must free it with <ref>freesprite</ref> when you are done.<warn>If you want to replace an existing sprite (or other slice) either use <ref>freesprite</ref> first, or use <ref>replacebackdropsprite</ref>!</warn></description>
			<seealso>
				<ref>showbackdrop</ref>
				<ref>replacebackdropsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="replacebackdropsprite">
			<canon>replace backdrop sprite (handle, num)</canon>
			<shortname>replace backdrop sprite</shortname>
			<description>Given an existing sprite <p>handle</p>, changes it to backdrop #<p>num</p>. You must free it with <ref>freesprite</ref> 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 <ref>freesprite</ref> when you are done.<note>You may use this on any sprite, not just ones loaded with <ref>loadbackdropsprite</ref>.</note></description>
			<seealso>
				<ref>loadbackdropsprite</ref>
				<ref>freesprite</ref>
			</seealso>
		</command>
		<command id="freesprite">
			<canon>free sprite (handle)</canon>
			<shortname>free sprite</shortname>
			<description>
				Deletes a sprite slice (e.g. created by <tt>load ... sprite</tt> commands).
				Identical to <ref>freeslice</ref> except it shows an error when used on a non-sprite,
				for additional error checking.
				This removes the sprite from the screen, and deletes any children it has.
				It is a good idea to free sprites when you are completely done with them.
				<note>
					You can't delete a protected slice, which includes most
					slices created by the engine such as NPC and hero sprites.
				</note>
			</description>
			<seealso>
				<ref>freeslice</ref>
			</seealso>
		</command>
		<command id="clonesprite">
			<canon>clone sprite (handle)</canon>
			<shortname>clone sprite</shortname>
			<description>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 <ref>spritelayer</ref> 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 <ref>freesprite</ref> on both the original and the clone.
				<note>
					If you want to copy a non-sprite slice, copy all the properties of the slice,
					or copy its children, then use the <ref>cloneslice</ref> command instead.
				</note>
			</description>
			<seealso>
				<ref>freesprite</ref>
				<ref>cloneslice</ref>
			</seealso>
		</command>
		<command id="putsprite">
			<canon>put sprite (handle, x, y)</canon>
			<shortname>put sprite</shortname>
			<description>Moves sprite <p>handle</p> to position (<p>x</p>, <p>y</p>). This can only be used on sprites, use <ref>putslice</ref> in general. </description>
		</command>
		<command id="placesprite">
			<alias>putsprite</alias>
			<shortname>place sprite</shortname>
		</command>
		<command id="getspritetype">
			<canon>get sprite type (handle)</canon>
			<shortname>get sprite type</shortname>
			<description>
				Gets the type of sprite slice <p>handle</p>, or returns -1 if the slice is not a sprite.
				You can compare the result with the following constants:
				<ul>
					<li>spritetype:hero</li>
					<li>spritetype:small enemy</li>
					<li>spritetype:medium enemy</li>
					<li>spritetype:large enemy</li>
					<li>spritetype:walkabout</li>
					<li>spritetype:weapon</li>
					<li>spritetype:attack</li>
					<li>spritetype:border</li>
					<li>spritetype:portrait</li>
					<li>spritetype:backdrop</li>
				</ul>
			</description>
			<seealso>
				<ref>getspritesetnumber</ref>
				<ref>getspritepalette</ref>
				<ref>getspriteframe</ref>
			</seealso>
		</command>
		<command id="setspritesetnumber">
			<canon>set sprite set number (handle, set number)</canon>
			<shortname>set sprite set number</shortname>
			<description>Changes the sprite set of a sprite slice <p>handle</p>. <p>set number</p> is the spriteset ID.</description>
			<seealso>
				<ref>getspritesetnumber</ref>
				<ref>setspritepalette</ref>
				<ref>setspriteframe</ref>
			</seealso>
		</command>
		<command id="getspritesetnumber">
			<canon>get sprite set number (handle)</canon>
			<shortname>get sprite set number</shortname>
			<description>Gets the sprite set ID of a sprite slice <p>handle</p>.</description>
			<seealso>
				<ref>getspritetype</ref>
				<ref>getspritepalette</ref>
				<ref>getspriteframe</ref>
			</seealso>
		</command>
		<command id="setspritepalette">
			<canon>set sprite palette (handle, num)</canon>
			<shortname>set sprite palette</shortname>
			<description>
				Changes the palette of sprite slice <p>handle</p> to be <p>num</p>.
				If <p>num</p> is -1 or omitted, the default palette for that sprite is loaded.
			</description>
			<seealso>
				<ref>getspritepalette</ref>
			</seealso>
		</command>
		<command id="getspritepalette">
			<canon>get sprite palette (handle)</canon>
			<shortname>get sprite palette</shortname>
			<description>
				Returns the palette of sprite slice <p>handle</p>,
				or returns -1 if the sprite is set to use the default palette
				(use <ref>getspritedefaultpal</ref> to figure which that is).
			</description>
			<seealso>
				<ref>getspritetype</ref>
				<ref>getspritesetnumber</ref>
				<ref>getspriteframe</ref>
			</seealso>
		</command>
		<command id="getspritedefaultpal">
			<canon>get sprite default pal (handle)</canon>
			<shortname>get sprite default pal</shortname>
			<description>
				Returns the default palette of sprite slice <p>handle</p>.
				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.
			</description>
			<seealso>
				<ref>getspritepalette</ref>
				<ref>setspritepalette</ref>
			</seealso>
		</command>
		<command id="setspriteframe">
			<canon>set sprite frame (handle, num)</canon>
			<shortname>set sprite frame</shortname>
			<description>
				Changes the frame of sprite slice <p>handle</p> to <p>num</p>.
				If the frame number is out of range, does nothing (and doesn't report an error).
			</description>
			<seealso>
				<ref>setspriteframeid</ref>
				<ref>getspriteframe</ref>
				<ref>spriteframecount</ref>
			</seealso>
		</command>
		<command id="setspriteframeid">
			<canon>set sprite frame id (handle, id, exact)</canon>
			<shortname>set sprite frame id</shortname>
			<description>
				Attempts to change the frame of sprite slice <p>handle</p> to the frame with ID <p>id</p>.
				Returns the frame number (as returned by <ref>getspriteframe</ref>) of the frame if
				it was found, or -1 if not.
				<lb/>
				<p>exact</p> is an optional arg defaulting to <tt>false</tt>.
				If it's <tt>false</tt> and you try to switch to a missing frame ID, then the last
				frame in the same frame group is used instead, if it exists.
				For example, if you have a default 8 frame walkabout set
				with frame IDs 0, 1, 100, 101, 200, 201, 300, 301 and try to switch to ID 103,
				then ID 101 is used instead as the nearest match, and the return value is 3.
				But if you try to switch to frame ID 400, nothing happens (returning -1).
			</description>
			<seealso>
				<ref>setspriteframe</ref>
				<ref>getspriteframeid</ref>
				<ref>spriteframegroupsize</ref>
			</seealso>
		</command>

		<command id="getspriteframe">
			<canon>get sprite frame (handle)</canon>
			<shortname>get sprite frame</shortname>
			<description>Returns the current frame number of sprite slice <p>handle</p>.</description>
			<seealso>
				<ref>setspriteframe</ref>
				<ref>getspriteframeid</ref>
				<ref>getspritetype</ref>
				<ref>getspritepalette</ref>
				<ref>getspritesetnumber</ref>
			</seealso>
		</command>
		<command id="getspriteframeid">
			<canon>get sprite frame id (handle)</canon>
			<shortname>get sprite frame id</shortname>
			<description>Returns the current frame ID of sprite slice <p>handle</p>.</description>
			<seealso>
				<ref>setspriteframeid</ref>
				<ref>getspriteframe</ref>
			</seealso>
		</command>
		<command id="findspriteframeid">
			<canon>find sprite frame id (handle, id)</canon>
			<shortname>find sprite frame id</shortname>
			<description>
				Searches the frames of the spriteset of a given sprite slice <p>handle</p> for a
				one with ID <p>id</p> and returns its frame number (which can be passed to
				<ref>setspriteframe</ref>), or -1 if no such frame exists.
				This searches for an exact ID match, like <ref>setspriteframeid</ref> with
				<tt>exact = true</tt>.
			</description>
		</command>

		<command id="spriteframecount">
			<canon>sprite frame count (handle)</canon>
			<shortname>sprite frame count</shortname>
			<description>
				Returns the total number of available frames for a given sprite slice <p>handle</p>.
				For example a backdrop has just one frame, a walkabout sprite has eight by default.
			</description>
		</command>
		<command id="spriteframegroupsize">
			<canon>sprite frame group size (handle, group)</canon>
			<shortname>sprite frame group size</shortname>
			<description>
				Returns the number of frames in one of the frame groups of a given sprite slice <p>handle</p>.
				The frame group of each frame is its ID divided by 100.
				<p>group</p> is an optional argument, a group number from 0 up.
				If it's missing (or -1), then the current frame group is used (i.e. <tt>get
				sprite frame id (handle) / 100</tt>).
				<lb/>
				For example frame IDs 200 and 201 are in group 2,
				and a walkabout sprite by default has four frame groups for the
				directions <ref>up</ref>, <ref>right</ref>, <ref>down</ref>, <ref>left</ref>
				(which are constants with values <tt>0, 1, 2, 3</tt>),
				so the number of Left walking frames an NPC has is:
				<example>sprite frame group size (get npc sprite (npc), left)</example>
				<note>
					Frames in the group will always have consecutive IDs, starting at
					<tt>group * 100</tt> up to <tt>group * 100 + groupsize -- 1</tt>.
				</note>
				<note>
					A frame group can be empty, e.g. a walkabout can have just a single frame,
					ID 200 (facing Down).
				</note>
			</description>
		</command>

		<command id="horizflipsprite">
			<canon>horiz flip sprite (handle, flip)</canon>
			<shortname>horiz flip sprite</shortname>
			<description>Flips a sprite slice <p>handle</p> horizontally. You can also unflip a previously flipped sprite using <p>horiz flip sprite(handle, false)</p></description>
			<seealso>
				<ref>vertflipsprite</ref>
				<ref>spriteishorizflipped</ref>
			</seealso>
		</command>
		<command id="vertflipsprite">
			<canon>vert flip sprite (handle, flip)</canon>
			<shortname>vert flip sprite</shortname>
			<description>Flips a sprite slice <p>handle</p> vertically. You can also unflip a previously flipped sprite using <p>vert flip sprite(handle, false)</p></description>
			<seealso>
				<ref>horizflipsprite</ref>
				<ref>spriteisvertflipped</ref>
			</seealso>
		</command>
		<command id="spriteishorizflipped">
			<canon>sprite is horiz flipped (handle)</canon>
			<shortname>sprite is horiz flipped</shortname>
			<description>Returns true if a sprite slice <p>handle</p> is flipped horizontally, or false if it is not.</description>
			<seealso>
				<ref>horizflipsprite</ref>
				<ref>spriteisvertflipped</ref>
			</seealso>
		</command>
		<command id="spriteisvertflipped">
			<canon>sprite is vert flipped (handle)</canon>
			<shortname>sprite is vert flipped</shortname>
			<description>Returns true if a sprite slice <p>handle</p> is flipped vertically, or false if it is not.</description>
			<seealso>
				<ref>vertflipsprite</ref>
				<ref>spriteishorizflipped</ref>
			</seealso>
		</command>
		<command id="getspritetrans">
			<canon>get sprite trans (handle)</canon>
			<shortname>get sprite trans</shortname>
			<description>Given a sprite slice <p>handle</p>, returns true if the sprite is drawn with transparency (that is, color 0 is transparent). All sprites default to transparent.</description>
			<seealso>
				<ref>setspritetrans</ref>
			</seealso>
		</command>
		<command id="setspritetrans">
			<canon>set sprite trans (handle, drawtransparent)</canon>
			<shortname>set sprite trans</shortname>
			<description>Given a sprite slice <p>handle</p>, 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.</description>
			<seealso>
				<ref>getspritetrans</ref>
			</seealso>
		</command>
		<command id="dissolvesprite">
			<canon>dissolve sprite (handle, dissolve type, total ticks, start tick, backwards, automatic)</canon>
			<shortname>dissolve sprite</shortname>
			<description>
				Dissolve a sprite using pre-defined dissolve animations.
				The first argument is a sprite slice <p>handle</p>.
				The second argument is the <p>dissolve type</p>.
				There are <tt>dissolve:name</tt> constants with the same names as the enemy dissolve animations.
				<lb/>
				The valid dissolve type constants are:
				<p>dissolve:random scatter</p>,
				<p>dissolve:crossfade</p>,
				<p>dissolve:diagonal vanish</p>,
				<p>dissolve:sink into ground</p>,
				<p>dissolve:squash</p>,
				<p>dissolve:melt</p>,
				<p>dissolve:vaporize (or dissolve:vaporise)</p>,
				<p>dissolve:phase out</p>,
				<p>dissolve:squeeze</p>,
				<p>dissolve:shrink</p>,
				<p>dissolve:flicker</p>.
				<p>dissolve:shrink to center</p>,
				<p>dissolve:fade</p>,
				<p>dissolve:ghostly fade</p>,
				<p>dissolve:fade to white</p>,
				<p>dissolve:puff</p>,
				<p>dissolve:fade up</p>,
				<p>dissolve:blip</p>.
				<lb/>
				The third argument is the total number of ticks that the animation should run.
				You can use <tt>dissolvetime:default</tt> or <tt>-1</tt> for the default number of ticks,
				which is equal to the sprites <tt>(width + height) / 10</tt>
				(this is not the same as the default length for enemy dissolves!)
				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.
			</description>
			<seealso>
				<ref>canceldissolve</ref>
				<ref>spriteisdissolving</ref>
				<ref>waitfordissolve</ref>
			</seealso>
		</command>
		<command id="canceldissolve">
			<canon>cancel dissolve (handle)</canon>
			<shortname>cancel dissolve</shortname>
			<description>If a sprite slice <p>handle</p> is currently dissolving, cancel the dissolve animation, restoring the sprite to normal.</description>
			<seealso>
				<ref>dissolvesprite</ref>
				<ref>spriteisdissolving</ref>
				<ref>waitfordissolve</ref>
			</seealso>
		</command>
		<command id="spriteisdissolving">
			<canon>sprite is dissolving (handle)</canon>
			<shortname>sprite is dissolving</shortname>
			<description>Returns true if a sprite slice <p>handle</p> 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.</description>
			<seealso>
				<ref>canceldissolve</ref>
				<ref>spriteisdissolving</ref>
				<ref>waitfordissolve</ref>
			</seealso>
		</command>
		<command id="waitfordissolve">
			<canon>wait for dissolve (handle)</canon>
			<shortname>wait for dissolve</shortname>
			<description>Pauses the current script until the sprite slice <p>handle</p> 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.</description>
			<seealso>
				<ref>canceldissolve</ref>
				<ref>spriteisdissolving</ref>
				<ref>waitfordissolve</ref>
			</seealso>
		</command>
		</section>		<!-- Sprite Slices-->


		<section title="Rect Slices">
		<command id="createrect">
			<canon>create rect (width, height, style)</canon>
			<shortname>create rect</shortname>
			<description>Create a new rectangle slice and return a handle to it. You can provide an optional <p>width</p> and <p>height</p>, and an optional <p>style</p>. 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 <ref>setparent</ref></description>
		</command>
		<reference ref="sliceisrect" />
		<command id="getrectstyle">
			<canon>get rect style (handle)</canon>
			<shortname>get rect style</shortname>
			<description>
				Given a rect slice <p>handle</p>, 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 <ref>setrectfgcol</ref>, <ref>setrectbgcol</ref>, <ref>setrectborder</ref>
				or <ref>setrectrawborder</ref> commands causes this command to return -1.
			</description>
			<seealso>
				<ref>setrectstyle</ref>
			</seealso>
		</command>
		<command id="setrectstyle">
			<canon>set rect style (handle, style)</canon>
			<shortname>set rect style</shortname>
			<description>
				Given a rect slice <p>handle</p>, change the box style it uses.
				The <p>style</p> 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.
			</description>
			<seealso>
				<ref>getrectstyle</ref>
				<ref>setrectfgcol</ref>
				<ref>setrectbgcol</ref>
				<ref>setrectborder</ref>
			</seealso>
		</command>
		<command id="getrectbgcol">
			<canon>get rect bgcol (handle)</canon>
			<shortname>get rect bgcol</shortname>
			<description>
				Given a rect slice <p>handle</p>, 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.
			</description>
			<seealso>
				<ref>setrectbgcol</ref>
				<ref>getrectfgcol</ref>
			</seealso>
		</command>
		<command id="setrectbgcol">
			<canon>set rect bgcol (handle, color)</canon>
			<shortname>set rect bgcol</shortname>
			<description>
				Given a rect slice <p>handle</p>, change the background color it uses,
				which is the color of the box.
				The <p>color</p> should be a number from 0 to 255 representing a color
				from the master palette.
			</description>
			<seealso>
				<ref>getrectbgcol</ref>
				<ref>setrectfgcol</ref>
			</seealso>
		</command>
		<command id="getrectfgcol">
			<canon>get rect fgcol (handle)</canon>
			<shortname>get rect fgcol</shortname>
			<description>Given a rect slice <p>handle</p>, 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.</description>
			<seealso>
				<ref>setrectfgcol</ref>
				<ref>getrectbgcol</ref>
			</seealso>
		</command>
		<command id="setrectfgcol">
			<canon>set rect fgcol (handle, color)</canon>
			<shortname>set rect fgcol</shortname>
			<description>Given a rect slice <p>handle</p>, 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 <p>color</p> should be a number from 0 to 255 representing a color from the master palette.</description>
			<seealso>
				<ref>getrectfgcol</ref>
				<ref>setrectbgcol</ref>
			</seealso>
		</command>
		<command id="getrectborder">
			<canon>get rect border (handle)</canon>
			<shortname>get rect border</shortname>
			<description>
				Given a rect slice <p>handle</p>, 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 <p>border:line</p> for a simple line border only,
				or <p>border:none</p> for no border at all,
				or <p>border:raw</p> if the box uses a "raw" box border spriteset number instead
				(in that case you need to call <ref>getrectrawborder</ref> to find out which it is).
			</description>
			<seealso>
				<ref>setrectborder</ref>
				<ref>getrectrawborder</ref>
			</seealso>
		</command>
		<command id="getrectrawborder">
			<canon>get rect raw border (handle)</canon>
			<shortname>get rect raw border</shortname>
			<description>
				Given a rect slice <p>handle</p>, return the spriteset ID number of the graphical border it uses,
				or <p>border:line</p> if it has a simple line border only,
				or <p>border:none</p> for no border at all.
				If the border is being determined by a box style number
				(e.g. due to <ref>setrectstyle</ref> or <ref>setrectborder</ref>),
				then this command returns the actual box border spriteset instead of the box style number.
			</description>
			<seealso>
				<ref>setrectrawborder</ref>
				<ref>getrectborder</ref>
			</seealso>
		</command>
		<command id="setrectborder">
			<canon>set rect border (handle, border)</canon>
			<shortname>set rect border</shortname>
			<description>
				Given a rect slice <p>handle</p>, change the graphical border it uses.
				The <p>border</p> should be a box style number from 0 to 14 representing a
				text box border style, or <p>border:line</p> for a simple line border only,
				or <p>border:none</p> for no border at all.
				(You can't use <p>border:raw</p>.)
				This command overrides both <ref>setrectstyle</ref> and <ref>setrectrawborder</ref>.
				<note>
					<p>border</p> is <b>not</b> a box border spriteset number, it's a box style number!
					If you want to specify the box border spriteset directly, use <ref>setrectrawborder</ref>.
				</note>
			</description>
			<seealso>
				<ref>getrectborder</ref>
				<ref>setrectrawborder</ref>
			</seealso>
		</command>
		<command id="setrectrawborder">
			<canon>set rect raw border (handle, border)</canon>
			<shortname>set rect raw border</shortname>
			<description>
				Given a rect slice <p>handle</p>, change the graphical border it uses.
				The <p>border</p> should be a border spriteset number (<b>not</b> a box style number),
				or <p>border:line</p> for a simple line border only,
				or <p>border:none</p> for no border at all.
				(You can't use <p>border:raw</p>.)
				This command overrides both <ref>setrectstyle</ref> and <ref>setrectborder</ref>.
			</description>
			<seealso>
				<ref>getrectrawborder</ref>
				<ref>setrectborder</ref>
			</seealso>
		</command>

		<command id="getrecttrans">
			<canon>get rect trans (handle)</canon>
			<shortname>get rect trans</shortname>
			<description>
				Given a rect slice <p>handle</p>, returns a constant like <tt>trans:fuzzy</tt>
				telling the background drawing mode;
				see <ref>setrecttrans</ref> for the different constants.
				Returns <tt>trans:hollow</tt> if the rect's opacity/fuzziness is 0,
				and <tt>trans:solid</tt> (equal to <tt>false</tt>) if it's 100.
			</description>
			<seealso>
				<ref>setrecttrans</ref>
				<ref>getrectfuzziness</ref>
				<ref>getrectfuzzyzoom</ref>
				<ref>getrectstationarypattern</ref>
			</seealso>
		</command>

		<command id="setrecttrans">
			<canon>set rect trans (handle, transparency setting)</canon>
			<shortname>set rect trans</shortname>
			<description>
				Given a rect slice <p>handle</p>, change how its background
				(the part that's not the border) is drawn.
				For <p>transparency setting</p>, pass in one of the constants:
				<ul>
					<li><tt>trans:fuzzy</tt> for checkered semi-transparency,</li>
					<li><tt>trans:blend</tt> for true transparency,</li>
					<li><tt>trans:hollow</tt> to not draw the background at all (only the border is drawn),</li>
					<li><tt>trans:solid</tt> (equal to <ref>false</ref>) for solid with no transparency.</li>
				</ul>
				When changing to <tt>trans:fuzzy</tt> and <tt>trans:blend</tt> the
				fuzziness/opacity defaults to 50% if it hasn't been previously set.
				Otherwise the previous value is restored:
				<example>set rect opacity(rect, 70)   # Becomes 70% opaque
set rect trans(rect, trans:solid)  # Becomes opaque
set rect trans(rect, trans:fuzzy)  # Becomes fuzzy with 70% fuzziness</example>
				<note>
					This command is less powerful than <ref>setrectfuzziness</ref>
					and <ref>setrectopacity</ref>,
					which together can change to any of the four <tt>trans:</tt> types,
					and also control the amount of transparency.
				</note>
			</description>
			<seealso>
				<ref>getrecttrans</ref>
				<ref>setrectfuzziness</ref>
				<ref>setrectopacity</ref>
				<ref>setrectfuzzyzoom</ref>
				<ref>setrectstationarypattern</ref>
			</seealso>
		</command>

		<command id="getrectfuzziness">
			<canon>get rect fuzziness (handle)</canon>
			<shortname>get rect fuzziness</shortname>
			<altcommand id="getrectopacity">
				<canon>get rect opacity (handle)</canon>
				<shortname>get rect opacity</shortname>
			</altcommand>
			<description>
				Given a rect slice <p>handle</p>, returns the percentage fuzziness or opacity 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' or 'blended (transparent)'
				(which share the same opacity value).
				Rectangles set to <tt>trans:fuzzy</tt> or <tt>trans:blend</tt> using <ref>setrecttrans</ref> default to 50% opacity.
			</description>
			<seealso>
				<ref>setrecttrans</ref>
				<ref>getrecttrans</ref>
				<ref>setrectfuzziness</ref>
				<ref>setrectopacity</ref>
				<ref>getopacity</ref>
				<ref>getrectfuzzyzoom</ref>
				<ref>getrectstationarypattern</ref>
			</seealso>
		</command>

		<command id="setrectfuzziness">
			<canon>set rect fuzziness (handle, percent)</canon>
			<shortname>set rect fuzziness</shortname>
			<description>
				Makes a rect slice <p>handle</p> 'fuzzy', and optionally sets the <p>percent</p>
				fuzziness/opacity (defaults to 50).
				A <p>percent</p> of 0 is equivalent to <tt><ref>setrecttrans</ref>(handle, trans:hollow)</tt>,
				a <p>percent</p> of 100 is equivalent to <tt><ref>setrecttrans</ref>(handle, trans:opaque)</tt>,
				and anything in between 1 and 99 implicitly does <tt><ref>setrecttrans</ref>(handle, trans:fuzzy)</tt>
				as well as setting the percentage.
			</description>
			<seealso>
				<ref>setrectopacity</ref>
				<ref>setrecttrans</ref>
				<ref>getrecttrans</ref>
				<ref>getrectfuzziness</ref>
				<ref>setrectfuzzyzoom</ref>
				<ref>setrectstationarypattern</ref>
			</seealso>
		</command>

		<command id="getrectfuzzyzoom">
			<canon>get rect fuzzy zoom (handle)</canon>
			<shortname>get rect fuzzy zoom</shortname>
			<description>
				Given a rect slice <p>handle</p> returns the zoom amount for its fuzzy background,
				if it has one. See <ref>setrectfuzzyzoom</ref>.
				The zoom is a value 1 or higher.
			</description>
			<seealso>
				<ref>getrectfuzziness</ref>
				<ref>getrectstationarypattern</ref>
			</seealso>
		</command>
		<command id="setrectfuzzyzoom">
			<canon>set rect fuzzy zoom (handle, zoom)</canon>
			<shortname>set rect fuzzy zoom</shortname>
			<description>
				Sets the zoom amount for the fuzzy background of a rect slice <p>handle</p> which has had
				its background set to <tt>trans:fuzzy</tt> using e.g. <ref>setrecttrans</ref>.
				If the rectangle doesn't have a fuzzy background then this setting has no effect.
				<p>zoom</p> must be 1 or higher, measuring the size of each 'block' in the fuzzy pattern in pixels.
			</description>
			<seealso>
				<ref>getrectfuzzyzoom</ref>
				<ref>setrectfuzziness</ref>
				<ref>setrectstationarypattern</ref>
			</seealso>
		</command>

		<command id="getrectstationarypattern">
			<canon>get rect stationary pattern (handle)</canon>
			<shortname>get rect stationary pattern</shortname>
			<description>
				Given a rect slice <p>handle</p> returns <tt>true</tt> or <tt>false</tt>,
				telling whether its fuzzy background pattern (if it has one) is set to be
				'stationary'. See <ref>setrectstationarypattern</ref>.
			</description>
			<seealso>
				<ref>getrectfuzziness</ref>
				<ref>getrectfuzzyzoom</ref>
			</seealso>
		</command>
		<command id="setrectstationarypattern">
			<canon>set rect stationary pattern (handle, value)</canon>
			<shortname>set rect stationary pattern</shortname>
			<description>
				Set whether a rect slice <p>handle</p> with a fuzzy background pattern is
				'stationary', meaning that as you move the slice around the pattern doesn't shift.
				This is especially useful when two fuzzy rects overlap.
				<p>value</p> should be <tt>true</tt> or <tt>false</tt>.
				If the rectangle doesn't have a fuzzy background then this setting has no effect.
			</description>
			<seealso>
				<ref>getrectstationarypattern</ref>
				<ref>setrectfuzziness</ref>
				<ref>setrectfuzzyzoom</ref>
			</seealso>
		</command>

		<command id="setrectopacity">
			<canon>set rect opacity (handle, percent)</canon>
			<shortname>set rect opacity</shortname>
			<description>
				Makes a rect slice <p>handle</p> (truly) transparent, and optionally sets the <p>percent</p>
				opacity (defaults to 50).
				A <p>percent</p> of 0 is equivalent to <tt><ref>setrecttrans</ref>(handle, trans:hollow)</tt>,
				a <p>percent</p> of 100 is equivalent to <tt><ref>setrecttrans</ref>(handle, trans:opaque)</tt>,
				and anything in between 1 and 99 implicitly does <tt><ref>setrecttrans</ref>(handle, trans:blend)</tt>
				as well as setting the percentage.
			</description>
			<seealso>
				<ref>setrectfuzziness</ref>
				<ref>setrecttrans</ref>
				<ref>getrecttrans</ref>
				<ref>getrectopacity</ref>
				<ref>setopacity</ref>
			</seealso>
		</command>

		</section>		<!--Rect Slices-->

		<section title="Line Slices">
		<description>
			Line slices are slighty different; their size doesn't exactly define the size of the rectangular part of the
			screen which they stretch across,
			but is instead used as the offset between their ends.
			Both ends are drawn inclusively.
			For example a width 10 height 0 Line slice positioned at x=50,y=20 will draw a line from 50,20 to 60,20,
			as a rectangle that's actually 11 pixels long and 1 pixel high.
			The line thickness is always 1 pixel.
			A width=0 height=0 line slice is a single pixel.
			<lb/>
			So you can give line slices a negative width or height too, to draw a line at any angle.
			The "top-left" alignment point of a line slice is its start point, and the "bottom-right" is its end point.
		</description>
		<command id="createline">
			<canon>create line (width, height, color)</canon>
			<shortname>create line</shortname>
			<description>
				Create a new line slice and return a handle to it.
				You can provide an optional <p>width</p> and <p>height</p> and an optional <p>color</p> (all default to 0).
				Like all slice types, an line slice can be used as a container for other slices with <ref>setparent</ref>.
			</description>
		</command>
		<reference ref="sliceisline" />
		<command id="getlinecolor">
			<canon>get line color (handle)</canon>
			<shortname>get line color</shortname>
			<description>
				Given an line slice <p>handle</p>, return its color.
				This will be a number from 0 to 255 representing a color from the master palette,
				or less than 0 for a UI color.
			</description>
			<seealso>
				<ref>setlinecolor</ref>
			</seealso>
		</command>
		<command id="setlinecolor">
			<canon>set line color (handle, color)</canon>
			<shortname>set line color</shortname>
			<description>
				Given an line slice <p>handle</p>, change its color.
				The <p>color</p> should be a number from 0 to 255 representing a color from the master palette.
			</description>
			<seealso>
				<ref>getlinecolor</ref>
			</seealso>
		</command>
		</section>		<!--Line Slices-->

		<section title="Ellipse Slices">
		<command id="createellipse">
			<canon>create ellipse (width, height, border color, fill color)</canon>
			<shortname>create ellipse</shortname>
			<description>Create a new ellipse slice and return a handle to it. You can provide an optional <p>width</p> and <p>height</p>, an optional <p>border color</p> and an optional <p>fill color</p>. 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 <ref>setparent</ref></description>
		</command>
		<reference ref="sliceisellipse" />
		<command id="getellipsebordercol">
			<canon>get ellipse border col (handle)</canon>
			<shortname>get ellipse border col</shortname>
			<description>Given an ellipse slice <p>handle</p>, 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.</description>
			<seealso>
				<ref>setellipsebordercol</ref>
				<ref>setellipsefillcol</ref>
				<ref>getellipsefillcol</ref>
			</seealso>
		</command>
		<command id="setellipsebordercol">
			<canon>set ellipse border col (handle, color)</canon>
			<shortname>set ellipse border col</shortname>
			<description>Given an ellipse slice <p>handle</p>, change the color it uses for its border. The <p>color</p> should be a number from 1 to 255 representing a color from the master palette. <p>color</p> 0 means 'transparent', which is not very useful.</description>
			<seealso>
				<ref>getellipsebordercol</ref>
				<ref>setellipsefillcol</ref>
				<ref>getellipsefillcol</ref>
			</seealso>
		</command>
		<command id="getellipsefillcol">
			<canon>get ellipse fill col (handle)</canon>
			<shortname>get ellipse fill col</shortname>
			<description>Given an ellipse slice <p>handle</p>, 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).</description>
			<seealso>
				<ref>setellipsebordercol</ref>
				<ref>getellipsebordercol</ref>
				<ref>setellipsefillcol</ref>
			</seealso>
		</command>
		<command id="setellipsefillcol">
			<canon>set ellipse fill col (handle, color)</canon>
			<shortname>set ellipse fill col</shortname>
			<description>Given an ellipse slice <p>handle</p>, change the color it uses for its fill. The <p>color</p> should be a number from 1 to 255 representing a color from the master palette, or 0 meaning transparent fill (hollow).</description>
			<seealso>
				<ref>setellipsebordercol</ref>
				<ref>getellipsebordercol</ref>
				<ref>getellipsefillcol</ref>
			</seealso>
		</command>
		</section>		<!--Ellipse Slices-->

		<section title="Text Slices">
		<command id="createtext">
			<canon>create text</canon>
			<shortname>create text</shortname>
			<description>Creates a new blank text slice and returns a <ref>slicehandle</ref> to it. A text slice holds a string of text, but it can be positioned and handled just like any other slice. Use the <ref>setslicetext</ref> command to copy a string into the text slice.</description>
			<seealso>
				<ref>setslicetext</ref>
			</seealso>
		</command>
		<reference ref="sliceistext" />
		<command id="setslicetext">
			<canon>set slice text(handle, string id)</canon>
			<shortname>set slice text</shortname>
			<description>
				Copy a string specified by <p>string id</p> into the text slice specified by <p>handle</p>.
				Afterwards, there is no link between the text slice and the string; they have different contents.
			</description>
			<seealso>
				<ref>createtext</ref>
				<ref>getslicetext</ref>
			</seealso>
		</command>
		<command id="getslicetext">
			<canon>get slice text(string id, slice handle)</canon>
			<shortname>get slice text</shortname>
			<description>
				Copy the contents of the text slice specified by <p>slice handle</p> into a string specified by <p>string id</p>.
				Afterwards, there is no link between the text slice and the string; they have different contents.
			</description>
			<seealso>
				<ref>createtext</ref>
				<ref>setslicetext</ref>
			</seealso>
		</command>
		<command id="expandstringsinslices">
			<canon>expand strings in slices(handle, saveslot)</canon>
			<shortname>expand strings in slices</shortname>
			<description>Starting with the slice handle, search for all child slices, and if any of them are text slices, then expand any text codes such as ${H1} ${V2} or ${S5}. This does the same thing that textboxes do automatically. The <p>saveslot</p> argument is optional. If you leave it out, the codes will be expanded based on the currently running game state. If you specify a save slot number from 1-1000 then the string will be expanded based on hero names, variables, and strings in that save slot.</description>
			<example>  variable (col)
  col := load slice collection(1)
  expand strings in slices(col)
</example>
			<seealso>
				<ref>expandstring</ref>
			</seealso>
		</command>
		<command id="gettextcolor">
			<canon>get text color(handle)</canon>
			<shortname>get text color</shortname>
			<description>Given a text slice <p>handle</p>, returns the current color of the text.</description>
			<seealso>
				<ref>settextcolor</ref>
			</seealso>
		</command>
		<command id="settextcolor">
			<canon>set text color(handle, color)</canon>
			<shortname>set text color</shortname>
			<description>Given a text slice <p>handle</p>, change <p>color</p> used to display the text.</description>
			<seealso>
				<ref>gettextcolor</ref>
			</seealso>
		</command>
		<command id="gettextbg">
			<canon>get text bg(handle)</canon>
			<shortname>get text bg</shortname>
			<description>Given a text slice <p>handle</p>, returns the current background color of the text. Note that this only matters if the text slice is not displaying an outline.</description>
			<seealso>
				<ref>gettextcolor</ref>
				<ref>settextbg</ref>
			</seealso>
		</command>
		<command id="settextbg">
			<canon>set text bg(handle, color)</canon>
			<shortname>set text bg</shortname>
			<description>Given a text slice <p>handle</p>, change the background <p>color</p> used to display the text. This only matters if the text slice is set to not use an outline.</description>
			<seealso>
				<ref>gettextbg</ref>
				<ref>settextcolor</ref>
			</seealso>
		</command>
		<command id="getoutline">
			<canon>get outline(handle)</canon>
			<shortname>get outline</shortname>
			<description>Given a text slice <p>handle</p>, <p>true</p> if the text slice is configured to display an outline, or <p>false</p> if it is configured not to display and outline.</description>
			<seealso>
				<ref>setoutline</ref>
			</seealso>
		</command>
		<command id="setoutline">
			<canon>set outline(handle, outline)</canon>
			<shortname>set outline</shortname>
			<description>Given a text slice <p>handle</p>, change whether or not it will be displayed with an outline. If the second argument is omitted or <p>true</p>, change the slice to show an outline, if the second argument is <p>false</p> change the slice to show no outline.</description>
			<seealso>
				<ref>getoutline</ref>
			</seealso>
		</command>
		<command id="getwrap">
			<canon>get wrap(handle)</canon>
			<shortname>get wrap</shortname>
			<description>Given a text slice <p>handle</p>, <p>true</p> if the text slice is configured to wrap, or <p>false</p> if it is configured not to wrap.</description>
			<seealso>
				<ref>setwrap</ref>
			</seealso>
		</command>
		<command id="setwrap">
			<canon>set wrap(handle, wrap)</canon>
			<shortname>set wrap</shortname>
			<description>Given a text slice <p>handle</p>, change whether or not it will wrap. If the second argument is omitted or <p>true</p>, change the slice to wrap-mode, if the second argument is <p>false</p> change the slice into non-wrapping mode.</description>
			<seealso>
				<ref>getwrap</ref>
			</seealso>
		</command>
		</section>		<!--Text Slices-->

		<section title="Grid Slices">
		<command id="creategrid">
			<canon>create grid (width, height, rows, columns)</canon>
			<shortname>create grid</shortname>
			<description>
				Creates a new grid slice, and returns a <ref>slicehandle</ref> 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 (a single large cell).
				<note>
					Beware that the order of the <p>rows, columns</p> args is reversed from what you might expect:
					they affect the height and width of each cell, not width and height.
				</note>
			</description>
		</command>
		<reference ref="sliceisgrid" />
		<command id="setgridcolumns">
			<canon>set grid columns (handle, columns)</canon>
			<shortname>set grid columns</shortname>
			<description>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.</description>
			<seealso>
				<ref>getgridcolumns</ref>
				<ref>setgridrows</ref>
				<ref>getgridrows</ref>
			</seealso>
		</command>
		<command id="getgridcolumns">
			<canon>get grid columns (handle)</canon>
			<shortname>get grid columns</shortname>
			<description>Returns the number of columns in a grid slice.</description>
			<seealso>
				<ref>setgridcolumns</ref>
				<ref>setgridrows</ref>
				<ref>getgridrows</ref>
			</seealso>
		</command>
		<command id="setgridrows">
			<canon>set grid rows (handle, rows)</canon>
			<shortname>set grid rows</shortname>
			<description>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.</description>
			<seealso>
				<ref>setgridcolumns</ref>
				<ref>getgridcolumns</ref>
				<ref>getgridrows</ref>
			</seealso>
		</command>
		<command id="getgridrows">
			<canon>get grid rows (handle)</canon>
			<shortname>get grid rows</shortname>
			<description>Returns the number of rows in a grid slice.</description>
			<seealso>
				<ref>setgridcolumns</ref>
				<ref>getgridcolumns</ref>
				<ref>setgridrows</ref>
			</seealso>
		</command>
		<command id="showgrid">
			<canon>show grid (handle, shown)</canon>
			<shortname>show grid</shortname>
			<description>Grid slices are normally invisible, but they can optionally display gridlines. This command takes a grid slice <p>handle</p> 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 <ref>setslicevisible</ref>.</description>
			<seealso>
				<ref>gridisshown</ref>
			</seealso>
		</command>
		<command id="gridisshown">
			<canon>grid is shown (handle)</canon>
			<shortname>grid is shown</shortname>
			<description>This command takes a grid slice <p>handle</p> 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 <ref>getslicevisible</ref>.</description>
			<seealso>
				<ref>showgrid</ref>
			</seealso>
		</command>
		</section>		<!-- Grid Slices-->

		<section title="Select Slices">
		<command id="createselect">
			<canon>create select (width, height)</canon>
			<shortname>create select</shortname>
			<description>Creates a new select slice, and returns a <ref>slicehandle</ref> 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.</description>
		</command>
		<reference ref="sliceisselect" />
		<command id="setselectsliceindex">
			<canon>set select slice index (handle, index)</canon>
			<shortname>set select slice index</shortname>
			<description>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.
				<lb/>
				Use <ref>setselectedchild</ref> instead if you want to set the selected child
				by its slice handles instead of index.
			</description>
			<seealso>
				<ref>getselectsliceindex</ref>
			</seealso>
		</command>
		<command id="getselectsliceindex">
			<canon>get select slice index (handle)</canon>
			<shortname>get select slice index</shortname>
			<description>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.
				<lb/>
				Use <ref>getselectedchild</ref> instead if you want a slice handle for
				the selected child instead of its index.
			</description>
			<seealso>
				<ref>setselectsliceindex</ref>
			</seealso>
		</command>
		<command id="setselectedchild">
			<canon>set selected child (select, child)</canon>
			<shortname>set selected child</shortname>
			<description>
				Given a select slice handle <p>select</p> and a slice handle for one of its
				children, <p>child</p>, selects that child.
				<lb/>
				This is just a convenience wrapper around <ref>setselectsliceindex</ref>.
			</description>
		</command>
		<command id="getselectedchild">
			<canon>get selected child (handle)</canon>
			<shortname>get selected child</shortname>
			<description>
				Given a select slice <p>handle</p>, returned the slice handle of the currently selected child.
				Returns <tt>false</tt>/0 if the selected index is out of range
				(including when slice has no children).
				<lb/>
				This is just a convenience wrapper around <ref>getselectsliceindex</ref>.
			</description>
		</command>
		</section>		<!-- Select Slices-->

		<section title="Scroll Slices">
		<command id="createscroll">
			<canon>create scroll (width, height)</canon>
			<shortname>create scroll</shortname>
			<description>
				Creates a new scroll slice, and returns a <ref>slicehandle</ref> 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.
			</description>
		</command>
		<reference ref="sliceisscroll" />
		<command id="setscrollbarstyle">
			<canon>set scroll bar style (handle, style)</canon>
			<shortname>set scroll bar style</shortname>
			<description>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.</description>
			<seealso>
				<ref>getscrollbarstyle</ref>
			</seealso>
		</command>
		<command id="getscrollbarstyle">
			<canon>get scroll bar style (handle)</canon>
			<shortname>get scroll bar style</shortname>
			<description>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.</description>
			<seealso>
				<ref>setscrollbarstyle</ref>
			</seealso>
		</command>
		<command id="setscrollcheckdepth">
			<canon>set scroll check depth (handle, depth)</canon>
			<shortname>set scroll check depth</shortname>
			<description>Changes the number of generations of <ref>descendent</ref>s that a scroll slice cares about. The first argument is the <ref>slicehandle</ref> of the scroll slice. The second argument is the desired depth, or 0 to check the entire <ref>slicesubtree</ref>. 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.</description>
			<seealso>
				<ref>getscrollcheckdepth</ref>
			</seealso>
		</command>
		<command id="getscrollcheckdepth">
			<canon>get scroll check depth (handle)</canon>
			<shortname>get scroll check depth</shortname>
			<description>Returns the number of generations of <ref>descendent</ref>s that a scroll slice cares about, or 0 if it considers the <ref>slicesubtree</ref>. The first argument is the <ref>slicehandle</ref> 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.</description>
			<seealso>
				<ref>setscrollcheckdepth</ref>
			</seealso>
		</command>
		<command id="scrolltochild">
			<alias>scrolltoslice</alias>
			<shortname>scroll to child</shortname>
		</command>
		<command id="scrolltoslice">
			<canon>scroll to slice (parent, sl, apply padding)</canon>
			<shortname>scroll to slice</shortname>
			<description>
				Causes all the children of the <p>parent</p> slice to be shifted by the same offset
				so the screen position of <p>sl</p> (which may be any <ref>descendent</ref> of <p>parent</p>) fits inside the parent.
				<lb/>
				If <p>apply padding</p> is true (the default is <tt>false</tt>),
				then <p>sl</p> is scrolled within the area of <p>parent</p>
				with padding subtracted (the area covered by a child set to Fill Parent).
				<note>
					This is mainly intended for scroll slices, such as those created with the <ref>createscroll</ref> command,
					but it can be used on any type of slice.
					(Children that are set to fill their parents, or children that are automatically
					positioned by a grid parent will be unaffected, and an error or warning may be shown.)
				</note>
				<note>
					This works for all descendent slices <p>sl</p>, not just children!
					It only changes the positions of the children of <p>parent</p>,
					but that causes the screen position of <p>sl</p> to also change.
				</note>
			</description>
		</command>
		</section>		<!--Scroll Slices-->

		<section title="Panel Slices">
		<description>
			Panel slices split up their area between their first two children in various ways,
			and don't display any other children.
		</description>
		<command id="createpanel">
			<canon>create panel (width, height)</canon>
			<shortname>create panel</shortname>
			<description>
				Creates a new panel slice, and returns a <ref>slicehandle</ref> 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.
			</description>
		</command>
		<reference ref="sliceispanel" />
		<command id="getpanelisvertical">
			<canon>get panel is vertical (handle)</canon>
			<shortname>get panel is vertical</shortname>
			<description>Returns true if the given panel slice <p>handle</p> is configured to orient its children vertically, or false if it orients them horizontally.</description>
		</command>
		<command id="setpanelisvertical">
			<canon>set panel is vertical (handle, value)</canon>
			<shortname>set panel is vertical</shortname>
			<description>Changes how the given panel slice <p>handle</p> orients its children. If the <p>value</p> is true, they will be oriented vertically, or if false it will orient them horizontally.</description>
		</command>
		<command id="getpanelprimaryindex">
			<canon>get panel primary index (handle)</canon>
			<shortname>get panel primary index</shortname>
			<description>Returns 0 or 1 to indicate whether the first or second child of the given panel slice <p>handle</p> 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.</description>
		</command>
		<command id="setpanelprimaryindex">
			<canon>set panel primary index (handle, zero or one)</canon>
			<shortname>set panel primary index</shortname>
			<description>Changes whether the first or second child of the given panel slice <p>handle</p> 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.</description>
		</command>
		<command id="getpanelsizedbychild">
			<canon>get panel sized by child (handle)</canon>
			<shortname>get panel sized by child</shortname>
			<description>Returns true if the given panel slice <p>handle</p> will adjust its split based on the primary child ("larger of primary child..." in the slice editor), or false if it only uses "fixed" sized based on percent and pixels.</description>
		</command>
		<command id="setpanelsizedbychild">
			<canon>set panel sized by child (handle, value)</canon>
			<shortname>set panel sized by child</shortname>
			<description>
				Changes whether the given panel slice <p>handle</p> is split using its primary child's size.
				If <p>value</p> is true, the width or height of the primary part will be the "larger of the primary child's size" and the usual percent plus pixels, aka "sized by child".
				If false then the split will be the "fixed" percent plus pixels size only.
				<lb/>
				Turning on sized-by-child does not set 'percent' and 'pixels' to zero.
			</description>
		</command>
		<command id="getpanelpercentasint">
			<canon>get panel percent as int (handle)</canon>
			<shortname>get panel percent as int</shortname>
			<description>Given a panel slice <p>handle</p>, returns an integer from 0 to 100 to indicate what percentage of the panel should be filled by the primary child slice</description>
		</command>
		<command id="setpanelpercent">
			<canon>set panel percent (handle, percent)</canon>
			<shortname>set panel percent</shortname>
			<description>Given a panel slice <p>handle</p>, 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. (If the panel is configured to take its split size from the child, then this option is ignored entirely)</description>
		</command>
		<command id="getpanelpixels">
			<canon>get panel pixels (handle)</canon>
			<shortname>get panel pixels</shortname>
			<description>Given a panel slice <p>handle</p>, returns the number of pixels of space that the panel will reserve for its primary child</description>
		</command>
		<command id="setpanelpixels">
			<canon>set panel pixels (handle, pixels)</canon>
			<shortname>set panel pixels</shortname>
			<description>Given a panel slice <p>handle</p>, 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. (If the panel is configured to take its split size from the child, then this option is ignored entirely)</description>
		</command>
		<command id="getpanelpadding">
			<canon>get panel padding (handle)</canon>
			<shortname>get panel padding</shortname>
			<description>Given a panel slice <p>handle</p>, returns the number of pixels of padding that will be left between the primary and secondary children</description>
		</command>
		<command id="setpanelpadding">
			<canon>set panel padding (handle, padding)</canon>
			<shortname>set panel padding</shortname>
			<description>Given a panel slice <p>handle</p>, changes the number of pixels of padding that the panel will leave between the primary and secondary children.</description>
		</command>
		</section>		<!-- Panel Slices-->


		<section title="Map Layer Slices">
		<description>
			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 <ref>lookupslice</ref> to get a handle
			for one of the map layer slices.
			They don't have any special attributes that you can access
			(use the <a href="#Tweaking Maps">map script commands</a> 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.
		</description>
		<reference ref="sliceismaplayer" />
		</section>		<!-- Map Layer Slices-->

		</section>		<!-- Slice Types-->

		<section title="Slice Collision Testing">
		<description>
			<note>
				For the purposes of collision testing, all slices are treated as solid rectangles,
				even if they are text slices, sprites, ellipses, lines or invisible.
				A point right on the boundary of this rectangle counts as a collision.
			</note>
		</description>

		<command id="slicecollidepoint">
			<canon>slice collide point (handle, x, y)</canon>
			<shortname>slice collide point</shortname>
			<description>
				Return true if a given <p>x</p> and <p>y</p> coordinate point lies inside the
				bounding rectangle for slice <p>handle</p>'s screen position.
				<p>x</p> and <p>y</p> are pixel coordinates relative to the screen,
				such as the ones returned by <ref>mousepixelx</ref> and <ref>mousepixely</ref>
				(but can also be off the screen).
				<note>
					Unlike <ref>sliceatpixel</ref>, this command ignores slice clipping.
				</note>
			</description>
			<seealso>
				<ref>slicecollide</ref>
			</seealso>
		</command>
		<command id="slicecollide">
			<canon>slice collide (handle1, handle2)</canon>
			<shortname>slice collide</shortname>
			<description>
				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 doesn't matter whether the slices are related or what their children are.
			</description>
			<seealso>
				<ref>slicecollidepoint</ref>
				<ref>slicecontains</ref>
			</seealso>
		</command>
		<command id="slicecontains">
			<canon>slice contains (handle1, handle2)</canon>
			<shortname>slice contains</shortname>
			<description>
				Return true if the screen position of slice <p>handle2</p> is completely inside
				slice <p>handle1</p> (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 doesn't matter whether the slices are related or what their children are.
			</description>
			<seealso>
				<ref>slicecollide</ref>
			</seealso>
		</command>
		<command id="sliceatpixel">
			<canon>slice at pixel (parent, x, y, number, check descendants, visible only)</canon>
			<shortname>slice at pixel</shortname>
			<description>
				Searches through all the descendants of <p>parent</p> for a slice containing the given <p>x</p>, <p>y</p> pixel screen position.
				To search all your slices, you can often use <ref>spritelayer</ref> as <p>parent</p>, since that is the default parent of new slices.
				<lb/>
				<p>number</p> 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.
				Alternatively, -1 is the topmost one, -2 is the second from the top, etc.
				slice at pixel returns 0 if <p>number</p> is out of range (<tt>number &lt; -count</tt> or  larger than or equal to the number of overlapping slices).
				If you pass <ref>getcount</ref> as <p>number</p> the number of slices at that pixel is returned instead of a slice handle.
				<lb/>
				<p>check descendants</p> is an optional argument defaulting to true.
				If false, then only <p>parent</p>'s children will be checked, not all its descendants.
				<lb/>
				<p>visible only</p> 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 <p>parent</p> itself
				is visible doesn't have any effect.)
				For example, pass true for <p>visibleonly</p> in order to avoid finding the children of Select slices
				which are not selected (and therefore invisible).
				<lb/>
				This command never returns Special slices, such as the <ref>spritelayer</ref> slice.
				<note>
					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!
				</note>
				<note>
					If a slice clips its children, then any parts of those children
					that are clipped off are ignored when looking for <p>x</p>, <p>y</p>.
					However, it doesn't matter whether <p>parent</p> or any of its ancestors
					are set to clip; it's assumed that they don't.
					<lb/>
					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
					<p>x</p>, <p>y</p>.
				</note>
			</description>
			<seealso>
				<ref>slicecollidepoint</ref>
				<ref>findcollidingslice</ref>
				<ref>menuitematpixel</ref>
			</seealso>
		</command>
		<command id="findcollidingslice">
			<canon>find colliding slice (parent, slice, number, check descendants, visible only)</canon>
			<shortname>find colliding slice</shortname>
			<description>
				Searches through all the descendants of <p>parent</p> for a slice colliding (intersecting) with the given <p>slice</p> (by screen position).
				(Children of <p>slice</p> are ignored.)
				To search all your slices, you can often use <ref>spritelayer</ref> as <p>parent</p>, since that is the default parent of new slices.
				<p>number</p> 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 <p>number</p> is too large (larger than or equal to the number of overlapping slices).
				If you pass <ref>getcount</ref> as <p>number</p> the number of overlapping slices is returned instead.
				<p>check descendants</p> is an optional argument defaulting to true.
				If false, then only <p>parent</p>'s children will be checked, not all its descendants.
				(That is, slices marked not-visible are ignored while searching for slices, but whether <p>parent</p> itself
				is visible doesn't have any effect.)
				Pass true for <p>visibleonly</p> in order to avoid finding the children of Select slices which are not selected (and therefore invisible).
				<p>visibleonly</p> defaults to false.
				<lb/>
				This command never returns Special slices, such as the <ref>spritelayer</ref> slice, nor will it return <p>slice</p> or any of its descendants.
				<note>
					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 <p>parent</p> or any of its ancestors
					are set to clip; it's assumed that they don't.
					<lb/>
					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 <p>slice</p>.
				</note>
			</description>
			<example># Example for the player picking up fruit by moving onto them using normal
# tile-based player movement, but you can use whatever 'player' slice you want)

global variable (1, fruit container)
global variable (2, collected fruits)  # Number picked up

# Create 10 randomly placed fruit slices on the map
plotscript, create fruit, begin
  # Where to put the fruit
  fruit container := lookup slice(sl:walkabout layer)

  variable (i, fruit)
  for (i, 1, 10) do (
    fruit := load walkabout sprite(42)   # Sprite set 42
    put slice(fruit, random(0, 500), random(0, 500))
    set parent(fruit, fruit container)
  )
end

# Call this from somewhere, such as an each-step script, or each tick from a loop, e.g.:
#   "while(true) do(pickup fruit, wait(1))"
plotscript, pickup fruit, begin
  variable (player, fruit)
  player := get hero slice(me)
  while (true) do (
     fruit := find colliding slice(fruit container, player)
     if (fruit == false) then (break)
     free slice (fruit)
     collected fruits += 1
   )
end
</example>
			<example>
# If you need to skip some colliding slices (e.g. other NPCs), or don't immediately free them on
# collision, use this version instead
plotscript, pickup fruit, begin
  variable (player, fruit, index)
  player := get hero slice(me)
  while (true) do (
     fruit := find colliding slice(fruit container, player, index)
     if (fruit == false) then (break)
     # Example of rejecting certain slices as not fruit
     if (slice is sprite(fruit) == false || get sprite set number(fruit) &lt;&gt; 42) then (
       index += 1
       continue  #skip
     )

     free slice (fruit)
     collected fruits += 1
   )
end
</example>
			<seealso>
				<ref>sliceatpixel</ref>
				<ref>slicecollide</ref>
			</seealso>
		</command>
		<reference ref="moveslicewithwallchecking" />
		<reference ref="checkwallcollisionxy" />
		</section>		<!--Slice Collision Testing-->

	</section>		<!--Slices-->

	<section title="Time Functions">
		<command id="daysofplay">
			<canon>days of play</canon>
			<shortname>days of play</shortname>
			<description>Returns the number of days that the game has been played</description>
		</command>
		<command id="setdaysofplay">
			<canon>set days of play (days)</canon>
			<shortname>set days of play</shortname>
			<description>Sets the number of days that the game has been "played" to <p>days</p>, as long as <p>days</p> is greater than 0. Useful if there are times that shouldn't count towards the play time, or for penalizing bad players >:)</description>
		</command>
		<command id="hoursofplay">
			<canon>hours of play</canon>
			<shortname>hours of play</shortname>
			<description>Returns the number of hours that the game has been played, 0 to 23</description>
		</command>
		<command id="sethoursofplay">
			<canon>set hours of play (hours)</canon>
			<shortname>set hours of play</shortname>
			<description>Sets the number of hours that the game has been "played" to <p>hours</p>, as long as <p>hours</p> is within the 0-23 range.</description>
		</command>
		<command id="minutesofplay">
			<canon>minutes of play</canon>
			<shortname>minutes of play</shortname>
			<description>Returns the number of minutes that the game has been played, 0 to 59</description>
		</command>
		<command id="setminutesofplay">
			<canon>set minutes of play (min)</canon>
			<shortname>set minutes of play</shortname>
			<description>Sets the number of minutes that the game has been "played" to <p>min</p>, as long as <p>min</p> is within the 0-59 range.</description>
		</command>
		<command id="secondsofplay">
			<canon>seconds of play</canon>
			<shortname>seconds of play</shortname>
			<description>Returns the number of seconds that the game has been played, 0 to 59</description>
		</command>
		<command id="setsecondssofplay">
			<canon>set seconds of play (sec)</canon>
			<shortname>set seconds of play</shortname>
			<description>Sets the number of seconds that the game has been "played" to <p>sec</p>, as long as <p>sec</p> is within the 0-59 range.</description>
		</command>
		<command id="systemyear">
			<canon>system year</canon>
			<shortname>system year</shortname>
			<description>Returns the current real-world year</description>
		</command>
		<command id="systemmonth">
			<canon>system month</canon>
			<shortname>system month</shortname>
			<description>Returns the current real-world month, 1 to 12</description>
		</command>
		<command id="systemday">
			<canon>system day</canon>
			<shortname>system day</shortname>
			<description>Returns the current real-world day, 1 to 31</description>
		</command>
		<command id="systemhour">
			<canon>system hour</canon>
			<shortname>system hour</shortname>
			<description>Returns the current real-world hour, 0 to 23</description>
		</command>
		<command id="systemminute">
			<canon>system minute</canon>
			<shortname>system minute</shortname>
			<description>Returns the current real-world minute, 0 to 59</description>
		</command>
		<command id="systemsecond">
			<canon>system second</canon>
			<shortname>system second</shortname>
			<description>Returns the current real-world second, 0 to 59</description>
		</command>
		<reference ref="milliseconds" />
		<reference ref="microseconds" />
		<command id="overridetickmilliseconds">
			<canon>override tick milliseconds (ms)</canon>
			<shortname>override tick milliseconds</shortname>
			<description>Changes the number of milliseconds in a game tick. The <p>ms</p> argument is a number of milliseconds in the range of 16 to 200</description>
		</command>
		<command id="canceloverridetickmilliseconds">
			<canon>cancel override tick milliseconds (ms)</canon>
			<shortname>cancel override tick milliseconds</shortname>
			<description>Resets the number of milliseconds in a game tick to whatever default is set up in the "Edit General Game Settings" menu.</description>
		</command>
	</section>

	<section title="Tweaking Maps">
		<command id="currentmap">
			<canon>current map</canon>
			<shortname>current map</shortname>
			<description>Returns the number (ID) of the current map.</description>
		</command>
		<command id="maxmapid">
			<canon>max map id</canon>
			<shortname>max map id</shortname>
			<description>Returns the number (ID) of the highest numbered map that exists in the game.</description>
		</command>
		<command id="mapwidth">
			<canon>map width (map)</canon>
			<shortname>map width</shortname>
			<description>Returns the width of a map in tiles. <p>map</p>, the map ID, is optional; the width of the current map is returned if it is not specified.</description>
		</command>
		<command id="mapheight">
			<canon>map height (map)</canon>
			<shortname>map height</shortname>
			<description>Returns the height of a map in tiles. <p>map</p>, the map ID, is optional; the height of the current map is returned if it is not specified.</description>
		</command>
		<command id="getmaptileset">
			<canon>get map tileset</canon>
			<shortname>get map tileset</shortname>
			<description>Returns the ID number of the default tileset for the map. <ref>loadtileset</ref> does not affect the value returned by this function, but <ref>changetileset</ref> does. Use <ref>layertileset</ref> instead to find the actual currently in-use tileset(s).</description>
		</command>
		<command id="layertileset">
			<canon>layer tileset (layer)</canon>
			<shortname>layer tileset</shortname>
			<description>Returns the ID number of the tileset that a certain tilemap layer is currently using.</description>
			<seealso>
				<ref>changetileset</ref>
				<ref>getmaptileset</ref>
			</seealso>
		</command>
		<command id="loadtileset">
			<canon>load tileset (tileset, layer)</canon>
			<shortname>load tileset</shortname>
			<description>Temporarily loads a different default or layer tileset for the currently displaying map.<lb/>Use <p>load tileset</p> (with no arguments) to restore the old tilesets after using load tileset (this has no effect after <ref>changetileset</ref>).<lb/>Use <p>load tileset (tileset)</p> to load a new default tileset. <p>tileset</p> is the ID number of the tileset to load. This changes the tileset for all layers that are set to 'Tileset: default'.<lb/>Use <p>load tileset (tileset, layer)</p> to load in a new a tileset for a single layer. <p>layer</p> is the layer number to target.
				<note>
					This command has a temporary effect: even if the map state is saved,
					the new tilesets will not persist if you leave the map and come back.
					<ref>changetileset</ref> is a more permanent alternative command.
				</note>
			</description>
			<seealso>
				<ref>getmaptileset</ref>
				<ref>layertileset</ref>
			</seealso>
		</command>
		<command id="changetileset">
			<canon>change tileset (tileset, layer)</canon>
			<shortname>change tileset</shortname>
			<description>An alternative to <ref>loadtileset</ref>: Changes and loads in the default or a map layer tileset for the current map. Unlike <ref>loadtileset</ref>, this command's effects last to the next time you come back to this map if you save the map state (in General Map Settings, or mapstate:mapsettings with <ref>savemapstate</ref>). To undo the effects, you'll need to use <ref>resetmapstate</ref>. <p>tileset</p> is the ID number of the tileset to load. You can use the constant <p>tileset:default</p> to set a layer to use the map's default tileset. <p>layer</p> is the layer number to change, or the constant <p>tileset:default</p> which changes the map's default tileset. It defaults to <p>tileset:default</p> if omitted. <p>change tileset</p> with no arguments undoes any changes to tilesets made using <ref>loadtileset</ref> (<b>not</b> <tt>change tileset</tt>).
				<warn>
					Any call to <tt>change tileset</tt> undoes all changes (to all map layers) made by <ref>loadtileset</ref>.
				</warn>
			</description>
			<seealso>
				<ref>getmaptileset</ref>
				<ref>layertileset</ref>
			</seealso>
		</command>
		<command id="lastlayerid">
			<canon>last layer id</canon>
			<shortname>last layer id</shortname>
			<description>
				Returns the ID number of the last map layer that exists on the current map.
				This is the topmost layer that is drawn on top of all the other layers.
			</description>
			<seealso>
				<ref>layeridunderwalkabouts</ref>
				<ref>layertileset</ref>
			</seealso>
		</command>
		<command id="layeridunderwalkabouts">
			<canon>layer id under walkabouts</canon>
			<shortname>layer id under walkabouts</shortname>
			<description>
				Returns the ID number of the map layer directly beneath the layer where hero and NPC walkabouts are drawn.
				This is the topmost layer that is not drawn on top of walkabouts.
			</description>
			<seealso>
				<ref>lastlayerid</ref>
				<ref>layertileset</ref>
			</seealso>
		</command>
		<command id="getlayername">
			<canon>get layer name(string id, layer)</canon>
			<shortname>get layer name</shortname>
			<description>
				Get the name of a layer on the current map and put it into the <p>string id</p>. The <p>layer</p> number is in the range of 0 to <ref>lastlayerid</ref>.
			</description>
			<seealso>
				<ref>lastlayerid</ref>
				<ref>findlayerbyname</ref>
				<ref>findlayerslicebyname</ref>
				<ref>maplayerslicebyid</ref>
			</seealso>
		</command>
		<command id="findlayerbyname">
			<canon>find layer by name(string id)</canon>
			<shortname>find layer by name</shortname>
			<description>
				Search for a named layer on the current map with a name that matches <p>string id</p>. Returns the layer id number, or -1 if no match is found. If more than one layer has the same matching name, the lowest id will be returned.
			</description>
			<seealso>
				<ref>lastlayerid</ref>
				<ref>getlayername</ref>
				<ref>findlayerslicebyname</ref>
				<ref>maplayerslicebyid</ref>
			</seealso>
		</command>
		<command id="findlayerslicebyname">
			<canon>find layer slice by name(string id)</canon>
			<shortname>find layer slice by name</shortname>
			<description>
				Search for a named layer on the current map with a name that matches <p>string id</p>. Returns the layer's slice handle, or 0 if no match is found. If more than one layer has the same matching name, the slice handle of the match with the lowest id will be returned.
			</description>
			<seealso>
				<ref>lastlayerid</ref>
				<ref>getlayername</ref>
				<ref>findlayerbyname</ref>
				<ref>maplayerslicebyid</ref>
			</seealso>
		</command>
		<command id="maplayerslicebyid">
			<canon>map layer slice by id(layer id)</canon>
			<shortname>map layer slice by id</shortname>
			<description>
				Given a <p>layer id</p> number, Returns the layer's slice handle for the current map. This is equivalent to <ref>lookupslice</ref> with the lookup codes such as <p>sli:Map layer 0</p>, <p>sli:Map layer 1</p>, etc... but it may be more convenient if you need to loop through the layers.
			</description>
			<seealso>
				<ref>lastlayerid</ref>
				<ref>getlayername</ref>
				<ref>findlayerbyname</ref>
				<ref>findlayerslicebyname</ref>
			</seealso>
		</command>

		<section title="Tilemap, Wallmap and Foemap">
		<command id="readmapblock">
			<canon>read map block (x, y, layer)</canon>
			<shortname>read map block</shortname>
			<description>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.</description>
			<seealso>
				<ref>currentdisplaytile</ref>
			</seealso>
		</command>
		<command id="writemapblock">
			<canon>write map block (x, y, value, layer)</canon>
			<shortname>write map block</shortname>
			<description>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.</description>
		</command>

		<command id="readwallbit">
			<canon>read wall bit (x, y, bit)</canon>
			<shortname>read wall bit</shortname>
			<description>
				Check the value of a single bit of one tile of the wallmap of the current map.
				Returns <tt>true</tt> or <tt>false</tt>.
				<lb/>
				<p>x</p>, <p>y</p> is the position in tiles.
				<lb/>
				<p>bit</p> can be <ref>northwall</ref>, <ref>eastwall</ref>, <ref>southwall</ref>,
				or <ref>westwall</ref> to check of the four possible walls on the tile,
				or <ref>vehiclea</ref>, <ref>vehicleb</ref>, <ref>harmtile</ref> or
				<ref>overheadtile</ref> to check one of the other bits.
				<lb/>
				See <ref>readpassblock</ref> for an example.
			</description>
			<seealso>
				<ref>readpassblock</ref>
			</seealso>
		</command>
		<command id="writewallbit">
			<canon>write wall bit (x, y, bit, value)</canon>
			<shortname>write wall bit</shortname>
			<description>
				Set the value of a single bit of one tile of the wallmap of the current map.
				<lb/>
				<p>x</p>, <p>y</p> is the position in tiles.
				<lb/>
				<p>bit</p> can be <ref>northwall</ref>, <ref>eastwall</ref>, <ref>southwall</ref>,
				or <ref>westwall</ref> to set the presense of the four possible walls on the tile,
				or <ref>vehiclea</ref>, <ref>vehicleb</ref>, <ref>harmtile</ref> or
				<ref>overheadtile</ref>.
				<lb/>
				<p>value</p> is optional should be either <tt>false</tt> or <tt>true</tt> (or any other non-zero
				value). The default is <tt>true</tt>.
			</description>
			<seealso>
				<ref>writepassblock</ref>
			</seealso>
		</command>

		<command id="readpassblock">
			<canon>read pass block (x, y)</canon>
			<shortname>read pass block</shortname>
			<description>Returns the value of a passability (wallmap) tile on the current map at the specified <p>x</p>, <p>y</p> position. The return value will be from 0 to 255 and consists of eight flag bits.<lb/><lb/>bit 1 = <ref>northwall</ref><lb/>bit 2 = <ref>eastwall</ref><lb/>bit 4 = <ref>southwall</ref><lb/>bit 8 = <ref>westwall</ref><lb/>bit 16 = <ref>vehiclea</ref><lb/>bit 32 = <ref>vehicleb</ref><lb/>bit 64 = <ref>harmtile</ref><lb/>bit 128 = <ref>overheadtile</ref><lb/><lb/>To check the value of a specific bit, use the <ref>and</ref> operator as in the following example, or just use the <ref>readwallbit</ref> command instead.</description>
			<example>  variable (pass)
  pass := read pass block(hero X(me), hero Y(me))
  if (pass, and, harm tile) then (
    # The hero is standing on a harm tile
  )

  # The following is equivalent:
  if (read wall bit(hero X(me), hero Y(me), harm tile)) then (
    # The hero is standing on a harm tile
  )
</example>
			<seealso>
				<ref>readwallbit</ref>
				<ref>checkwallcollisionxy</ref>
			</seealso>
		</command>
		<command id="writepassblock">
			<canon>write pass block (x,y,value)</canon>
			<shortname>write pass block</shortname>
			<description>Writes a new passability (wallmap) information to the specified <p>x</p>, <p>y</p> 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.<lb/><lb/>bit 1 = <ref>northwall</ref><lb/>bit 2 = <ref>eastwall</ref><lb/>bit 4 = <ref>southwall</ref><lb/>bit 8 = <ref>westwall</ref><lb/>bit 16 = <ref>vehiclea</ref><lb/>bit 32 = <ref>vehicleb</ref><lb/>bit 64 = <ref>harmtile</ref><lb/>bit 128 = <ref>overheadtile</ref><lb/><lb/>You can <ref>add</ref> the constants together (but it might be easier to use <ref>writewallbit</ref> instead). For example:</description>
			<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</example>
			<seealso>
				<ref>writewallbit</ref>
			</seealso>
		</command>

		<command id="readfoemap">
			<canon>read foemap (x, y)</canon>
			<shortname>read foemap</shortname>
			<description>
				Reads and returns a formation set number (which is a value 0-255) from the foemap at tile position <p>x</p>,<p>y</p>.
				The foemap is used to trigger random battles.
				0 means no formation set at that position.
			</description>
			<seealso>
				<ref>getbattlecountdown</ref>
			</seealso>
		</command>

		<section title="Tile Animations">
		<command id="currentdisplaytile">
			<canon>current display tile (tile number, layer)</canon>
			<shortname>current display tile</shortname>
			<description>Returns the tile number from the tileset, in the range 0-159, that a given tile (read with <ref>readmapblock</ref>, 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.</description>
		</command>
		<command id="animationstarttile">
			<canon>animation start tile (tile number, layer)</canon>
			<shortname>animation start tile</shortname>
			<description>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 <p>tile number</p> argument is typically returned from <ref>readmapblock</ref>. 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.</description>
			<seealso>
				<ref>currentdisplaytile</ref>
			</seealso>
		</command>
		<command id="gettileanimationoffset">
			<canon>get tile animation offset (animation pattern, layer)</canon>
			<shortname>get tile animation offset</shortname>
			<description>Returns the offset from the starting tile that the <p>animation pattern</p> (either 0 or 1) of the tileset in use by the <p>layer</p> (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.<note>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.</note></description>
			<seealso>
				<ref>readmapblock</ref>
			<ref>animationstarttile</ref>
			</seealso>
		</command>
		<command id="settileanimationoffset">
			<canon>set tile animation offset (animation pattern, offset, layer)</canon>
			<shortname>set tile animation offset</shortname>
			<description>Sets the offset from the starting tile that an <p>animation pattern</p> (either 0 or 1) of a tileset in use by a <p>layer</p> (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. <note>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.</note></description>
		</command>
		</section>		<!--Tile Animations-->

		<section title="Wall Checking">

		<reference ref="readpassblock" />
		<reference ref="checkherowall" />
		<reference ref="checknpcwall" />
		
		<command id="checkwallcollisionxy">
			<canon>check wall collision x (x, y, width, height, relative x, relative y, friction%)</canon>
			<canon>check wall collision y (x, y, width, height, relative x, relative y, friction%)</canon>
			<shortname>check wall collision x/y</shortname>
			<description>
				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 <p>x</p> and <p>y</p> map position in pixels of the top left
				corner of the hitbox (relative to the top-left of the map),
				its <p>width</p> and <p>height</p> in pixels,
				and the <p>relative x/y</p> offset of the target position of the object
				(for example <tt>relative x</tt> is 20 for one tile to the right).
				See <ref>moveslicewithwallchecking</ref> for information about what the optional <p>friction%</p>
				argument (which defaults to 100) does.
				<lb/>
				The return value is the maximum x or y offset
				(for <tt>check wall collision x</tt> or <tt>y</tt> respectively) 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 <p>relative x</p> or <p>relative y</p>.
				<lb/>
				For example, to check whether the hero can walk a full tile north (-20 pixels in the 'y' direction), you could write
				<example>if (check wall collision y(hero pixel x(me), hero pixel y(me), 20, 20, 0, -20) == -20) then (...)</example>
				(The <ref>checkherowall</ref> command is a much easier way to check the same thing,
				but only works if the hero is tile-aligned.)
				<lb/>
				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.
				<note>
					<ref>moveslicewithwallchecking</ref> is a more convenient way to check walls
					if you want to move a slice, e.g. when scripting a platformer.
				</note>
				<note>
					If you're moving diagonally, you'll need to call both
					<tt>check wall collision x</tt> and <tt>check wall collision y</tt> with identical
					arguments to find the x,y position of the collision point.
				</note>
				<danger>
					This command hasn't been updated to support one-way walls yet.
					Running into a one-way wall edge-on will give strange results.
				</danger>
			</description>
			<seealso>
				<ref>moveslicewithwallchecking</ref>
				<ref>findcollidingslice</ref>
				<ref>checkherowall</ref>
				<ref>checknpcwall</ref>
			</seealso>
		</command>
		<!--
		<command id="checkwallcollisionx">
			<alias>checkwallcollisionxy</alias>
			<shortname>check wall collision x</shortname>
		</command>
		<command id="checkwallcollisiony">
			<alias>checkwallcollisionxy</alias>
			<shortname>check wall collision y</shortname>
		</command>
		-->
		<command id="moveslicewithwallchecking">
			<canon>move slice with wallchecking (sl, relative x, relative y, friction%)</canon>
			<shortname>move slice with wallchecking</shortname>
			<description>
				Instantly moves a slice <p>sl</p> 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).
				<p>relative x/y</p> 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 (<ref>slicescreenx</ref>, etc).
				The slice's "colliding box" (or "hitbox") is, as you expect, the same as its size.
				<lb/>
				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.
				<lb/>
				<p>friction%</p> 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 (<p>relative x/y</p>), reduced by <p>friction%</p> percent.
				For example if <tt>relative x == 15, relative y == 3, friction% == 30</tt> 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).
				<lb/>
				If you're creating a platformer or zelda-like, you probably want friction to be 0% or a low value.
				<lb/>
				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 <ref>northwall</ref>, <ref>southwall</ref>, <ref>eastwall</ref>, <ref>westwall</ref>
				and the bitwise-<ref>and</ref> operator to 'test' the bitmask.
				For example <tt>bitmask, and, southwall</tt> 'tests' whether <p>sl</p>
				hit and is now resting against a wall on its south side (useful for a platformer).
				<lb/>
				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 <p>northeast corner</p>, <p>northwest corner</p>,
				<p>southeast corner</p>, <p>southwest corner</p>,
				all of which 'test' false when checked with
				<ref>northwall</ref>, <ref>southwall</ref>, <ref>eastwall</ref>, <ref>westwall</ref>.
				That's because the slice isn't actually resting against any walls, although it stopped!
				Use <ref>equal</ref>, not <ref>and</ref>, to check for these values.
				<lb/>
				You can check for walls without needing a slice using the alternative <ref>checkwallcollisionxy</ref> commands.
				<danger>
					This command hasn't been updated to support one-way walls yet.
					Running into a one-way wall edge-on will give strange results.
				</danger>
			</description>
			<example># 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</example>
			<seealso>
				<ref>checkwallcollisionxy</ref>
				<ref>findcollidingslice</ref>
			</seealso>
		</command>
		</section>		<!--Wall Checking-->

		</section>		<!--Tilemap, Wallmap and Foemap-->


		<section title="Zonemaps">
			<description>
				<note>
					All zone commands accept zone handles (returned by <ref>getzone</ref>)
					in place of zone IDs.
				</note>
			</description>

		<command id="writezone">
			<canon>write zone (zone id, x, y, value)</canon>
			<shortname>write zone</shortname>
			<description>
				Sets whether the tile at (<p>x,y</p>) is part of the specified zone.
				<p>zone id</p> is a valid ID number (see <ref>readzone</ref>) or zone handle,
				and <p>value</p> is interpreted as either <p>true</p> (non-zero) or <p>false</p> (zero).
				<note>
					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 <ref>false</ref>. Normally it returns <ref>true</ref>.
					If you choose to "Show all warnings" in General Game Settings in Custom,
					you will also get a warning message.
				</note>
				<note>
					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).
				</note>
			</description>
			<seealso>
				<ref>readzone</ref>
			</seealso>
		</command>
		<command id="readzone">
			<canon>read zone (zone id, x, y)</canon>
			<shortname>read zone</shortname>
			<description>
				Returns <ref>true</ref> if the tile at (<p>x,y</p>) is part of the specified zone.
				The <p>zone id</p> is an ID number from 1 to 9999 for zones defined in the map editor,
				or a zone handle,
				or can be the ID one of these special zones:
				<ul>
					<li>
						<tt>zone:OneWayExit == 10000</tt>
						- Marks tiles with one-way walls.
					</li>
				</ul>
			</description>
			<seealso>
				<ref>writezone</ref>
				<ref>zoneatspot</ref>
			</seealso>
		</command>
		<command id="zoneatspot">
			<canon>zone at spot (x, y, count)</canon>
			<shortname>zone at spot</shortname>
			<description>
				Used to get the set of all IDs of zones that contain the tile at (<p>x,y</p>).
				Since zones may overlap, <p>count</p> is used to specify which zone ID to return:
				0 is the first, 1 the second, and so on.
				<p>count</p> may also be the constant <ref>getcount</ref>,
				in which case the total number of zones which overlap there is returned.
				If <p>count</p> too large (greater than or equal to the number of zones),
				0 (<ref>false</ref>) is returned.
				<note>
					The order in which the ID numbers are returned is completely arbitrary.
					Also note this returns IDs, not zone handles.
				</note>
			</description>
			<seealso>
				<ref>readzone</ref>
			</seealso>
		</command>
		<command id="getzonename">
			<canon>get zone name (string id, zone id)</canon>
			<shortname>get zone name</shortname>
			<description>
				Places in the string with id number <p>string id</p> the name of zone <p>zone id</p>.
			</description>
		</command>
		<command id="getzoneextra">
			<canon>get zone extra (zone id, extra num)</canon>
			<shortname>get zone extra</shortname>
			<description>
				Returns the value in one of a zone's "extra data" fields, which you can set in the Zone Info editor.
				<p>extra num</p> is an <ref>extradataindex</ref>.
				<lb/>
				This command is the same as <ref>getextra</ref> but only works on zones, and accepts zone IDs as well as zone handles.
			</description>
		</command>
		<command id="setzoneextra">
			<canon>set zone extra (zone id, extra num, value)</canon>
			<shortname>set zone extra</shortname>
			<description>
				Sets the value of one of a zone's "extra data" fields.
				<p>extra num</p> is an <ref>extradataindex</ref>.
				<lb/>
				Extra data has no builtin meaning or effect, so you're free to use it for whatever you want.
				<lb/>
				This command is the same as <ref>setextra</ref> but only works on zones, and accepts zone IDs as well as zone handles.
				See <ref>appendextra</ref> and <ref>resizeextra</ref> for more ways to
				modify zone extra data.
				<note>
					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.
				</note>
			</description>
		</command>
		<command id="zonenumberoftiles">
			<canon>zone number of tiles (zone id)</canon>
			<shortname>zone number of tiles</shortname>
			<description>
				Given a <p>zone id</p> (from 1 to 9999 or a special id) or zone handle,
				returns the number of tiles that the zone contains.
			</description>
		</command>

		<command id="getzone">
			<canon>get zone (zone id)</canon>
			<shortname>get zone</shortname>
			<description>
				Given a <p>zone id</p> (from 1 to 9999 or a special ID), returns a "zone handle",
				which is a value that can be passed to any of the <secref>Extra Data Array Functions</secref>
				to access the zone's extra data.
				It can also be used in place of the zone ID in any zone command,
				but it does nothing useful in that case.
				For example, you can also pass a zone handle to this command and it returns it unchanged.
				<note>
					Zone handles are just numbers that can be recognised by the engine as referring to a zone --
					because what is <tt>5</tt>?
					Is it a zone ID, NPC ID, party slot, map number, ...??
					There's no way to or necessity to destroy a zone handle after use.
				</note>
				<example>  # Resize to 5 extra data slots
resize extra(get zone(10), 5)
# Set the last (10th) extra data field to 42
set extra(get zone(10), -1, 42) # Can also be written as  set zone extra(10, -1, 42)
				</example>
			</description>
		</command>

		<command id="nextzonetilex">
			<canon>next zone tile x (zone id, current x, current y)</canon>
			<shortname>next zone tile x</shortname>
			<altcommand id="nextzonetiley" alias="hide">
				<canon>next zone tile y (zone id, current x, current y)</canon>
				<shortname>next zone tile y</shortname>
			</altcommand>
			<description>
				Functions to find all tiles in a zone one by one, returning the x and y coordinate of the next tile
				after the <p>current x</p>, <p>current y</p> position.
				The map is scanned row-by-row from left to right, top to bottom.
				<p>zone id</p> is a zone ID (from 1 to 9999 or a special ID) or zone handle.
				<p>current x</p> and <p>current y</p> are optional, leave them out or pass -1 for both to get the first tile in the zone.
				<lb/>
				Returns -1 if there are no more tiles after the current position or if the zone is empty.
				<example># Finds the shortest distance (simple X + Y distance) in tiles between the player and any
# tile in the given zone, or returns 9999 if the zone is empty.
# Note: doesn't consider distances over the edges of a wrapping map!
script, hero distance to zone, zone, begin
  # Where we measure from
  variable (from x, from y)
  from x := hero x (me)
  from y := hero y (me)

  # Iterate through all tiles in the zone
  variable (x, y, current x, current y, closest distance, distance)
  closest distance := 9999
  x := next zone tile x (zone)
  y := next zone tile y (zone)
  while (x > -1) do (
    # Do something with the tile at (x, y)
    distance := abs(from x -- x) + abs(from y -- y)  # Manhatten distance formula
    closest distance := min (closest distance, distance)

    current x := x
    current y := y
    x := next zone tile x (zone, current x, current y)
    y := next zone tile y (zone, current x, current y)
  )
  return (closest distance)
end
				</example>
				<note>
					Make sure you pass the *same* x,y values into both of <tt>next zone tile x</tt>
					and <tt>next zone tile y</tt>, as shown in the example.
				</note>
			</description>
			<seealso>
				<ref>nextzonetiley</ref>
				<ref>readzone</ref>
				<ref>zonenumberoftiles</ref>
			</seealso>
		</command>

		</section>		<!--Zone functions-->


		<section title="General Map Settings">
		<command id="allowminimap">
			<canon>allow minimap (setting)</canon>
			<shortname>allow minimap</shortname>
			<description>
				Sets whether the Map option appears in the menu.
				Give no argument or <ref>true</ref> to enable, or <ref>false</ref> to disable.
				The effect goes away if you change maps or fight a battle.
			</description>
			<seealso>
				<ref>showminimap</ref>
			</seealso>
		</command>
		<command id="allowsaveanywhere">
			<canon>allow save anywhere (setting)</canon>
			<shortname>allow save anywhere</shortname>
			<description>
				Sets whether the Save option appears in the menu.
				Give no argument or <ref>true</ref> to enable,
				or <ref>false</ref> to disable.
				The effect goes away if you change maps or fight a battle.
			</description>
			<seealso>
				<ref>savemenu</ref>
			</seealso>
		</command>
		<command id="setharmtiledamage">
			<canon>set harm tile damage (amount)</canon>
			<shortname>set harm tile damage</shortname>
			<description>
				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.
			</description>
		</command>
		<command id="setharmtileflash">
			<canon>set harm tile flash (color)</canon>
			<shortname>set harm tile flash</shortname>
			<description>
				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.
			</description>
		</command>
		<command id="setfootoffset">
			<canon>set foot offset (offset)</canon>
			<shortname>set foot offset</shortname>
			<description>
				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.
			</description>
		</command>
		<command id="getfootoffset">
			<canon>get foot offset</canon>
			<shortname>get foot offset</shortname>
			<description>Returns the map's foot offset.</description>
		</command>
		<command id="drawnpcsaboveheroes">
			<canon>draw NPCs above heroes (setting)</canon>
			<shortname>draw NPCs above heroes</shortname>
			<description>
				Sets whether NPCs are drawn above, beneath or together (Y-sorted) with heroes.
				The effect goes away if you change maps or fight a battle (unless saved by <ref>savemapstate</ref>).
				<p>setting</p> is one of:
				<ul>
					<li>layering: heroes over NPCs</li>
					<li>layering: NPCS over heroes</li>
					<li>layering: heroes and NPCs together</li>
				</ul>
			</description>
		</command>
		<command id="setmapedgemode">
			<canon>set map edge mode (mode, default tile)</canon>
			<shortname>set map edge mode</shortname>
			<description>
				Sets the behaviour at the edge of the map.
				Use the constants <ref>crop</ref>, <ref>wrap</ref> and <ref>defaulttile</ref>.
				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.
			</description>
		</command>
		<command id="getmapedgemode">
			<canon>get map edge mode</canon>
			<shortname>get map edge mode</shortname>
			<description>
				Returns the map's edge mode.
				Use the constants <ref>crop</ref>, <ref>wrap</ref> and <ref>defaulttile</ref>
				to compare with the value returned.
			</description>
		</command>
		</section>		<!--General Map Data-->

		<section title="Map State">
		<command id="savemapstate">
			<canon>save map state (whichdata, customid)</canon>
			<shortname>save map state</shortname>
			<description>
				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.
				<lb/>
				Map state is not saved in saved games, and the temporary files will be deleted when you load or start a new a game!
				<lb/>
				<p>whichdata</p> is an <ref>or</ref>'d combination of the following constants,
				which specify exactly what you want to save:
				<lb/>
				<ul>
					<li>mapstate:all = mapstate:mapsettings, or, mapstate:npcs, or, mapstate:tiles</li>
					<li>mapstate:npcs = mapstate:npclocations, or, mapstate:npcdefinitions</li>
					<li>mapstate:tiles = mapstate:tilemap, or, mapstate:passmap, or, mapstate:zonemap</li>
					<li>mapstate:mapsettings</li>
					<li>mapstate:npclocations</li>
					<li>mapstate:npcdefinitions - local NPC definitions only, not global NPCs</li>
					<li>mapstate:tilemap</li>
					<li>mapstate:passmap</li>
					<li>mapstate:zonemap</li>
				</ul>
				The default is mapstate:all.
				<lb/>
				If <p>customid</p> is passed, it is used to save the state in a separate state file with an id
				number of <p>customid</p> which can only be loaded with <ref>loadmapstate</ref>.
				There are 32 available slots for use: 0 - 31.
				<lb/>
				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.
			</description>
			<example>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</example>
		</command>
		<command id="loadmapstate">
			<canon>load map state (whichdata, customid)</canon>
			<shortname>load map state</shortname>
			<description>Load temporary map state data previously saved either by <ref>savemapstate</ref> or when leaving a map set to remember state. The two arguments are optional and for advanced use. <p>whichdata</p> is a set of bits in the <ref>savemapstate</ref> format to determine what exactly to load. The default is mapstate:all. <p>customid</p> 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 <p>customid</p>, in which case nothing will be loaded.</description>
		</command>
		<command id="resetmapstate">
			<canon>reset map state (whichdata)</canon>
			<shortname>reset map state</shortname>
			<description>Reloads original unaltered map data from the RPG file. <p>whichdata</p> is a set of bits in the <ref>savemapstate</ref> format to determine what exactly to load. It is optional and the default is mapstate:all (which doesn't reset global NPC definitions). This does not remove temp state files for the map, so they could still be loaded instead when you next enter the map, use <ref>deletemapstate</ref> to remove them if wanted.</description>
		</command>
		<command id="deletemapstate">
			<canon>delete map state (whichdata, custom id)</canon>
			<shortname>delete map state</shortname>
			<description>
				Deletes temporary map state for the current map saved either with <ref>savemapstate</ref>
				or by leaving a map set to save state.
				By default (if both arguments are omitted), if the map is set to load NPC or tile
				data it will instead load the original data from the game files when it is entered.
				<lb/>
				<p>whichdata</p> is an optional set of bits in the <ref>savemapstate</ref> format to determine
				what exactly to delete. The default is <tt>mapstate:all</tt>.
				<p>customid</p> is an optional number between 0 and 31 of a slot in which a custom save was made.
			</description>
		</command>
		</section>		<!--Map State-->

	</section>

	<section title="Timers">
		<command id="settimer">
			<canon>set timer (id, count, speed, trigger, string, flags)</canon>
			<shortname>set timer</shortname>
			<description>
				Changes the settings for a given timer, and starts it.
				<p>id</p> is the number of a timer -- by default, there are 16 timers, numbered 0 to 15
				but you can change the number of available timers with <ref>allocatetimers</ref>.
				All other parameters are optional, or you can pass <ref>timer:default</ref> as any of them.
				This will leave the parameter unchanged (from the last time you set it or from the default initial value),
				it will NOT cause that timer setting to be reset to the default initial value.
				<p>Count</p> is the length of the timer.
				While it's running, the count will go down by one every <p>speed</p> game ticks (frames).
				I.e., if you set speed to 18, it will count down once every 18 ticks, close to one second
				if using the default framerate of 18.3fps.
				Use a speed of 1 to count down in ticks.
				Changing the timer's <p>count</p> (as opposed to passing <p>timer:default</p> as the second argument)
				will cause the timer to restart from the new value.
				<lb/>
				<p>trigger</p> is what happens when the timer runs out.
				You can use the constant <ref>timer:gameover</ref> to indicate that the game should end (the gameover script is not called),
				or specify a plotscript (in the form <tt>@my script</tt>) to have that run.
				A plotscript will get passed the id of the timer that triggered it as its first argument, if it has one,
				unless you specify the arguments using <ref>settimerargs</ref>.
				If the timer runs out during a battle then the effect happens after the battle ends.
				<lb/>
				You can bind a timer to a string using the <p>string</p> parameter to create a countdown that shows up on screen.
				Pass it the id of a string, and that string will be updated every time the timer counts down.
				You are responsible for displaying and positioning the string.
				<lb/>
				A timer also has a few other options in the form of <p>flags</p>.
				You can pass any combination of these flags (by <ref>or</ref>ing them together; see the example):
				<ul>
					<li>
						<ref>timerflag:battle</ref> to have it count down during battles (including in menus which
						pause the battle, except the Pause screen itself).
						You can turn on the "Never show script timers during battles" Peference Bitset to
						cause battle-timers to count down but not display.
						Note: Only the first battle-timer will show in battle! You can't show more than one.
					</li>
					<li><ref>timerflag:menu</ref> to have it count down even while the player is in a menu which pauses the game (e.g. the status menu)</li>
					<li><ref>timerflag:critical</ref> to have the timer end a battle or exit a menu if it runs out during it</li>
				</ul>
				<lb/>
				<note>
					Timers start counting down not from the current game 'tick', but from next one.
					So if you want to trigger something next tick (eg. run a script every frame)
					you need to pass <p>count</p> as 0 and <p>speed</p> as 1.
					A timer count set to 1 would counter-intuitively trigger in 2 ticks time.
				</note>
				<note>
					Timer settings are not saved in saved games.
				</note>
			<example># This starts a 300 second (5 minute) timer that counts down once every 18 ticks (approximately one second).
# If it runs out during battle, the battle won't end but a game-over will happen afterwards.
set timer (0, 300, 18, timer: game over, 0, (timerflag: battle, or, timerflag: menu))</example>
				See <ref>settimerargs</ref> for a larger example.
			</description>
			<seealso>
				<ref>settimerargs</ref>
				<ref>stoptimer</ref>
				<ref>readtimer</ref>
				<ref>systemsecond</ref>
				<ref>secondsofplay</ref>
				<ref>milliseconds</ref>
				<ref>runscriptbyid</ref>
			</seealso>
		</command>

		<command id="settimerargs">
			<canon>set timer args (id, args...)</canon>
			<shortname>set timer args</shortname>
			<description>
				Sets the arguments that a timer will pass to the script it triggers.
				(If the timer isn't set to call a script this shows an error,
				so you have to call <ref>settimer</ref> before <tt>set timer args</tt>.)
				<lb/>
				This overrides the default first argument to the script, which is the timer ID.
				So if you want the timer ID to be first argument you have to write something like
				<lb/>
				<tt>set timer args(id, id, 20)  # Script gets args 'id, 20'</tt>
				<lb/>
				If you call this with no arguments (<tt>set timer args(id)</tt>)
				then all the script's arguments default to 0.
				If the script doesn't take as many args as you pass it the extra
				ones will be ignored without error.
				<warn>
					After the script runs the arguments will still be remembered for next time
					the timer is run (you can re-start a timer by calling <tt>set timer(id, count)</tt>),
					unless the script ID is changed (or set to 0).
				</warn>
				<danger>
					Due to a bug, the script's default arguments will be ignored,
					and missing arguments are instead set to 0.
					This happens whether you use <tt>set timer args</tt> or not, and affects
					all triggered scripts.
					This will be fixed in some future version.
				</danger>
				<example># This script changes the tile at x,y on tilemap 'layer' between tile IDs 'tile'
# and 'othertile' in the tileset every 5 ticks, repeating until the map changes.
script, blink tile, x, y, layer, tile, othertile, timerid, whichmap = -1, begin

  # Remember which map we started running on, and stop if the map changes
  if (whichmap == -1) then (
    whichmap := current map
  ) else (
    if (whichmap &lt;&gt; current map) then (exit script)
  )

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

  # Cause this script to run again in 10 ticks, but this time
  # swap 'tile' and 'othertile'
  set timer (timerid, 0, 10, @blink tile)
  set timer args (timerid, x, y, layer, othertile, tile, timerid, whichmap)
end

# Some timer IDs
define constant (10, timer:blink1)
define constant (11, timer:blink2)

# This is an auto-run script for a map
plotscript, blinky map, begin
  blink tile (4, 5, 0, 0, 1, timer:blink1)   # Blink x=4,y=5,layer=0 between tiles 0 &amp; 1
  blink tile (11, 10, 1, 5, 10, timer:blink2) # Blink x=11,y=10,layer=1 between tiles 5 &amp; 10
end</example>
			</description>
			<seealso>
				<ref>settimer</ref>
			</seealso>
		</command>

		<command id="stoptimer">
			<canon>stop timer (id)</canon>
			<shortname>stop timer</shortname>
			<description>
				Stops a timer by setting its speed to 0. All of its other settings remain the same.
				You can resume it by calling <tt>set timer(id, timer:default, speed)</tt>
				if you know the original speed.
			</description>
			<seealso><ref>settimer</ref></seealso>
		</command>

<!--
		<command id="unusedtimer">
			<canon>unused timer</canon>
			<shortname>unused timer</shortname>
			<description>Returns the ID of a timer that is not currently used (which includes those which have already fired and have not been reset, and those stopped with <ref>stoptimer</ref>). This command will automatically increase the number of timers (like <ref>allocatetimers</ref>) if they are all in use.</description>
			<seealso>
				<ref>settimer</ref>
			</seealso>
		</command>
-->
		<command id="allocatetimers">
			<canon>allocate timers (number)</canon>
			<shortname>allocate timers</shortname>
			<description>Changes the number of available timers. The range of valid timer IDs becomes 0 to <p>number</p>-1. You can reduce the number of timers down to zero, and increase it up to 100000 (not recommended, each timer must be processed continuously). All existing timers that are not removed continue to run. The default number of timers is 16.</description>
		</command>
		<command id="readtimer">
			<canon>read timer (id)</canon>
			<shortname>read timer</shortname>
			<description>
				Returns the "count" of a given timer.
				A timer's count is at first equal to the <p>count</p> argument to <ref>settimer</ref>
				(or zero, if the timer hasn't been used).
				After <p>speed</p> ticks since <ref>settimer</ref> was called,
				the count is reduced by one.
				<lb/>
				The timer is triggered when the count becomes negative.
				Normally a timer that has finished has a count of -1,
				unless it had a negative count to begin with, most likely to happen
				if you restart a timer by passing <tt>timer:default</tt> as the <p>count</p> argument
				to <ref>settimer</ref>.
				(So if you keep repeating it that way, each time its count will reduce further: -1, -2, -3, ...)
			</description>
			<seealso><ref>settimer</ref></seealso>
		</command>
	</section>		<!-- Timers-->

	<section title="Script Triggers">
		<command id="setdeathscript">
			<canon>set death script (id)</canon>
			<shortname>set death script</shortname>
			<description>
				Changes the script that is run when you die in battle.
				The argument is the script&apos;s ID number, NOT the script&apos;s name.
				Calling set death script with no argument disables the death script.
			</description>
		</command>
		<command id="getdeathscript">
			<canon>get death script</canon>
			<shortname>get death script</shortname>
			<description>
				Returns the ID number of script that is run when you die in battle.
			</description>
		</command>
		<command id="setloadscript">
			<canon>set load script (id)</canon>
			<shortname>set load script</shortname>
			<description>
				Changes the script that will be run when you load <b>this</b> game after it is saved.
				The argument is the script&apos;s ID number, NOT the script&apos;s name.
				Calling set load script with no argument disables the load script.
				<warn>
					This command has no effect if the "Save gameover/loadgame script IDs" Preference Bitset is turned off!
				</warn>
				<note>
					Setting the load script and then loading an existing saved game has no effect, because the load game script
					already stored in that saved game is used instead.
					Unless "Save gameover/loadgame script IDs" is off, in which case the default one is used.
				</note>
			</description>
		</command>
		<command id="getloadscript">
			<canon>get load script</canon>
			<shortname>get load script</shortname>
			<description>Returns the ID number of script that is run when you load a saved game.</description>
		</command>
		<command id="setonkeypressscript">
			<canon>set on keypress script (id)</canon>
			<shortname>set on keypress script</shortname>
			<description>
				Changes the script that is run when you press a key.
				The argument is the script&apos;s name preceded by an @ sign.
				You can also use the ID number for old-style scripts.
				Calling set on keypress script with no argument disables the keypress script.
				The effect goes away if you change maps or fight a battle.
			</description>
			<example>set on keypress script(@keyhandlerscript)</example>
		</command>
		<command id="getonkeypressscript">
			<canon>get on keypress script</canon>
			<shortname>get on keypress script</shortname>
			<description>Returns the ID number of script that is run when you press a key.</description>
		</command>
		<command id="seteachstepscript">
			<canon>set each step script (id)</canon>
			<shortname>set each step script</shortname>
			<description>
				Changes the script that is run when you take a step.
				The argument is the script&apos;s name preceded by an @ sign.
				You can also use the ID number for old-style scripts.
				Calling set each step script with no argument disables the each step script.
				The effect goes away if you change maps or fight a battle.
			</description>
		</command>
		<command id="geteachstepscript">
			<canon>get each step script</canon>
			<shortname>get each step script</shortname>
			<description>Returns the ID number of script that is run when you take a step.</description>
		</command>
		<command id="setinsteadofbattlescript">
			<canon>set instead of battle script (id)</canon>
			<shortname>set instead of battle script</shortname>
			<description>
				Changes the script that is run instead of a random battle when one is triggered.
				The argument is a reference to the script in the form @scriptname.
				Calling set instead of battle script with no argument disables the instead of battle script.
				The effect goes away if you change maps or fight a battle.
			</description>
		</command>
		<command id="getinsteadofbattlescript">
			<canon>get instead of battle script</canon>
			<shortname>get instead of battle script</shortname>
			<description>Returns a reference to the script that is run instead of battles.</description>
		</command>
		<command id="getcurrentmapautorunscript">
			<canon>get current map autorun script</canon>
			<shortname>get current map autorun script</shortname>
			<description>Returns a reference to the script that is run automatically when you load the current map.</description>
		</command>
		<command id="getcurrentmapautorunscriptargument">
			<canon>get current map autorun script argument</canon>
			<shortname>get current map autorun script argument</shortname>
			<description>Returns the argument value that will be automatically passed to the autorun script on the current map. Is this useful? Not very!</description>
		</command>
	</section>		<!--Script Triggers-->

	<section title="General Game Settings">
		<description>These commands access data in the General Game Settings menu.</description>

		<command id="setcaterpillarmode">
			<canon>set caterpillar mode (state)</canon>
			<shortname>set caterpillar mode</shortname>
			<description>
				Sets whether or not to display the whole party in "caterpillar" style.
				This sets the "Enable Caterpillar Party" general preference bitset.
				If the argument is <ref>off</ref> then only the leader will be displayed.
				If the argument is <ref>on</ref> then the whole active (battle) party will be
				displayed and will normally walk behind the leader.
				<warn>
					Do not confuse this with the <ref>suspendcaterpillar</ref>
					and <ref>resumecaterpillar</ref> commands,
					which only apply when caterpillar mode is ON.
				</warn>
			</description>
		</command>
		<command id="sethpleveluprestore">
			<canon>set HP level up restore (state)</canon>
			<shortname>set HP level up restore</shortname>
			<description>
				Sets whether or not a hero regains full HP after a level-up.
				If the argument is <ref>on</ref> then HP is restored on a level-up.
				If the argument is <ref>off</ref> then the hero's HP is not restored on a level-up.
			</description>
		</command>
		<command id="setnompleveluprestore">
			<canon>set MP level up restore (state)</canon>
			<shortname>set MP level up restore</shortname>
			<description>
				Sets whether or not a hero regains full MP after a level-up.
				If the argument is <ref>on</ref> then MP is restored on a level-up.
				If the argument is <ref>off</ref> then the hero's MP is not restored on a level-up.
			</description>
		</command>
		<command id="setinnnorevivemode">
			<canon>set inn revive mode (state)</canon>
			<shortname>set inn revive mode</shortname>
			<description>
				Sets whether or not inns restore dead heroes to life.
				If the argument is <ref>on</ref> then dead heroes are restored by inns.
				If the argument is <ref>off</ref> then dead heroes remain dead in inns.
			</description>
		</command>
		<command id="setfullheroswapmode">
			<canon>set full hero swap mode (state)</canon>
			<shortname>set full hero swap mode</shortname>
			<description>
				Sets whether or not you can swap heroes in and out of your active party from the menu.
				If the argument is <ref>off</ref> then the "Order" menu will be available.
				If the argument is <ref>on</ref> then the "Team" menu will be available.
			</description>
		</command>
		<command id="setdebugkeysdisable">
			<canon>set debug keys disable (state)</canon>
			<shortname>set debug keys disable</shortname>
			<description>
				Sets whether or not the debugging keys are allowed.
				If the argument is <ref>off</ref> then debugging keys are allowed.
				If the argument is <ref>on</ref> then debugging keys are disabled.
			</description>
		</command>
		<command id="extendedscancodesenabled">
			<canon>extended scancodes enabled</canon>
			<shortname>extended scancodes enabled</shortname>
			<description>
				Returns the state of the "Disable better scancodes for scripts" backcompat bitset,
				returning <tt>true</tt> if it's off.
				This means that numpad keys are distinguishable from Home, Up, etc. keys.
				See <ref>scancode</ref>.
			</description>
		</command>
		<command id="getscreenwidth">
			<canon>get screen width</canon>
			<shortname>get screen width</shortname>
			<description>
				Returns the width of the screen in pixels.
			</description>
			<seealso>
				<ref>getscreenheight</ref>
			</seealso>
		</command>
		<command id="getscreenheight">
			<canon>get screen height</canon>
			<shortname>get screen height</shortname>
			<description>
				Returns the height of the screen in pixels.
			</description>
			<seealso>
				<ref>getscreenwidth</ref>
			</seealso>
		</command>
		<command id="readpreferencebit">
			<canon>read preference bit (bitnum)</canon>
			<shortname>read preference bit</shortname>
			<description>
				Returns the value (true or false) of one of the bits in the Preference Bitsets,
				Active-time Battle Bitsets or Backwards-compatibility Bitsets
				menus (in the General Game Settings menu).
				You can use this command if there isn't a dedicated command to read the bit,
				such as <ref>extendedscancodesenabled</ref>.
				Get the value of <p>bitnum</p> from the list below or
				by checking <a href="https://rpg.hamsterrepublic.com/ohrrpgce/GEN#General_bitsets">this list on the wiki</a>
				(which might possibly be more up-to-date).
				<ul>
					<li>0 - Pause in battle on spell and item menus</li>
					<li>1 - Enable Caterpillar party</li>
					<li>2 - <b>Don't</b> restore HP on level-up</li>
					<li>3 - <b>Don't</b> restore MP on level-up</li>
					<li>4 - Inns <b>don't</b> revive dead heros</li>
					<li>5 - Hero swapping always available</li>
					<li>6 - <b>Hide</b> ready meter in battle</li>
					<li>7 - <b>Hide</b> health bar in battle</li>
					<li>8 - <b>Disable</b> debugging keys</li>
					<li>9 - Simulate old level-up bug</li>
					<li>10 - Permit double-triggering of scripts</li>
					<li>11 - Skip title screen</li>
					<li>12 - Skip load screen</li>
					<li>13 - Pause in battle on all menus</li>
					<li>14 - Disable Hero's Battle Cursor</li>
					<li>15 - Default passability disabled by default</li>
					<li>16 - Simulate pushable NPC collision bug</li>
					<li>17 - <b>Disable</b> ESC to run from battle</li>
					<li>18 - <b>Don't</b> save gameover/loadgame script IDs</li>
					<li>19 - Dead heroes gain share of experience</li>
					<li>20 - Locked heros can't be rearranged</li>
					<li>21 - Attack captions pause battle meters</li>
					<li>22 - <b>Don't</b> randomize battle ready-meters</li>
					<li>23 - Battle menus wait for attack animations</li>
					<li>24 - <b>Enable</b> better scancodes for scripts</li>
					<li>25 - Simulate old fail vs. elemental resist bit</li>
					<li>26 - 0 damage when immune to attack elements</li>
					<li>27 - <b>Do</b> recreate map slices when changing maps</li>
					<li>28 - Harm tiles <b>do</b> harm non-caterpillar heroes</li>
					<li>29 - Attacks ignore extra hits by default</li>
					<li>30 - <b>Don't</b> divide experience between heroes</li>
					<li>31 - Don't reset max stats after OOB attack</li>
					<li>32 - <b>Don't</b> limit max tags to 999</li>
					<li>33 - Simulate Bug #430 script wait skips</li>
					<li>34 - showtextbox happens immediately</li>
					<li>35 - Pause battle while targeting attacks</li>
					<li>36 - Old attack positioning at bottom-left of target</li>
					<li>37 - Wrap map layers over edge of Crop maps</li>
					<li>38 - Never show script timer during battles</li>
					<li>39 - Draw Backdrop slice above Script layer</li>
					<li>40 - <b>Don't</b> stop music when starting/loading game</li>
					<li>41 - Keep caterpillar length the same when speed changes</li>
					<li>42 - Heroes use Walk in Place animation while idle</li>
					<li>43 - Cap minimum stats at zero</li>
					<li>44 - Hide empty save slots at the bottom of the save/load menu</li>
					<li>45 - Attack IDs in scripts are offset by +1</li>
					<li>46 - Negative damage harmtiles <b>don't</b> cure above max HP</li>
					<li>47 - <b>Don't</b> map joystick controls to keyboard keys for scripts</li>
					<li>48 - <b>Disable</b> ESC to cancel/change a hero's attack (turn-based battles only)</li>
					<li>49 - Show hero MP meter</li>
					<li>50 - Non-turn attack delays <b>don't</b> also cause turn delays</li>
				</ul>
				<warn>
					Some bits have names which are opposite above/on the wiki and in the editor!
					If that's the case, you need to set the bit off instead of on and vice versa.
					They might also have slightly different names.
					For example to check whether "Randomize initial ready meters" is <b>on</b>,
					use <tt>read preference bit(22) == off</tt>,
					because bit 22 is documented as "<b>Don't</b> randomize battle ready-meters".
					In the above list, any bit will an inverted name is (hopefully) shown with part of
					the description in <b>bold</b>.
				</warn>
			</description>
			<seealso>
				<ref>writepreferencebit</ref>
			</seealso>
		</command>
		<command id="writepreferencebit">
			<canon>write preference bit (bitnum, value)</canon>
			<shortname>write preference bit</shortname>
			<description>
				Sets the <p>value</p> (true or false) of one of the bits in the Preference Bitsets,
				Active-time Battle Bitsets or Backwards-compatibility Bitsets
				menus (in the General Game Settings menu).
				You can use this command if there isn't a dedicated command to write the bit,
				such as <ref>setbattlewaitmode</ref>.
				Get the value of <p>bitnum</p> from the list at <ref>readpreferencebit</ref> or
				by checking <a href="https://rpg.hamsterrepublic.com/ohrrpgce/GEN#General_bitsets">this list on the wiki</a>
				(which might possibly be more up-to-date).
				<warn>
					Some bits are shown with the opposite names here/the wiki and in the editor!
					If that's the case, you need to set the bit off instead of on and vice versa.
					They might also have slightly different names.
					For example to turn <b>on</b> "Randomize initial ready meters", use
					<tt>write preference bit(22, off)</tt>,
					because bit 22 is documented as "Don't randomize battle ready-meters".
				</warn>
				<danger>
					Use common sense. Some bits, such as "Limit maximum tags to 999" might be disastrous
					to change in the middle of a game!
					Or they might have no effect.
				</danger>
			</description>
			<seealso>
				<ref>readpreferencebit</ref>
			</seealso>
		</command>

		<section title="Battle System Settings">
		<description>
			These commands access data either in the Battle Settings submenu in General Game Settings menu,
			or in the Preference Bitsets submenu.
		</description>

		<command id="setbattlewaitmode">
			<canon>set battle wait mode (state)</canon>
			<shortname>set battle wait mode</shortname>
			<description>
				Set whether or not battles pause on spell and item menus.
				If the argument is <ref>off</ref> then enemies continue to attack while menus are up,
				if the argument is <ref>on</ref> then enemies wait while menus are up.
			</description>
		</command>
		<command id="getactivebattlepauseonallmenus">
			<canon>get active battle pause on all menus</canon>
			<shortname>get active battle pause on all menus</shortname>
			<description>
				Returns true if active-time battles are configured to pause on all menus.
			</description>
			<seealso><ref>setactivebattlepauseonallmenus</ref></seealso>
		</command>
		<command id="setactivebattlepauseonallmenus">
			<canon>set active battle pause on all menus (value)</canon>
			<shortname>set active battle pause on all menus</shortname>
			<description>
				Changes whether active-time battles will pause on all menus.
				The argument should be <p>true</p> to pause, or <p>false</p> 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.
			</description>
			<seealso><ref>getactivebattlepauseonallmenus</ref></seealso>
		</command>
		<command id="setturnbasedbattlemode">
			<canon>set turn based battle mode</canon>
			<shortname>set turn based battle mode</shortname>
			<description>
				Changes the battle mode to turn based.
				This option is not stored in save-games,
				so changing it only lasts until the game is quit and reloaded.
			</description>
			<seealso>
				<ref>getturnbasedbattlemode</ref>
				<ref>setactivetimebattlemode</ref>
				<ref>getactivetimebattlemode</ref>
			</seealso>
		</command>
		<command id="getturnbasedbattlemode">
			<canon>get turn based battle mode</canon>
			<shortname>get turn based battle mode</shortname>
			<description>
				Return true if the battle mode is currently turn based.
			</description>
			<seealso>
				<ref>setturnbasedbattlemode</ref>
				<ref>setactivetimebattlemode</ref>
				<ref>getactivetimebattlemode</ref>
			</seealso>
		</command>
		<command id="setactivetimebattlemode">
			<canon>set active time battle mode</canon>
			<shortname>set active time battle mode</shortname>
			<description>
				Changes the battle mode to active time.
				This option is not stored in save-games,
				so changing it only lasts until the game is quit and reloaded.
			</description>
			<seealso>
				<ref>setturnbasedbattlemode</ref>
				<ref>getturnbasedbattlemode</ref>
				<ref>getactivetimebattlemode</ref>
			</seealso>
		</command>
		<command id="getactivetimebattlemode">
			<canon>get active time battle mode</canon>
			<shortname>get active time battle mode</shortname>
			<description>
				Return true if the battle mode is currently active time.
			</description>
			<seealso>
				<ref>setturnbasedbattlemode</ref>
				<ref>getturnbasedbattlemode</ref>
				<ref>setactivetimebattlemode</ref>
			</seealso>
		</command>
		<command id="showbattlereadymeter">
			<canon>show battle ready meter (state)</canon>
			<shortname>show battle ready meter</shortname>
			<description>
				Sets whether or not the ready meter appears in battle, or will be hidden.
				<p>state</p> should be <tt>true</tt> or <tt>false</tt>.
			</description>
		</command>
		<command id="showbattlehealthmeter">
			<canon>show battle health meter (state)</canon>
			<shortname>show battle health meter</shortname>
			<description>
				Sets whether or not the health meter appears in battle, or will be hidden.
				<p>state</p> should be <tt>true</tt> or <tt>false</tt>.
			</description>
		</command>
		<command id="setdeadheroesgainexperience">
			<canon>set dead heroes gain experience (state)</canon>
			<shortname>set dead heroes gain experience</shortname>
			<description>
				Sets whether or not dead heroes gain experience from battles.
				If the argument is <ref>false</ref> then only living heroes gain experience.
				If the argument is <ref>true</ref> then dead heroes get it too.
			</description>
		</command>
		</section>		<!-- Battle settings -->

		<section title="Caps">
		<command id="getdamagecap">
			<canon>get damage cap</canon>
			<shortname>get damage cap</shortname>
			<description>Returns the current damage cap, or 0 if there is none.</description>
		</command>
		<command id="setdamagecap">
			<canon>set damage cap (cap)</canon>
			<shortname>set damage cap</shortname>
			<description>Sets the current damage cap to <p>cap</p>. Use 0 for no cap.</description>
		</command>
		<command id="getlevelcap">
			<canon>get level cap</canon>
			<shortname>get level cap</shortname>
			<description>Returns the current level cap.</description>
		</command>
		<command id="setlevelcap">
			<canon>set level cap (cap)</canon>
			<shortname>set level cap</shortname>
			<description>
				Sets the level cap.
				<p>cap</p> 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, <ref>giveexperience</ref>, or <ref>setexperience</ref>,
				and the status screen doesn't show their experience to next level.
				You however can use <ref>setherolevel</ref> 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.
			</description>
		</command>
		</section>		<!-- Caps-->
	</section>

	<section title="Saved Games">
		<reference ref="loadmenu" />
		<command id="autosave">
			<canon>autosave</canon>
			<shortname>autosave</shortname>
			<description>
				Transparently saves the game to the last save slot saved to or loaded from
				(see <ref>lastsaveslot</ref>),
				or if playing a new game which has not been saved yet, calls <ref>savemenu</ref>.
				Returns the number of the save slot saved to, or if the user cancelled the save menu,
				returns false.
			</description>
			<seealso>
				<ref>lastsaveslot</ref>
			</seealso>
		</command>
		<command id="saveinslot">
			<canon>save in slot (slot)</canon>
			<shortname>save in slot</shortname>
			<description>Saves in the specified save slot (1 to 1000, regardless of how many are visible on the save and load menus). If a saved game already exists in the slot, it will be overwritten. If you want to make sure that no save game will be overwritten, use <ref>saveslotused</ref>. To display the save game menu instead, use <ref>savemenu</ref>.</description>
		</command>
		<command id="loadfromslot">
			<canon>load from slot (slot, args...)</canon>
			<shortname>load from slot</shortname>
			<description>
				Loads a saved game from a save <p>slot</p> as if it had been loaded from the load game menu.
				<p>slot</p> is a slot number from 1 to 1000, (regardless of how many are displayed on the Load and Save menus).
				This command will end the current game (and fade out and in again) if it successfully loads.
				If the load fails because the slot has never been saved in, the script will continue.
				Anything that you want to happen after loading a saved game needs to be put in the 'load game' script instead (specified in Special Plotscripts).
				You can pass any number of additional optional <p>args</p> to the loadgame script.
				(<p>slot</p> is also always passed as the first argument to the loadgame script,
				so <p>args</p> are the 2nd and later arguments.)
				<danger>
					The default arguments of a loadgame script (and all other triggered scripts)
					are currently ignored.
					If you don't pass enough <p>args</p>, then the remaining arguments default to zero,
					so don't use defaults other than zero!
				</danger>
			</description>
			<example># 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</example>
			<seealso>
				<ref>loadmenu</ref>
				<ref>saveinslot</ref>
				<ref>saveslotused</ref>
				<ref>lastsaveslot</ref>
				<ref>resetgame</ref>
			</seealso>
		</command>
		<command id="deletesave">
			<canon>delete save (slot)</canon>
			<shortname>delete save</shortname>
			<description>
				Deletes a saved game in the specified save <p>slot</p> (1 to 1000,
				regardless of how many are displayed on the Load and Save menus).
				The save will no longer be visible on the load game menu or loadable with <ref>loadfromslot</ref>.
			</description>
			<seealso>
				<ref>saveinslot</ref>
			</seealso>
		</command>
		<command id="lastsaveslot">
			<canon>last save slot</canon>
			<shortname>last save slot</shortname>
			<description>
				Returns the last save slot either loaded or saved to (whichever happened last)
				or <ref>false</ref> if this is an unsaved new game.
				Save slots are numbered starting at 1.
				<lb/>
				<ref>savemenu</ref><tt>(false)</tt> and <ref>loadmenu</ref><tt>(false)</tt>
				(which show the menus but don't actually save or load) don't change the last save slot.
				<lb/>
				<tt>last save slot</tt> returns the last save slot used, even if the save
				in it has since been deleted (e.g. with <ref>deletesave</ref>).
				<warn>
					In versions before Callipygous, <ref>saveinslot</ref> didn't change
					the value returned by <tt>last save slot</tt>, but
					<ref>savemenu</ref><tt>(false)</tt> and <ref>loadmenu</ref><tt>(false)</tt>
					did.
				</warn>
			</description>
			<seealso>
				<ref>autosave</ref>
				<ref>saveinslot</ref>
			</seealso>
		</command>
		<command id="setlastsaveslot">
			<canon>set last save slot (slot)</canon>
			<shortname>set last save slot</shortname>
			<description>
				Sets the value returned by <ref>lastsaveslot</ref>.
				This changes the slot used by <ref>autosave</ref>.
				<p>slot</p> can be any slot from 1 to 1000, or 0 for none, even if the
				number of save slots visible to the player in the load/save menu is less.
			</description>
		</command>
		<command id="saveslotused">
			<canon>save slot used (slot)</canon>
			<shortname>save slot used</shortname>
			<description>
				Returns whether a game has been saved in the save slot.
				For example, you can use this if you don't want to overwrite a saved game with <ref>saveinslot</ref>.
				This returns <tt>false</tt> if the slot has never been saved to normally,
				but has been written to using <ref>exportglobals</ref>
				(which will create a nearly-empty .rsav file containing just globals,
				if it doesn't already exist).
			</description>
		</command>
		<reference ref="sendemail" />
		<reference ref="getloadscript" />
		<reference ref="setloadscript" />
		<command id="importglobals">
			<canon>import globals (slot, first, last)</canon>
			<canon>import globals (slot, id)</canon>
			<canon>import globals (slot)</canon>
			<shortname>import globals</shortname>
			<description>
				Loads a range of globals from a saved game, overwriting the current globals in that range.
				<p>slot</p> is the save slot number, from 1 to 1000.
				Note that only slots 1-4 appear by default on the save/load menus.
				<p>first</p> and <p>last</p> are the id numbers of the globals at
				the beginning and end of the range (inclusive).
				If you leave out both of <p>first</p> and <p>last</p> all global variables will be imported.
				<lb/>
				To read a single global from a save slot without modifying any of your globals,
				use the form <tt>var := import globals (slot, id)</tt>.
				This is NOT the same thing as <tt>import globals (slot, id, id)</tt>,
				which does modify the global variable.
				<lb/>
				<tt>import globals</tt> and <ref>exportglobals</ref> can be used to save and
				retrieve info about a saved game without loading it,
				and also to store variables that any game the player starts can use,
				such as high scores and other "global" data, like in the following example:
				<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</example>
				<note>
					You can import globals from an empty save slot; it's not an error to do so.
					This reads the value of all of the globals as zero.
					You can also export/import globals to/from an empty save slot
					that doesn't have a full saved game in it; see <ref>exportglobals</ref>.
				</note>
			</description>

			<seealso>
				<ref>exportglobals</ref>
				<ref>readglobal</ref>
			</seealso>
		</command>
		<command id="exportglobals">
			<canon>export globals (slot, first, last)</canon>
			<shortname>export globals</shortname>
			<description>
				Writes a range of globals to a save game slot, overwriting the saved game's globals.
				<p>slot</p> is the save slot number, from 1 to 1000,
				regardless of how many save slots enabled in the save/load menus.
				<p>first</p> and <p>last</p> are the id numbers of the globals at the
				beginning and end of the range.
				<p>first</p> defaults to 0, and <p>last</p> defaults to 50000.
				Therefore, if you pass no range, all the globals will be written.
				<note>
					You can export globals to an empty slot!
					This doesn't create a visible save game that the player can load
					(and <ref>saveslotused</ref> will still return <tt>false</tt> for that slot),
					however you will be able to read them with <ref>importglobals</ref>.
					You can delete these globals using <ref>deletesave</ref>.
				</note>
				<danger>
					Unlike importglobals, <tt>export globals (slot, first)</tt> does
					NOT export a single global variable!
				</danger>
			</description>
			<seealso>
				<ref>importglobals</ref>
				<ref>writeglobal</ref>
			</seealso>
		</command>
	</section>		<!--Saved games-->

	<section title="Advanced Functions">
		<command id="runscriptbyid">
			<canon>run script by ID (id, argument1, argument2, argument3...)</canon>
			<shortname>run script by ID</shortname>
			<description>
				The <p>run script by id</p> command allows you to run a script using its <ref>scriptid</ref>.
				You can get the ID of a script by writing <p>@</p> (the 'reference' operator)
				in front of its name, see the example.
				You can not run a built-in command like <ref>wait</ref>; they aren't scripts.
				Arguments after the ID will be passed to the script.
				The return value of this command is whatever value the script returns.
				A run-time error is displayed and -1 is returned if the script does not exist.
				You can pass up to 31 arguments to the script.
				<lb/>
				The advantage of this command as opposed to just calling the script
				directly is that the ID may be stored in a variable,
				or it could be the function return value of another script.
				For example, using <ref>setsliceextra</ref> you might want to store the ID
				of a script that should be run when the player clicks on a slice.
				<danger>
					If you pass too few arguments, the unspecified ones will have value zero
					<b>regardless</b> of any default values given in the script declaration.
					This bug will be fixed in some future version.
					<lb/>
					If you pass too many (which does not cause an error),
					the extra ones are ignored.
				</danger>
			</description>
			<example>plotscript,scriptcallingtest,begin
  show value (run script by id (@sum, 1, 2, 3))
end

script,sum,a,b,c,begin
  return(a+b+c)
end</example>
			<seealso>
				<ref>getscriptname</ref>
				<ref>getcallingscriptid</ref>
			</seealso>
		</command>
		<command id="rungame">
			<canon>run game(file string id)</canon>
			<shortname>run game</shortname>
			<description>
				Quit the current game and switch to a different .rpg file/.rpgdir.
				When that game is quit, the program either exits or goes to the game browser as usual.
				So if you want to return to the original game you need to call <tt>run game</tt> a
				second time from that game instead of using <ref>gameover</ref>.)
				<p>file string id</p> is the ID of a string that contains the filename of the game to load.
				If the game is not in the same directory, then you need to provide a relative
				path, like "bonus content\Prequel.rpg" or "../selectmenu.rpg".
				The path is case-insensitive and <p>/</p> and <p>\</p> are interchangeable.
			</description>
			<example># load another game in the same directory
$0 = "part2.rpg"
run game(0)</example>
		</command>
		<command id="checkgameexists">
			<canon>check game exists (file string id)</canon>
			<shortname>check game exists</shortname>
			<description>
				Check whether an .rpg file/.rpgdir directory exists, returning true or false.
				This is useful before calling <ref>rungame</ref>, which will show an error if the game doesn't exist.
				<!--If you give it a file with an .rpg extension it will also check for an .rpgdir if the .rpg
				doesn't exist, and vice-vesa, just like <ref>rungame</ref> does;
				see that command for more information about the filename.-->
				See <ref>rungame</ref> for more information about the filename.
			</description>
			<seealso>
				<ref>rungame</ref>
			</seealso>
		</command>
		<command id="milliseconds">
			<canon>milliseconds</canon>
			<shortname>milliseconds</shortname>
			<description>Use to measure time intervals accurately. Subtract two values returned by milliseconds at different times to find the number of ms (1000ths of a second) elapsed in between. A single value is useless (the computer's up-time or any random value).</description>
			<seealso>
				<ref>microseconds</ref>
			</seealso>
		</command>
		<command id="microseconds">
			<canon>microseconds</canon>
			<shortname>microseconds</shortname>
			<description>An alternative to <ref>milliseconds</ref> which measures millionths of a second. This command only exists for accurate benchmarking.</description>
		</command>
		<command id="savescreenshot">
			<canon>save screenshot</canon>
			<shortname>save screenshot</shortname>
			<description>
				Saves a screenshot, as if the player pressed F12.
				A popup will appear telling the filename of the screenshot.
				<warn>
					The screenshot might be taken either of the previous frame or the next one.
					To be safe, if you're displaying something and then taking a screenshot of
					it, put a <tt>wait(1)</tt> in between.
				</warn>
			</description>
		</command>

		<command id="pathfindintoextraashero">
			<canon>pathfind into extra as hero (extra, start x, start y, dest x, dest y, maxdepth, append, skip first)</canon>
			<shortname>pathfind into extra as hero</shortname>
			<description>
				Perform pathfinding between 2 points, using the wall+obstruction rules for heroes. Store the results into extra data (for example, on a slice or an npc)
				The x and y values of each step in the path will be put into the extra data with 2 values for each, X,Y,X,Y,X,Y to the end of the path. All values are in tile coordinates. If you need pixel coordinates, multiply by 20.
				The function return value will be true of the destination was reachable, or false if the pathfinding had to give up before reaching the destination. (If it gave up, the extra data will still be filled with the path leading to the closest reachable tile)
				The first argument <p>extra</p> is the slice handle or npc reference to put the extra data into.
				The next 4 arguments are the X,Y of the start position, and the X,Y of the destination. Current hero positions don't matter, but if you wanted to pathfind based on the leader hero's current positions, you could use <tt>hero x(me), hero y(me)</tt> for the start x and y.
				The <p>maxdepth</p> argument is the maximum search depth in tiles to seach before giving up. The default value of 0 means no maximum (search the entire map)
				The <p>append</p> argument can be set to true if you want to append data to the existing extra data. The default value of false means that the existing extra data will be replaced.
				The <p>skip first</p> argument can be set to true if you want to exclude the start position from the path (this can be useful if you are appending multiple paths together, or in other situations where it may be convenient)
			</description>
			<seealso>
				<ref>pathfindintoextraasnpc</ref>
			</seealso>
		</command>
		<command id="pathfindintoextraasnpc">
			<canon>pathfind into extra as npc (extra, npc ref, start x, start y, dest x, dest y, maxdepth, append, skip first)</canon>
			<shortname>pathfind into extra as npc</shortname>
			<description>
				Perform pathfinding between 2 points, using the wall+obstruction rules for a specific NPC. Store the results into extra data (for example, on a slice or an npc)
				The x and y values of each step in the path will be put into the extra data with 2 values for each, X,Y,X,Y,X,Y to the end of the path. All values are in tile coordinates. If you need pixel coordinates, multiply by 20.
				The function return value will be true of the destination was reachable, or false if the pathfinding had to give up before reaching the destination. (If it gave up, the extra data will still be filled with the path leading to the closest reachable tile)
				The first argument <p>extra</p> is the slice handle or npc reference to put the extra data into.
				The second argument <p>npc ref</p> is the NPC reference of the NPC who will be used for pathfinding. You can also use an NPC ID, but this will use the first copy of that NPC on the map, which might matter for the pathfinding, because an NPC can path through itself, but cannot (by default) path through other copies of the same NPC ID.
				The next 4 arguments are the X,Y of the start position, and the X,Y of the destination. Current NPC position does not matter, but if you wanted to pathfind based on the NPCs current position, you could use <tt>npc x(npc ref), npc y(npc ref)</tt> for the start x and y.
				The <p>maxdepth</p> argument is the maximum search depth in tiles to seach before giving up. The default value of 0 means no maximum (search the entire map)
				The <p>append</p> argument can be set to true if you want to append data to the existing extra data. The default value of false means that the existing extra data will be replaced.
				The <p>skip first</p> argument can be set to true if you want to exclude the start position from the path (this can be useful if you are appending multiple paths together, or in other situations where it may be convenient)
			</description>
			<seealso>
				<ref>pathfindintoextraashero</ref>
			</seealso>
		</command>

		<section title="Debugging">
		<command id="trace">
			<canon>trace (string)</canon>
			<shortname>trace</shortname>
			<description>Writes string #<p>string</p> to "g_debug.txt", located in the same directory as the RPG file or game.exe. For debugging you will nearly always use <ref>tracevalue</ref> instead, which is much easier.</description>
			<example>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</example>
		</command>
		<command id="tracevalue">
			<canon>trace value (expression, ...)</canon>
			<canon>trace value of (expression, ...)</canon>
			<shortname>trace value</shortname>
			<description>
				Prints one or more <ref>expression</ref>s 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 <ref>trace</ref> instead.
				<lb/>
				<p>trace value of</p> is an alias to <p>trace value</p>.
			</description>
			<example>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))</example>
			<seealso>
				<ref>assert</ref>
				<ref>dumpslicetree</ref>
			</seealso>
		</command>
		<command id="dumpslicetree">
			<canon>dump slice tree (slice)</canon>
			<shortname>dump slice tree</shortname>
			<description>
				Prints out a brief description of a slice and all its <ref>descendent</ref>s to "g_debug.txt".
				<p>slice</p> is optional; if omitted the whole tree is printed out.
				<lb/>
				This is also available as "List slices to g_debug.txt" in the F8 Debug Menu.
				<note>
					Most of the slice data isn't printed; if you want to inspect it the easiest
					way to do so is either to press <p>Shift+F4</p> to view the slice editor/debugger,
					or to call <ref>scripterror</ref> at the exact moment you want to check the slice tree;
					you can then enter the slice debugger from the Script Error menu.
				</note>
			</description>
			<seealso>
				<ref>tracevalue</ref>
				<ref>scripterror</ref>
			</seealso>
		</command>
		<command id="scripterror">
			<canon>script error (string id)</canon>
			<shortname>script error</shortname>
			<description>Shows an error message, like any other script error. This allows you to open the script debugger. (Use <ref>breakpoint</ref> to skip the menu straight to the debugger.) The optional <p>string id</p> argument gives the error message to display.</description>
			<example>if (x &lt; 0 || x &gt;= map width || y &lt; 0 || y &gt;= map height) then (
  $0="Coordinates went off the edge of the map"
  script error(0)
)</example>
			<seealso>
				<ref>assert</ref>
				<ref>tracevalue</ref>
				<ref>debugmenu</ref>
				<ref>breakpoint</ref>
			</seealso>
		</command>

		<command id="breakpoint">
			<canon>breakpoint</canon>
			<shortname>breakpoint</shortname>
			<description>
				Open the script debugger; this is slightly simpler than using `script error`.
				You can temporarily add this to a script you're trying to debug
				if you want to examine its state at a certain point.
			</description>
			<seealso>
				<ref>scripterror</ref>
				<ref>assert</ref>
				<ref>tracevalue</ref>
			</seealso>
		</command>

		<command id="debugmenu">
			<canon>debug menu</canon>
			<shortname>debug menu</shortname>
			<description>
				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.
			</description>
			<seealso>
				<ref>scripterror</ref>
				<ref>showminimap</ref>
			</seealso>
		</command>
		<command id="assert">
			<canon>assert (expression)</canon>
			<shortname>assert</shortname>
			<description>If <p>expression</p> is false, then writes the script filename, line number and <ref>expression</ref> into the string given by the constant or global variable named <p>assert expression string</p>, and then calls the script named <p>assert failure</p>. You can use this to detect bugs in your scripts, by checking that your assumptions about the state of the game are correct.</description>
			<example># 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
)</example>
			<example># 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
</example>
			<seealso>
				<ref>scripterror</ref>
				<ref>tracevalue</ref>
			</seealso>
		</command>

		<command id="getslicelookupname">
			<canon>get slice lookup name (string id, code, use default name)</canon>
			<shortname>get slice lookup name</shortname>
			<description>
				Lookup the codename of a slice lookup code ID (either user-defined or builtin).
				<p>string id</p> is the ID of a string to put the name into
				and <p>code</p> is a slice lookup code like <tt>sl:map layer 2</tt>.
				<lb/>
				The <tt>sl:</tt> or <tt>sli:</tt> prefix (for builtin and user codes
				respectively) isn't prefixed to the codename.
				For example, might set the string to "map layer2".
				<p>use default name</p> is optional, defaulting to <tt>true</tt>.
				When true, if there is no codename with that code, the produced codename
				is e.g. "Lookup40"; when false, the string is set to "".
				But if <tt>code == 0</tt> then the string is always set to "".
			</description>
		</command>

		<command id="getscriptname">
			<canon>get script name (string id, script id)</canon>
			<shortname>get script name</shortname>
			<description>Fetches the name of a script given its <ref>scriptid</ref> 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 <tt>@scriptname</tt>.</description>
		</command>
		<command id="getcallingscriptid">
			<canon>get calling script id (depth)</canon>
			<shortname>get calling script id</shortname>
			<description>
				Returns the ID number of the script which called this one, or some other scriptin the call stack.
				The optional <p>depth</p> argument, which defaults to 1, allows returning the ID of a
				deeper ancestor script instead: 0 is the current script, 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 <tt>@scriptname</tt>.
			</description>
			<seealso>
				<ref>getscriptname</ref>
			</seealso>
		</command>
		<command id="sendemail">
			<canon>send email (save slot, subject string id, message string id)</canon>
			<shortname>send email</shortname>
			<description>
				<warn>
					This command is only implemented on Android!
					Calling it on other platforms does nothing.
				</warn>
				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:
				<lb/>
				The email is sent to the address set in the Distribute Game->Distribution Info menu.
				<lb/>
				<p>subject string id</p> 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".
				<lb/>
				<p>message string id</p> 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)".
				<lb/>
				The <p>save slot</p> argument is optional, and is either an existing save slot number,
				or <p>false</p> (the default) to not attach a save.
				You can use <ref>saveinslot</ref> 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 <ref>trace</ref> and <ref>tracevalue</ref>.
				You can also check it for error messages, such as script errors (errors will start with
				a <p>!</p> at the beginning of the line).
				g_debug_archive.txt contains backups of g_debug.txt from previous times the game was played.
				<lb/>
				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.
			</description>
		</command>
		</section>		<!-- Debugging-->
	</section>		<!-- Advanced Functions-->

	<section title="Platform Specific">
		<command id="windowisfocused">
			<canon>window is focused</canon>
			<shortname>window is focused</shortname>
			<description>
				Returns true if the game's window is the currently active (focused) one (or if it's fullscreen and active), or false if the user has switched to a different program.
				This is always true when running on a smartphone, because when the app is backgrounded the game is
				paused and scripts don't run.
				<lb/>
				Use this command if you want to pause something when the player switches to another program.
			</description>
		</command>
		<command id="runningondesktop">
			<canon>running on desktop</canon>
			<shortname>running on desktop</shortname>
			<description>This command returns true if the game is currently running on any Windows/Mac/Linux desktop computer. You should avoid using this command unless you really need it. Most games will never need this command.</description>
		</command>
		<command id="runningonwindows">
			<canon>running on Windows</canon>
			<shortname>running on Windows</shortname>
			<description>This command returns true if the game is currently running on a Windows computer. You should avoid using this command unless you really need it. Most games will never need this command.</description>
		</command>
		<command id="runningonmac">
			<canon>running on Mac</canon>
			<shortname>running on Mac</shortname>
			<description>This command returns true if the game is currently running on a Macintosh computer. You should avoid using this command unless you really need it. Most games will never need this command.</description>
		</command>
		<command id="runningonlinux">
			<canon>running on Linux</canon>
			<shortname>running on Linux</shortname>
			<description>This command returns true if the game is currently running on a GNU/Linux desktop computer (not including Android or other non-PC Linux-based OS). You should avoid using this command unless you really need it. Most games will never need this command.</description>
		</command>
		<command id="runningonmobile">
			<canon>running on mobile</canon>
			<shortname>running on mobile</shortname>
			<description>This command returns true if the game is currently running on a mobile device such as an Android phone or tablet. You should avoid using this command unless you really need it. Most games can support mobile devices without ever using this command. See the "Platform-Specific Options" menu under "Edit General Game Data".</description>
		</command>
		<command id="runningonconsole">
			<canon>running on console</canon>
			<shortname>running on console</shortname>
			<description>This command returns true if the game is currently running on an console. Currently supported consoles include OUYA, MOJO, GameStick, and FireTV. You should avoid using this command unless you really need it. Most games can support the consoles without ever using this command. See the "Platform-Specific Options" menu under "Edit General Game Data".</description>
		</command>
		<command id="runningonweb">
			<canon>running on web</canon>
			<shortname>running on web</shortname>
			<description>This command returns true if the game is currently running on a web browser. You should avoid using this command unless you really need it. Most games can support web without ever using this command.</description>
		</command>
		<command id="runningonouya">
			<canon>running on ouya</canon>
			<shortname>running on ouya</shortname>
			<description>This command returns true if the game is currently running on an OUYA console. Ouya is an obsolete console that is no longer generally available. You should avoid using this command unless you really need it. Most games can support the OUYA console without ever using this command, and even if you do need to do special scripting just for ouya, you should consider using <ref>runningonconsole</ref> instead, since the only thing different about OUYA is its button names and in-app-purchase support. See the "Platform-Specific Options" menu under "Edit General Game Data".</description>
		</command>
		<command id="hidevirtualgamepad">
			<canon>hide virtual gamepad</canon>
			<shortname>hide virtual gamepad</shortname>
			<description>If the game is running on a platform that supports a touchscreen virtual gamepad (such as Android) this command forces the virtual gamepad to become hidden, even if it would normally be visible. On other platforms, this command does nothing. The effects of this command can be cancelled by using the <ref>autovirtualgamepad</ref> command.</description>
		</command>
		<command id="showvirtualgamepad">
			<canon>show virtual gamepad</canon>
			<shortname>show virtual gamepad</shortname>
			<description>If the game is running on a platform that supports a touchscreen virtual gamepad (such as Android) this command forces the virtual gamepad to become visible, even if it would normally be hidden. On other platforms, this command does nothing. The effects of this command can be cancelled by using the <ref>autovirtualgamepad</ref> command.</description>
		</command>
		<command id="autovirtualgamepad">
			<canon>auto virtual gamepad</canon>
			<shortname>auto virtual gamepad</shortname>
			<description>If the game is running on a platform that supports a touchscreen virtual gamepad (such as Android) this command cancels a previous <ref>showvirtualgamepad</ref> or <ref>hidevirtualgamepad</ref> command. The virtual gamepad will once again automatically show or hide itself automatically based on various factors such as textboxes, menus, battles, or <ref>suspendplayer</ref>. On other platforms, this command does nothing.</description>
		</command>
	</section>

	<section title="Types and Handles" topics="yes">
		<description>
			This section documents many of the different types of values that are used by various script
			commands, such as NPC references.
			Note that in HamsterSpeak everything is a number, so there are no types
			as in other programming languages; instead identifiers are used for everything.
			Values of different ID numbers and handles overlap: there's no way to tell if
			a number refers to an NPC or a slice or a map.
			<ul>
				<li>
					An <p>ID number</p> normally refers to something which is defined
					in an editor, such as an NPC definition or map ID number,
					or something which is fixed supply, like global and string ID numbers.
					ID numbers always count upwards from 0 or sometimes 1.
					Many IDs have constants automatically defined, for example if there's
					a map named Overworld, there's a constant named <p>map:Overworld</p> with its ID number.
				</li>
				<li>
					A <p>handle</p> or a <p>reference</p> is an identifier for something that can
					be created during play, like slice handles, menu handles and NPC references.
					It can change from game to game, and it becomes invalid if the thing
					it refers to is deleted.
					After becoming invalid, the value can generally even be reassigned to a new thing of that type,
					so be careful about handles you've stored in variables when deleting things!
				</li>
				<li>
					A <p>constant</p> (or "enum") is a fixed value, used for things that
					don't change, like different available NPC movement types, or map numbers.
					Many constants in HamsterSpeak start with a prefix like <p>key:</p>.
					There's nothing special about these prefixes or names, and <p>:</p> is treated
					like any letter which you can use freely.
				</li>
			</ul>
		</description>

		<command id="npcid">
			<canon>NPC IDs</canon>
			<shortname>NPC ID</shortname>
			<description>
				An NPC ID refers to an NPC type (aka NPC definition), as defined in the Edit
				Local/Global NPCs menus.
				Local and global <ref>npcpool</ref>s both have ID numbers that count from 0 upwards,
				so the ID doesn't tell you whether it's a local or global NPC.
				Some commands such as <ref>npccopycount</ref> take both an NPC ID and an NPC pool
				as separate arguments.
				But most NPC commands, such as <ref>walknpc</ref>, don't take a pool argument.
				If you pass an ID to these, then it's interpreted as an ID in the local NPC pool.
				<lb/>
				A copy of an NPC is referred to using an <ref>npcref</ref>.
			</description>
		</command>

		<command id="npcpool">
			<canon>NPC pool numbers</canon>
			<shortname>NPC pool</shortname>
			<description>
				An NPC pool number tells whether an NPC ID refers to an NPC in the local
				or global NPC pools. (In future there may be more than two pools.)
				It can be either <p>pool:local</p> (which is <p>0</p>; NPCs specific to one map) or <p>pool:global</p>
				(which is <p>1</p>).
				Most commands that accept NPC IDs don't have an argument to tell the pool number.
				These always default to the local pool, and you need to first use the
				<ref>npcreference</ref> or <ref>globalnpcreference</ref> functions to get an
				<ref>npcref</ref> to pass to these commands if you want to refer to a global NPC by ID.
			</description>
		</command>

		<command id="npcref">
			<canon>NPC references</canon>
			<shortname>NPC reference</shortname>
			<description>
				What is an NPC reference?
				A reference is a number that uniquely identifies an NPC instance on the map.
				You can use an NPC reference to specify which NPC you are controlling in most NPC-related commands.
				<lb/>
				NPC references are handles for NPC instances on the map,
				that is, a copy of an NPC definition.
				NPC references are always negative values, while NPC IDs count from 0 up.
				An <ref>npcid</ref> for a local NPC can always be used with any command that expects
				an NPC reference, in which case it refers to the first
				instance/copy of that NPC ID from the local <ref>npcpool</ref>, not to the NPC definition itself.
				(If you want to refer to a global NPC, you need to first use <ref>globalnpcreference</ref>.)
				So <tt>wait for NPC(5)</tt> is equivalent to <tt>wait for NPC(<ref>npcreference</ref>(5, 0))</tt>.
				<note>
					If you want to loop over all NPC instances (that is, over all NPC references), use
					<ref>nextnpcreference</ref>.
					An NPC reference historically was (and still is for now) a number between -1 and -300,
					but that will change in an upcoming version.
					So it's strongly recommended that you don't loop over values -1 to -300.
				</note>
				<warn>
					If you move to a different map you mustn't use the old references on the new map.
					If you set the map to save NPC data when leaving, the previous references will be valid when you get back to it.
				</warn>
			</description>
		</command>

		<command id="slicehandle">
			<canon>Slice handles</canon>
			<shortname>slice handle</shortname>
			<description>
				Slices are referred to with <p>slice handles</p>. A slice handle is just a value that you can store in a <p>variable</p>,
				just like an <ref>npcref</ref> or a <ref>menuhandle</ref>.
				A handle is <p>valid</p> if it currently refers to an existing slice.
				<ref>false</ref> (zero) is never a valid slice handle, so slice commands return 0 to indicate "no slice found" or similar failures.
				<note>
					<ref>lookupcode</ref>s like "sl:map layer 0" or "sli:quit button" are NOT slice handles;
					they can only be used by the <ref>lookupslice</ref> command.
				</note>
			</description>
		</command>
		<command id="blendableslicehandle">
			<canon>Blendable slice handles</canon>
			<shortname>blendable slice handle</shortname>
			<description>
				A <ref>slicehandle</ref> for a slice type which has blending settings (opacity and blend mode),
				which currently are Sprite and Map (map layer) slices.
				More slice types will become blendable in future versions.
				<note>
					Rectangle slices aren't blendable, however the background of a
					rect <b>can</b> be made transparent using <ref>setrectopacity</ref>
					instead of <ref>setopacity</ref>.
					This doesn't make the box border transparent, and <ref>getopacity</ref>
					will still return 100.
				</note>
			</description>
			<seealso>
				<ref>setopacity</ref>
				<ref>setblendmode</ref>
				<ref>setblendingenabled</ref>
			</seealso>
		</command>

		<command id="objecthandle">
			<canon>Object handles</canon>
			<shortname>object handle</shortname>
			<description>
				Object handles are handles to things that have extra data arrays,
				they can be passed to <secref>Extra Data Array Functions</secref>.
				An object handle is either a <ref>slicehandle</ref>, an <ref>npcref</ref> (NOT an NPC ID!),
				a zone handle (returned by <ref>getzone</ref>; NOT a zone ID!),
				or a <ref>menuitemhandle</ref>.
				Menu handles are distinct from all the others but don't (yet) count, because they
				don't have extra data.
				<ref>false</ref> (zero) is never a valid object handle.
			</description>
		</command>

		<command id="lookupcode">
			<canon>Slice lookup codes</canon>
			<shortname>slice lookup code</shortname>
			<description>
				Slice lookup codes are used to search for a particular slice using <ref>lookupslice</ref>.
				There are two types.
				User defined slice lookup codes are
				defined (named) in the slice collection editor.
				You will find them as constants in your .hsi file with sli: prefixes, and they count up from 1.
				You can also use any non-negative value, even if you haven't named it in the editor.
				There are also many special slice lookup codes with names that start with sl: prefixes.
				See <ref>lookupslice</ref> for the list. They are always negative.
			</description>
			<seealso>
				<ref>getslicelookupname</ref>
			</seealso>
		</command>

		<command id="menuhandle">
			<canon>Menu handles</canon>
			<shortname>menu handle</shortname>
			<description>
				A handle for a currently open menu, for example, the one returned by <ref>openmenu</ref> or
				<ref>createmenu</ref> or <ref>topmenu</ref>.
				Menu handle <p>0</p> (<p>false</p>) means none/invalid.
				Not the same thing as a menu ID (which is a menu defined in the menu editor).
				There can be multiple open copies of a single menu ID.
			</description>
		</command>
		<command id="menuitemhandle">
			<canon>Menu item handles</canon>
			<shortname>menu item handle</shortname>
			<description>
				A handle to one of the items in a currently open menu,
				for example, the one returned by <ref>selectedmenuitem</ref>.
				Menu items in different menus are always different, so it's possible to lookup
				which menu its in with <ref>parentmenu</ref>, and menu handles are never reused.
			</description>
		</command>

		<command id="extradataindex">
			<canon>Extra data array index</canon>
			<shortname>extra array index</shortname>
			<description>
				An extra array index is a number telling which element of an NPC's, slice's, etc, extra data array to read/write.
				(An "array" is a list of values.)
				The first element of the array is index 0, the second is index 1, etc, up to <tt>extra length(handle) -- 1</tt>.
				<lb/>
				By default all slices/NPCs/etc start with a length 3 extra data array, so <p>extra</p> is typically a value from 0 to 2.
				You may also use the obsolete constants <p>extra 0</p>, <p>extra 1</p>, <p>extra 2</p>
				which have values 0, 1, 2, if you find them more readable.
				<lb/>
				For convenience, negative indexing like Python is also supported:
				the last element is index -1, the second last is index -2, down to <tt>-1 * extra length(handle)</tt> which is the first element.
				Negative indexing is only supported by commands that explicitly say they accept an array index.
			</description>
		</command>

		<command id="scriptid">
			<canon>Script IDs</canon>
			<shortname>script ID</shortname>
			<description>
				Script IDs are used to refer to scripts, for example for <ref>setdeathscript</ref>.
				Get the ID of a script by writing <p>@name of the script</p>, which is a constant.
				You can call a script using its ID instead of the normal way with <ref>runscriptbyid</ref>.
				You used to have to manually assign IDs to scripts using <tt>define script</tt>,
				but that's now obsolete and IDs are automatically assigned.
				The ID number of a script will remain the same as long as it isn't renamed,
				so they're safe to store in saved games.
				The ID <p>0</p> means no script (e.g. no death script).
			</description>
			<seealso>
				<ref>getscriptname</ref>
			</seealso>
		</command>

		<command id="colorcode">
			<canon>Color codes</canon>
			<shortname>color code</shortname>
			<description>
				A number indicating a color in the master palette.
				A value from 1-255 is specifies the master palette index directly.
				The meaning of 0 depends on the particular script command:
				it might mean either 'transparent' or 'the default color'
				or 'color 0 in the palette'.
				Negative values are <tt>ui:...</tt> constants, for colors defined in
				the User-Interface Colors editor.
				(You can get the master palette index for a <tt>ui:</tt> constant with <ref>getuicolor</ref>.)
			</description>
		</command>
		<command id="scancode">
			<canon>Scancodes</canon>
			<shortname>scancode</shortname>
			<description>
				A scancode is a constant referring to a keyboard key, a joystick button,
				or is a virtual scancode for a control like <ref>usekey</ref> or <ref>anykey</ref>
				(see <ref>controlcodes</ref> for the full list)
				which is an action that can be triggered by various keys or buttons.
				<lb/>
				The scancodes are also listed in the <b>scancode.hsi</b> file included with the engine.
				<example>key:Esc
key:F1
key:F2
key:F3
...
key:F15          # Mac keyboards usually have 15 instead of 12 F# buttons

key:Num Lock     # Tells whether numlock is on, not whether the key is down.
key:Caps Lock    # Tells whether capslock is on, not whether the key is down.
key:Scroll Lock  # Unreliable across different OSes/backends, avoid.

key:Print Screen # Unreliable across different OSes/backends, avoid
key:Pause        # Works for "keypress" and "new keypress" but not "key is pressed"

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      # &quot;
key:Apostrophe       # &apos;
key:Backquote        # `
key:Tilde            # ~
key:Backslash        # \
key:Pipe             # |
key:Comma            # ,
key:Left Caret       # &lt;
key:Period           # .
key:Right Caret      # >
key:Slash            # /
key:Question Mark    # ?
key:Enter
key:Space
key:Tab

key:Home
key:End
key:Page Up
key:Page Down
key:Insert
key:Delete

key:Up
key:Left
key:Right
key:Down

key:Meta           # Either Command/Windows key
key:Win Logo       # Equal to key:Meta
key:Command        # Equal to key:Meta
key:Left Meta      # Left Command/Windows key
key:Right Meta     # Right Command/Windows key
key:Left Win Logo  # equal to key:Left Meta
key:Right Win Logo # equal to key:Right Meta
key:Left Command   # Macintosh, equal to key:Left Meta
key:Right Command  # Macintosh, equal to key:Right Meta
key:Context        # Context Menu key, next to right Windows key on PC keyboards

key:Alt            # either Alt key pressed
key:Left Alt
key:Right Alt
key:Filtered Alt   # either Alt key pressed, unless a key combinations like Alt+Tab is
                   # pressed, however key presses are delayed until key release.
key:Ctrl           # either Ctrl key pressed
key:Left Ctrl
key:Right Ctrl
key:Shift          # either Shift key pressed
key:Left Shift
key:Right Shift
key:Any Enter      # either Enter or Numpad Enter key pressed

key:Numpad 0
key:Numpad 1
key:Numpad 2
key:Numpad 3
key:Numpad 4
key:Numpad 5
key:Numpad 6
key:Numpad 7
key:Numpad 8
key:Numpad 9
key:Numpad Period
key:Numpad Asterisk
key:Numpad Slash
key:Numpad Plus
key:Numpad Minus
key:Numpad Enter

#  Joystick scancodes:
# (The following button names are only correct for supported controllers that are gamepads)

# Dpad, and also translates axis:X/Y (left thumbstick on a gamepad) to button presses
# (unless "Map joystick (left) stick to dpad" is disabled)
joy:Left
joy:Right
joy:Up
joy:Down

joy:A              # B button on a SNES controller!
joy:Cross          # Equal to joy:A
joy:B              # A button on a SNES controller!
joy:Circle         # Equal to joy:B
joy:X              # Y button on a SNES controller!
joy:Square         # Equal to joy:X
joy:Y              # X button on a SNES controller!
joy:Triangle       # Equal to joy:Y

# Translation of right stick (axis:RightX/Y) to button presses
joy:RStick Left
joy:RStick Right
joy:RStick Up
joy:RStick Down

joy:L1             # Left shoulder
joy:R1             # Right shoulder
joy:L2             # Left trigger. Also axis:L2
joy:R2             # Right trigger. Also axis:R2

# The thumbsticks when pressed as a button
joy:Left Stick
joy:Right Stick
# Center-left button: Select (NES, SNES, PS1-3), Back (Xbox), Share (PS4), View (Xbox)
joy:Select
joy:Back           # Equal to joy:Select
# Center button: PS button (PS3), Xbox guide button
joy:Logo
joy:Guide          # Equal to joy:Logo
# Center-right button: Start (NES, SNES, Genesis, N64, Saturn, PS1-3, Xbox), Options (PS4), Menu (XBox)
joy:Start

# Obsolete aliases
joy:x left         # Aka joy:Left
joy:x right        # Aka joy:Right
joy:y up           # Aka joy:Up
joy:y down         # Aka joy:Down

# You can use button numbers instead of the above names:
joy:button 1
joy:button 2
joy:button 3
...
joy:button 16
joy:button 17      # Warning: joy:button17 is not joy:button16 + 1! All other button codes are consecutive
...
joy:button 32

#  Virtual scancodes:
any key            # Any keyboard key except Numlock, Capslock and Scrolllock, or any joystick button
                   # (including joystick left/right/up/down) that has a builtin meaning like 'use'
                   # (e.g. X/Y/L1/L2/R1/R2/Select aren't included),
                   # and also any mouse button if "'any key', etc, include mouse clicks" is turned on in
		   # the Mouse Controls menu.
up key             # Up key on the keyboard, or on any joystick
down key           # ...ditto
left key
right key
use key            # Space, Ctrl or Enter, or A button on any gamepad. Includes left clicks
                   # if "'any key', etc, include mouse" turned on in Mouse Controls menu.
cancel key         # Alt or Esc, or B button on any gamepad. Optionally includes right clicks as above.
menu key           # Alt or Esc, or B or Start button on any gamepad. Optionally includes right clicks as above.
flee key           # Esc or Tab, or B button on any gamepad (Hold to flee (run) from battle)
run key            # Alias for 'flee key'
</example>
				<note>
					Previously it was necessary to <tt>include, scancode.hsi</tt>
					to use the <tt>key:</tt> constants, but no longer.
				</note>
				<note>
					Gamepad constants like <tt>joy:A</tt> only mean what they say if the controller
					is a gamepad and if you're using the default gfx_sdl2 backend. All the other
					backends number gamepad buttons and axes unpredictably.
				</note>
				<note>
					If the "Map joystick controls to keyboard keys for scripts" general preference
					bitset is ON (which it is by default), then checking the
					<tt>key:up</tt>, <tt>key:down</tt>, <tt>key:left</tt>, <tt>key:right</tt>,
					<tt>key:esc</tt>, <tt>key:enter</tt> keys will report <tt>true</tt>
					if the corresponding button on any joystick is pressed.
				</note>
				<note>
					Since Zenzizenzic, keyboard support has been improved: some keys (such as key:down and key:numpad 2)
					which were previously the same scancode are now distinct (read scancode.hsi for the complete list).
					However for backwards compatibility, the old behaviour is emulated
					(so you won't be able to tell the two keys apart even if recompile and use the new, distinct scancodes)
					unless you turn off &quot;Disable better scancodes for scripts&quot;
					in the Backwards-Compatibility settings menu (in the General Game Settings menu).
				</note>
			</description>
			<seealso>
				<ref>extendedscancodesenabled</ref>
			</seealso>
		</command>
		<reference ref="controlcodes" />

		<command id="playernumber">
			<canon>Player number</canon>
			<shortname>player number</shortname>
			<description>
				Commands for reading keyboard or joystick/gamepad input (see below)
				take an optional <p>player</p> argument which you should completely
				ignore unless you're making a multiplayer game.
				These tell which player's joystick/gamepad to check and usually shouldn't be
				used when reading the keyboard.
				Player 0 (which is always the default argument) means check all joysticks
				and the keyboard, as applicable, and combine their input,
				while player 1 and up are specific joysticks: the first joystick is player 1, etc.
				Out of range player numbers are always OK to use,
				and just report no input without showing an error.
				(There's currently no way to get the number of joysticks or players!)
				<lb/>
				The keyboard is also considered to be to player 1,
				so scancodes like <tt>key:ctrl</tt> will always return <tt>false</tt>
				for players 2 and up, but <ref>controlcodes</ref> like <tt>use key</tt>
				can be used with any player.
				<lb/>
				For example,
				<tt>key is pressed(use key)</tt> checks the keyboard (ctrl, space, and enter keys) and
				the A button on any gamepad, while
				<tt>key is pressed(use key, 1)</tt> checks the keyboard and A button
				on the first gamepad,
				and <tt>key is pressed(use key, 2)</tt>
				checks only the A button on the second gamepad.
			</description>
			<seealso>
				<ref>keypress</ref>
				<ref>newkeypress</ref>
				<ref>keyispressed</ref>
				<ref>joystickbutton</ref>
				<ref>joystickaxis</ref>
			</seealso>
		</command>
	</section>

	<section title="Glossary">
		<gloss id="ancestor">
			<canon>ancestor (of a slice)</canon>
			<shortname>ancestor</shortname>
			<description>
				A slice's parent, grandparent, great-grandparent, etc., all the way to the root.
				Use <ref>checkparentage</ref> to see if one slice is an ancestor of another.
			</description>
		</gloss>
		<gloss id="descendent">
			<canon>descendent (of a slice)</canon>
			<shortname>descendent</shortname>
			<description>
				Any child, or grandchild, or great-grandchild, etc. of a slice.
				Use <ref>checkparentage</ref> to see if one slice is a descendent of another.
			</description>
		</gloss>
		<gloss id="slicesubtree">
			<canon>slice subtree</canon>
			<description>
				A slice together with all of its <ref>descendent</ref>s forms a slice subtree.
				The slice is the 'root' of the subtree.
				You can iterate over all the slices in a subtree (or the whole tree) with <ref>nextsliceintree</ref>.
			</description>
		</gloss>
		<gloss id="subtree">
			<alias>slicesubtree</alias>
			<shortname>subtree</shortname>
		</gloss>
		<gloss id="expression">
			<canon>expression</canon>
			<description>
				An expression is any piece of code that can be evaluated to a value, which can be passed to a command
				or stored in a variable.
				Examples include numbers like <tt>3</tt>, variables like <tt>x</tt>,
				formulas like <tt>20 * x</tt>, commands or scripts which return values like <ref>npcdirection</ref>,
				compound expressions like <tt><ref>heropixelx</ref>(who + 1) / 20</tt>
				and the string expressions <ref>__setstring__</ref> and <ref>__appendstring__</ref> (which return <tt>id</tt>).
				Flow control (<ref>if</ref>, <ref>switch</ref>, etc) as well as <ref>variable</ref>
				are <p>statements</p>, not expressions.
				<lb/>
				<ref>setvariable</ref> expressions like <tt>x := 3</tt> can also be used as expressions, but it's often considered poor taste to do so.
			</description>
		</gloss>

	</section>

	<section title="Predefined Constants" constants="yes">
		<description>
			This section only lists constants which can be used for multiple commands.
			There are many other builtin constants, but they're documented along with the commands they're for.
		</description>

		<command id="controlcodes">
			<canon>Control Codes</canon>
			<shortname>control codes</shortname>
			<description>
				A constant specifying a keyboard key or joystick button by its builtin function.
				(Possibly includes mouse buttons too, if enabled in the Mouse Controls menu.)
				They can be passed to <ref>keyispressed</ref>, <ref>keyval</ref>, <ref>waitforkey</ref>,
				<ref>keypress</ref>, <ref>newkeypress</ref> and <ref>waitforscancode</ref>.
				<lb />
				Previously these could only be used with the <ref>waitforkey</ref> command, but that's changed!
				<lb />
				Possible values:
				<lb />
				<p>any key</p>, <p>up key</p>, <p>down key</p>, <p>left key</p>, <p>right key</p>,
				<p>use key</p>, <p>menu key</p>, <p>cancel key</p>, <p>flee key</p>, <p>run key</p>.
				<lb />
				(<p>flee key</p> and <p>run key</p> are different names for the same constant;
				<p>menu key</p> and <p>cancel key</p> used to be the same but are now different:
				the Start button on a gamepad is a menu key.)
				<note>
					All commands which accept a key constant can also accept a scancode (like <tt>key:enter</tt>) instead.
					See <ref>scancode</ref>.
				</note>
			</description>
			<altcommand id="anykey">
				<shortname>any key</shortname>
			</altcommand>
			<altcommand id="upkey">
				<shortname>up key</shortname>
			</altcommand>
			<altcommand id="downkey">
				<shortname>down key</shortname>
			</altcommand>
			<altcommand id="leftkey">
				<shortname>left key</shortname>
			</altcommand>
			<altcommand id="rightkey">
				<shortname>right key</shortname>
			</altcommand>
			<altcommand id="usekey">
				<shortname>use key</shortname>
			</altcommand>
			<altcommand id="menukey">
				<shortname>menu key</shortname>
			</altcommand>
			<altcommand id="cancelkey">
				<shortname>cancel key</shortname>
			</altcommand>
			<altcommand id="runkey">
				<shortname>run key</shortname>
			</altcommand>
			<altcommand id="fleekey">
				<shortname>flee key</shortname>
			</altcommand>
		</command>
		<command id="keyconstants">
			<alias>controlcodes</alias>
			<shortname>Key Constants</shortname>
		</command>

		<command id="numericconstants">
			<canon>Numeric Constants</canon>
			<shortname>Numeric Constants</shortname>
			<description>
				There are pre-defined constants for the numbers from 0 to 10.
				You can use these constants to make your scripts look friendly :)
				<lb />
				<p>zero, one, two, three, four, five, six, seven, eight, nine, ten</p>
			</description>
		</command>
		<command id="booleanconstants">
			<canon>Boolean Constants</canon>
			<shortname>Boolean Constants</shortname>
			<description>
			There are constants are named <p>true</p> and <p>false</p>, and for <p>on</p> and <p>off</p>.
			These are useful for checking and setting the values of tags, and in conditional statements.
			<tt>true</tt>/<tt>on</tt> are equal to 1, <tt>false</tt>/<tt>off</tt> are equal to 0.
			</description>
			<altcommand id="true">
				<shortname>true</shortname>
			</altcommand>
			<altcommand id="false">
				<shortname>false</shortname>
			</altcommand>
			<altcommand id="on">
				<shortname>on</shortname>
			</altcommand>
			<altcommand id="off">
				<shortname>off</shortname>
			</altcommand>
		</command>
		<command id="direction">
			<canon>Directions</canon>
			<shortname>direction</shortname>
			<description>
				A direction is a value 0-3 used by commands such as <ref>walkhero</ref> and
				<ref>walknpc</ref>, which goes clockwise from north:
				<lb/>
				<p>north</p> = <p>up</p> = <p>0</p><lb/>
				<p>east</p> = <p>right</p> = <p>1</p><lb/>
				<p>south</p> = <p>down</p> = <p>2</p><lb/>
				<p>west</p> = <p>left</p> = <p>3</p><lb/>
				You can convert a direction into relative X and Y values using the <ref>dirx</ref> and <ref>diry</ref> functions.
			</description>
			<altcommand id="north">
				<shortname>north</shortname>
			</altcommand>
			<altcommand id="south">
				<shortname>south</shortname>
			</altcommand>
			<altcommand id="east">
				<shortname>east</shortname>
			</altcommand>
			<altcommand id="west">
				<shortname>west</shortname>
			</altcommand>
			<altcommand id="up">
				<shortname>up</shortname>
			</altcommand>
			<altcommand id="down">
				<shortname>down</shortname>
			</altcommand>
			<altcommand id="right">
				<shortname>right</shortname>
			</altcommand>
			<altcommand id="left">
				<shortname>left</shortname>
			</altcommand>
		</command>
		<command id="me">
			<canon>me</canon>
			<shortname>me</shortname>
			<description>
                        	<tt>me</tt> is a constant that can be used to refer to the first hero in your caterpillar party
                                (hero zero) in any command that takes a caterpillar party rank as an argument.
                                It is equal to zero.
                                You can't write <tt>me</tt> where a hero party slot or hero ID is needed!
                                See <a href="https://rpg.hamsterrepublic.com/ohrrpgce/Ways_to_refer_to_a_hero_in_a_script">
				Ways to refer to a hero in a script</a>.
                        </description>
		</command>
		<command id="none">
			<canon>none</canon>
			<shortname>none</shortname>
			<description><tt>none</tt> is a constant that means the same as zero.</description>
		</command>
		<command id="autonumber">
			<canon>autonumber</canon>
			<shortname>autonumber</shortname>
			<deprecated>ubersetzung</deprecated>
			<description><tt>autonumber</tt> is an obsolete constant that is used as the ID number in old-style <b>define script</b> commands. This is not needed anymore. Use <ref>script</ref> instead.</description>
		</command>
		<command id="currentstat">
			<canon>current stat</canon>
			<shortname>current stat</shortname>
			<description>A constant for use with the <ref>getherostat</ref>, <ref>setherostat</ref>, <ref>setcappedherostat</ref> and <ref>getlevelmp</ref> commands.
<lb/>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 <ref>setherostat</ref>. Both maximum and current values of a stat are normally limited to the stat cap.</description>
		</command>
		<command id="maximumstat">
			<canon>maximum stat</canon>
			<shortname>maximum stat</shortname>
			<description>A constant for use with the <ref>getherostat</ref>, <ref>setherostat</ref>, <ref>setcappedherostat</ref> and <ref>getlevelmp</ref> commands.
<lb/>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 <ref>currentstat</ref> for more information. Both maximum and current values of a stat are normally limited to the stat cap.</description>
		</command>
		<command id="basestat">
			<canon>base stat</canon>
			<shortname>base stat</shortname>
			<description>A constant for use with the <ref>getherostat</ref>, <ref>setherostat</ref> and <ref>setcappedherostat</ref> commands.
<lb/>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.</description>
		</command>
		<command id="insidebattle">
			<canon>inside battle</canon>
			<shortname>inside battle</shortname>
			<altcommand id="outsidebattle" alias="hide">
				<canon>outside battle</canon>
				<shortname>outside battle</shortname>
			</altcommand>
			<altcommand id="heroportrait" alias="hide">
				<canon>hero portrait</canon>
				<shortname>hero portrait</shortname>
			</altcommand>
			<description>
				A constant used in the <ref>getheropicture</ref>, <ref>setheropicture</ref>,
				<ref>getheropalette</ref>, <ref>setheropalette</ref>, <ref>resetheropicture</ref>
				and <ref>resetheropalette</ref> commands:
				<ul>
					<li><p>inside battle</p> indicates the hero battle spriteset.</li>
					<li><p>outside battle</p> indicates the walkabout spriteset.</li>
					<li><p>hero portrait</p> indicates the portrait spriteset.</li>
				</ul>
			</description>
		</command>
		<command id="colorconstants">
			<canon>Color Constants</canon>
			<shortname>Color Constants</shortname>
			<description>
				Constants for each of the three primary colors are used in commands like
				<ref>readcolor</ref> or <ref>writecolor</ref>:
				<lb/>
				<p>color:red, color:green, color:blue</p>
			</description>
			<altcommand id="colorred">
				<shortname>color:red</shortname>
			</altcommand>
			<altcommand id="colorgreen">
				<shortname>color:green</shortname>
			</altcommand>
			<altcommand id="colorblue">
				<shortname>color:blue</shortname>
			</altcommand>
		</command>
		<command id="mouseconstants">
			<canon>Mouse Constants</canon>
			<shortname>Mouse Constants</shortname>
			<description>
				The following constants are for use with the mouse functions such as <ref>mousebutton</ref>.
				<lb/>
				<p>left button</p>, <p>middle button</p>, <p>right button</p>
			</description>
			<altcommand id="leftbutton">
				<shortname>left button</shortname>
			</altcommand>
			<altcommand id="middlebutton">
				<shortname>middle button</shortname>
			</altcommand>
			<altcommand id="rightbutton">
				<shortname>right button</shortname>
			</altcommand>
		</command>
		<command id="getcount">
			<canon>get count</canon>
			<shortname>get count</shortname>
			<description>When passed to <ref>npcatpixel</ref>, <ref>npcatspot</ref>, <ref>sliceatpixel</ref>, <ref>findcollidingslice</ref> or <ref>zoneatspot</ref> they return the number of NPCs, slices or zones at that spot. With <ref>spellslearned</ref> returns the number of spells a hero learnt. With <ref>findenemyinformation</ref>, returns the number of enemies, or the number of some kind of enemy in the formation.</description>
		</command>
		<command id="wallconstants">
			<canon>Wall Bit Constants</canon>
			<shortname>Wall Bit Constants</shortname>
			<description>
				The following constants are for use with functions like <ref>readpassblock</ref> or <ref>writepassblock</ref>:
				<lb/>
				<p>north wall, east wall, south wall, west wall, vehicle A, vehicle B, harm tile, overhead tile</p>
			</description>
			<altcommand id="northwall">
				<shortname>north wall</shortname>
			</altcommand>
			<altcommand id="eastwall">
				<shortname>east wall</shortname>
			</altcommand>
			<altcommand id="westwall">
				<shortname>west wall</shortname>
			</altcommand>
			<altcommand id="southwall">
				<shortname>south wall</shortname>
			</altcommand>
			<altcommand id="vehiclea">
				<shortname>vehicle A</shortname>
			</altcommand>
			<altcommand id="vehicleb">
				<shortname>vehicle B</shortname>
			</altcommand>
			<altcommand id="harmtile">
				<shortname>harm tile</shortname>
			</altcommand>
			<altcommand id="overheadtile">
				<shortname>overhead tile</shortname>
			</altcommand>
		</command>

		<command id="crop">
			<canon>crop</canon>
			<shortname>crop</shortname>
			<description>A constant used in <ref>setmapedgemode</ref> which makes the edges of the map impassible and prevents the camera from scrolling off them.</description>
		</command>
		<command id="wrap">
			<canon>wrap</canon>
			<shortname>wrap</shortname>
			<description>A constant used in <ref>setmapedgemode</ref> which lets the player walk over the edge of the map around to the opposite side.</description>
		</command>
		<command id="defaulttile">
			<canon>default tile</canon>
			<shortname>default tile</shortname>
			<description>A constant used in <ref>setmapedgemode</ref> which makes the edges of the map impassible and displays a specified tile everywhere off the edge of the map.</description>
		</command>
		<command id="party">
			<canon>party</canon>
			<shortname>party</shortname>
			<description>Pass as first argument to <ref>giveexperience</ref> to divide the experience between all the live heroes in the battle (active) party.</description>
		</command>
		<command id="timer:default">
			<canon>timer: default</canon>
			<shortname>timer: default</shortname>
			<description>Pass to <ref>settimer</ref> to leave one of the parameters at its default setting. Valid for any parameter except <p>id</p></description>
		</command>
		<command id="timer:gameover">
			<canon>timer: game over</canon>
			<shortname>timer: game over</shortname>
			<description>Pass to <ref>settimer</ref> in the <p>trigger</p> field to have the game end when the timer runs out.</description>
		</command>
		<command id="timerflag:critical">
			<canon>timer flag: critical</canon>
			<shortname>timer flag: critical</shortname>
			<description>Pass to <ref>settimer</ref> in the <p>flags</p> field to indicate that if the timer runs out during a battle, it should end the battle immediately.</description>
		</command>
		<command id="timerflag:battle">
			<canon>timer flag: battle</canon>
			<shortname>timer flag: battle</shortname>
			<description>Pass to <ref>settimer</ref> in the <p>flags</p> field to indicate that the timer should run during battle. Otherwise, the timer will be paused during battle.</description>
		</command>
		<command id="timerflag:menu">
			<canon>timer flag: menu</canon>
			<shortname>timer flag: menu</shortname>
			<description>Pass to <ref>settimer</ref> in the <p>flags</p> 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.</description>
		</command>
		<command id="song:silence">
			<canon>song: silence</canon>
			<shortname>song: silence</shortname>
			<description>Used with <ref>setformationsong</ref> and <ref>getformationsong</ref> to indicate an enemy formation without music. Used by <ref>setambientmusic</ref> and <ref>getambientmusic</ref> for a silent map.</description>
		</command>
		<command id="song:sameaslastmap">
			<canon>song: same as last map</canon>
			<shortname>song: same as last map</shortname>
			<altcommand id="song:sameasmap">
				<canon>song: same as map</canon>
				<shortname>song: same as map</shortname>
			</altcommand>
			<description>Used with <ref>setformationsong</ref> and <ref>getformationsong</ref> to indicate an enemy formation which uses the same music as the map. Used by <ref>setambientmusic</ref> and <ref>getambientmusic</ref> for a map that continues with the last map's music.</description>
		</command>
	</section>
</plotscript>
