Plotscripting Dictionary

This is a listing of all the plotscripting commands implemented as of February 18, 2006.

In addition to reading this document, I also recommend you check out Plotscripting Tutorial and the HamsterSpeak Specification

Alphabetical Index

number + number
add hero (who)
advance text box
allow minimap (setting)
allow save anywhere (setting)
alter NPC (who,NPCstat,value)
value,and,value
any key
append ascii (ID, char)
append number (ID, number)
autonumber
autosave
begin,other commands,end
Boolean Constants
camera follows hero (who)
camera follows NPC (who)
camera pixel X
camera pixel Y
cancel key
cancel map name display
can learn spell (hero,attack)
center string at (ID, x, y)
change NPC ID (reference,new ID)
check equipment (hero,slot)
check tag (tag)
clear string(ID)
color:blue
Color Constants
color:green
color:red
concatenate strings (dest, source)
copy string (dest, source)
create NPC (ID,X,Y,direction)
crop
current map
current song
current stat
days of play
decrement (variable,amount)
default tile
define constant (number,name)
define script (id,name,arguments)
delete char (ID, position)
delete hero (who)
delete item (item,number)
delete save (slot)
destroy NPC (reference)
Direction Constants
dismount vehicle
number / number
do
down
down key
draw NPCs above heroes (setting)
east
east wall
eight
else
end
number == number
equip menu (who)
equip where (hero,item)
number ^ power
export globals (slot, first, last)
fade screen in
fade screen out (red,green,blue)
false
fight formation (number)
find hero (who)
five
focus camera (x,y,speed)
for(counter,start,finish,step) do(commands)
force equip (hero,slot,item)
forget spell (hero,attack)
four
game over
get ambient music
get attack name (ID, attack)
get count
get damage cap
get death script
get default weapon (hero)
get each step script
get enemy appearance (enemyid, appearance)
get enemy name (enemyid, stringid)
get enemy stat(enemy, stat)
get foot offset
get formation song (formation)
get global string (ID, global)
get hero level (who)
get hero name (ID, hero)
get hero palette (who,type)
get hero picture (who,type)
get hero stat (who,stat,type)
get instead of battle script
get item (item,number)
get item name (ID, item)
get load script
get map edge mode
get map name (ID, map)
get map tileset
get money (amount)
get music volume
get NPC ID (reference)
get on keypress script
get song name (ID, song)
give experience (hero,amount)
globals to string(ID, starting global, length)
global variable (id,name)
number >> number
number >= number
greyscale palette (first,last)
harm tile
hero by rank (where)
hero by slot (where)
hero direction (who)
hero is walking (who)
hero levelled (who)
hero pixel X (who)
hero pixel Y (who)
hero X (who)
hero Y (who)
hide battle health meter (state)
hide battle ready meter (state)
hide string (ID)
hours of play
if(condition) then(commands) else(commands)
import globals (slot, first, last)
include, filename
increment (variable,amount)
init mouse
input string (ID, use current)
inside battle
inventory (item)
items menu
Key Constants
key is pressed (scancode)
knows spell (hero,attack)
last save slot
leader
left
left button
left key
number << number
number <= number
load from slot (slot)
load tileset (set)
lock hero (who)
lose money (amount)
map height
map width
maximum stat
me
menu key
minutes of play
number,mod,number
mouse button (which)
Mouse Constants
mouse pixel X
mouse pixel Y
mouse region (x min, x max, y min, y max)
number * number
nine
none
north
north wall
number <> number
NPC at pixel (x,y,number)
NPC at spot (x,y,number)
NPC copy count (ID)
NPC direction (who)
NPC is walking (who)
NPC pixel X (who)
NPC pixel Y (who)
NPC reference (ID,copy)
NPC X (who)
NPC Y (who)
Numeric Constants
off
on
one
value,or,value
order menu
outside battle
overhead tile
pan camera (direction,distance,pixelstep)
party
pay money (amount)
pick hero
play song (song)
positionstring (ID, x, y)
put camera (x,y)
put hero (who,x,y)
put mouse (X,Y)
put npc (who,x,y)
random (lownumber, highnumber)
rank in caterpillar (who)
read color (index,element)
read enemy data (enemyid, data)
read global (id)
read map block (x,y)
read NPC (who,NPCstat)
read pass block (x,y)
read spell (hero,list,slot)
rename hero(who)
rename hero by slot(who)
replace char (ID, position, char)
reset palette
resume box advance
resume catapillar
resume caterpillar
resume hero walls
resume map music
resume NPCs
resume NPC walls
resume obstruction
resume overlay
resume player
resume random enemies
resume random enemys
return(value)
right
right button
right key
room in active party
run script by ID (id, argument1, argument2, argument3...)
save in slot (slot)
save menu (reallysave)
save slot used (slot)
script, name, argumentnames (statements)
seconds of play
set ambient music (song)
set battle wait mode (state)
set caterpillar mode (state)
set damage cap (cap)
set days of play (days)
set death script (id)
set debug keys disable (state)
set default weapon (hero,item)
set each step script (id)
set enemy appearance (enemyid, appearance,value)
set enemy name (enemyid, stringid)
set enemy stat(enemy, stat, value)
set foot offset (offset)
set formation song (formation, song)
set full hero swap mode (state)
set harm tile damage (amount)
set harm tile flash (color)
set hero direction(who, direction)
set hero frame(who, frame)
set hero level (who, level, forgetspells)
set hero name (ID, hero)
set hero palette (who,palette,type)
set hero picture (who,picture,type)
set hero position (who, x, y)
set hero speed (who, speed)
set hero stat (who,stat,value,type)
set hero z (who, z)
set hours of play (hours)
set inn no revive mode (state)
set instead of battle script (id)
set load script (id)
set map edge mode (mode, default tile)
set minutes of play (min)
set music volume (volume)
set no HP level up restore (state)
set no MP level up restore (state)
set NPC direction (who,direction)
set NPC frame (who,frame)
set NPC position (who,X,Y)
set NPC speed (who,speed)
set on keypress script (id)
set seconds of play (sec)
set tag (tag,value)
set variable (variable,value)
set victory music (song)
seven
show backdrop (number)
show map
show mini map
show no value
show string (ID)
show string at (ID, x, y)
show text box (number)
show value (number)
six
south
south wall
spells learnt (hero,number)
spells menu (who)
status screen (who)
stop song
string color (ID, foreground color, background color)
string length (ID)
string style (ID, style)
string to globals (ID, starting global, length)
string X (ID)
string Y (ID)
number -- number
suspend box advance
suspend catapillar
suspend caterpillar
suspend hero walls
suspend map music
suspend NPCs
suspend NPC walls
suspend obstruction
suspend overlay
suspend player
suspend random enemies
suspend random enemys
swap by name (name,name)
swap by position (position,position)
swap in hero (who)
swap out hero (who)
system hour
system minute
system second
teach spell (hero,attack)
team menu
teleport to map (map, x, y)
nine
then
three
Tile Constants
trace (string)
true
tweak palette (red, green ,blue ,first,last)
two
unequip (hero,slot)
unlock hero (who)
up
update palette
up key
use door (number)
use key
Use NPC (who)
use shop (shop)
variable (name)
vehicle A
vehicle B
wait (ticks)
wait for all
wait for camera
wait for hero (who)
wait for key (key)
wait for NPC (who)
wait for text box
walk hero (who, direction, distance)
walk hero to x (who,x)
walk hero to y (who,x)
walk NPC (who,direction,distance)
walk NPC to X (who,X)
walk NPC to Y (who,Y)
west
west wall
while(condition) do(commands)
wrap
write color (index,element,value)
write enemy data (enemyid, data, value)
write global (id,value)
write map block (x,y,value)
write pass block (x,y,value)
write spell (hero,list,slot,attack)
value,xor,value
zero

Declarations

define script (id,name,arguments) The define script command names a script, and associates it with an ID number. Every script must have a unique ID number for your game to call it directly (scripts that will only be called indirectly, by other scripts can use the special ID autonumber). The first argument is the ID number. It is a number between 1 and 16383. If you try to give two individual scripts the same ID number, your script file will not compile. The next argument is the name 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 dont) then use none. If there are arguments, you then follow the argument count with default values for each argument.

# example of a simple script definition
define script (1,my first script,none)

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

script, name, argumentnames (statements) The script command contains the actual source code of a plotscript. every script command must have a corresponding define script statement. 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. Then comes the text of the script. It is usually enclosed in begin and end statements.

# example of a simple script
script,my first script,begin
	# commands go here
end

# example of a script with arguments script,my fancy script,fe,fi,fo,begin # commands go here, # and they can use the aruments fe, fi, and fo # that where passed to the script end

global variable (id,name) Creates a global variable that can be used in any script. The first argument to the global variable declaration is a unique ID number. The second argument is the name of the variable. The ID number for a global variable is a number from 0 to 1024. Each global variable must have a unique number, but this number will not conflict with the ID numbers you use for scripts. It is all right to have a script and a global variable with the same ID number. See also variable

# any script can read and set the value of a global
global variable(1,mini game score)

variable (name) Creates a local variable that can only be used inside the script where it was created. The value of this variable is lost when the script ends. If you need a variable who's value persists between calls to a script, or that is automatically saved when the player saves their game, you will need to use a global variable instead.

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

define constant (number,name) Creates a global constant. The first argument is the number that the constant will represent, and the second argument is the name of the constant. Use constants to replace commonly used numbers with friendly names. The following constants have been delacred for you in PLOTSRC.HSD: zero one two three four five six seven eight nine nine false true off on north east south west up down left right up key down key left key right key use key cancel key menu key any key me none autonumber current stat maximum stat north wall east wall south wall west wall vehicle A vehicle A harm tile overhead tile

include, filename 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.

include, plotscr.hsd # Plotscripting definitions
include, mygame.hsi # constants particular to my game

Wait Commands

wait (ticks) Makes the script wait for the specified number of ticks. I havent timed how many ticks there are in a second, but I would guess roughly 15. If you leave out the argument, it will wait for one tick.

show text box(2) # Show a text box
wait(45) # Wait about 3 seconds
advance text box # "hit spacebar"

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

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

wait for hero (who) Waits for the specified hero stop walking. Use the constant me to refer to the leader, or use numbers 0,1,2,3 to refer to a specific hero. If you leave out the argument, the first hero will be assumed.

move hero to y (me, 10) # move hero to (x, 10)
wait for hero (me) # wait until he stops

wait for key (key) Waits for the player to press a key. You can use the follwing constants: any key, up key, down key, left key, right key, use key, cancel key, or menu key. If you do not specify, then any key will be used.

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

wait for NPC (who) Waits for the specified NPC to stop walking. The argument is the number of the NPC, 0 to 35. If more than one copy of the NPC exists on the map, it only checks the first one.

walk NPC (2,up,3) # make the NPC go up three spaces
wait for NPC (2) # wait until he's done

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

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

wait for all Waits for any camera motion to stop, waits for all heros to stop walking, and if suspend NPCs is active, waits for all NPCs to stop walking.

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

Suspend and Resume

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

suspend player
# do stuff
resume player

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

suspend player
# do stuff
resume player

suspend NPCs Stops NPCs from walking around automatically. When suspend NPCs is run, all NPCs stop in their tracks, ready for you to control them with the walk NPC command

suspend NPCs
# do stuff
resume NPCs

resume NPCs Restores automatic NPC movement after a suspend NPCs command

suspend NPCs
# do stuff
resume NPCs

suspend obstruction Allows heros to walk through NPCs, allows NPCs to walk through heros, and allows NPCs to walk through each other. Use resume obstruction to restore normal obstruction behavior.

suspend obstruction
# walk through things
resume obstruction

resume obstruction Restores normal obstruction after a suspend obstruction command

suspend obstruction
# walk through things
resume obstruction

suspend hero walls Allows heros to walk through walls. Use resume hero walls to restore normal wall behavior.

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

resume hero walls Restores normal wall behavior after a suspend hero walls command

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

suspend NPC walls Allows NPCs to walk through walls. Use resume NPC walls to restore normal wall behavior.

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

resume NPC walls Restores normal wall behavior after a suspend NPC walls command.

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

suspend caterpillar Stops your other heros from following the leader. This is useful when you want to control them individually with walk hero commands. In earlier versions this was misspelled as suspend catapillar. The old spelling still works for backwards compatability.

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

resume caterpillar Reverses the suspend caterpillar command, and makes your other heros follow the leader as normal. In earlier versions this was misspelled as resume catapillar. The old spelling still works for backwards compatability.

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

suspend catapillar See suspend caterpillar

resume catapillar See resume caterpillar

suspend random enemies Prevents enemies from attacking your party while walking over tiles that can normally spawn random battles. This is useful to prevent battles from interrupting a plotscript. In earlier versions, this was misspelled as suspend random enemys. The old spelling still works for backwards compatability.

suspend random enemies # no battles for now
walk hero (me, up, 10) # cross pit of evil monsters of doom
resume random enemies # back to normal

resume random enemies Undoes the suspend random enemies command and allows random battles to occur as normal. In earlier versions, this was misspelled as resume random enemys. The old spelling still works for backwards compatability.

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

suspend random enemys See suspend random enemies

resume random enemys See resume random enemies

suspend box advance Prevents the player from advancing or clearing text boxes by pressing keys. While this is active, the only way to make a text box advance is with the advance text box command. Be very careful with this command, since you do not want to leave the player stuck on a text box forever.

suspend box advance # stop players from mucking things up
show text box(2) # Show a text box
wait(45) # Wait about 3 seconds
advance text box # "hit spacebar"
resume box advance # go back to normal

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

suspend box advance # stop players from mucking things up
show text box(2) # Show a text box
wait(45) # Wait about 3 seconds
advance text box # "hit spacebar"
resume box advance # go back to normal

suspend overlay Prevents overhead tiles from being drawn over heros and NPCs.

resume overlay Causes overhead tiles to be drawn over heros and NPCs as normal.

suspend map music Causes ambient music not to automatically play when you enter a map. Does not affect the currently playing music, or the map's ambient music. Use when playing thematic music during a scene that involves changing maps.

# begin scene
play song(song:Happy Times)
show textbox (117)
wait for textbox
# goto another map without triggering music
fade screen out
wait
suspend map music
use door(3)
fade screen in
# continue scene
show textbox (118)
wait for textbox
# return to normal music behaviour and play the ambient music
resume map music
play song (get ambient music)

See also: set ambient music, get ambient music

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

Moving Heros

walk hero (who, direction, distance) Makes the specified hero move in the specified direction for the specified number of tiles. The first argument tells who to move. Use me or numbers 0-3. The second argument is the direction. Use the constants: north, south, east, west, up, down, left, or right. The third argument is the number of tiles to move. If you leave out the third argument, the hero will move one tile. Walk hero is usually used with the wait for hero command. You should normally use the suspend player command before moving heros, and if you want to move heros other than the leader, you should use the suspend caterpillar command.

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

set hero direction(who, direction) Makes the specified hero face in the specified direction. The following constants are avaialable for direction: north, south, east, west, up, down, left, or right.

set hero direction(me,right) # face right

set hero frame(who, frame) Sets the walking frame of the specified hero to 0 or 1.

set hero position (who, x, y) Instantly moves the specified hero to an X,Y position on the map. The coordinates are in units of tiles. For pixel-positioning use the put hero command.

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

walk hero to x (who,x) Makes the specified hero walk to a given X coordinate on the map

walk hero to y (who,x) Makes the specified hero walk to a given Y coordinate on the map

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

use door (number) Instantly uses the numbered door, just as if you had stepped into it.

teleport to map (map, x, y) An alternative to use door, teleport to map moves you to a given x,y position on the specified map without the need to create a door-link on the map. Teleport to map does not fade to black.

dismount vehicle Makes you dismount whatever vehicle you are riding. If you are not riding a vehicle, nothing will happen.

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

put hero (who,x,y) Moves a hero to a precise location on the map. The first argument is the her's position in the walkabout party. 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 hero with the tile-grid, preventing it from walking normally. To position the hero by tile, use the set hero position command.

Moving NPCs

NPC reference (ID,copy) What is an NPC reference? A reference is a number that uniquely identifies an NPC on a map. You can use an NPC reference to specify which NPC you are controlling in most NPC-related commands. The first argument to NPC reference is the ID number of the NPC you want to work with. The ID is the same number that appears in CUSTOM.EXE when you are editing NPCs or placing NPCs on the map. The second argument is optional. It specifies which copy of the NPC you want, in case there are more than one on the map. If you dont specify which copy you want, you will just get a reference to the first NPC on the map with the right ID. If you plan on using the same NPC reference many times in a script you can store it in a variable. 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 false.

include,plotscr.hsd
define script(1,ref example,none)

#---NPC reference example---

script,ref example,begin

  variable(Fred)

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

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

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

end

See also: NPC at spot, NPC at pixel, create NPC

NPC at spot (x,y,number) 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 get count for the third argument to return the total number of npcs on that tile. See also:

NPC reference

NPC at pixel (x,y,number) This command returns a reference to the NPC at the given X and Y coordinate in pixels. That is, any npc whose 20x20 sprite (including transparent sections) is over that pixel. The optional third argument lets you choose which NPC to reference in case there is more than one NPC standing on that same spot (starting from the bottom-most NPC, which is number 0). You can also pass the constant get count for the third argument to return the total number of npcs on that tile. See also:

NPC reference

walk NPC (who,direction,distance) Makes the specified NPC move in the specified direction for the specified number of tiles. The first argument tells who to move. You can use an NPC reference or the NPC's ID number. The second argument is the direction. Use the constants: north, south, east, west, up, down, left, or right. The third argument is the number of tiles to move. If you leave out the third argument, the NPC will move one tile. walk NPC is usually used with the wait for NPC command. You should normally use the suspend NPCs command before moving NPCs to prevent their automatic movements from interfering with your scripted movements.

set NPC direction (who,direction) Makes the specified NPC face in the specified direction. The following constants are avaialable for direction: north, south, east, west, up, down, left, or right. You can use either an NPC reference or the NPC's ID number to specify which NPC will turn.

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

set NPC position (who,X,Y) Instantly moves the specified NPC to an X,Y position on the map. The coordinates are in units of tiles. You can use either an NPC reference or the NPC's ID number to specify which NPC will be moved.

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

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

set NPC speed (who,speed) Changes the walking speed of the specified NPC. If you do not specify a speed, the NPC's speed will return to the default, 4. Be careful with using speeds that do not divide evenly into 20, because tiles are 20 pixels in size, and an irregular walking speed may cause the NPC to become misaligned with the tiles. Normally you would only give an NPC ID number to set NPC speed, but if you want to use an NPC reference it will still work. Just remember that set NPC speed changes every copy of the NPC on the map, not just the specific one you referenced.

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

get NPC ID (reference) This command is the opposite of NPC reference. If you give get NPC ID a reference to an NPC it will return the NPC&s ID. (Note: in some older versions, This command was useful if you needed to do an alter NPC or a set NPC speed 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))

NPC copy count (ID) 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.

include,plotscr.hsd
define script(1,every NPC example,none)

#---NPC copy count example---

script,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
  set variable(guard count,NPC copy count(10))

  # this loop repeats once for each copy of NPC 10
  for(loop,0,guard count) do,begin

    set variable(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 t a time

  end

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

end

change NPC ID (reference,new ID) This command takes an NPC reference and lets you change the ID number of the NPC it points to. This means that the NPC will now use a different picture, an different palette, a different walking speed, an different text box, everything. This change is not permanent. It only lasts until the next time a map gets loaded.

create NPC (ID,X,Y,direction) This command will magically create a new copy of an NPC with the given ID number. You can specify an X and Y position where it will be created, and optionally a direction too (if you leave out the direction, the new NPC will be facing south). create NPC returns an NPC reference that you can use to refer to the new NPC in other commands like walk NPC. If the new NPC cannot be created (there is a maximum of 300 total NPC copies in memory at a time) then create NPC will return false (zero). The new NPC is not permanent. It only lasts until a new map is loaded.

destroy NPC (reference) This command will erase the specified NPC. You can use either an NPC reference or the NPC's ID number. The deletion is not permanent. Unless this is an NPC that you created with create NPC, the NPC will be back again next time the map gets loaded. If you need to permanently remove an NPC, use tags. (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)

put npc (who,x,y) Moves an NPC to a precise location on the map. The first argument is and NPC reference or an NPC ID number. The second and third arguments are the X,Y pixel position relative to the top left corner of the map. Be aware that using this command can mis-align your NPC with the tile-grid, preventing it from walking normally. To position the NPC by tile, use the set NPC position command.

Moving the Camera

camera follows hero (who) Normally, the camera follows your leader. With this command, you can make the camera follow any hero you want. If you leave out the argument, the camera will follow your leader as normal.

camera follows NPC (who) With this command, you can make the camera follow an NPC instead of the hero. If more than one copy of the specified NPC exists, the camera will follow the first one. To revert the camera to normal, use camera follows hero.

pan camera (direction,distance,pixelstep) This command causes the camera to stop following your leader and pan in the specified direction. For direction, you can use the constants: north, south, east, west, up, down, left, or right. The distance is the number of tiles you want the camera to move before it stops. You can also specify the number of pixels you want the camera to move for each tick. if you leave the last argument out, the camera will move by 2 pixels per tick. This command is normally used with wait for camera. To revert the camera to normal, use camera follows hero.

focus camera (x,y,speed) This command causes the camera to focus itself on the specified X,Y coordinates of the map. These coordinates are in units of tiles. The third argument, the speed, tells how fast the camera will pan. If you do not specify a speed, the camera will pan 2 pixels per tick. This command is normally used with wait for camera. To revert the camera to normal, use camera follows hero.

put camera (x,y) This command causes the top left corner of the camera to instantly jump to the specified X,Y pixel coordinates of the map. These coordinates are in units of pixels, not tiles. To position the camera by tiles, just multiply the tile position by 20. To revert the camera to normal, use camera follows hero.

Text Boxes

show text box (number) Displays the numbered text box, just as if you had talked to an NPC. The text box will not actually pop up until the next wait command. This command is most often used with the wait for text box command.

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

advance text box Advances a text box just as if the player had pressed a key. For use while suspend box advance is active.

suspend box advance # stop players from mucking things up
show text box(2) # Show a text box
wait(45) # Wait about 3 seconds
advance text box # "hit spacebar"
resume box advance # go back to normal

Triggering and Showing Stuff

fight formation (number) Starts a battle with the numbered enemy formation. This command returns false if you lost or ran from battle, or true if you won.

Use NPC (who) Remotely trigger an NPC. You can use either an NPC reference or an NPC ID number. Whatever actions are associated with triggering that NPC will be taken, text box, script, vehicle, item, whatever.

game over Resets the game and returns you to the title screen. This command is most useful for after-you-win-the-game type scripts, and for death-scripts that are triggered when you lose in battle.

show value (number) Displays the number in the bottom left corner of the screen. Useful for count-down timers, and for debugging complicated scripts.

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

cancel map name display If the map name is being displayed, this command makes it disappear. For example, this may be useful if you want the map name to appear when you enter a map normally, but not when you jump to the map for a plotscripted cutscene.

show backdrop (number) displays the specified full screen backdrop on the screen. This allows you to show full screen pictures without attaching them to text boxes. You can also do some simple animation effects by calling show backdrop many times with wait commands in between.

show map shows the map again after a show backdrop command

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

show mini map Displays the mini-map

items menu Takes you directly to the items menu. Note that if the player uses an item that calls up a text box, the items menu command will behave like a show text box command for that text box.

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

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

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

save menu (reallysave) Takes you directly to the save menu. Will return a number 1-4 indicating the slot the player saved in, or false if the player did not save. You can optionally pass an argument of false to make the menu display without actually saving See also:

autosave

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

team menu Takes you directly to the team menu, where you can change the order of the heroes in your active party, and swap heroes in and out of your reserve.

Adding and Removing

get money (amount) Adds the specified amount to your party's money

lose money (amount) Subtracts the specified amount from your party's money.

pay money (amount) A function that checks to see if you have enough money to pay the amount specified. If you do, it subtracts it, and returns true. If you do not have enough, it subtracts nothing, but returns false. Intended for use in if statements.

if(pay money(1000)) then, begin
	get item(item:uber sword)
end, else, begin
	show text box(61) # ha ha, no uber sword for you!
	wait for text box
end

add hero (who) Puts the named hero in your party. If there is no room, the hero will be added to your reserve. Use the constants defined in your HSI file. They are in the form of hero:name

delete hero (who) Removes the named hero from your party. If you have more than one copy of the hero in your party, only the first one will be deleted. Use the constants defined in your HSI file. They are in the form of hero:name

swap in hero (who) Moves the named hero in your from your reserves to your active party. If there is no room in your active party, the hero will not be moved. Use the constants defined in your HSI file. They are in the form of hero:name

swap out hero (who) Moves the named hero from your active party into your reserve. Use the constants defined in your HSI file. They are in the form of hero:name

lock hero (who) Locking a hero prevents the player from moving the hero on the party menu. Locked heros in the active party cannot be moved into the reserve, and locked heros in the reserve are completely hidden. Also prevents a hero from being moved by swap in hero or swap out hero. Use the constants defined in your HSI file. They are in the form of hero:name

unlock hero (who) Reverses lock hero, and makes it possible to move a hero in and out of the active party again. Use the constants defined in your HSI file. They are in the form of hero:name

swap by name (name,name) Swaps two named heros in your party no matter what position they are in. Use the names defined in your HSI file in the form hero:name

swap by position (position,position) Swaps two heros in your party based on their positions in the party

get item (item,number) Adds the specified number of the specified item to your inventory. If you do not specify a number, only one will be added. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name

delete item (item,number) Removes the specified number of the specified item from your inventory. If you do not specify a number, only one will be removed. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name

unequip (hero,slot) Removes the item that the specified hero has equipped in the specified slot. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (use find hero if you want to refer to the hero by name). The second argument is the slot to unequip. Use the number 1-5 or the names slot:weapon, slot:armor, etc.

force equip (hero,slot,item) Forces a hero to equip an item, even if it is not normally equipable. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (use find hero if you want to refer to the hero by name). The second argument is the slot to equip. Use the number 1-5 or the names slot:weapon, slot:armor, etc. The third argument is the item to equip. you can use the item's number or the item:name constants from your .HSI file.

equip where (hero,item) 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 find hero if you want to refer to the hero by name). The second argument is the item to check the equipability of. you can use the item's number or the item:name constants from your .HSI file.

check equipment (hero,slot) eturns the number of the item that the specified hero has equipped in the specified slot, or -1 if there is nothing equipped there. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (use find hero if you want to refer to the hero by name). The second argument is the slot to unequip. Use the number 1-5 or the names slot:weapon, slot:armor, etc.

get default weapon (hero) Returns the number of the item that the specified hero uses as a default weapon when no other weapon is equipped. The argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (use find hero if you want to refer to the hero by name).

set default weapon (hero,item) Changes the item that the specified hero uses as a default weapon when no other weapon is equipped. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (use find hero if you want to refer to the hero by name). The second argument is the item to use as the new default weapon. you can use the item's number or the item:name constants from your .HSI file.

give experience (hero,amount) Gives (or removes, but you can't drop level) experience to either a hero by position in party (use result returned by find hero command) or the whole active party, if the constant party is passed as first argument. If you give experience to the whole party, then it will be split amongst live heroes as it is in battle. This command can cause heroes to level up and learn spells but does not inform the player or trigger any effects. See hero levelled and spells learnt for dealing with this.

Effects

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

current song Returns the number of the currently playing song.

stop song Stops whatever music is currently playing.

set victory music (song) Changes the after-battle victory music to the specified song. Use the constants defined in your HSI file. They appear in the form of song:name

set ambient music (song) Plays a song and sets it as the map's ambient music, that is the song that is played after a textbox with 'restore music' set. The effect goes away if you change maps or fight a battle. Calling set ambient music with no argument stops the music and disables the ambient music. See also:

play song

get ambient music Returns the song number of the map's ambient music. See also:

current song

set music volume (volume) Sets the volume at which music is played, volume being a number on the scale of 0 to 255, 0 being silent, 255 loudest. 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. By default volume is not maximum, 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.

get music volume Returns the volume at which music is played, on a scale of 0 to 15, 0 being silent, 255 loudest.

fade screen out (red,green,blue) Fades the screen to a solid color. If you do not specify any arguments, the screen will fade to black. The red, green, blue values are numbers from 0 to 63 that tell how bright that particular color should be. (63,0,0) would be blood red. (40,0,40) would be purple. (63,63,63) would be bright white. The screen will remain faded out until you run fade screen in, fight a battle, or use a door.

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

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

greyscale palette (first,last) converts a section of the master palette from color to greyscale. The two arguments determine what range of colors will be affected. If called with no arguments, the entire palette is affected. Changes do not take effect until you call update palette or fade screen in. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-load plotscript trigger.

tweak palette (red, green ,blue ,first,last) Color-adjusts a section of the master palette. The first three arguments are the changes to make to the red, green, and blue values of each palette color. For example, tweak palette (20,-30,0) would redden everything, and drop out most of the green. The last two arguments determine what range of colors will be affected. If they are left out, the entire palette is affected. Changes do not take effect until you call update palette or fade screen in. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-load plotscript trigger.

reset palette Reloads the default palette, undoing any changes you have made with other palette-altering commands such as tweak palette or greyscale palette Changes do not take effect until you call update palette or fade screen in

read color (index,element) Returns a color value from the master palette. The first argument is the index in the palette to read from, 0 to 255. The second argument is the color value to read, red, green, or blue. You can use 0,1, and 2, or you can use the predefined constants color:red, color:green, and color:blue. The counterpart to this is write color.

write color (index,element,value) Writes a color value into the master palette. The first argument is the index in the palette to write to, 0 to 255. The second argument is the color value to write, red, green, or blue. You can use 0,1, and 2, or you can use the predefined constants color:red, color:green, and color:blue. The third argument is the color value to write. It can be in the range of 0 to 63. Changes do not take effect until you call update palette or fade screen in The counterpart to this is read color. 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.

Hero's Spells

teach spell (hero,attack) Tries to teach a hero a spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to learn. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero is capable of learning the spell, teach spell will return true, or if the hero cannot learn the spell it will return false. Note that this only works when a spell is set to "learned from item". It will not work for spells learned based on level.

forget spell (hero,attack) Causes a hero to forget a spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to forget. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero does not know the spell, nothing happens.

read spell (hero,list,slot) Returns the ID number of a chosen spell slot, or 0 (false) if there is no spell in that slot. The first argument is the hero's position in the party (as returned by find hero). The second argument is the number of the spell list to check. This is a value from 0 to 3. The third argument is the slot to check. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on.

write spell (hero,list,slot,attack) Forces a hero to learn a particular spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the spell list to put the spell in. This is a number from 0 to 3. The third argument is the slot to put the spell in. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on. The last argument is the attack to put in the spell list. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). You can also erase a spell by writing 0 or none as the attack ID. Note that this command will overwrite and replace any spell that is already in that slot. If you overwrite a slot that can normally learn another spell, you will never learn that other spell (unless you first erase the spell you wrote there)

knows spell (hero,attack) Checks to see if a hero already knows a spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero knows the spell, knows spell will return true. If the hero does not know the spell, it will return false

can learn spell (hero,attack) Checks to see if a hero is capable of learning a spell from an item or from the teach spell command. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero can learn the spell, can learn spell will return true. If the hero cannot learn the spell (or learns it from levelups), it will return false

spells learnt (hero,number) Used to return the id numbers of spells the hero learnt from the last battle or give experience or set hero level command. (Returns only the spells learnt from the very last battle or give experience/set hero level command). If the second argument is get count then the number of spells that the hero learnt 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 learnt:

define script (autonumber, print learnt spells, 1, 0)
# the following script uses strings 0, 1, 2 for its use (will be overwritten)
script, print learnt spells, who, begin
  variable(i)
  get hero name (1, who) # construct the static part of the text in string 1
  $1+" learnt spell "
  for (i, 0, spells learnt (who, get count) -- 1) do (
    get attack name (2, spells learnt (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

Mouse Functions

init mouse Initializes the mouse, returning true if one is present, and loads the mouse driver. This command much be run before any mouse functions can be used. Therefore, it is a good idea to place this command in the newgame and loadgame scripts if you are going to use the mouse. The mouse will start in the middle of the screen with bounds of 0-319 horizontally and 0-199 vertically. The bounds can be changed with mouse region, and you can reposition the mouse with put mouse. NOTE: Running this command does not draw a cursor on screen - your script must do this itself by placing an npc at the appropriate location. Here is an example:

include,plotscr.hsd
define script(1,displaymouse,none)

#Mouse cursor example

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

mouse pixel X Returns the X coordinate in pixels of the mouse on the screen. init mouse must be called before this command can be used.

mouse pixel Y Returns the Y coordinate in pixels of the mouse on the screen. init mouse must be called before this command can be used.

mouse button (which) Returns true if the specified mouse button is pressed. You can use the constants left button and right button to specify the button. init mouse must be called before this command can be used.

put mouse (X,Y) Changes the location of the mouse on the screen, in pixels. init mouse must be called before this command can be used.

mouse region (x min, x max, y min, y max) 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. init mouse must be called before this command can be used.

String Functions

When refering to a position in a string, position is a 1-based index into the string, not a 0-based index. For example, given a string "ABCDEFG", position=3 is "C", not "D". This is because the string commands are based on BASIC string commands, which are 1-based. This also means that position 0 is invalid. Beware!
Also note that a string cannot exceed 40 characters. If it does, it will be truncated to 40 characters.

show string (ID) Displays string #ID on the screen, as with the show value command. Use show no value to remove the string from the screen. Note that this command displays the value of the string at the moment the command was run. Later changes to the value of the string will not appear unless you run show string again. If you need real-time display of changes to a string, use show string at or center string at instead. See also:

show value, show no value, show string at, center string at

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

append ascii (ID, char) Appends the character with ascii code 'ascii' to the string with ID #ID. Remember: Numbers are 48 - 57, uppercase letters are 65 - 90, lowercase letters are 97 - 122. See also:

append number

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

append number

copy string (dest, source) Copies the text from string #source to string #dest, overwriting the existing string completely. If you prefer, you can write dest $= source instead. You must supply string id numbers, not strings, as arguments.

concatenate strings (dest, source) Copies the text from string #source to string #dest. However, unlike copy string, the text is appended to the end of dest. The resulting string is then trimmed to the limit of 40 characters. If you prefer, you can write dest $+ source instead. You must supply string id numbers, not strings, as arguments.

string length (ID) Returns the length of string #ID.

replace char (ID, position, char) Replaces the character at position in string #ID with a character with ascii code char.

delete char (ID, position) This deletes the character at postion in string #ID, causing all the following characters to move over a slot.

string to globals (ID, starting global, length) This command will fill global variables (starting with #starting global), up to length globals, with the ascii values of the characters in string #ID. Don"t ask us why you would want to, but I"m sure there"s a use (encryption?) See also:

globals to string

globals to string(ID, starting global, length) This command is the opposite of string to globals. It will build a new string in slot #ID, using the ascii values from the global variables #starting global and length globals thereafter. If a global has a value greater than 255, the value will be ignored. See also:

string to globals

get hero name (ID, hero) This command will take the name of hero #hero, and stick it in string #ID, overwriting its contents.

set hero name (ID, hero) This command will take string #ID, and set hero #hero's name to it.

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

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

get attack name (ID, attack) This command will take the name of attack #attack and stick it in string #ID, overwriting its contents.

get global string (ID, global) This command will take the name of global string #global and stick it in string #ID, overwriting its contents. Global strings include every text string in the game, such as prompts and messages. See a 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 #global will produce valid results.

input string (ID, use current) Allows the player to type in a string. Returns false if they press ESC to cancel.

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

center string at (ID, x, y) Displays string #ID on the screen, Centering it at the given x,y coordinates. Unlike show string, changes to the string will be displayed in real-time.

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

string style (ID, style) Changes the appearance of a string previously displayed with show string at or center string at. Choice of style is string:outline and string:flat

string color (ID, foreground color, background color) Changes the color of a string previously displayed with show string at or center string at. Use 0 for transparent, and 1 to 255 for each different color in the palette. If you ommit background color, the background will be transparent.

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

string X (ID) returns the horizontal X position of the top left corner of string #ID

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

get song name (ID, song) Gets the name of song #song and puts it in string #ID.

Misc Functions

random (lownumber, highnumber) Returns a random number in the range of the two numbers. The returned value will be greater than or equal to the first number, and less than or equal to the second number

inventory (item) Returns a count of how many of the specified item are in your inventory. If you do not have the item, it returns zero or false. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name

leader Returns the hero number of the current leader

hero X (who) returns the specified hero's X position in tiles.

hero Y (who) returns the specified hero's Y position in tiles.

NPC X (who) returns the specified NPC's X position in tiles.

NPC Y (who) returns the specified NPC's Y position in tiles.

hero direction (who) Returns the specified hero's direction.

NPC direction (who) Returns the specified NPC's direction.

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

current map Returns the number of the current map.

map width Returns the width of the map in tiles.

map height Returns the height of the map in tiles.

get map tileset Returns the ID number of the default tileset for the map. load tileset does NOT affect the value returned by this function.

days of play Returns the number of days that the game has been played

set days of play (days) Sets the number of days that the game has been "played" to days, as long as days is greater than 0. Useful if there are times that shouldn't count towards the play time, or for penalizing bad players >:)

hours of play Returns the number of hours that the game has been played, 0 to 23

set hours of play (hours) Sets the number of hours that the game has been "played" to hours, as long as hours is within the 0-23 range.

minutes of play returns the number of minutes that the game has been played, 0 to 59

set minutes of play (min) Sets the number of minutes that the game has been "played" to min, as long as min is within the 0-59 range.

seconds of play returns the number of seconds that the game has been played, 0 to 59

set seconds of play (sec) Sets the number of seconds that the game has been "played" to sec, as long as sec is within the 0-59 range.

system hour Returns the current real-world hour, 0 to 23

system minute Returns the current real-world minute, 0 to 59

system second Returns the current real-world second, 0 to 59

key is pressed (scancode) Returns true if the keyboard key with the specified scancode is being pressed, or false if it is not. The argument is a scancode, NOT the up key, down key, etc used with wait for key. I have provided an extra include file, SCANCODE.HSI that you can use to define friendly names for all the scancodes.

00 01 ESC 02 1 03 2 04 3 05 4 06 5 07 6 08 7 09 8 10 9 11 0 12 - _ 13 = + 14 BACKSPACE 15 TAB 16 Q 17 W 18 E 19 R 20 T 21 Y 22 U 23 I 24 O 25 P 26 [ { 27 ] } 28 ENTER 29 CTRL 30 A 31 S 32 D 33 F 34 G 35 H 36 J 37 K 38 L 39 ; : 40 " ' 41 ` ~ 42 LEFT SHIFT 43 \ | 44 Z 45 X 46 C 47 V 48 B 49 N 50 M 51 , < 52 . > 53 / ? 54 RIGHT SHIFT 55 PRINT SCREEN * 56 ALT 57 SPACE 58 CAPSLOCK 59 F1 60 F2 61 F3 62 F4 63 F5 64 F6 65 F7 66 F8 67 F9 68 F10 69 NUMLOCK 70 SCROLL LOCK 71 HOME 7 72 UP 8 73 PAGEUP 9 74 KEYPAD - 75 LEFT 4 76 KEYPAD 5 77 RIGHT 6 78 KEYPAD + 79 END 1 80 DOWN 2 81 PAGEDOWN 3 82 INSERT 0 83 DEL . 84 85 86 87 F11 88 F12 89 90 91 L WIN LOGO 92 R WIN LOGO 93 CONTEXT

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

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

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

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

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

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

pick hero Pops up a hero-picker box that lets you choose one of the heros in your active party. The return value is the position in the party of the hero you picked.

rename hero(who) Pops up a name-editing box that allows you to change a hero's name. The argument is the hero's ID number, or name in the format hero:name

rename hero by slot(who) Pops up a name-editing box that allows you to change a hero's name. The argument is the hero's position in the party as returned by find hero

last save slot Returns the last save slot saved in, or false if the game has not been saved yet. See also:

save in slot, save menu

save slot used (slot) Returns whether a game has been saved in the save slot. Use if you, for example, don't want to overwrite a saved game with save in slot.

get enemy stat(enemy, stat) Returns the selected stat from the selected enemy. The first argument is the number of the enemy whose stats you want to check. The second argument is the name of the stat that you want to check. The names of the stats are also defined in your HSI file in the form stat:name. See also:

set enemy stat, get hero stat, set hero stat

set enemy stat(enemy, stat, value) Sets the selected stat of the selected enemy to the value you supply. The first argument is the number of the enemy whose stats you want to set. The second argument is the name of the stat that you want to set. The names of the stats are 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 save game. See also:

get enemy stat, get hero stat, set hero stat

get enemy name (enemyid, stringid) Lets you use the enemy name in a string. The first argument is the number of the enemy you want to get the name from, second argument is the number of the string that you want to store the name of the enemy. See also:

set enemy name

set enemy name (enemyid, stringid) Lets you set the enemy name from a string, the string length cannot be more then 16 characters, if it is more then 16 the name will be truncated. The first argument is the number of the enemy's name you want to change, second argument is the number of the string that you supply the name of the enemy from. Note: Enemy name changes are temporary. They are not saved in the save game. See also:

get enemy name

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

enemy:picture

enemy:palette enemy:picturesize You can compare the values returned from enemy:picturesize with the constants enemysize:small, enemysize:medium and enemysize:large See also: set enemy appearance

set enemy appearance (enemyid, appearance,value) Lets you change an enemy's appearance. Enemyid is the number of the enemy's appearance that you want to change, appearance is one of the constants given in get enemy appearance. Value can is the new number that you want to assign, constants enemysize:small, enemysize:medium, or enemysize:large when changing picture size, or palette number when changing palette. Note: Enemy appearance changes are temporary. They are not saved in the save game. See also:

get enemy appearance

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

enemy:gold

enemy:experience enemy:item enemy:itempercent enemy:rareitem enemy:rareitempercent stealability stealableitem stealableitemchance stealablerareitem stealablerareitemchance See also: write enemy data

write enemy data (enemyid, data, value) Lets you set items of an enemy's data. Enemyid is the number of enemy, data is a predefined constant for the data you want to change. Value is the new value given to that setting. Use the same constants as are given at read enemy data. Note: Enemy data changes are temporary. They are not saved in the save game. See also:

read enemy data

get formation song (formation) Returns the song associated with formation. If there is none, it will return 0, otherwise it will return the song number + 1. If there is an error (such as formation not existing), it will return -1. See also:

set formation song

set formation song (formation, song) Sets an enemy formation to use song as its music. Use 0 for none, or the song number + 1 for a song. Note: Formation data changes are temporary. They are not saved in the save game. See also:

get formation song

hero levelled (who) Returns the number of levels the specified hero (use result from find hero) gained from only the very last battle or give experience command - levels gained from previous battles or commands is not recorded. In other words, does not return true or false, but can be be used in an if statement like:

give experience (party, 50)
if (herolevelled (find hero (hero: Bob))) then (
  $31="Bob gained "
  append number(31, hero levelled (find hero (hero: Bob)))
  $31+" levels!"
  show textbox (233) # ${S31} :show string 31
)

Tweaking Maps

read map block (x,y) 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.

write map block (x,y,value) 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.

read pass block (x,y) Returns the value of a passability (wallmap) tile on the current map at the specified X,Y position. The return value will be from 0 to 255 and consists of eight flag bits. bit 1 = north wall bit 2 = east wall bit 4 = south wall bit 8 = west wall bit 16 = vehicle A bit 32 = vehicle B bit 64 = harm tile bit 128 = overhead tile To check the value of a specific bit, use the and operator. For example:

  variable (pass)
  set variable(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

write pass block (x,y,value) Writes a new passability (wallmap) information to the specified X,Y position on the current map. This change will only persist until you leave the map or fight a battle. The value is a number from from 0 to 255 that consists of eight flag bits. bit 1 = north wall bit 2 = east wall bit 4 = south wall bit 8 = west wall bit 16 = vehicle A bit 32 = vehicle B bit 64 = harm tile bit 128 = overhead tile You can add the constants together. For example:

variable (pass)
set variable(pass,northwall+southwall+eastwall+westwall)
write pass block(15,3,pass)
# this makes the fifteenth tile in the third column
# impassable on all directions

load tileset (set) Loads a different tileset for the currently displaying map. The argument is the ID number of the tileset to load. To restore the map's default tileset, use load tileset with no arguments. See also:

get map tileset

Working with Tags

set tag (tag,value) Sets the value of a tag. The available constants are: off, on, true, or false. You can specify the number of the tag, or you can use the constants in your HSI file. These constants are in the form of tag:name.

check tag (tag) A function that checks the value of a tag, and returns true if the tag is turned on, and false if the tag is turned off. It can be used in if and while statements. You can specify the number of the tag, or you can use the constants in your HSI file. These constants are in the form of tag:name.

Working with Variables

set variable (variable,value) This command assigns a new value to a variable. If you do not specify the new value, the variable will be reset to zero. This command works exactly the same for global and local variables. If you prefer, you can also set variables by writing variable := value

increment (variable,amount) This command adds an amount to the current value of a variable. If you do not specify the amount, then the variable will be incremented by one. This command works exactly the same for global and local variables. You can also increment variables by writing variable += amount

decrement (variable,amount) This command subtracts an amount from the current value of a variable. If you do not specify the amount, then the variable will be decremented by one. This command works exactly the same for global and local variables. You can also decrement variables by writing variable -= amount

Math, Comparison, and Logic Operators

Pre-December 1999 versions of HamsterSpeak used a different syntax for math. For more information, see the HamsterSpeak Specification

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

number -- number Subtracts the second number from the first number and returns the result. It is 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)

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

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

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

number ^ power Raises a number to a power and returns the result. Normally you will only be raising things to a power of 2. Raising to very large powers will most certainly produce an overflow error. This can also be written as exponent(number,power)

number == number Checks to see if the two numbers are equal. If they are equal it returns true, otherwise it returns false. This can also be written as equal(number,number)

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

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

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

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

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

value,and,value Returns true if both of the values are true (non-zero). If either of them is false, and returns false.

value,or,value Returns true if at least one of the values are true (non-zero). Only if both of them are false does or return false.

value,xor,value Returns true if one, but not both of the values are true (non-zero). If both of them are true, or both of them are false, xor returns false.

Flow Control

begin,other commands,end 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:

if (check tag(2)) then (show text box (5),wait for text box)

if (check tag(2)) then begin show text box (5) wait for text box end

end See begin

if(condition) then(commands) else(commands) The if statement checks the value of its condition, and if the value is true, it runs the commands in the then block. If the value is false, it runs the commands in its else block. The conditional is usually an equality operator such as == or <>, or it is a check tag 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

then See if

else See if

while(condition) do(commands) The while command checks the value of its condition, and if the value is true it runs the commands in the do block. It keeps checking the conditional and runs the do block over and over again until the conditional returns false. The conditional is usually an equality operator such as == or <>, or it is a check tag command.

do See also:

while, for

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

return(value) 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. This command does NOT cause the script to terminate, it just sets the return value. If return is used more than once in the same script, only the last one executed matters

Advanced Commands

set hero picture (who,picture,type) Permanently changes a hero's picture. The first argument is the heros position in the party as returned by find hero. The second argument is the index number of the picture to use, and the last argument is a constant inside battle or outside battle, which determines if you are changing the heros battle picture or their walkabout picture. If the last argument is left out, outside battle is assumed.

set hero palette (who,palette,type) Permanently changes a hero's 16-color palette. The first argument is the heros position in the party as returned by find hero. The second argument is the index number of the 16-color palette to use, and the last argument is a constant inside battle or outside battle, which determines if you are changing the heros battle palette or their walkabout palette. If the last argument is left out, outside battle is assumed.

get hero picture (who,type) A function that returns the index number of a hero's picture. The first argument is the heros position in the party as returned by find hero. The second argument is a constant inside battle or outside battle, which determines if you are checking the heros battle picture or their walkabout picture. If the second argument is left out, outside battle is assumed.

get hero palette (who,type) A function that returns the index number of a hero's 16-color palette. The first argument is the heros position in the party as returned by find hero. The second argument is a constant inside battle or outside battle, which determines if you are checking the heros battle palette or their walkabout palette. If the second argument is left out, outside battle is assumed.

alter NPC (who,NPCstat,value) Changes the stats of an NPC. Constants for this command have been included in PLOTSCR.HSD. Alter NPC can be used for many purposes.

Alter NPC (who,NPCstat:picture,picture number) Alter NPC (who,NPCstat:palette,palette number) Alter NPC (who,NPCstat:move type,move type code) Available move types NPCmovetype:standstill NPCmovetype:wander NPCmovetype:pace NPCmovetype:rightturns NPCmovetype:leftturns NPCmovetype:randomturns NPCmovetype:chaseyou NPCmovetype:avoidyou Alter NPC (who,NPCstat:move speed,speed) Alter NPC (who,NPCstat:display text,text box number) Alter NPC (who,NPCstat:when activated,when activated code) Available when activated codes NPCwhenactivated:changedirection NPCwhenactivated:faceplayer NPCwhenactivated:donotfaceplayer Alter NPC (who,NPCstat:give item,item number) Alter NPC (who,NPCstat:pushability,pushability code) Available pushability codes NPCpush:off NPCpush:full NPCpush:horizontal NPCpush:vertical NPCpush:uponly NPCpush:rightonly NPCpush:downonly NPCpush:leftonly Alter NPC (who,NPCstat:activation,activation code) Available activation codes NPCactivation:use NPCactivation:touch NPCactivation:stepon Alter NPC (who,NPCstat:script,script ID) Alter NPC (who,NPCstat:script argument,number) Alter NPC (who,NPCstat:vehicle,vehicle ID)

Normally you would only give an NPC ID number to alter NPC, but if you want to use an NPC reference it will still work. Just remember that alter NPC changes every copy of the NPC on the map, not just the specific one you referenced. A good way to make use of Alter NPC is to wrap it in your own script. For example: # Example AlterNPC wrapper for changing NPC appearance Define Script (autonumber,change NPC,3,0,0,0) script,change NPC,who,picture,palette,begin Alter NPC(who,NPCstat:picture,picture) Alter NPC(who,NPCstat:palette,palette) end

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

set death script (id) Changes the script that is run when you die in battle. The argument is the script's ID number, NOT the script's name. Calling set death script with no argument disables the death script.

get death script Returns the ID number of script that is run when you die in battle.

set load script (id) Changes the script that is run when you load a saved game. The argument is the script's ID number, NOT the script's name. Calling set load script with no argument disables the load script.

get load script Returns the ID number of script that is run when you load a saved game.

set on keypress script (id) Changes the script that is run when you press a key. The argument is the script's ID number, NOT the script's name. Calling set on keypress script with no argument disables the keypress script. The effect goes away if you change maps or fight a battle.

get on keypress script Returns the ID number of script that is run when you press a key.

set each step script (id) Changes the script that is run when you take a step. The argument is the script's ID number, NOT the script'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.

get each step script Returns the ID number of script that is run when you take a step.

set instead of battle script (id) Changes the script that is run instead of a battle when one is triggered. The argument is the script's ID number, NOT the script'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.

get instead of battle script Returns the ID number of script that is run instead of battles.

set harm tile damage (amount) Sets the amount of damage taken when you step on a harm tile. The effect goes away if you change maps or fight a battle.

set harm tile flash (color) Sets the color (from the master palette) which the screen 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.

set foot offset (offset) Sets the foot offset in pixels, the vertical displacement of npc and hero sprites from the base of the tiles on which they stand. The effect goes away if you change maps or fight a battle.

get foot offset Returns the map's foot offset.

draw NPCs above heroes (setting) Sets whether NPCs are drawn above heros or the default of beneath. The effect goes away if you change maps or fight a battle.

set map edge mode (mode, default tile) Sets the behaviour at the edge of the map. Use the constants crop, wrap and default tile. When the behaviour is default tile, you should give a second argument specifying which tile should be displayed off the boundaries of the map, otherwise ignore the second argument. The effect goes away if you change maps or fight a battle.

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

find hero (who) Searches through your 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. Use the names defined in your HSI file in the format hero:name. 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, but it will return a number 4 or higher if the hero is in the reserve. See also:

rank in caterpillar

hero by slot (where) This command is the reverse of find hero. Given a position in your party, it will tell you which hero is in that slot, or -1 if no hero is in that slot. The number returned can be compared with the names defined in your HSI file in the format hero:name.

rank in caterpillar (who) Searches through your active party to see if the specified hero is there, and returns the position int the walkabout caterpillar where the hero was found, or -1 if the hero was not found. Use the names defined in your HSI file in the format hero:name. This is particularaly useful if you need to use a command like walk hero but you are not sure which position the hero is in. See also:

find hero

hero by rank (where) This command is the reverse of rank in caterpillar. Given a position in your walkabout party, it will tell you which hero is in that position, or -1 if no hero is in that position. The number returned can be compared with the names defined in your HSI file in the format hero:name.

get hero stat (who,stat,type) A function that returns one of a hero's stats. The first argument is the position of the hero you want to check in your party as as returned by find hero. The second argument is the name of the stat that you want to check. The names of the stats are also define in your HSI file in the form stat:name. The third argument is either current stat or maximum stat. If you leave the last argument blank, current stat will be assumed. See also:

set hero stat, set enemy stat, get enemy stat

set hero stat (who,stat,value,type) A command that changes one of a hero's stats. The first argument is the position of the hero you want to change in your party as returned by find hero. The second argument is the name of the stat that you want to change. The names of the stats are 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 current stat or maximum stat. If you leave the last argument blank, current stat will be assumed. See also:

get hero stat, set enemy stat, get enemy stat

get hero level (who) A function that returns a hero's current level. The argument is the position of the hero you want to check in your party as as returned by find hero. The return value with be your current level, from 0 to 99

set hero level (who, level, forgetspells) A command that sets a hero's current level. The first argument is the position of the hero you want to change in your party as as returned by find hero. You can specify any hero in the active or reserve party and any (positive) 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's level, which will cause spells to be forgotten, unless the optional 3rd argument (defaulting to true) is set as false.

read global (id) A function that returns the value of a global variable using its ID number instead of its name. Why would you want to do a silly thing like that? Because it allows you to simulate simple fake arrays, in the old C-pointer style. See also:

write global

write global (id,value) A function that writes a value into a global variable using its ID number instead of its name. Why would you want to do a silly thing like that? Because it allows you to simulate simple fake arrays, in the old C-pointer style See also:

read global

set battle wait mode (state) Set whether or not battles pause on spell and item menus. If the argument is off then enemies continue to attack while menus are up, if the argument is on then enemies wait while menus are up.

set caterpillar mode (state) Sets whether or not to display the whole party in "caterpillar" style. If the argument is off then only the leader will be displayed. If the argument is on then the whole party will be displayed. (do not confuse this with the suspend caterpillar and resume caterpillar commands, which only apply when caterpillar mode is ON)

set no HP level up restore (state) Sets whether or not a hero regains full HP after a levelup. If the argument is off then HP is restored on a levelup. If the argument is on then the hero's HP is not restored on a levelup.

set no MP level up restore (state) Sets whether or not a hero regains full MP after a levelup. If the argument is off then MP is restored on a levelup. If the argument is on then the hero's MP is not restored on a levelup.

set inn no revive mode (state) Sets whether or not inns restore dead heros to life. If the argument is off then dead heros are restored by inns. If the argument is on then dead heros remain dead in inns.

set full hero swap mode (state) Sets whether or not you can swap heros in and out of your active party from the menu. If the argument is off then the "Order" menu will be available. If the argument is on then the "Team" menu will be available.

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

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

set debug keys disable (state) Sets whether or not the debugging keys are allowed. If the argument is off then debugging keys are allowed. If the argument is on then debugging keys are disabled.

allow minimap (setting) Sets whether the Map option appears in the menu. Give no argument or true to enable, or false to disable. The effect goes away if you change maps or fight a battle. See also:

show mini map

allow save anywhere (setting) Sets whether the Save option appears in the menu. Give no argument or true to enable, or false to disable. The effect goes away if you change maps or fight a battle. See also:

save menu

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

last save slot

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

load from slot (slot) Loads a saved game from a save slot as if it had been loaded from the load game menu. This command will end the current game.

delete save (slot) Deletes a saved game. The save will no longer be visible on the load game menu or loadable with load from slot. However, import globals can still be used to read globals out of the slot. See also:

save in slot

import globals (slot, first, last) Loads a range of globals from a saved game, overwriting the current globals in that range. First and Last are the id numbers of the globals at the beginning and end of the range. First defaults to 0, and Last defaults to 1024 if both are not given. To read a single global from a save slot without overwriting any, use the form 'var := import globals (slot, id)' import globals and export globals can be used to save and retrieve info about a saved game without loading it, and also to store variables that any game the player starts can use, like in the following example:

define script (21, game finished, none)

define script (22, check game finished, none)

global variable (100, game completed)
global variable (101, hours to complete)
global variable (102, minutes to complete)

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

script, check game finished, begin
  import globals (5, 100, 102) #copy saved values into globals 100, 101, 102
  if (game completed) then (
    show textbox (105) #"you have previously finished this game in ${V101} hours and ${V102} minutes"
  ) else (
    show textbox (106) #"you have yet to complete the game!"
  )
  wait for textbox
end

See also: read global

export globals (slot, first, last) Writes a range of globals to a saved game, overwriting the saved games globals. "First" and "Last" are the id numbers of the globals at the beginning and end of the range. First defaults to 0, and Last defaults to 1024. Therefore, if you pass no range, all the globals will be written. See also:

write global

run script by ID (id, argument1, argument2, argument3...) To making switching between scripts easier, you can call a script by its ID number. Pass arguments after the ID as normal. The script can also return a value as normal. -1 is returned if the script does not exist.

variable (return value)
return value := run script by id (10, 1, 2, 3)
show value (return value)

define script (10,sum,3,0,0,0)
script,sum,a,b,c,begin
  return(a+b+c)
end

get damage cap Returns the current damage cap, or 0 if none

set damage cap (cap) Sets the current damage cap to cap. Use 0 for no cap.

trace (string) Writes string #string to "G_DEBUG.TXT".

variable(i)
i:= random(1,1000)
$1="i = "
append number(1,i) #"i = 1"
trace(1) # writes "TRACE: i = 1" to G_DEBUG.TXT

Predefined Constants

Numeric Constants PLOTSCR.HSD defines constants for the numbers from 0 to 10. you can use these constants to make your scripts look friendly :) zero, one, two, three, four, five, six, seven, eight, nine, ten

zero See Numeric Constants

one See Numeric Constants

two See Numeric Constants

three See Numeric Constants

four See Numeric Constants

five See Numeric Constants

six See Numeric Constants

seven See Numeric Constants

eight See Numeric Constants

nine See Numeric Constants

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

any key See Key Constants

up key See Key Constants

down key See Key Constants

left key See Key Constants

right key See Key Constants

use key See Key Constants

menu key See Key Constants

cancel key See Key Constants

Boolean Constants PLOTSCR.HSD defines constants for true and false, and for ON and OFF. These are useful for checking and setting the values of tags, and in conditional statements. true, false, on, off

true See Boolean Constants

false See Boolean Constants

on See Boolean Constants

off See Boolean Constants

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

north See Direction Constants

south See Direction Constants

east See Direction Constants

west See Direction Constants

up See Direction Constants

down See Direction Constants

right See Direction Constants

left See Direction Constants

me me is a constant that can be used to refer to the first hero in your party (hero zero) in any command that takes a hero number as an argument.

none none is a constant that means the same as zero. It is normally used in define script commands for scripts that do not have any arguments

autonumber autonumber is a constant that is used as the ID number in define script commands for scripts that do not need to be called directly from the OHRRPGCE. Autonumber scripts are only called from within other scripts.

current stat A constant for use with the get hero stat and set hero stat commands.

maximum stat A constant for use with the get hero stat and set hero stat commands.

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

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

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

color:red See Color Constants

color:green See Color Constants

color:blue See Color Constants

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

left button See Mouse Constants

right button See Mouse Constants

get count When passed to NPC at pixel or NPC at spot, they return the number of NPCs at that spot. With spells learnt returns the number of spells a hero learnt.

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

north wall See Tile Constants

east wall See Tile Constants

west wall See Tile Constants

south wall See Tile Constants

vehicle A See Tile Constants

vehicle B See Tile Constants

harm tile See Tile Constants

overhead tile See Tile Constants

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

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

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

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

Stats: There are 366 commands in this file, of which 51 are only references to other commands.

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

Plotscripting Dictionary

Commands by Category

Alphabetical Index