HamsterSpeak is the language used by the OHRRPGCE for plotscripting, This file explains the syntax and reserved words for HamsterSpeak.

This document may appear ovewhelming to non-programmers, so instead, you will want to read the Plotscripting Tutorial, which is written for beginners, and the Dictionary of PlotScripting Commands.

HamsterSpeak is a semicompiler that parses scripts and converts them into bytecodes that can be easyly and quickly parsed by an interpreter such as the one that will be built into the OHRRPGCE.

HamsterSpeak function and variable names are case insensitive and whitespace insensitive. The following are all valid ways of writing the same command:

Suspend Player
suspendplayer
sUsPeNdPlAyRr
Susp Endpla Yer

Statements are separated by commas or newlines. Blank lines are ignored, and double commas are treated as single commas. You can use commas and newlines interchangeably. For example, the following blocks of code are the same:

Suspend Player
Suspend NPCs
Suspend Obstruction

Suspend Player, Suspend NPCs, Suspend Obstruction

Most HamsterSpeak functions take arguments. The arguments for a function follow it in parenthesis. The following are examples of HamsterSpeak functions:

walk hero (me,north,3)
wait for hero (me)
show text box (37)

Also, as an alternative to using parenthesis, you can use the begin and end commands. These are useful for functions that take lots of arguments easyer to look at.

The following blocks of code do exactly the same thing

walk hero (me, north, 3)

You can use the # symbol to put comments in your script. Anything from the # to the end of the line is ignored.

walk hero, begin
  me      # who does the walking? Me!
  north   # this is the direction we want to walk
  3       # this is how many tiles we want to go
end

There are seven kinds of declarations in HamsterSpeak. script, define script, define function, define constant, define operator, global variable, and variable,

script and definescript

Most of the code in HamsterSpeak is in script statements. for every script statement, there must also be a definescript statement that assigns the script a unique ID number, and tells how many arguments it can accept.

Here is a sample script

Define Script (1,My Script,none)

script, My Script, begin
  # code goes here
end

Each script you define needs a number(1), a name(My Script), and the argument count(none). Scripts that have arguments, need default values fot those arguments in the definescript statement, and names for the arguments in the script statement.

Here is a sample script with arguments

Define Script (2,My Fancy Script,2,0,0)
# this script has two arguments, both default to zero

script, My Fancy Script, firstarg, secondarg, begin
  # This script can use the arguments by name
  # just as if they were local variables
end

Okay, now lets look in more detail at the definescript statement. Every script you write needs a number, a name, and info about it's arguments.

include, plotscr.hsd

Define Script (1,My Script,none)
Define Script (2,My Other Script,none)

script, My Script, begin
  # do nothing
end

script, My Other Script, begin
  # do nothing
end

The first argument of definescript is the id number of the script. This is the number that the OHRRPGCE identifies the script by. No two scripts can have the same id number

# this is bad! It will not compile. BAD! BAD! BAD!
Define Script (1,My Script,none)
Define Script (1,My Other Script,none)

If you do this, and give two scripts the same number, the compiler will throw a fit.

The second argument of definescript is the friendly name of your script. When the compiler sees My Script in the code, it will know you mean the script with ID number 1

Why do scripts need ID numbers? That is how CUSTOM.EXE and GAME.EXE know what script to attach to what event, without having to remember the entire name of the script. But if you have a script that will never be called directly by your game, and is only called by other scripts, you can autonumber the script.

Here is a sample script that is autonumbered

Define Script (autonumber,My Numberless Script,none)
# this script will be hidden in CUSTOM.EXE,
# but can be called by other scripts

script, My Numberless Script, begin
  # blah blah blah
end

You can call scripts by using their names, just like you call built-in functions

definefunction

For a script to make use of any plotscripting functions, It needs definefunction statements. Definefunction statements are just like definescript statements, except that they refer to special functions that are hard-coded into the interpreter.
( you are getting sleepy, very sleepy. Your eyes are growing heavy. Now you will sleep. When you awake you will forget anything you ever heard about about "battlescripting". There is no such thing as battlescripting )

If you had to manually type your definefunction statements, your code would look like this, only there would be waaaaay more of them:

define function, begin
 0,noop,0
 1,wait,1,1
 2,waitforall,0
 3,waitforhero,1,0
 4,waitfornpc,1,0
 5,suspendnpcs,0
 6,suspendplayer,0
 7,resumenpcs,0
 8,resumeplayer,0
 9,waitforkey,1,99
 10,walkhero,3,0,2,1
 11,showtextbox,1,1
 12,checktag,1,0
 13,settag,2,0,0
 # this isnt all! there are more than 120 plotscripting functions!
end

Define Script (1,My Script,none)

script, My Script, begin
  # I can only use functions here if they have been declared
end

obviously nobody wants to type all that junk at the top of their script just to make it run, so I have put all of the plotscripting functions into a single file called plotscr.hsd
All you have to do is add one include statement, and all of the plotscripting functions will be ready to use.

include, plotscr.hsd

Define Script (1,My Script,none)

script, My Script, begin
  # I can use any plotscripting function here I want,
  # because they have all been declared in the include file.
end

defineconstant

plotscr.hsd also has some constants to make life easyer. Thanks to constants, there is no need to know what numbers plotscripting uses to internaly represent things. The following are some of the constants defined in plotscr.hsd
zero, one, two, three, four, five, six, seven, eight, nine, ten, false, true, off, on, north, east, south, west, up, down, left, right, upkey, downkey, leftkey, rightkey, usekey, cancelkey, menukey, anykey, me, none, autonumber...

Another use for constants is the ability to refer to heros, maps, songs, items, and all sorts of other things in your RPG by name instead of by number. CUSTOM.EXE can export an include file from its Script Management that is full of constants that represent the names in your RPG. This file will have the same name as your RPG file, with the extension HSI (HamsterSpeak Include), and you can include it into your script the exact same way you include the plotscr.hsd file

You can add your own constants to your script with a defineconstant statement

include, plotscr.hsd
include, myrpg.hsi

Define Constant (1000,thousand)
Define Script (1,My Script,none)

script, My Script, begin
  # now I can use the word thousand instead of 1000 in my script
  get money (thousand)
end

defineoperator

The defineoperator command substitutes an infix operator for a function or script that is defined elswhere. Hamsterspeak uses this to support math and logic operators such as 1+2. If you dont know what "infix" means, or what "operators" are, dont worry. You will never use defineoperator for anything. I only mention it here for the sake of documentation. If you want to turn some of your scripts into operators, you can use PLOTSCR.HSD as an example, or mail me and ask questions.

The important part is knowing how to use the infix operators that have already been defined for you. The most common use of these operators is for doing math, and checking equality. For a complete list of them, check the Operator section of the Plotscripting Dictionary.

Math: Math operators take the value on their left, and the value on their right, preform math on them, and return the result.

include, plotscr.hsd

Define Script (1,Math Sample,none)

script, Math Sample, begin
  variable (n)
  n:=100
  # we start with 100
  n:=n+5  # now n is 105
  n:=n*2  # now n is 210
  n:=n--6 # now n is 204
  n:=n/4  # now n is 51
  show value (n)
end

Notice that the symbol for subtract is -- That is neccisary to avoid confusion with script names and constants that have hyphens in them, and numbers that start with - to indicate negativity. If you wanted to subtract a negative number, you should write n -- -6

Comparison and Logic: Comparison and logic operators take the value on their left, and the value on their right, compare them, and return true or false based on the comparison. They are most often used in if statements

include, plotscr.hsd

Define Script (1,Comparison Sample,none)

script, Comparison Sample, begin

  if (5==7)
  then,begin
    # five is never equal to seven, so this cant be true
  end

  if (5<<7)
  then,begin
    # five is always less than seven, so this is always true
  end

  if (5>>7)
  then,begin
    # five is never greater than seven, so this cant be true
  end

  if (5<=random(1,10))
  then,begin
    # there is a 50% chance that 5 will be less than or equal to
    # the random number between 1 and 10, so sometimes this will be
    # true and other times it will be false
  end

  if (1==1,and,2<>2)
  then,begin
    # one is always equal to one, but two is never not-equal to itself
    # so this can never be true
  end

end

include, plotscr.hsd

Define Script (1,one script,none)
Define Script (2,another script,none)

Global Variable (1,var)

script, one script, begin
  # I can set a global variable in one script...
  var:=100
end

script, one script, begin
  # ...and use it in another
  show value (var)
end

include, plotscr.hsd

Define Script (1,test script,none)

script, test script, begin
  variable (var)
  # this variable is only available to this script
  var:=100
end

If you wrote a HamsterSpeak script before December XX 1999, you probably used the old style of math and logic operators. When you try to compile one of these old scripts with HSPEAK.EXE version 1, you may run into errors when compiling, or strange behavior after the script is imported into your RPG file. Fortunately, that lack of backwards compatability has been fixed in HSPEAK.EXE version 2. You can use whichever you prefer; the old style functions, or the new style operators. You can even mix them in the same script. The notable exception to this is the or and xor and modulus commands. These ones are NOT backwards compatable. You must use the operator-style, not the old function style.

for explanations of all the operators, see the Math, Comparison, and Logic Operators section of the Plotscripting Dictionary