HamsterSpeak version 0
Last Updated May 4 2000

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.

Syntax
Declarations
Old vs. New Style Operators
Syntax

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

Remember this when you are naming your scripts and variables.

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)


walk hero, begin
   me
   north
   3
end

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

Declarations

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

definefunction

For a script to make use of any plotscripting functions or battlescripting 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.

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 80 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)
  set variable (n,100)
  # we start with 100
  set variable (n,n+5)  # now n is 105
  set variable (n,n*2)  # now n is 210
  set variable (n,n--6) # now n is 204
  set variable (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

variables

A variable is a named number-holder in your script that you can give any value to. Variables can be global, which means they are available to every single script, and are saved in your RPG, or they can be local, which means they only work in the script they where created in, and once that script ends, they go away.

Global variables are defined with the globalvariable statement. Like scripts, global variables need unique ID numbers. 


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...
  set variable (var,100)
end

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

Local variables are declared with the variable statement. A local variable always starts out as zero when the script starts. You can use the variable throughout the script, and when the script finishes, zap! the variable is gone. If you run the script a second time, it will be created all over again. Local variables do not need an ID number 


include, plotscr.hsd

Define Script (1,test script,none)

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

Note that globalvariable always goes outside of your scripts. Variable always goes inside a script. Local variables are created as soon as the script starts, regardless of where in the script you define them.

Old vs. New Style Operators

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 a newer version of HSPEAK.EXE, you may run into errors when compiling, or strange behavior after the script is imported into your RPG file. The following table will help you convert your script to the new version. Special attention should be payed to the conditions in if statements.

Old Style New Style
add(n,n) n+n
subtract(n,n) n--n
multiply(n,n) n*n
divide(n,n) n/n
modulus(n,n) n,mod,n
exponent(n,n) n^n
equal(n,n) n==n
notequal(n,n) n<>n
lessthan(n,n) n<<n
greaterthan(n,n) n>>n
lessthanorequalto(n,n) n<=n
greaterthanorequalto(n,n) n>=n
and(n,n) n,and,n
or(n,n) n,or,n
xor(n,n) n,xor,n

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