<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet type="text/xsl" href="htmlplot.xsl"?>

<!DOCTYPE plotscript [
	<!ELEMENT plotscript (section+)>
	<!ATTLIST plotscript lastmodified CDATA "the dawn of time">
	<!ATTLIST plotscript show-alias CDATA "yes">
	<!ELEMENT section (description?,command*)>
	<!ATTLIST section title CDATA #REQUIRED>
	<!ELEMENT command ((canon,shortname,description,example*,seealso?) |
					   (alias,shortname))>
	<!ATTLIST command id ID #REQUIRED
			          created CDATA #IMPLIED>
	<!ELEMENT canon      (#PCDATA)>
	<!ELEMENT shortname   (#PCDATA)>
	<!ELEMENT description ANY>
	<!ELEMENT example     (#PCDATA)>
	<!ATTLIST example c IDREF #IMPLIED>
	<!ELEMENT alias       (#PCDATA)>
	<!ELEMENT seealso (ref+)>

	<!ELEMENT ref         (#PCDATA)>
	<!ELEMENT lb		  (#PCDATA)>
	<!ELEMENT param		  (#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 a lastmodified attribute,
which is the text date that the file was last modified. Update this when you
make a change.

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

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. It's used in many ways, from
crosslinking command entries to generating a file for HssEd to use.

Inside the <command> element are either two or four+ elements, in this order:
Case 1: Full command definition
  <canon> - This is the "canonical" form of the command: the fully spaced
  			 command with parameter prototypes. Example: move hero to x (who, x)
  <shortname> - This is the short version of the command, used for crosslinking,
  				indexes, etc. It is the <canon> element, minus the parameters.
  				Example: move hero to x
  <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 refering to a parameter (to avoid user
  				  confusion) No HTML is allowed (at this time) Example: Well, it
  				  would be pretty long...
  <example>* - Finally, most commands should have some sort of example on how to
  			   use the command. It will be displayed in a mono-space font, so
  			   it's easy to Plotscript. 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>

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

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

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>


#=====

Which reminds me: Indentation. For each "level" you go down in the heirarchy,
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.

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

-->
<plotscript lastmodified="right now">
	<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. Plotscript starts with the keyword plotscript, a comma, and then the name of the plotscript. If there are any arguments to the script, you list their names separated by commas after the name of the script with default values. Then comes the text of the script. It is enclosed in <ref>begin</ref> and <ref>end</ref> statements. Scripts that are defined as plotscripts can be called directly from events in your game, or by name within other scripts.</description>
			<example># example of a simple script
plotscript,my first script,begin
	# commands go here
end</example>
			<example># example of a script with arguments
plotscript,my fancy script,fe=0,fi=0,fo=0,begin
	# commands go here,
	# and they can use the aruments fe, fi, and fo
	# that where passed to the script
end</example>
		</command>
		<command id="script">
			<canon>script, name, argumentnames (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 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
script,my fancy script,fe=0,fi=0,fo=0,begin
	# commands go here,
	# and they can use the aruments fe, fi, and fo
	# that where passed to the script
end</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 4095. 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. The value of this variable is lost when the script ends. If you need a variable who&apos;s value persists between calls to a script, or that is automatically saved when the player saves their game, you will need to use a <ref>globalvariable</ref> instead.</description>
			<example>variable(points) # make a new variable
variable+=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 constants have been delacred for you in PLOTSRC.HSD:<lb /><ref>zero</ref> <ref>one</ref> <ref>two</ref> <ref>three</ref> <ref>four</ref> <ref>five</ref> <ref>six</ref> <ref>seven</ref> <ref>eight</ref> <ref>nine</ref> <ref>ten</ref> <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>upkey</ref> <ref>downkey</ref> <ref>leftkey</ref> <ref>rightkey</ref> <ref>usekey</ref> <ref>cancelkey</ref> <ref>menukey</ref> <ref>anykey</ref> <ref>me</ref> <ref>none</ref> <ref>autonumber</ref> <ref>currentstat</ref> <ref>maximumstat</ref> <ref>northwall</ref> <ref>eastwall</ref> <ref>southwall</ref> <ref>westwall</ref> <ref>vehiclea</ref> <ref>vehiclea</ref> <ref>harmtile</ref> <ref>overheadtile</ref></description>
		</command>
		<command id="include">
			<canon>include, filename</canon>
			<shortname>include</shortname>
			<description>The include command inserts another text file into your script. It is followed by a single filename that tells what file will be included. Windows long filenames are not supported. Every plotscript file should start with include, plotscr.hsd The PLOTSCR.HSD file contains definitions and constants for most of the other plotscripting commands.</description>
			<example>include, plotscr.hsd # Plotscripting definitions
include, mygame.hsi # constants particular to my game</example>
		</command>
		<command id="definescript">
			<canon>define script (id,name,arguments)</canon>
			<shortname>define script</shortname>
			<deprecated>ubersetzung</deprecated>
			<description><note>This declaration is available for backwards compatability, but it is not required anymore. See <ref>script</ref> and <ref>plotscript</ref> instead.</note> The define script command names an old-style script, and associates it with an ID number. Old scripts used to require a unique ID number. The first argument is the <p>ID number</p>. It is a number between 1 and 16383. If you try to give two individual scripts the same <p>ID number</p>, your script file will not compile. The next argument is the <p>name</p> of the script. this is the same name that will used later in your script command. The third argument is the number of arguments that the script can accept. If it doesnt need any arguments (most scripts don't) then use <ref>none</ref>. If there are arguments, you then follow the argument count with default values for each argument.</description>
			<example># example of a simple script definition
define script (1,my first script,none)</example>
			<example># example of a script definition with arguments. this script
# has three arguments, all of which default to zero if they
# are not specified
define script (2,my fancy script,3,0,0,0)</example>
		</command>
	</section>
	<section title="Wait Commands">
		<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.</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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>
		</command>
		<command id="waitforkey">
			<canon>wait for key (key)</canon>
			<shortname>wait for key</shortname>
			<description>Waits for the player to press a key. You can use the following constants: <ref>anykey</ref>, <ref>upkey</ref>, <ref>downkey</ref>, <ref>leftkey</ref>, <ref>rightkey</ref>, <ref>usekey</ref>, <ref>cancelkey</ref>, or <ref>menukey</ref>. If you do not specify, then <ref>anykey</ref> will be used. These are not scancodes, and can not be mixed with scancodes! Use <ref>waitforscancode</ref> if you want to use scancodes or wait for other keys. <p>usekey</p> will wait for Space, Ctrl or Enter; and <p>cancelkey</p> and <p>menukey</p> both wait for Alt or Esc. If and only if anykey is used, waitforkey will return the scancode of the key that was pressed.</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>Waits for the player to press a specific key. You can use any of the constants from <ref>keyispressed</ref> to specify the key. <note>You must <ref>include</ref> scancode.hsi to use these constants.</note></description>
			<example>show text box(624) # "press P!"
wait for scancode(key:P)</example>
		</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).</description>
			<example>walk NPC (2,up,3) # make the NPC go up three spaces
wait for NPC (2) # wait until he&apos;s done</example>
		</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> or <ref>focuscamera</ref> command.</description>
			<example>pan camera (left,10) # show the villan 10 tiles off screen
wait for camera # wait until he&apos;s on screen</example>
		</command>
		<command id="waitforall">
			<canon>wait for all</canon>
			<shortname>wait for all</shortname>
			<description>Waits for any camera motion to stop, waits for all heroes to stop walking, and if <ref>suspendnpcs</ref> is active, waits for all NPCs to stop walking.</description>
			<example># do a bunch of things all at once
wait for all # wait until everything is done</example>
		</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 one exception to this is text boxes. The player can advance text boxes no matter what, unless you use <ref>suspendboxadvance</ref>.</description>
			<example>suspend player
# do stuff
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="suspendnpcs">
			<canon>suspend NPCs</canon>
			<shortname>suspend NPCs</shortname>
			<description>Stops NPCs from walking around automatically. When suspend NPCs is run, all NPCs stop in their tracks once they've finished their current move, ready for you to control them with the <ref>walknpc</ref> command. You can use <ref>waitforall</ref> to wait for all NPCs to stop moving. Use <ref>setnpcmoves</ref>(who, false) instead to prevent a single NPC from moving.</description>
			<example>suspend NPCs
# do stuff
resume NPCs</example>
			<seealso>
				<ref>waitfornpc</ref>
				<ref>waitforall</ref>
				<ref>setnpcmoves</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="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. 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>
		</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="suspendherowalls">
			<canon>suspend hero walls</canon>
			<shortname>suspend hero walls</shortname>
			<description>Allows heroes to walk through walls. 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="suspendnpcwalls">
			<canon>suspend NPC walls</canon>
			<shortname>suspend NPC walls</shortname>
			<description>Allows NPCs to walk through walls. 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.</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="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 compatability.</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 compatability.</description>
			<example c="suspendcaterpillar" />
		</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="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 compatability.</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 compatability.</description>
			<example c="suspendrandomenemies" />
		</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 or clearing text boxes by pressing keys. While this is active, the only way to make a text box advance is with the <ref>advancetextbox</ref> command (or <ref>showtextbox</ref>). 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.</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 # "hit spacebar"
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 and allows the player to advance and clear text boxes by pressing keys as normal.</description>
			<example c="suspendboxadvance" />
		</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="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="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>
	</section>
	<section title="Moving Heroes">
		<command id="walkhero">
			<canon>walk hero (who, direction, distance)</canon>
			<shortname>walk hero</shortname>
			<description>Makes the specified hero move in the specified direction for the specified number of tiles. The first argument tells who to move. Use <ref>me</ref> or numbers 0-3. The second argument is the direction. Use the constants: <ref>north</ref>, <ref>south</ref>, <ref>east</ref>, <ref>west</ref>, <ref>up</ref>, <ref>down</ref>, <ref>left</ref>, or <ref>right</ref>. The third argument is the number of tiles to move. If you leave out the third argument, the hero will move one tile. 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>
		<command id="setherodirection">
			<canon>set hero direction (who, direction)</canon>
			<shortname>set hero direction</shortname>
			<description>Makes the specified hero face in the specified direction. The following constants are avaialable for direction: <ref>north</ref>, <ref>south</ref>, <ref>east</ref>, <ref>west</ref>, <ref>up</ref>, <ref>down</ref>, <ref>left</ref>, or <ref>right</ref>.</description>
			<example>set hero direction (me,right) # face right</example>
		</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 to 0 or 1.</description>
			<seealso>
				<ref>heroframe</ref>
			</seealso>
		</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>
		</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 location is the number of pixels above the tile they are standing on. Useful for scripts where you want a hero to jump or levitate.</description>
		</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 direction. No actual movement takes place.</description>
		</command>
		<command id="setherospeed">
			<canon>set hero speed (who, speed)</canon>
			<shortname>set hero speed</shortname>
			<description>Changes the walking speed of the specified hero. If you do not specify a speed, the hero&apos;s speed will return to the default, 4. Be careful with using speeds that do not divide evenly into 20, because tiles are 20 pixels in size, and an irregular walking speed may cause your hero to become misaligned with the tiles.</description>
			<seealso>
				<ref>getherospeed</ref>
			</seealso>
		</command>
		<command id="usedoor">
			<canon>use door (number)</canon>
			<shortname>use door</shortname>
			<description>Instantly uses the numbered door, just as if you had stepped into it. (This command implies a one-tick <ref>wait</ref>)</description>
		</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 on the specified map without the need to create a door-link on the map. Teleport to map does not fade to black. (This command implies a one-tick <ref>wait</ref>)</description>
		</command>
		<command id="dismountvehicle">
			<canon>dismount vehicle</canon>
			<shortname>dismount vehicle</shortname>
			<description>Makes you dismount whatever vehicle you are riding. If you are not riding a vehicle, nothing will happen.</description>
		</command>
		<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>
		<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>
	</section>
	<section title="Moving NPCs">
		<command id="npcreference">
			<canon>NPC reference (ID, copy)</canon>
			<shortname>NPC reference</shortname>
			<description>What is an NPC reference? A reference is a number that uniquely identifies an NPC on a map. You can use an NPC reference to specify which NPC you are controlling in most NPC-related commands. The first argument to NPC reference is the ID number of the NPC you want to work with. The ID is the same number that appears in CUSTOM.EXE when you are editing NPCs or placing NPCs on the map. The second argument is optional. It specifies which copy of the NPC you want, in case there are more than one on the map. If you dont specify which copy you want, you will just get a reference to the first NPC on the map with the right ID. Copies are counted starting from zero; you can see the copy number of NPCs in the Map Editor if you placed them in Custom.<lb/> If you plan on using the same NPC reference many times in a script you can store it in a <ref>variable</ref>. If the NPC with the ID you asked for (or the NPC copy you asked for with ID you asked for) is not found on the map then NPC reference will return <ref>false</ref>.</description>
			<example>include,plotscr.hsd

#---NPC reference example---

plotscript,ref example,begin

  variable(Fred)

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

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

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

end</example>
			<seealso>
				<ref>npcatspot</ref>
				<ref>npcatpixel</ref>
				<ref>createnpc</ref>
				<ref>npccopycount</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 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). 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). 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>
		<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>npcreference</ref> or the NPC&apos;s ID number. The second argument is the direction. Use the constants: <ref>north</ref>, <ref>south</ref>, <ref>east</ref>, <ref>west</ref>, <ref>up</ref>, <ref>down</ref>, <ref>left</ref>, or <ref>right</ref>. The third argument is the number of tiles to move. If you leave out the third argument, the NPC will move one tile. 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="setnpcdirection">
			<canon>set NPC direction (who, direction)</canon>
			<shortname>set NPC direction</shortname>
			<description>Makes the specified NPC face in the specified direction. The following constants are avaialable for direction: <ref>north</ref>, <ref>south</ref>, <ref>east</ref>, <ref>west</ref>, <ref>up</ref>, <ref>down</ref>, <ref>left</ref>, or <ref>right</ref>. You can use either an <ref>npcreference</ref> or the NPC&apos;s ID number to specify which NPC will turn.</description>
		</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. You can use either an <ref>npcreference</ref> or the NPC&apos;s ID number to specify which NPC will change.</description>
			<seealso>
				<ref>npcframe</ref>
			</seealso>
		</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>npcreference</ref> or the NPC&apos;s ID number to specify which NPC will be moved.</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>npcreference</ref> or the NPC&apos;s ID number 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>npcreference</ref> or the NPC&apos;s ID number to specify which NPC will move.</description>
		</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 direction. No actual movement takes place. It does not matter whether the NPC is set to ignore walls.</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. If you do not specify a speed, the NPC&apos;s speed will return to the default, 4. Be careful with using speeds that do not divide evenly into 20, because tiles are 20 pixels in size, and an irregular walking speed may cause the NPC to become misaligned with the tiles.<lb/>Normally you would only give an NPC ID number to set NPC speed, but if you want to use an <ref>npcreference</ref> it will still work. Just remember that set NPC speed changes every copy of the NPC on the map, not just the specific one you referenced.</description>
		</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. Returns <ref>false</ref> if the NPC is standing still. You can use either an <ref>npcreference</ref> or the NPC&apos;s ID number to specify which NPC will be checked.</description>
		</command>
		<command id="getnpcid">
			<canon>get NPC ID (reference)</canon>
			<shortname>get NPC ID</shortname>
			<description>This command is the opposite of <ref>npcreference</ref>. If you give get NPC ID a reference to an NPC it will return the NPC&amp;s ID. If the NPC ID is not valid then <p>get NPC ID</p> will return -1<lb/><note>In some older versions, This command was useful if you needed to do an <ref>alternpc</ref> or a <ref>setnpcspeed</ref> on an NPC that you are working with by reference. This is no longer neccisary, because both those commands now support NPC references (although they still affect every copy of that NPC on the map)</note></description>
		</command>
		<command id="npccopycount">
			<canon>NPC copy count (ID)</canon>
			<shortname>NPC copy count</shortname>
			<description>This command tells you how many copys 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.</description>
			<example>include,plotscr.hsd

#---NPC copy count example---

plotscript,every NPC example,begin

  variable(loop,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(loop,0,guard count) do,begin

    current guard := NPC reference(10,loop)
    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

  # but we want them to all walk at the same time,
  # so we just wait here
  wait for all

end</example>
		</command>
		<command id="changenpcid">
			<canon>change NPC ID (reference,new ID)</canon>
			<shortname>change NPC ID</shortname>
			<description>This command takes an <ref>npcreference</ref> and lets you change the ID number of the NPC it points to. This means that the NPC will now use a different picture, an different palette, a different walking speed, an different text box, everything. This change is not permanent. It only lasts until the next time a map gets loaded.</description>
		</command>
		<command id="createnpc">
			<canon>create NPC (ID,X,Y,direction)</canon>
			<shortname>create NPC</shortname>
			<description>This command will magically create a new copy of an NPC with the given ID number. You can specify an X and Y position where it will be created, and optionally a direction too (if you leave out the direction, the new NPC will be facing south). create NPC returns an <ref>npcreference</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>
		</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>npcreference</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></description>
		</command>
		<command id="putnpc">
			<canon>put npc (who,x,y)</canon>
			<shortname>put npc</shortname>
			<description>Moves an NPC to a precise location on the map. 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>
	</section>
	<section title="Moving the Camera">
		<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="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. For direction, you can use the constants: <ref>north</ref>, <ref>south</ref>, <ref>east</ref>, <ref>west</ref>, <ref>up</ref>, <ref>down</ref>, <ref>left</ref>, or <ref>right</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 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="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>
	</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>
		<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>
		</command>
	</section>
	<section title="Triggering and Showing Stuff">
		<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>false</ref> if you lost or ran from battle, or <ref>true</ref> if you won. However, if you lose the battle, the game will still end as normal unless you set a death script. (This command implies a one-tick <ref>wait</ref>)</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>npcreference</ref> or an NPC ID number. Whatever actions are associated with triggering that NPC will be taken, text box, script, vehicle, item, whatever. (This command implies a one-tick <ref>wait</ref>)</description>
		</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. This command is similar to <ref>resetgame</ref>, the main difference being that if the title screen and load screen have been disabled, it will completely exit the game, taking you back to the game select screen, or exiting to the operating system.</description>
		</command>
		<command id="resetgame">
			<canon>reset game</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> as it will not exit the program if the title screen and load screen have been disabled. It always resets the game back to the beginning.</description>
		</command>
		<command id="showvalue">
			<canon>show value (number)</canon>
			<shortname>show value</shortname>
			<description>Displays the number in the bottom left corner of the screen. Useful for count-down timers, and for debugging complicated scripts.</description>
		</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> 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. You can also do some simple animation effects by calling show backdrop many times with <ref>wait</ref> commands in between.</description>
		</command>
		<command id="showmap">
			<canon>show map</canon>
			<shortname>show map</shortname>
			<description>shows the map again after a <ref>showbackdrop</ref> command</description>
		</command>
		<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>
		<command id="mainmenu">
			<canon>main menu</canon>
			<shortname>main menu</shortname>
			<description>Takes you directly to the main menu.</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.</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. The <ref>pickhero</ref> command can also be useful.</description>
		</command>
		<command id="equipmenu">
			<canon>equip menu (who)</canon>
			<shortname>equip menu</shortname>
			<description>Takes you directly to a hero&apos;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, the first hero in the party will be used.</description>
		</command>
		<command id="savemenu">
			<canon>save menu (reallysave)</canon>
			<shortname>save menu</shortname>
			<description>Takes you directly to the save menu. Will return a number 1-4 indicating 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)</canon>
			<shortname>load menu</shortname>
			<description>Displays the load game menu. The player can load a game or select New Game or Exit/Cancel. If the player picks New Game then the calling script continues, otherwise the current game is terminated and either quits to the titlescreen (if there is one) or a game is loaded. If you want the New Game option to actually reset the game, call <ref>resetgame</ref> immediately after <p>load menu</p>. You can optionally pass an argument of <ref>false</ref> to make the menu display without actually loading or quiting. If you do this, you'll need to interpret the return value to find out which option the player selected: positive values are save slot numbers, 0 means New Game and -1 is Quit.</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>
	</section>
	<section title="Adding and Removing">
		<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="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>Removes the named hero from your party. If you have more than one copy of the hero in your party, only the first one will be deleted. Use the constants defined in your HSI file. They are in the form of hero:name</description>
		</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. Use the constants defined in your HSI file. They are in the form of hero:name</description>
		</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 hero:name</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 on the party menu. Locked heroes in the active party cannot be moved into the reserve, and locked heroes in the reserve are completely hidden. Also prevents a hero from being moved by <ref>swapinhero</ref> or <ref>swapouthero</ref>. Use the constants defined in your HSI file. They are in the form of hero:name</description>
		</command>
		<command id="unlockhero">
			<canon>unlock hero (who)</canon>
			<shortname>unlock hero</shortname>
			<description>Reverses <ref>lockhero</ref>, and makes it possible to move a hero in and out of the active party again. Use the constants defined in your HSI file. They are in the form of hero:name</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 (position,position)</canon>
			<shortname>swap by position</shortname>
			<description>Swaps two heroes in your party based on their positions in the party</description>
		</command>
		<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</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="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 number 1-5 or the names slot:weapon, slot:armor, etc.</description>
		</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 number 1-5 or the names slot:weapon, slot:armor, etc. The third argument is the item to equip. you can use the item&apos;s number or the item:name constants from your .HSI file.</description>
		</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, or false if the hero cannot equip it. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (use <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&apos;s number or the item:name constants from your .HSI file.</description>
		</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 number 1-5 or the names slot:weapon, slot:armor, etc.</description>
		</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>
		<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) or the whole active party, if the constant <ref>party</ref> is passed as first argument. If you give experience to the whole battle 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. 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>spellslearnt</ref> for dealing with this. You should use <ref>setexperience</ref> to remove experience in a way that allows delevelling.</description>
		</command>
	</section>
	<section title="Effects">
		<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="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="stopsong">
			<canon>stop song</canon>
			<shortname>stop song</shortname>
			<description>Stops whatever music is currently playing.</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 deault 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. If you want to manipulate the sound (e.g. fading out the music) you should take note of the original vulume that the player has set and return to this. The default volume is 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 your implementation. Currently vanilla OHR uses only 0-15 internally, so 240-255 all translate to the same volume, etc.</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.</description>
		</command>
		<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 applies the changes made with other palette commands such as <ref>greyscalepalette</ref>, <ref>tweakpalette</ref>, <ref>resetpalette</ref>, and <ref>writecolor</ref>.</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> or <ref>greyscalepalette</ref> 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="readcolor">
			<canon>read color (index, element)</canon>
			<shortname>read color</shortname>
			<description>Returns a color value from the master palette. The first argument is the index in the palette to read from, 0 to 255. The second argument is the color value to read, red, green, or blue. You can use 0,1, and 2, or you can use the predefined constants <ref>colorred</ref>, <ref>colorgreen</ref>, and <ref>colorblue</ref>. The counterpart to this is <ref>writecolor</ref>.
			<note>This command operates on values from 0-63. For operation on full color values (0-255), see <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 can be in the range of 0 to 63. Changes do not take effect until you call <ref>updatepalette</ref> or <ref>fadescreenin</ref> The counterpart to this is <ref>readcolor</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>
			<seealso>
				<ref>setcolor</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>.</description>
			<seealso>
				<ref>getcolor</ref>
				<ref>rgb</ref>
			</seealso>
		</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, 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>
		<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. 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>, and the sound is already playing, this command will do nothing.</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>, wherein it will 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.</description>
			<seealso>
				<ref>playsound</ref>
				<ref>stopsound</ref>
			</seealso>
		</command>
	</section>
	<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. 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 is capable of learning the spell, teach spell will return <ref>true</ref>, or if the hero cannot learn the spell it will return <ref>false</ref>. Note that this only works when a spell is set to "learned from item". It will not work for spells learned based on level.</description>
		</command>
		<command id="forgetspell">
			<canon>forget spell (hero,attack)</canon>
			<shortname>forget spell</shortname>
			<description>Causes a hero to forget a spell. 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 forget. 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 does not know the spell, nothing happens.</description>
		</command>
		<command id="readspell">
			<canon>read spell (hero,list,slot)</canon>
			<shortname>read spell</shortname>
			<description>Returns the ID number of a chosen spell slot, or 0 (<ref>false</ref>) if there is no spell in that slot. 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 find hero). The second argument is the spell list to put the spell in. This is a number from 0 to 3. The third argument is the slot to put the spell in. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on. The last argument is the attack to put in the spell list. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack&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 to see if a hero already knows a spell. 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 check for. 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 knows the spell, knows spell will return <ref>true</ref>. If the hero does not know the spell, it will return <ref>false</ref></description>
		</command>
		<command id="canlearnspell">
			<canon>can learn spell (hero,attack)</canon>
			<shortname>can learn spell</shortname>
			<description>Checks to see if a hero is capable of learning a spell from an item or from the teach spell command. The first argument is the hero&apos;s position in the party (as returned by <ref>findhero</ref>). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack&apos;s ID number. This is the number you see in the attack editor + 1). If the hero can learn the spell, can learn spell will return <ref>true</ref>. If the hero cannot learn the spell (or learns it from levelups), it will return <ref>false</ref></description>
		</command>
		<command id="spellslearnt">
			<alias>spellslearned</alias>
			<shortname>spells learnt</shortname>
		</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 (for heroes in the active battle party) or <ref>giveexperience</ref>, <ref>setherolevel</ref> or <ref>setexperience</ref> command that involved this hero. If the second argument is <ref>getcount</ref> then the number of spells that the hero learned is returned. Pass 0 for number to get the first spell learnt, 1 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 use this command with attack ID numbers, you must add 1 to the ID number.</note>
			</description>
			<example># the following script uses strings 0, 1, 2 for its use (will be overwritten)
plotscript, print learned spells, who=0, begin
  variable(i)
  get hero name (1, who) # construct the static part of the text in string 1
  $1+" learned spell "
  for (i, 0, spells learned (who, get count) -- 1) do (
    read attack name (2, spells learned (who, i))  # get the i-th spell learnt
    0 $= 1  # copy the static part to the displayed string
    0 $+ 2  # combine with the spell name
    show string at (0, 160, 100)
    wait for keypress (anykey)
  )
  hide string (0)
end</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 spell is most useful for situations where you are manipulating the heros level, and for some reason do not want to use <ref>setherolevel</ref> which automatically handles 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>
		<command id="outsidebattlecure">
			<alias>outsidebattlecure</alias>
			<shortname>outside battle cure</shortname>
		</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 ommitted 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></note>
			</description>
		</command>
	</section>
	<section title="Mouse Functions">
		<command id="initmouse">
			<canon>init mouse</canon>
			<shortname>init mouse</shortname>
			<description>Initializes the mouse, returning <ref>true</ref> if one is present. This command should be run before any mouse functions are be used. It causes the normal mouse cursor to be hidden when over the game's window, prevents the mouse cursor from leaving the window, and causes mouse clicks 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 on screen - your script must do this itself by placing a slice or npc at the appropriate location.</note> Here is an example:</description>
			<example>include,plotscr.hsd

#Mouse cursor example

plotscript, display mouse, begin

  #start up the mouse
  init mouse

  #loop while the game is running
  while (true) do,begin

    #NPC 0 is the mouse cursor
    put npc (0, mouse pixel x + camera pixel x, mouse pixel y + camera pixel y)
    wait
  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.</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.</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 pressed. You can use the constants <ref>leftbutton</ref> and <ref>rightbutton</ref> to specify the button.</description>
		</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. <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>Sets the edges of the rectangle to which the mouse is constricted. Use if you want to force the mouse into some region, like a choice selection box. The maximum values are inclusive. Without arguments, resets the rectangle to the whole window. You can unrestrict the mouse and let it leave the window by calling <p>mouse region (-1, -1, -1, -1)</p>. <ref>initmouse</ref> should be called before this command is used.</description>
		</command>
	</section>
	<section title="String Functions">
		<description>When refering 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 is because the string commands are based on BASIC string commands, which are 1-based. This also means that position 0 is invalid. Beware!<lb/>There is no limit on string length (previously, they were limited to 40 characters, the width of the screen)</description>
		<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="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="appendascii">
			<canon>append ascii (ID, char)</canon>
			<shortname>append ascii</shortname>
			<description>Appends the character with ascii code 'ascii' to the string with ID #ID. Remember: Numbers are 48 - 57, uppercase letters are 65 - 90, lowercase letters are 97 - 122.</description>
			<seealso><ref>appendnumber</ref></seealso>
		</command>
		<command id="appendnumber">
			<canon>append number (ID, number)</canon>
			<shortname>append number</shortname>
			<description>Appends the textual representation of <p>number</p> to the string with ID #<p>ID</p>. For example, append number(1,65) will append "65", not "A".</description>
			<seealso><ref>appendascii</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 thre string can start with a - sign for negatives. No other characters except numerical digits can appear in the string. You can also provide an optional default value that will be returned if the string is not a valid number (for example, if it contains a non-numeric letter)</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="stringcompare">
			<canon>string compare (ID1, ID2)</canon>
			<shortname>string compare</shortname>
			<description>Returns true if the two strings #<p>ID1</p> and #<p>ID2</p> are identical, case sensitive.</description>
		</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>postion</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>
		<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.</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.</description>
			<seealso><ref>stringtoglobals</ref></seealso>
		</command>
		<command id="getheroname">
			<canon>get hero name (ID, hero)</canon>
			<shortname>get hero name</shortname>
			<description>This command will take the name of hero #<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(hero by rank(0))) 
</example>
		</command>
		<command id="setheroname">
			<canon>set hero name (ID, hero)</canon>
			<shortname>set hero name</shortname>
			<description>This command will take string #<p>ID</p>, and set hero #<p>hero</p>&apos;s name to it.</description>
		</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="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="getattackname">
			<alias>readattackname</alias>
			<shortname>get attack name</shortname>
		</command>
		<command id="readattackname">
			<canon>read attack name (ID, attack)</canon>
			<shortname>read attack name</shortname>
			<description>This command will take the name of <p>attack</p> and stick it in string #<p>ID</p>, 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="getglobalstring">
			<canon>get global string (ID, global)</canon>
			<shortname>get global string</shortname>
			<description>This command will take the name of global string #<p>global</p> and stick it in string #<p>ID</p>, overwriting its contents. Global strings include every text string in the game, such as prompts and messages. See the Global String Editor in CUSTOM for a list of all of them. Due to the way global strings are stored internally, not all values of #<p>global</p> will produce valid results. <!-- TMC is creating an HSI file for getglobalstring, it's partially finished and misplaced --></description>
		</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. Returns false if they press ESC to cancel. All arguments are optional: <p>ID</p> is the string you want to use, default is string #0. <p>maxlen</p> is the length of input, if left blank the limit will be set to 40 (max visible onscreen length). <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>. <p>center</p> centers the string input at position x/y. If left blank the string will use its current positioning. Otherwise, valid arguments are <ref>true</ref> or <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, and are the position at which the string will be shown as it is being typed. The default values are 160,110.</description>
		</command>
		<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.</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.<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 topleft corner will stay fixed.</note></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 previously displayed with <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 not outline but can have a solid background of any colour 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 previously displayed with <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 ommit <p>background color</p>, the background will be transparent.</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>
		<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>
		<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 expression 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>
			<shortname>trim string</shortname>
			<description>Cuts the string to the specified length, OR removes blank space from the beginning and ends of the string. <p>ID</p> is the string you want to be cut. If you wish to cut <p>ID</p> to a certain length, you must specify <p>start</p> and <p>length</p>. <p>start</p> is the position at which you want to start cutting, anything to the left of this number will be deleted in a string. <p>length</p> is the size of the string you want to preserve, anything to the right of this number will be deleted in a string. If you leave these parameters blank, it will trim whitespace from the beginning and ends of <p>ID</p>.</description>
		</command>
		<command id="stringfromtextbox">
			<canon>string from textbox (ID, textbox, line, expand)</canon>
			<shortname>string from textbox</shortname>
			<description>Loads text from the <p>line</p> in a <p>textbox</p> into a string <p>ID</p>. The command automatically erases white spaces from the begining of the string and end of the string. Valid numbers for <p>line</p> are 0-7. If <p>expand</p> is true, then codes like ${H1} in the string will be substituted automatically.</description>
			<seealso>
				<ref>expandstring</ref>
			</seealso>
		</command>
		<command id="expandstring">
			<canon>expand string(ID)</canon>
			<shortname>expand string</shortname>
			<description>Expands codes in <p>ID</p> like ${H1}. This does the same thing that textboxes do automatically.</description>
		</command>
	</section>

	<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 menu:name. The menu will be opened on top of any menus that are already open. The optional second argument <p>allow duplicates</p> 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. The return value is a menu handle that you should store in a variable for use with other menu-related commands.</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" bitset turned on by default.</description>
		</command>
		<command id="closemenu">
			<canon>close menu(menu handle)</canon>
			<shortname>close menu</shortname>
			<description>Close a menu. The argument is a <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref> or <ref>topmenu</ref>)</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 <p>menu handle</p> (for example, the one return by <ref>bottommenu</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 return a menu handle to it.</description>
		</command>
		<command id="menuisopen">
			<canon>menu is open(menu handle)</canon>
			<shortname>menu is open</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <p>open menu</p>), Check to see if it is already open, and return <ref>true</ref> if it is, or <ref>false</ref> if it is not</description>
		</command>
		<command id="addmenuitem">
			<canon>add menu item(menu handle)</canon>
			<shortname>add menu item</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>createmenu</ref>), Add a new 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 <p>menu item handle</p> (for example, the one returned by <ref>addmenuitem</ref> or <ref>selectedmenuitem</ref>), delete the menu item from the menu.</description>
		</command>
		<command id="selectmenuitem">
			<canon>select menu item(menu item handle)</canon>
			<shortname>select menu item</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>addmenuitem</ref>), Move the menu selection cursor to point to that menu item</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, false if no menus are open, or, when given an optional <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>) returns the selected item in that menu.</description>
		</command>
		<command id="usemenuitem">
			<canon>use menu item(menu item handle)</canon>
			<shortname>use menu item</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</ref>), activate the menu item. This will cause whatever actions (text box, menu, script, tag changes) 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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Return a menu item handle for the menu item at the top of the menu.</description>
		</command>
		<command id="menuitembyslot">
			<canon>menu item by slot(menu handle, slot, visible only)</canon>
			<shortname>menu item by slot</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>openmenu</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</description>
			<seealso>
				<ref>menuitemslot</ref>
			</seealso>
		</command>
		<command id="menuitemslot">
			<canon>menu item slot(menu item handle)</canon>
			<shortname>menu item slot</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>addmenuitem</ref>), return a the slot number of the menu item. The first slot in the menu is 0.</description>
			<seealso>
				<ref>menuitembyslot</ref>
			</seealso>
		</command>
		<command id="nextmenuitem">
			<canon>next menu item(menu item handle, visible only)</canon>
			<shortname>next menu item</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 that invisible menu items are always at the end of the menu, after the last visible menu item</description>
			<example>variable(mi)
mi := first menu item
while(mi) do, begin
  # do things to each 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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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</description>
			<example>variable(m)
m := previous menu item(selected menu item)</example>
		</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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. 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="getmenuitemcaption">
			<canon>get menu item caption(menu item handle, string ID)</canon>
			<shortname>get menu item caption</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</ref>), Change the type of the menu item to <p>new type</p>. Available constants are: <p>menutype:label</p>,<p>menutype:special</p>, <p>menutype:menu</p>, <p>menutype:textbox</p>, and <p>menutype:script</p></description>
		</command>
		<command id="getmenuitemsubtype">
			<canon>get menu item subtype(menu item handle)</canon>
			<shortname>get menu item subtype</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</ref>), Return the subtype of the menu item. The meaning of the subtype varies depending on the type.</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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. For menutype:special you can use constants like: <p>menuspecial:items</p>, <p>menuspecial:spells</p>, <p>menuspecial:status</p>, <p>menuspecial:equip</p>, <p>menuspecial:order</p>, <p>menuspecial:team</p>, <p>menuspecial:orderteam</p>, <p>menuspecial:map</p>, <p>menuspecial:save</p>, <p>menuspecial:load</p>, <p>menuspecial:quit</p>,  and <p>menuspecial:volume</p>. For menutype:textbox you can use the textbox's ID number. For menutype:menu you can use the menu's ID number or a menu:name constant from your HSI file. For menutype:script you can use script references in the form @scriptname</description>
		</command>
		<command id="getmenuitemtag">
			<canon>get menu item tag(menu item handle, whichtag)</canon>
			<shortname>get menu item tag</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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. You can use constants for the <p>bit</p> bit number in the form of <p>menu item bit:Hide when disabled</p> and <p>menu item bit:Close menu if selected</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</ref>), and bit number <p>bit</p>, Set the bitset is ON or OFF depending on <p>value</p>. You can use constants for the <p>bit</p> bit number in the form of <p>menu item bit:Hide when disabled</p> and <p>menu item bit:close menu when selected</p></description>
		</command>
		<command id="getmenuitemextra">
			<canon>get menu item extra(menu item handle, extra)</canon>
			<shortname>get menu item extra</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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="getmenubit">
			<canon>get menu bit(menu handle, bit)</canon>
			<shortname>get menu bit</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>topmenu</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></ul></description>
		</command>
		<command id="setmenubit">
			<canon>set menu bit(menu handle, bit, value)</canon>
			<shortname>set menu bit</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>topmenu</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 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></ul></description>
		</command>
		<command id="parentmenu">
			<canon>parent menu(menu item handle)</canon>
			<shortname>parent menu</shortname>
			<description>Given a <p>menu item handle</p> (for example, the one returned by <ref>selectedmenuitem</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 <p>menu handle</p> (for example, the one returned by <ref>parentmenu</ref>), Return a the ID number of the menu, or -1 if the men was created with the <ref>createmenu</ref> command.</description>
		</command>
		<command id="swapmenuitems">
			<canon>swap menu items(handle1, handle2)</canon>
			<shortname>swap menu items</shortname>
			<description>Given two menu item handles (for example, the ones returned by <ref>selectedmenuitem</ref> and <ref>nextmenuitem</ref>) 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="getmenuboxstyle">
			<canon>get menu boxstyle(menu handle)</canon>
			<shortname>get menu boxstyle</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Return a the boxstyle of the menu. This will be a number from 0 to 15</description>
		</command>
		<command id="setmenuboxstyle">
			<canon>set menu boxstyle(menu handle, new box style)</canon>
			<shortname>set menu boxstyle</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Change the boxstyle of the menu. <p>new box style</p> will be a number from 0 to 15</description>
		</command>
		<command id="getmenutextcolor">
			<canon>get menu textcolor(menu handle)</canon>
			<shortname>get menu textcolor</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Return a the text color of the menu. This will be a number from 0 to 255</description>
		</command>
		<command id="setmenutextcolor">
			<canon>set menu textcolor(menu handle, new textcolor)</canon>
			<shortname>set menu textcolor</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Change the text color of the menu. <p>new textcolor</p> will be a number from 0 to 255. 0 is the default color.</description>
		</command>
		<command id="getmenumaxrows">
			<canon>get menu max rows(menu handle)</canon>
			<shortname>get menu max rows</shortname>
			<description>Given a <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Return the x offset position of the menu 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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Return the y offset position of the menu 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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Change the x offset position of the menu 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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Change the y offset position of the menu 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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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></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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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></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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Change the vertical y anchor position of the menu. Change the horizontal x 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></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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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></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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Change the text alingment of the menu. The <p>new align</p> can be <p>align:center</p>, <p>align:left</p> or <p>align:right</p></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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Return a script id 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 <p>menu handle</p> (for example, the one returned by <ref>openmenu</ref>), Assign script id 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>

	</section>
	
	<section title="Sprite Functions">
		<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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads hero battle sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads walkabout sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads small enemy sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads medium enemy sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads large enemy sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads attack battle sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads weapon battle sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads border battle sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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 handle. 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>Do not load a sprite onto another sprite that has not been freed. 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>Loads portrait battle sprite #<p>num</p> with palette <p>palette</p> into sprite <p>handle</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 sprite, 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="freesprite">
			<canon>free sprite (handle)</canon>
			<shortname>free sprite</shortname>
			<description>Unloads a sprite loaded by any of the "load x sprite" functions. This removes the sprite from the screen and removes it from memory. It is a good idea to free sprites when you are completely done with them. Unlike <ref>freeslice</ref>, this command only works on sprites, but it will still also free any children of the sprite it is freeing regardless of what kind of children they are. The only purpose of this command is additional error checking.</description>
			<seealso>
				<ref>freeslice</ref>
				<ref>loadherosprite</ref>
			</seealso>
		</command>
		<command id="clonesprite">
			<canon>clone sprite (handle)</canon>
			<shortname>clone sprite</shortname>
			<description>Returns a new handle to a duplicate of a sprite. If you clone a sprite, remember that you will need to call <ref>freesprite</ref> on both the original and the clone.</description>
			<seealso>
				<ref>loadherosprite</ref>
				<ref>freesprite</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></ul></description>
			<seealso>
				<ref>getspritesetnumber</ref>
				<ref>getspritepalette</ref>
				<ref>getspriteframe</ref>
			</seealso>
		</command>
		<command id="getspritesetnumber">
			<canon>get sprite set number (handle)</canon>
			<shortname>get sprite set number</shortname>
			<description>Gets the number of the spriteset of a slice sprite <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 <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 <p>handle</p>.</description>
			<seealso>
				<ref>getspritetype</ref>
				<ref>getspritesetnumber</ref>
				<ref>getspriteframe</ref>
			</seealso>
		</command>
		<command id="setspriteframe">
			<canon>set sprite frame (handle, num)</canon>
			<shortname>set sprite frame</shortname>
			<description>Changes the frame of sprite <p>handle</p> to be <p>num</p>. If <p>num</p> is less than 0, or greater than or equal to the number of frames, nothing will change.</description>
			<seealso>
				<ref>getspriteframe</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 <p>handle</p>.</description>
			<seealso>
				<ref>getspritetype</ref>
				<ref>getspritepalette</ref>
				<ref>getspritesetnumber</ref>
			</seealso>
		</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 <p>handle</p>.</description>
		</command>
		<command id="spritelayer">
			<canon>sprite layer</canon>
			<shortname>sprite layer</shortname>
			<description>Returns a slice handle for the layer which contains slices created with commands such as <ref>loadherosprite</ref>, <ref>createrect</ref> and others. You can use this together with <ref>firstchild</ref> if you want to loop through all your slices without knowing their handles. This is the default parent of all new slices.</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="horizflipsprite">
			<canon>horiz flip sprite (handle, flip)</canon>
			<shortname>horiz flip sprite</shortname>
			<description>Flips a sprite <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 <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 <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 <p>handle</p> is flipped vertically, or false if it is not.</description>
			<seealso>
				<ref>vertflipsprite</ref>
				<ref>spriteishorizflipped</ref>
			</seealso>
		</command>
	</section>
	<section title="Slice Functions">
		<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. The argument is the <p>id</p> number of the collection. The return value is a handle to the container that holds the loaded collection.</description>
		</command>
		<command id="lookupslice">
			<canon>lookup slice (lookup code, start slice)</canon>
			<shortname>lookup slice</shortname>
			<description>Search for an important slice using a lookup code, and return a handle to it, or 0 if it is not found. User defined slice lookup codes are defined in the slice collection editor. You will find them as constants in your .hsi file with sli: prefixes. There are also some special slice lookup codes with names that start with sl: prefixes. You can optionally specify a slice for the <p>lookup slice</p> command to start searching from, but if you do not, the whole slice tree will be searched.
				<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! You may parent your own slices to these special slices, but moving special slices around is definitely a bad idea.</note>
				<note>Be aware that when there is more than one slice with the same lookup code, the <p>lookup slice</p> command will only return the first one it finds in a depth-first search. If you need to find multiple slices with the same lookup code, you must search manually using <ref>getslicelookup</ref>.</note>
			You may <ref>setparent</ref> a slice to a map layer to make it move with the camera just like heros 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)
protrait = lookup slice(sl:textbox portrait)
if(portrait) then(
  replace portrait sprite(portrait, 5)
)

# This is a list of special slice lookup codes
lookup slice(sl:textbox text)
lookup slice(sl:textbox portrait)
lookup slice(sl:textbox choice0)
lookup slice(sl:textbox choice1)
lookup slice(sl:script layer)
lookup slice(sl:textbox layer)
lookup slice(sl:string layer)
lookup slice(sl:maproot)
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)
</example>
			<seealso>
				<ref>setslicelookup</ref>
				<ref>getslicelookup</ref>
			</seealso>
		</command>
		<command id="getslicelookup">
			<canon>get slice lookup (handle)</canon>
			<shortname>get slice lookup</shortname>
			<description>Returns the lookup code 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 lookup values in plotscr.hsd</description>
			<seealso>
				<ref>lookupslice</ref>
				<ref>setslicelookup</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 slice handle, the second is the new lookup code. You can pass <ref>false</ref> as the second argument to remove a slice's lookup code. This command works with the <p>sli:</p> slice lookup values in your hsi file. It does not work with the <p>sl:</p> special lookup values in plotscr.hsd, nor can it modify the lookup code of slices that already have special lookup codes. Only user-defined lookup codes can be changed. Built-in special lookup codes cannot.</description>
			<seealso>
				<ref>lookupslice</ref>
				<ref>getslicelookup</ref>
			</seealso>
		</command>
		<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.</description>
<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.
		</command>
		<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>
		<command id="sliceisvalid">
			<canon>slice is valid (id)</canon>
			<shortname>slice is valid</shortname>
			<description>Returns true if the given <p>id</p> is a valid sprite handle. The main use of this command is to check whether a slice has been deleted, avoiding a script error.</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.</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.</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.</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.</description>
		</command>
		<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.</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>
			</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, and may depend upon the slice's Align settings.</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, and may depend upon the slice's Align settings.</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 screen X position of any 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.</description>
			<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 screen Y position of any 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.</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>
		<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 container slice or a rect slice. This command does not work on sprite slices because they have a fixed width.</description>
			<seealso>
				<ref>slicewidth</ref>
				<ref>setsliceheight</ref>
			</seealso>
		</command>
		<command id="setsliceheight">
			<canon>set slice height (handle, height)</canon>
			<shortname>set slice height</shortname>
			<description>Changes the height of a container slice or a rect slice. This command does not work on sprite slices because they have a fixed height.</description>
			<seealso>
				<ref>sliceheight</ref>
				<ref>setslicewidth</ref>
			</seealso>
		</command>
		<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></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></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></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 x 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></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>. The default value is edge:left.</description>
			<seealso>
				<ref>setvertalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</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>. The default value is edge:top.</description>
			<seealso>
				<ref>sethorizalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</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>. The default value is edge:left.</description>
			<seealso>
				<ref>setvertalign</ref>
				<ref>sethorizalign</ref>
				<ref>setvertanchor</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>. The default value is edge:top.</description>
			<seealso>
				<ref>setvertalign</ref>
				<ref>sethorizalign</ref>
				<ref>sethorizanchor</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>
			</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.</description>
			<seealso>
				<ref>sethorizalign</ref>
				<ref>setvertalign</ref>
				<ref>sethorizanchor</ref>
				<ref>setvertanchor</ref>
			</seealso>
		</command>
		<command id="setslicevisible">
			<canon>set slice visible (handle, vis)</canon>
			<shortname>set slice visible</shortname>
			<description>Makes slice <p>handle</p> invisible or visible, according to <p>vis</p>. 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 visibilty 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 child of an invisible parent or grandparent.</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>
		<command id="freeslice">
			<canon>free slice (handle)</canon>
			<shortname>free slice</shortname>
			<description>Unloads a slice and any child slices. This works on any type of slice. This removes the slice from the screen and removes it from memory. You should free your slices after you are completely done with them.</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="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="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, begin
   # do an operation on each sprite
 end
 sl := next sibling(sl)
end
</example>
			<seealso>
				<ref>previoussibling</ref>
				<ref>nextspritesibling</ref>
				<ref>nextrectsibling</ref>
				<ref>nextcontainersibling</ref>
				<ref>slicechild</ref>
				<ref>freeslice</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>
				<ref>freeslice</ref>
				<ref>slicetofront</ref>
				<ref>slicetoback</ref>
				<ref>movesliceabove</ref>
				<ref>moveslicebelow</ref>
			</seealso>
		</command>
		<command id="firstspritechild">
			<canon>first sprite child(handle)</canon>
			<shortname>first sprite child</shortname>
			<description>Returns a slice handle for the first sprite child of a given slice <p>handle</p>. Returns <p>false</p> if the slice has no sprite children. Children of other types will be ignored. This is useful when looping through sprites.</description>
			<seealso>
				<ref>firstchild</ref>
				<ref>nextspritesibling</ref>
			</seealso>
		</command>
		<command id="nextspritesibling">
			<canon>next sprite sibling(handle)</canon>
			<shortname>next sprite sibling</shortname>
			<description>Returns a slice handle for the next sprite sibling of a given slice <p>handle</p>. Returns <p>false</p> if the given slice is the last sprite sibling of its parent. Slices of other types will be ignored. This is useful when looping through sprites.</description>
			<seealso>
				<ref>firstspritechild</ref>
				<ref>nextsibling</ref>
			</seealso>
		</command>
		<command id="firstrectchild">
			<canon>first rect child(handle)</canon>
			<shortname>first rect child</shortname>
			<description>Returns a slice handle for the first rect child of a given slice <p>handle</p>. Returns <p>false</p> if the slice has no rect children. Children of other types will be ignored. This is useful when looping through rects.</description>
			<seealso>
				<ref>firstchild</ref>
				<ref>nextrectsibling</ref>
			</seealso>
		</command>
		<command id="nextrectsibling">
			<canon>next rect sibling(handle)</canon>
			<shortname>next rect sibling</shortname>
			<description>Returns a slice handle for the next rect sibling of a given slice <p>handle</p>. Returns <p>false</p> if the given slice is the last rect sibling of its parent. Slices of other types will be ignored. This is useful when looping through rects.</description>
			<seealso>
				<ref>firstrectchild</ref>
				<ref>nextsibling</ref>
			</seealso>
		</command>
		<command id="firstcontainerchild">
			<canon>first container child(handle)</canon>
			<shortname>first container child</shortname>
			<description>Returns a slice handle for the first container child of a given slice <p>handle</p>. Returns <p>false</p> if the slice has no container children. Children of other types will be ignored. This is useful when looping through containers.</description>
			<seealso>
				<ref>firstchild</ref>
				<ref>nextcontainersibling</ref>
			</seealso>
		</command>
		<command id="nextcontainersibling">
			<canon>next container sibling(handle)</canon>
			<shortname>next container sibling</shortname>
			<description>Returns a slice handle for the next container sibling of a given slice <p>handle</p>. Returns <p>false</p> if the given slice is the last container sibling of its parent. Slices of other types will be ignored. This is useful when looping through containers.</description>
			<seealso>
				<ref>firstcontainerchild</ref>
				<ref>nextsibling</ref>
			</seealso>
		</command>
		<command id="parentslice">
			<canon>parent slice (handle)</canon>
			<shortname>parent slice</shortname>
			<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>checkparentage</ref>
				<ref>slicechild</ref>
			</seealso>
		</command>
		<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.</description>
			<seealso>
				<ref>parentslice</ref>
				<ref>checkparentage</ref>
				<ref>slicechild</ref>
			</seealso>
		</command>
		<command id="checkparentage">
			<canon>check parentage (handle, parent handle)</canon>
			<shortname>check parentage</shortname>
			<description>Checks to see if <p>handle</p> is a child (or grandchild, or great-grandchild, etc...) of <p>parent handle</p>. Returns <ref>true</ref> or <ref>false</ref>.</description>
			<seealso>
				<ref>parentslice</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="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>
		<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="setsliceextra">
			<canon>set slice extra (handle, extra, value)</canon>
			<shortname>set slice extra</shortname>
			<description>Sets one of three extra data variables that every slice has, on the slice <p>handle</p>. <p>extra</p> is a number from 0 to 2 which indicates which extra data field to write  (you may also use the constants <p>extra 0</p>, <p>extra 1</p>, <p>extra 2</p>). The extra data has no meaning to the slice, it is only for use by scripts.</description>
			<seealso>
				<ref>getsliceextra</ref>
			</seealso>
		</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 a number from 0 to 2 which indicates which extra data field to read.</description>
		</command>
		<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 a -1 if the rect is not using a standard style.</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 style it uses. The <p>style</p> should be a number from 0 to 14 representing a text box style.</description>
			<seealso>
				<ref>getrectstyle</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. 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. 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 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 the old simple line border only, or <p>border:none</p> for no border at all.</description>
			<seealso>
				<ref>setrectborder</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 number from 0 to 14 representing a text box border style, or <p>border:line</p> for the old simple line border only, or <p>border:none</p> for no border at all.</description>
			<seealso>
				<ref>getrectborder</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 one of: the constant <p>trans:fuzzy</p> if it is drawn semi-transparent, <p>trans:hollow</p> if it is fully transparent, or <p>trans:solid</p> (equal to <ref>false</ref>) if it is drawn solid.</description>
			<seealso>
				<ref>setrecttrans</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 transparently it is drawn. For <p>transparency setting</p>, pass in one of the constants <p>trans:fuzzy</p> for semi-transparency (checkered), <p>trans:hollow</p> for fully transparent (the border drawn only), or <p>trans:solid</p> (equal to <ref>false</ref>) for solid.</description>
			<seealso>
				<ref>getrecttrans</ref>
			</seealso>
		</command>
		<command id="createtext">
			<canon>create text</canon>
			<shortname>create text</shortname>
			<description>Creates a new blank text slice and returns a handle to it. A text slice holds a string of text, but it can be positioned and handled just like any other slice. Use the <ref>setslicetext</ref> command to copy a string into the text slice.</description>
			<seealso>
				<ref>setslicetext</ref>
			</seealso>
		</command>
		<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>.</description>
			<seealso>
				<ref>createtext</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>
		<command id="creategrid">
			<canon>create grid (width, height, rows, columns)</canon>
			<shortname>create grid</shortname>
			<description>Creates a new grid slice, and returns an handle to it. Grid slices are special containers that automatically arrange their children into rows and columns. No manual child positioning is required. The first two arguments are the width and height of the whole grid. The next two arguments are the number of rows and columns that should appear in the grid. If rows or columns are left out, the grid with be a boring 1x1.</description>
		</command>
		<command id="sliceisgrid">
			<canon>slice is grid (handle)</canon>
			<shortname>slice is grid</shortname>
			<description>Return true if the <p>handle</p> is a grid slice, or false if it is any other type of slice.</description>
		</command>
		<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.</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.</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>gridisshown</ref>
			</seealso>
		</command>
		<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 collides with a 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></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 they collide with one another. Parent/child relationships have nothing to do with this test; it does not matter if the slices are related.</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>. Parent/child relationships have nothing to do with this test; it does not matter if the slices are related.</description>
			<seealso>
				<ref>slicecollide</ref>
			</seealso>
		</command>
		<command id="sliceatpixel">
			<canon>slice at pixel (parent, x, y, number, check descendants)</canon>
			<shortname>slice at pixel</shortname>
			<description>Searches through all the descendants of <p>parent</p> for slices containing the given <p>x</p>, <p>y</p> pixel screen position. To search all your slices, you can normally use <ref>spritelayer</ref> as <p>parent</p>. <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. slice at pixel returns 0 if you pass too high a <p>number</p>. If you pass <ref>getcount</ref> as <p>number</p> the number of slices at that pixel 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. This command never returns Special slices, such as the sprite layer slice.</description>
			<seealso>
				<ref>slicecollidepoint</ref>
				<ref>findcollidingslice</ref>
			</seealso>
		</command>
		<command id="findcollidingslice">
			<canon>find colliding slice (parent, slice, number, check descendants)</canon>
			<shortname>find colliding slice</shortname>
			<description>Searches through all the descendants of <p>parent</p> for slices colliding with the given <p>slice</p> (by screen position). To search all your slices, you can normally use <ref>spritelayer</ref> as <p>parent</p>. <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. slice at pixel returns 0 if you pass too high a <p>number</p>. If you pass <ref>getcount</ref> as <p>number</p> the number of slices at that pixel 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. This command never returns Special slices, such as the sprite layer slice, and ignores collisions with the children of <p>slice</p>.</description>
			<seealso>
				<ref>sliceatpixel</ref>
				<ref>slicecollide</ref>
			</seealso>
		</command>
		<command id="clampslice">
			<canon>clamp slice (handle1, handle2)</canon>
			<shortname>clamp slice</shortname>
			<description>Try to move the slice <p>handle1</p> so that its screen position will be inside the screen position of slice <p>handle2</p>. The size of the slices will not be changed. It does not matter if the slices are related.</description>
			<seealso>
				<ref>slicecontains</ref>
			</seealso>
		</command>
		<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>
		<command id="fillparent">
			<canon>fill parent (handle, true_or_false)</canon>
			<shortname>fill parent</shortname>
			<description>Make a slice <p>handle</p> automatically fill its parent. This will change the position and size of the slice so that it completely fills the parent (minus the parent's padding). You can also disable filling with this command by passing <p>false</p> as the second argument, such as <p>fill parent(handle, false)</p>. If a slice is filling its parent, then any commands which modify the width or height of the slice will fail. You should resize the parent instead. This command only works on rects and containers. It will not work on sprites because they cannot change size.</description>
			<seealso>
				<ref>isfillingparent</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 sprite slice handles because sprites cannot be set to fill parent.</description>
			<seealso>
				<ref>fillparent</ref>
			</seealso>
		</command>
	</section>
	<section title="Misc Functions">
		<command id="random">
			<canon>random (lownumber, highnumber)</canon>
			<shortname>random</shortname>
			<description>Returns a random number in the range of the two numbers. The returned value will be greater than or equal to the first number, and less than or equal to the second number</description>
		</command>
		<command id="seedrandom">
			<canon>seed random (new seed)</canon>
			<shortname>seedrandom</shortname>
			<description>Reseeds the random number generator. If called with no argument, this will reseed the random number generator to a new random sequence. If you pass in a number (other than 0), the random number generator will be seeded with that number, allowing for repeatable random sequences.</description>
			<seealso>
				<ref>random</ref>
			</seealso>
		</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, 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 and item slot, use -1 as the item ID</description>
			<seealso>
				<ref>iteminslot</ref>
				<ref>itemcountinslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</ref>
			</seealso>
		</command>
		<command id="itemcountinslot">
			<canon>item count in slot (slot)</canon>
			<shortname>item count in slot</shortname>
			<description>Return a the count of items at a specific slot in your inventory, or 0 if that slot is empty. Slots are numbered from 0 to <ref>getinventorysize</ref>-1.</description>
			<seealso>
				<ref>iteminslot</ref>
				<ref>setiteminslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</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 to 99, or 0 if you want to delete any items currently in the slot. If the slot is empty, this command will fail.</description>
			<seealso>
				<ref>iteminslot</ref>
				<ref>setiteminslot</ref>
				<ref>setitemcountinslot</ref>
				<ref>getinventorysize</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 <ref>zero</ref> 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="getinventorysize">
			<canon>get inventory size</canon>
			<shortname>get inventory size</shortname>
			<description>Returns the number of inventory slots.</description>
		</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>
		</command>
		<command id="leader">
			<canon>leader</canon>
			<shortname>leader</shortname>
			<description>Returns the hero ID number (as given in the Edit Hero Stats menu) of the current caterpillar party leader.</description>
		</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="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="herodirection">
			<canon>hero direction (who)</canon>
			<shortname>hero direction</shortname>
			<description>Returns the specified hero&apos;s direction.</description>
		</command>
		<command id="heroframe">
			<canon>hero frame (who)</canon>
			<shortname>hero frame</shortname>
			<description>Returns the walking frame (0 or 1) of the specified hero.</description>
		</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="npcdirection">
			<canon>NPC direction (who)</canon>
			<shortname>NPC direction</shortname>
			<description>Returns the specified NPC&apos;s direction.</description>
		</command>
		<command id="npcframe">
			<canon>NPC frame (who)</canon>
			<shortname>NPC frame</shortname>
			<description>Returns the walking frame (0 or 1) of the specified NPC.</description>
		</command>
		<command id="npcextra">
			<canon>NPC extra (who, which)</canon>
			<shortname>NPC extra</shortname>
			<description>Returns the npc instance-specific extra data field requested in <p>which</p>, a number from 0 to 2. You may use the constants <p>extra 0</p>, <p>extra 1</p> and <p>extra 2</p> to refer to them. If you use an NPC ID for <p>who</p>, the first instance's data will be used.</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 the npc instance-specific extra data field requested in <p>which</p>, a number from 0 to 2. You may use the constants <p>extra 0</p>, <p>extra 1</p> and <p>extra 2</p> to refer to them.  If you use an NPC ID for <p>who</p>, the first instance's data will be used.<note>Unlike other NPC instance data, the extra data for NPCs on the current map is not saved in save games! However, it is saved in mapstate NPC saves (see <ref>savemapstate</ref>)</note></description>
			<seealso>
				<ref>npcextra</ref>
			</seealso>
		</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 <ref>zero</ref> or <ref>false</ref> if there is no room.</description>
		</command>
		<command id="currentmap">
			<canon>current map</canon>
			<shortname>current map</shortname>
			<description>Returns the number of the current map.</description>
		</command>
		<command id="mapwidth">
			<canon>map width</canon>
			<shortname>map width</shortname>
			<description>Returns the width of the map in tiles.</description>
		</command>
		<command id="mapheight">
			<canon>map height</canon>
			<shortname>map height</shortname>
			<description>Returns the height of the map in tiles.</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="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>
		<command id="keyispressed">
			<canon>key is pressed (scancode)</canon>
			<shortname>key is pressed</shortname>
			<description>Returns <ref>true</ref> if the keyboard key with the specified scancode is being pressed (either held down or pressed since last tick), or <ref>false</ref> if it is not. The argument is a scancode, NOT the <ref>upkey</ref>, <ref>downkey</ref>, etc used with <ref>waitforkey</ref>. I have provided an extra include file, SCANCODE.HSI that you can use to define friendly names for all the scancodes.<lb/>
			    Keyboard scan codes:
          <ul><li>00</li><li>01 ESC</li><li>02 1</li><li>03 2</li><li>04 3</li><li>05 4</li><li>06 5</li><li>07 6</li><li>08 7</li><li>09 8</li><li>10 9</li><li>11 0</li><li>12 - _</li><li>13 = +</li><li>14 BACKSPACE</li><li>15 TAB</li><li>16 Q</li><li>17 W</li><li>18 E</li><li>19 R</li><li>20 T</li><li>21 Y</li><li>22 U</li><li>23 I</li><li>24 O</li><li>25 P</li><li>26 [ {</li><li>27 ] }</li><li>28 ENTER</li><li>29 CTRL</li><li>30 A</li><li>31 S</li><li>32 D</li><li>33 F</li><li>34 G</li><li>35 H</li><li>36 J</li><li>37 K</li><li>38 L</li><li>39 ; :</li><li>40 &quot; &apos;</li><li>41 ` ~</li><li>42 LEFT SHIFT</li><li>43 \ |</li><li>44 Z</li><li>45 X</li><li>46 C</li><li>47 V</li><li>48 B</li><li>49 N</li><li>50 M</li><li>51 , &lt;</li><li>52 . ></li><li>53 / ?</li><li>54 RIGHT SHIFT</li><li>55 PRINT SCREEN *</li><li>56 ALT</li><li>57 SPACE</li><li>58 CAPSLOCK</li><li>59 F1</li><li>60 F2</li><li>61 F3</li><li>62 F4</li><li>63 F5</li><li>64 F6</li><li>65 F7</li><li>66 F8</li><li>67 F9</li><li>68 F10</li><li>69 NUMLOCK</li><li>70 SCROLL LOCK</li><li>71 HOME 7</li><li>72 UP 8</li><li>73 PAGEUP 9</li><li>74 KEYPAD -</li><li>75 LEFT 4</li><li>76 KEYPAD 5</li><li>77 RIGHT 6</li><li>78 KEYPAD +</li><li>79 END 1</li><li>80 DOWN 2</li><li>81 PAGEDOWN 3</li><li>82 INSERT 0</li><li>83 DEL .</li><li>84</li><li>85</li><li>86</li><li>87 F11</li><li>88 F12</li><li>89</li><li>90</li><li>91 L WIN LOGO</li><li>92 R WIN LOGO</li><li>93 CONTEXT</li></ul><lb/>
          Joystick scan codes:
          <ul><li>128 BUTTON 1</li><li>129 BUTTON 2</li><li>130-143 BUTTON 3-16</li><li>144 X LEFT</li><li>145 X RIGHT</li><li>146 Y UP</li><li>147 Y DOWN</li></ul>
          <note>You can NOT wait for the player to press a key by continually polling <p>key is pressed</p> unless you stick a <ref>wait</ref> in your do loop. That's because <p>key is pressed</p> does not return real time data, but the state of the keyboard at the beginning of the current game tick.</note></description>
			<seealso>
				<ref>keyval</ref>
			</seealso>
		</command>
		<command id="keyval">
			<canon>keyval (scancode)</canon>
			<shortname>keyval</shortname>
			<description>Returns a bitmask for the state of the specified key. The argument is a scancode, see <ref>keyispressed</ref>. The first (least significant) bit is whether the key was depressed at the beginning of the current tick. The second bit is whether the key was pushed down by the player since the start of the previous tick (or when the key starts to repeatedly trigger after being held down for a while). It can therefore return 0, 1, 2 or 3: <lb/><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)
			<danger>Just like <ref>keyispressed</ref>, this command does not return real time data, but the situation at the beginning of the current game tick.</danger>
			<note>The joystick scancodes described in <ref>keyispressed</ref> do not work in this command.</note></description>
			<seealso>
				<ref>keyispressed</ref>
			</seealso>
		</command>
		<command id="lastascii">
			<canon>last ascii</canon>
			<shortname>last ascii</shortname>
			<description>Returns the ascii code of any currently pressed key. If more than one key corresponding to an ascii character is being pressed, then only one can be returned.</description>
		</command>
		<command id="joystickbutton">
			<canon>joystick button (button,joystick)</canon>
			<shortname>joystick button</shortname>
			<description>Returns <ref>true</ref> or <ref>false</ref> depending on whether button #<p>button</p> on joystick #<p>joystick</p> is pressed. <p>button</p> can be from 1-16 (assuming the joystick has that many buttons), and <p>joystick</p> can be from 0-7. Most of the time, you will want to use joystick #0, so that is what <p>joystick</p> defaults to.</description>
		</command>
		<command id="joystickaxis">
			<canon>joystick axis (axis,multiplier,joystick)</canon>
			<shortname>joystick axis</shortname>
			<description>Returns the position of the joystick along the X or Y axis on joystick #<p>joystick</p>. <p>axis</p> can be one of the constants <ref>xaxis</ref> or <ref>yaxis</ref>. <p>multiplier</p> is slightly complicated: The position of the joystick is actually a decimal between -1 and 1. Since plotscripting can't handle decimals, this position must be multiplied and rounded off until it is within plotscripting's capabilities. By default, it is 100 (so it will return -100 - 100). <p>joystick</p> can be from 0-7. Most of the time, you will want to use joystick #0, so that is what <p>joystick</p> defaults to.</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="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="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="pickhero">
			<canon>pick hero</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.</description>
		</command>
		<command id="renamehero">
			<canon>rename hero(who)</canon>
			<shortname>rename hero</shortname>
			<description>Pops up a name-editing box that allows you to change a hero&apos;s name. The argument is the hero&apos;s ID number, or name in the format hero:name</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 a hero&apos;s name. The argument is the hero&apos;s position in the party as returned by <ref>findhero</ref></description>
		</command>
		<command id="lastsaveslot">
			<canon>last save slot</canon>
			<shortname>last save slot</shortname>
			<description>Returns the last save slot saved in, or <ref>false</ref> if the game has not been saved yet. Save slots are numbered starting at 1.</description>
			<seealso>
				<ref>saveinslot</ref>
				<ref>savemenu</ref>
			</seealso>
		</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. Use if you, for example, don&apos;t want to overwrite a saved game with <ref>saveinslot</ref>.</description>
		</command>
		<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 targetted this hero (or the active battle party if the hero is in it) - 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>
		<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)</canon>
			<shortname>experience to level</shortname>
			<description>Returns the total experience required to reach a specified level from level 0.</description>
		</command>
		<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. 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, or specify a plotscript (in the form "@my script") to have that run. A plotscript will get passed the id of the timer that triggered it as its first argument, if it has one. If the timer runs out during a battle then the effect happens after the battle ends.<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 or <ref>add</ref>ing them together): <ul><li><ref>timerflag:battle</ref> to have it count down during battles (not including menus which pause the battle)</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), the in-battle pause button doesn't count</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 game saves.</note></description>
			<seealso>
				<ref>stoptimer</ref>
				<ref>readtimer</ref>
				<ref>systemsecond</ref>
				<ref>secondsofplay</ref>
				<ref>milliseconds</ref>
				<ref>runscriptbyid</ref>
			</seealso>
			<example>#this starts a 300 second (5 minute) timer that counts down once every 18 ticks (a 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)</example>
		</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.</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.</description>
			<seealso><ref>settimer</ref></seealso>
		</command>
	</section>
	<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. 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 also defined in your HSI file in the form stat:name. </description>
			<seealso>
				<ref>setenemystat</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 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 also defined in your HSI file in the form stat:name. The third is the new value of the stat.<note>Enemy stat changes are temporary. They are not saved in the game save.</note></description>
			<seealso>
				<ref>getenemystat</ref>
				<ref>getherostat</ref>
				<ref>setherostat</ref>
			</seealso>
		</command>
		<command id="getenemyname">
			<canon>get enemy name (enemyid, stringid)</canon>
			<shortname>get enemy name</shortname>
			<description>Lets you use the enemy name in a string. The first argument is the number of the enemy you want to get the name from, second argument is the number of the string that you want to store the name of the enemy.</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 set the enemy name from a string, the string length cannot be more then 16 characters, if it is more then 16 the name will be truncated.  The first argument is the number of the enemy's name you want to change, second argument is the number of the string that you supply the name of the enemy from.<note>Enemy name changes are temporary. They are not saved in the game save.</note></description>
			<seealso>
				<ref>getenemyname</ref>
			</seealso>
		</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. Enemyid is the enemy number that you want to return the appearance of, appearance is either picture, palette, or size. You can use the following constants for appearance: <ul><li>enemy:picture</li><li>enemy:palette</li><li>enemy:picturesize</li></ul> <lb/>You can compare the values returned from enemy:picturesize with the constants enemysize:small, enemysize:medium and enemysize:large</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.  Enemyid is the number of the enemy's appearance that you want to change, appearance is one of the constants given in <ref>getenemyappearance</ref>. Value can is the new number that you want to assign, constants enemysize:small, enemysize:medium, or enemysize:large when changing picture size, or palette number when changing palette.<note>Enemy appearance changes are temporary. They are not saved in the save game.</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. Enemyid is the number of enemy, data is a predefined constant for the data you want to change. Value is the new value given to that setting. Use the same constants as are given at <ref>readenemydata</ref>.<note>Enemy data changes are temporary. They are not saved in saved games.</note></description>
			<seealso>
				<ref>readenemydata</ref>
			</seealso>
		</command>
		<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>. <p>x</p> (up to 230) and <p>y</p> (up to 199) give the position of the center of the bottom edge of the enemy - approximately where it appears to stand. <p>slot</p> (0 to 7) is an optional argument, if given then the enemy is created in the suggested slot if empty. Otherwise it's 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>Searchs 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 enemies 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 enemies 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, background)</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="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>
		</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).</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 99) of a <p>formation set</p> (1 to 255). Note that the frequency is not actually a probability (as a percentage) of a battle occuring each step, but is roughly the number of battles per 80 steps, spaced semi-randomly.</description>
			<seealso>
				<ref>randomformation</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>
	<section title="Tweaking Maps">
		<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 can be 0, 1, or 2. The bottom layer will be read by default.</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 can be 0, 1, or 2. The bottom layer will be written to by default</description>
		</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 X,Y 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. For example:  </description>
			<example>  variable (pass)
  pass := read pass block(hero X(me),hero Y(me))
  if (pass,and,harm tile) then begin
    # this checks if the hero is standing
    # on a harm tile
  end</example>
		</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 X,Y position on the current map. This change will only persist until you leave the map or fight a battle. The value is a number from from 0 to 255 that consists of eight flag bits.<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. 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</example>
		</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 affects tilesets for all layers that are set to 'Tileset: default'. This effectively changes the map's tileset if you haven't done anything fancy with layer tilesets.<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 (0-2) 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 powerful command for this.</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 load tileset, 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 default tileset. <p>layer</p> is the layer number (0-2) to change, or the constant <p>tileset:default</p> which changes the default tileset. It defaults to <p>tileset:default</p> if omitted. <p>change tileset</p> with no arguments restores the set tilesets after using load tileset. </description>
			<seealso>
				<ref>getmaptileset</ref>
				<ref>layertileset</ref>
			</seealso>
		</command>
		<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>
	</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>
	</section>
	<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/>You should normally set variables by writing <p>variable := value</p> but for backwards compatability, you can also use the old form <p>set variable(variable, value)</p></description>
		</command>
		<command id="increment">
			<canon>increment (variable,amount)</canon>
			<shortname>increment</shortname>
			<description>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/>You can also increment variables by writing variable += amount</description>
		</command>
		<command id="decrement">
			<canon>decrement (variable,amount)</canon>
			<shortname>decrement</shortname>
			<description>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/>You can also decrement variables by writing variable -= amount</description>
		</command>
	</section>
	<section title="Math, Comparison, and Logic Operators">
		<description>Pre-December 1999 versions of HamsterSpeak used a different syntax for math. For more information, see the HamsterSpeak Specification</description>
		<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 add(number,number)</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 neccisary to use the double minus so that HSPEAK.EXE can tell the difference between subtraction, and a minus sign that indicates a negative number. You can also write subtract(number,number)</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 multiply(number,number)</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 divide(number,number)</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 modulus(number,number)</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 exponent(number,power)</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 equal(number,number)</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 not equal(number,number)</description>
		</command>
		<command id="lessthan">
			<canon>number &lt;&lt; number</canon>
			<shortname>&lt;&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 less than(number,number)</description>
		</command>
		<command id="greaterthan">
			<canon>number &gt;&gt; number</canon>
			<shortname>&gt;&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 greater than(number,number)</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 less than or equal to(number,number)</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 greater than or equal to(number,number)</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>
	</section>
	<section title="Flow Control">
		<command id="begin">
			<canon>begin,other commands,end</canon>
			<shortname>begin</shortname>
			<description>Begin is a synonym for ( and end is a synonym for ). Parenthesis are normally used for bracketing things that all fit on the same line, and begin/end statements are often used to enclose very long things such as whole scripts or long flow control blocks that take up several lines. For example, the following two blocks of code are identical:</description>
			<example>if (check tag(2)) then (show text box (5),wait for text box)</example>
			<example>if (check tag(2)) then
begin
	show text box (5)
	wait for text box
end</example>
		</command>
		<command id="end">
			<alias>begin</alias>
			<shortname>end</shortname>
		</command>
		<command id="if">
			<canon>if(condition) then(commands) else(commands)</canon>
			<shortname>if</shortname>
			<description>The if statement checks the value of its condition, and if the value is <ref>true</ref>, it runs the commands in the then block. If the value is <ref>false</ref>, it runs the commands in its else block. The conditional is usually an equality operator such as <ref>equal</ref> or <ref>notequal</ref>, or it is a <ref>checktag</ref> command. The else is optional as long as you have a then, and the then is optional as long as you have an else. There are some examples of if statements in the HamsterSpeak Specification, and in WANDERP.HSS</description>
		</command>
		<command id="then">
			<alias>if</alias>
			<shortname>then</shortname>
		</command>
		<command id="else">
			<alias>if</alias>
			<shortname>else</shortname>
		</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> it runs the commands in the do block. It keeps checking the conditional and runs the do block over and over again until the conditional returns <ref>false</ref>. The conditional is usually an equality operator such as <ref>equal</ref> or <ref>notequal</ref>, or it is a check tag command.</description>
		</command>
		<command id="do">
			<canon>do</canon>
			<shortname>do</shortname>
			<description />
			<seealso>
				<ref>while</ref>
				<ref>for</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. There are examples of for commands in WANDERP.HSS</description>
		</command>
		<command id="return">
			<canon>return(value)</canon>
			<shortname>return</shortname>
			<description>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 a 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 the wait was cancelled by a keypress.
  # or false (0) if the wait finished uninterrupted.
  variable(i)
  for(i, 1, ticks) do, begin
    wait(1)
    if(key is pressed(key:ENTER)) then(return(true))
    if(key is pressed(key:SPACE)) then(return(true))
    if(key is pressed(key:CTRL)) then(return(true))
    if(key is pressed(key:ALT)) then(return(true))
    if(key is pressed(key:ESC)) then(return(true))
    if(key is pressed(joy:button 1)) then(return(true))
    if(key is pressed(joy:button 2)) then(return(true))
  end
end

plotscript, usage example, begin
  show text box(5) # let all volunteers take one step forward!
  if(key wait(40)) then(
    walk hero(me, north, 1)
    wait for hero(me)
    show text box(6) # You there! I saw you move! You volunteer!
  )else(
    show text box(7) # a bunch of lily livered cowards, eh?
  )
end
</example>
			</description>
			<seealso>
				<ref>exitreturning</ref>
			</seealso>
		</command>
		<command id="exitreturning">
			<canon>exit returning(value)</canon>
			<shortname>exit returning</shortname>
			<added>ubersetzung</added>
			<description>Sets the value to be returned by the script, and exits the script. This is only useful when the script has been called as a function from another script.
<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(key:ENTER)) then(exit returning(true))
    if(key is pressed(key:SPACE)) then(exit returning(true))
    if(key is pressed(key:CTRL)) then(exit returning(true))
    if(key is pressed(key:ALT)) then(exit returning(true))
    if(key is pressed(key:ESC)) then(exit returning(true))
    if(key is pressed(joy:button 1)) then(exit returning(true))
    if(key is pressed(joy:button 2)) then(exit returning(true))
  end
  exit returning(false)
end

plotscript, usage example, begin
  show text box(5) # let all volunteers take one step forward!
  if(key wait(40)) then(
    walk hero(me, north, 1)
    wait for hero(me)
    show text box(6) # You there! I saw you move! You volunteer!
  )else(
    show text box(7) # a bunch of lily livered cowards, eh?
  )
end
</example>
The <p>exit returning</p> command works exactly the same as the <ref>return</ref> command followed immediately by <ref>exit script</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>
			<shortname>exit script</shortname>
			<added>ubersetzung</added>
			<description>Causes the script to end immediately</description>
			<seealso>
				<ref>exitreturning</ref>
			</seealso>
		</command>
		<command id="break">
			<canon>break</canon>
			<shortname>break</shortname>
			<added>ubersetzung</added>
			<description>breaks out of a <ref>for</ref> or <ref>while</ref> command and continue the script after the end of the <ref>do</ref> block.</description>
		</command>
		<command id="continue">
			<canon>continue</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, continue skips the rest of the do block and continues on to the next loop. When used inside a <ref>switch</ref> statement, continue flows on to the next <ref>case</ref> block</description>
		</command>
		<command id="switch">
			<canon>switch(expression)</canon>
			<shortname>switch</shortname>
			<added>ubersetzung</added>
			<description>select between a number of <ref>case</ref> statements based on the value of an expression.
<example>switch(v) do(
  case(0) do(
    do foo
  )
  case(1) do(
    do bar
  )
  case(2) do(
    do baz
  )
  case(3) do(
    do something else
  )
  case(10) do(
    do yet another thing
  )
)</example>
The select 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. The example below shows how the same switch stattement would be written with if/then/else
<example>if(v == 0) then(
  do foo
)else(
  if(v == 1) then(
    do bar
  )else(
    if(v == 2) then(
      do baz
    )else(
      if(v == 3) then(
        do something else
      )else(
        if(v == 10) then(
          do yet another thing
        )
      )
    )
  )
)</example>
Besides readability, there is one other important difference between these two examples. The switch command only checks the value of v once. the if/the/else method checks v repeatedly, so it could be slower, and could be suceptible to errors if you accidentally change the value of v somewhere in the middle.
		</description>
		<seealso>
			<ref>case</ref>
		</seealso>
		</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="Advanced Commands">
		<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, and the last argument is a constant <ref>insidebattle</ref> or <ref>outsidebattle</ref>, which determines if you are changing the hero's battle picture or their walkabout picture. If the last argument is left out, <ref>outsidebattle</ref> is assumed.</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>, which determines if you are changing the hero's battle palette or their walkabout 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>, which determines if you are checking the hero's battle picture or their walkabout picture. 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>, which determines if you are checking the hero's battle palette or their walkabout 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>, which determines if you are changing the hero's battle picture or their walkabout picture. If the last argument is left out, <ref>outsidebattle</ref> is assumed.</description>
			<seealso>
				<ref>setheropicture</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>, which determines if you are changing the hero's battle palette or their walkabout palette. If the last argument is left out, <ref>outsidebattle</ref> is assumed.</description>
			<seealso>
				<ref>setheropicture</ref>
			</seealso>
		</command>
		<command id="alternpc">
			<canon>alter NPC (who,NPCstat,value)</canon>
			<shortname>alter NPC</shortname>
			<description>Changes the stats of an NPC type. Constants for this command have been included in PLOTSCR.HSD. Alter NPC can be used for many purposes.<lb/>
<ul><li>Alter NPC (who,NPCstat:picture,picture number)</li><li>Alter NPC (who,NPCstat:palette,palette number)</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</li><li>NPCmovetype:avoidyou</li><li>NPCmovetype:walkinplace</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 when activated 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:script,script ID)</li><li>Alter NPC (who,NPCstat:script argument,number)</li><li>Alter NPC (who,NPCstat:vehicle,vehicle ID+1)</li></ul>Normally you would only give an NPC ID number to alter NPC, but if you want to use an <ref>npcreference</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/>A good way to make use of Alter NPC is to wrap it in your own script. For example:
		<example># Example AlterNPC wrapper for changing NPC appearance

plotscript,change NPC,who=0,picture=0,palette=0,begin
  Alter NPC(who,NPCstat:picture,picture)
  Alter NPC(who,NPCstat:palette,palette)
end</example>
				<note>If you want to change an NPC's palette back to the default, you can use <p>Alter NPC(who, NPCstat:palette, -1)</p></note>
			</description>
			<seealso>
				<ref>setnpcusable</ref>
				<ref>setnpcmoves</ref>
				<ref>setnpcignoreswalls</ref>
				<ref>setnpcobstructs</ref>
			</seealso>
		</command>
		<command id="readnpc">
			<canon>read NPC (who,NPCstat)</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>. <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="setnpcignoreswalls">
			<canon>set NPC ignores walls (who, value)</canon>
			<shortname>set NPC ignores walls</shortname>
			<description>Given an NPC reference or NPC ID (in which case the first NPC with that ID is used), set whether that NPC can walk through walls. <p>value</p> should be true or false.</description>
			<seealso>
				<ref>getnpcignoreswalls</ref>
			</seealso>
		</command>
		<command id="getnpcignoreswalls">
			<canon>get NPC ignores walls (who)</canon>
			<shortname>get NPC ignores walls</shortname>
			<description>Given an NPC reference or NPC ID (in which case the first NPC with that ID is used), returns whether that NPC can walk through walls.</description>
			<seealso>
				<ref>setnpcignoreswalls</ref>
			</seealso>
		</command>
		<command id="setnpcmoves">
			<canon>set NPC moves (who, value)</canon>
			<shortname>set NPC moves</shortname>
			<description>Given an NPC reference or NPC ID (in which case the first NPC with that ID is used), set whether that NPC moves according to its move-type, or whether it stands still. <p>value</p> should be true or false.</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 NPC reference or NPC ID (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 NPC reference or NPC ID (in which case the first NPC with that ID is used), set whether the NPC should be an obstruction to heroes and other NPCS. If set to false, the NPC can move through heroes and other NPCs and vice-versa. Heroes can always pass through Step-on NPCs. <p>value</p> should be true or false.</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 NPC reference or NPC ID (in which case the first NPC with that ID is used), returns false if that NPC's obstruction has been suspended with <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 NPC reference or NPC ID (in which case the first NPC with that ID is used), set whether the NPC can be activated by the player as normal (as defined in the NPC ID data). <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 NPC reference or NPC ID (in which case the first NPC with that ID is used), returns false if normal activation of that NPC has been suspended with <ref>setnpcusable</ref>. This is always true otherwise, even for NPC types which are not activateable.</description>
			<seealso>
				<ref>setnpcusable</ref>
			</seealso>
		</command>
		<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 is run when you load a saved game. 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.</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 ID number, NOT the script&apos;s name. 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 battle when one is triggered. The argument is the script&apos;s ID number, NOT the script&apos;s name. 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 the ID number of script that is run instead of battles.</description>
		</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 flashs 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 heroes or the default of beneath. The effect goes away if you change maps or fight a battle.</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>
		<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 defined in your HSI file in the format hero:name for the ID number of the hero (as it has in the Edit Hero Stats menu). Not only does this tell you if a hero is in your party, but you can also use it to tell whether or not the hero is in your active party. find hero will return 0, 1, 2 or 3 if the hero is in the active party, and 4 or higher if the hero is in the reserve. Note that position in the battle party is not the same as position in the caterpillar: the leader is not necessarily hero 0. The opposite to find hero is <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 defined in your HSI file in the format hero:name.</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 int the walkabout caterpillar where the hero was found, or -1 if the hero was not found. Use the names defined in your HSI file in the format hero:name. This is particularaly useful if you need to use a command like walk hero 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 defined in your HSI file in the format hero:name.</description>
		</command>
		<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 also define in your HSI file in the form stat:name. The third argument is either <ref>currentstat</ref> or <ref>maximumstat</ref>. If you leave the last argument blank, <ref>currentstat</ref> will be assumed.</description>
			<seealso>
				<ref>setherostat</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 find hero. The second argument is the name of the stat that you want to change. The names of the stats are also define 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>. If you leave the last argument blank, <ref>currentstat</ref> will be assumed.</description>
			<seealso>
				<ref>getherostat</ref>
				<ref>setenemystat</ref>
				<ref>getenemystat</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 find hero. The second argument is the name of the stat that you want to change. The names of the stats are also define 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>. If you leave the last argument blank, <ref>currentstat</ref> will be assumed. Unlike <ref>setherostat</ref>, this command is not allowed to exceed the stat caps.</description>
			<seealso>
				<ref>setherostat</ref>
				<ref>getherostatcap</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. The argument is the stat you want to check, either as a number or using 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>
			</seealso>
		</command>
		<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. Unlike old workarounds, this command teachs the hero any spells they would have learnt by that level and correctly sets the experience to next levelup (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.</description>
			<seealso>
				<ref>setherolevel</ref>
				<ref>totalexperience</ref>
				<ref>herolevelled</ref>
				<ref>spellslearnt</ref>
			</seealso>
		</command>
		<command id="getlevelmp">
			<canon>get level MP (who, mp level slot)</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.</description>
		</command>
		<command id="setlevelmp">
			<canon>set level MP (who, mp level slot, new value)</canon>
			<shortname>get level MP</shortname>
			<description>Changes 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 argument <p>new value</p> is the new number of level MP points. Each point represents one spell from that row.</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>
		<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="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. If the argument is <ref>off</ref> then only the leader will be displayed. If the argument is <ref>on</ref> then the whole party will be displayed. (do not confuse this with the <ref>suspendcaterpillar</ref> and <ref>resumecaterpillar</ref> commands, which only apply when caterpillar mode is ON)</description>
		</command>
		<command id="setnohpleveluprestore">
			<canon>set no HP level up restore (state)</canon>
			<shortname>set no HP level up restore</shortname>
			<description>Sets whether or not a hero regains full HP after a levelup. If the argument is <ref>off</ref> then HP is restored on a levelup. If the argument is <ref>on</ref> then the hero&apos;s HP is not restored on a levelup.</description>
		</command>
		<command id="setnompleveluprestore">
			<canon>set no MP level up restore (state)</canon>
			<shortname>set no MP level up restore</shortname>
			<description>Sets whether or not a hero regains full MP after a levelup. If the argument is <ref>off</ref> then MP is restored on a levelup. If the argument is <ref>on</ref> then the hero&apos;s MP is not restored on a levelup.</description>
		</command>
		<command id="setinnnorevivemode">
			<canon>set inn no revive mode (state)</canon>
			<shortname>set inn no revive mode</shortname>
			<description>Sets whether or not inns restore dead heroes to life. If the argument is <ref>off</ref> then dead heroes are restored by inns. If the argument is <ref>on</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="hidebattlereadymeter">
			<canon>hide battle ready meter (state)</canon>
			<shortname>hide battle ready meter</shortname>
			<description>Sets whether or not the ready meter appears in battle. If the argument is <ref>off</ref> then the ready meter appears. If the argument is <ref>on</ref> then the ready meter will be hidden.</description>
		</command>
		<command id="hidebattlehealthmeter">
			<canon>hide battle health meter (state)</canon>
			<shortname>hide battle health meter</shortname>
			<description>Sets whether or not the health meter appears in battle. If the argument is <ref>off</ref> then the health meter appears. If the argument is <ref>on</ref> then the health meter will be hidden.</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="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>off</ref> then only living heroes gain experience. If the argument is <ref>on</ref> then dead heroes get it too.</description>
		</command>
		<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="autosave">
			<canon>autosave</canon>
			<shortname>autosave</shortname>
			<description>Transparently saves the game to the last save slot used, or if the game has not been saved yet, calls <ref>savemenu</ref>. Returns the number of the last save slot, 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 32, where only 1 to 4 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)</canon>
			<shortname>load from slot</shortname>
			<description>Loads a saved game from a save slot (where <p>slot</p> is a slot number from 1 to 32, slots 5-32 are hidden) as if it had been loaded from the load game menu. This command will end the current game if it successfully loads. If the load fails because the slot has never been saved in, the script will continue.</description>
		</command>
		<command id="deletesave">
			<canon>delete save (slot)</canon>
			<shortname>delete save</shortname>
			<description>Deletes a saved game in the specified save slot (1 to 32, only 1 to 4 appear on the builtin menus). The save will no longer be visible on the load game menu or loadable with <ref>loadfromslot</ref>. However, <ref>importglobals</ref> can still be used to read globals out of the slot.</description>
			<seealso>
				<ref>saveinslot</ref>
			</seealso>
		</command>
		<command id="importglobals">
			<canon>import globals (slot, first, last)</canon>
			<shortname>import globals</shortname>
			<description>and<lb/><p>import globals (slot, id)</p><lb/>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 32. Note that only slots 1-4 appear 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. 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 'var := import globals (slot, id)'<lb/>This is NOT the same thing as 'import globals (slot, id, id)', which does modify the global variable.<lb/>import globals 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, like in the following example:</description>
			<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>
			<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 32. Note that only slots 1-4 appear 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. <p>first</p> defaults to 0, and <p>last</p> defaults to 4095. 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, however you will still be able to read them with <ref>importglobals</ref>.</note><note>Unlike importglobals, 'export globals (slot, first)' does NOT export a single global variable!</note></description>
			<seealso>
				<ref>importglobals</ref>
				<ref>writeglobal</ref>
			</seealso>
		</command>
		<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> allows you to run a script using its ID. The advantage of this 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. Arguments after the ID will be passed to the script. The script can also return a value as normal. A runtime error is displayed and -1 is returned if the script does not exist. You can pass up to 31 arguments to the script.<note>No check on the correct number of arguments can be performed, so default arguments are not used.</note></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>
		</command>
		<command id="getdamagecap">
			<canon>get damage cap</canon>
			<shortname>get damage cap</shortname>
			<description>Returns the current damage cap, or 0 if 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="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>
			<shortname>trace value</shortname>
			<description>Prints one or more expressions and their values to "g_debug.txt". The number of arguments to this command is variable; each is printed as source text along with its value. You can't print strings with this command; use <ref>trace</ref> instead.</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>
		</command>
		<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</li><li>mapstate:mapsettings</li><li>mapstate:npclocations</li><li>mapstate:npcdefinitions</li><li>mapstate:tilemap</li><li>mapstate:passmap</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 tileset, ambient music, footoffset, map trigger scripts, and so forth.</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. 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)</canon>
			<shortname>delete map state</shortname>
			<description>Deletes temporary map state files for the current map, so that if the map is set to load NPC or tile data it will load the original data from the game files when it is entered. <p>whichdata</p> is a set of bits in the <ref>savemapstate</ref> format to determine what exactly to delete. The default is mapstate:all.</description>
		</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>
		<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 uptime or any random value).</description>
		</command>
	</section>
	<section title="Predefined Constants">
		<command id="numericconstants">
			<canon>Numeric Constants</canon>
			<shortname>Numeric Constants</shortname>
			<description>PLOTSCR.HSD defines constants for the numbers from 0 to 10. you can use these constants to make your scripts look friendly :)<lb />zero, one, two, three, four, five, six, seven, eight, nine, ten</description>
		</command>
		<command id="zero">
			<alias>numericconstants</alias>
			<shortname>zero</shortname>
		</command>
		<command id="one">
			<alias>numericconstants</alias>
			<shortname>one</shortname>
		</command>
		<command id="two">
			<alias>numericconstants</alias>
			<shortname>two</shortname>
		</command>
		<command id="three">
			<alias>numericconstants</alias>
			<shortname>three</shortname>
		</command>
		<command id="four">
			<alias>numericconstants</alias>
			<shortname>four</shortname>
		</command>
		<command id="five">
			<alias>numericconstants</alias>
			<shortname>five</shortname>
		</command>
		<command id="six">
			<alias>numericconstants</alias>
			<shortname>six</shortname>
		</command>
		<command id="seven">
			<alias>numericconstants</alias>
			<shortname>seven</shortname>
		</command>
		<command id="eight">
			<alias>numericconstants</alias>
			<shortname>eight</shortname>
		</command>
		<command id="nine">
			<alias>numericconstants</alias>
			<shortname>nine</shortname>
		</command>
		<command id="ten">
			<alias>numericconstants</alias>
			<shortname>nine</shortname>
		</command>
		<command id="keyconstants">
			<canon>Key Constants</canon>
			<shortname>Key Constants</shortname>
			<description>PLOTSCR.HSD defines constants that correspond to each of the usable keys (or joystick buttons) that the player can press while playing. These are useful with the <ref>waitforkey</ref> command.<lb />any key, up key, down key, left key, right key, use key, menu key, cancel key</description>
		</command>
		<command id="anykey">
			<alias>keyconstants</alias>
			<shortname>any key</shortname>
		</command>
		<command id="upkey">
			<alias>keyconstants</alias>
			<shortname>up key</shortname>
		</command>
		<command id="downkey">
			<alias>keyconstants</alias>
			<shortname>down key</shortname>
		</command>
		<command id="leftkey">
			<alias>keyconstants</alias>
			<shortname>left key</shortname>
		</command>
		<command id="rightkey">
			<alias>keyconstants</alias>
			<shortname>right key</shortname>
		</command>
		<command id="usekey">
			<alias>keyconstants</alias>
			<shortname>use key</shortname>
		</command>
		<command id="menukey">
			<alias>keyconstants</alias>
			<shortname>menu key</shortname>
		</command>
		<command id="cancelkey">
			<alias>keyconstants</alias>
			<shortname>cancel key</shortname>
		</command>
		<command id="booleanconstants">
			<canon>Boolean Constants</canon>
			<shortname>Boolean Constants</shortname>
			<description>PLOTSCR.HSD defines constants for true and false, and for ON and OFF. These are useful for checking and setting the values of tags, and in conditional statements.<lb/>true, false, on, off</description>
		</command>
		<command id="true">
			<alias>booleanconstants</alias>
			<shortname>true</shortname>
		</command>
		<command id="false">
			<alias>booleanconstants</alias>
			<shortname>false</shortname>
		</command>
		<command id="on">
			<alias>booleanconstants</alias>
			<shortname>on</shortname>
		</command>
		<command id="off">
			<alias>booleanconstants</alias>
			<shortname>off</shortname>
		</command>
		<command id="directionconstants">
			<canon>Direction Constants</canon>
			<shortname>Direction Constants</shortname>
			<description>PLOTSCR.HSD defines constants for each of the four directions. These constants are useful for commands such as <ref>walkhero</ref> and <ref>walknpc</ref>, which take a direction as an argument.<lb/>north, south, east, west, up, down, right, left</description>
		</command>
		<command id="north">
			<alias>directionconstants</alias>
			<shortname>north</shortname>
		</command>
		<command id="south">
			<alias>directionconstants</alias>
			<shortname>south</shortname>
		</command>
		<command id="east">
			<alias>directionconstants</alias>
			<shortname>east</shortname>
		</command>
		<command id="west">
			<alias>directionconstants</alias>
			<shortname>west</shortname>
		</command>
		<command id="up">
			<alias>directionconstants</alias>
			<shortname>up</shortname>
		</command>
		<command id="down">
			<alias>directionconstants</alias>
			<shortname>down</shortname>
		</command>
		<command id="right">
			<alias>directionconstants</alias>
			<shortname>right</shortname>
		</command>
		<command id="left">
			<alias>directionconstants</alias>
			<shortname>left</shortname>
		</command>
		<command id="me">
			<canon>me</canon>
			<shortname>me</shortname>
			<description>me is a constant that can be used to refer to the first hero in your party (hero zero) in any command that takes a hero number as an argument.</description>
		</command>
		<command id="none">
			<canon>none</canon>
			<shortname>none</shortname>
			<description>none is a constant that means the same as zero.</description>
		</command>
		<command id="autonumber">
			<canon>autonumber</canon>
			<shortname>autonumber</shortname>
			<deprecated>ubersetzung</deprecated>
			<description>autonumber is a constant that is used as the ID number in old-style <ref>definescript</ref> 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> and <ref>setherostat</ref> commands.</description>
		</command>
		<command id="maximumstat">
			<canon>maximum stat</canon>
			<shortname>maximum stat</shortname>
			<description>A constant for use with the <ref>getherostat</ref> and <ref>setherostat</ref> commands.</description>
		</command>
		<command id="insidebattle">
			<canon>inside battle</canon>
			<shortname>inside battle</shortname>
			<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 to represent the battle graphics.</description>
		</command>
		<command id="outsidebattle">
			<canon>outside battle</canon>
			<shortname>outside battle</shortname>
			<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 to represent the walkabout graphics.</description>
		</command>
		<command id="colorconstants">
			<canon>Color Constants</canon>
			<shortname>Color Constants</shortname>
			<description>PLOTSCR.HSD defines constants for each of the three primary colors. These are used in commands like <ref>readcolor</ref> or <ref>writecolor</ref><lb/>color:red, color:green, color:blue</description>
		</command>
		<command id="colorred">
			<alias>colorconstants</alias>
			<shortname>color:red</shortname>
		</command>
		<command id="colorgreen">
			<alias>colorconstants</alias>
			<shortname>color:green</shortname>
		</command>
		<command id="colorblue">
			<alias>colorconstants</alias>
			<shortname>color:blue</shortname>
		</command>
		<command id="mouseconstants">
			<canon>Mouse Constants</canon>
			<shortname>Mouse Constants</shortname>
			<description>PLOTSCR.HSD defines constants for use with the mouse functions. They&apos;re used the <ref>mousebutton</ref> command.<lb/>left button, right button</description>
		</command>
		<command id="leftbutton">
			<alias>mouseconstants</alias>
			<shortname>left button</shortname>
		</command>
		<command id="rightbutton">
			<alias>mouseconstants</alias>
			<shortname>right button</shortname>
		</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> or <ref>childsliceatpixel</ref> they return the number of NPCs or slices at that spot. With <ref>spellslearnt</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="tileconstants">
			<canon>Tile Constants</canon>
			<shortname>Tile Constants</shortname>
			<description>PLOTSCR.HSD defines constants for use with functions like <ref>readpassblock</ref> or <ref>writepassblock</ref>.<lb/>north wall, east wall, south wall, west wall, vehicle A, vehicle B, harm tile, overhead tile</description>
		</command>
		<command id="northwall">
			<alias>tileconstants</alias>
			<shortname>north wall</shortname>
		</command>
		<command id="eastwall">
			<alias>tileconstants</alias>
			<shortname>east wall</shortname>
		</command>
		<command id="westwall">
			<alias>tileconstants</alias>
			<shortname>west wall</shortname>
		</command>
		<command id="southwall">
			<alias>tileconstants</alias>
			<shortname>south wall</shortname>
		</command>
		<command id="vehiclea">
			<alias>tileconstants</alias>
			<shortname>vehicle A</shortname>
		</command>
		<command id="vehicleb">
			<alias>tileconstants</alias>
			<shortname>vehicle B</shortname>
		</command>
		<command id="harmtile">
			<alias>tileconstants</alias>
			<shortname>harm tile</shortname>
		</command>
		<command id="overheadtile">
			<alias>tileconstants</alias>
			<shortname>overhead tile</shortname>
		</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="xaxis">
			<canon>x axis</canon>
			<shortname>x axis</shortname>
			<description>Pass to <ref>joystickaxis</ref> to specify the X axis (left and right).</description>
		</command>
		<command id="yaxis">
			<canon>y axis</canon>
			<shortname>y axis</shortname>
			<description>Pass to <ref>joystickaxis</ref> to specify the Y axis (up and down).</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>
			<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>
		<command id="song:sameasmap">
			<alias>song:sameaslastmap</alias>
			<shortname>song: same as map</shortname>
		</command>
	</section>
</plotscript>
