Plotscripting Tutorial for the O.H.R.RPG.C.E.

This document is obsolete. For the current version, see the Plotscripting Tutorial @ the OHRRPGCE Wiki

PlotScripting - tutorial for beginners

Last Updated June 7 2001

What is plotscripting? From the most simple perspective plotscripting is where the computer takes control of the characters in your RPG, and moves them around, and makes them say stuff. Anyone who has played popular RPGs like Final Fantasy will be familiar with this concept.

Plotscripting is actually capable of far more than that, even allowing you to create puzzles, mini-games, and special effects in your game, but that sort of thing is not covered in this tutorial. People who want to use the programming-language-like features of plotscripting should read the Dictionary of PlotScripting Commands and the HamsterSpeak Specification

Getting Started
Creating a Script File
Your First Script
Compiling Your Script
Importing Your Script into CUSTOM.EXE
Calling Your Script
Running Your Script
Making the Hero Walk Around
Stopping Normal Controls
Starting a Script with an NPC
Making your Script Easyer to Read
Giving a Script Arguments
Other Ways to Start a Script
Learning More

Getting Started

First of all, you need to make sure that you have the latest version of the OHRRPGCE from http://HamsterRepublic.com/html/ohrrpgce.html. Versions older than November X 1999 do not have plotscripting.

Okay. This tutorial will walk you through writing a script, compiling it with HSPEAK.EXE, importing it into CUSTOM.EXE, telling your RPG file when and where to run it, and testing the finished script in GAME.EXE. The examples will use PSTUTOR.RPG (included in CUSTOM.ZIP) but if you already have an RPG file in progress, you may want to adapt these instructions for your own game. These examples will assume that you have installed the O.H.R.RPG.C.E in C:\OHRRPGCE\ if you put it somewhere else, just substitute your directory in the examples.

To make sure you have the OHRRPGCE installed and running okay, run GAME.EXE and pick PSTUTOR.RPG from the list. Press a key to get past the title screen, and you should see a silly looking little robot standing on a small platform in space. This is the file that you will be adding plotscripts to as you follow this tutorial. Press ESC and quit.

Creating a Script File

Plotscripts are just plain text files that you can create with any text editor, but you will probably want to use HssEd, which has built-in help, and easy compiling. There is also a third-party editor made by IronHoof7. Both of these editors are Windows-only, so if you are a DOS user, I reccomend using EDIT.COM to write your scripts.

Open a new text file in editor, and save it as C:\OHRRPGCE\PSTUTOR.HSS
The .HSS extension stands for HamsterSpeak Script. (this is just suggested. you can use whatever extension you want, even .TXT)

At the top of your script, type the following two lines:

include, plotscr.hsd
include, pstutor.hsi

plotscr.hsd had the definitions of all of the Plotscripting commands.
pstutor.hsi contains information about PSTUTOR.RPG. This tutorial will explain later how to create an HSI file (HamsterSpeak Include)

Your First Script

Okay, now it is time to write a script. the first step is to define the script.

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)

This tells the compiler that your script's ID number is 1, and it is going to be named "Hello World" and that it doesnt need any arguments. (arguments are explained later)

now, you write the body of the script.

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)

script, Hello World, begin
show text box (1)
end

this script only has one command, "show text box". When the script is run, it will display the text box numbered in the parenthesis (1) just as if you had talked to an NPC. (Text Box 1 in PSTUTOR.RPG has already been made for you, and all it says is "Hello world!")

Save your script

Compiling Your Script

Now it is time to compile your plotscript. This takes script you just wrote, and converts it into a binary file that can be used by the OHRRPGCE.

If you are using HssEd, press F5 or choose "Compile" from the "Script" menu. (The first time you do this, it might ask you to locate HSPEAK.EXE, but once you have located it one, HssEd will remember where it is)

If you are using DOS, or a DOS prompt in windows, go to C:\OHRRPGCE and type:
HSPEAK PSTUTOR.HSS

If you are one of them point-and-click people:

use Windows Explorer or My Computer to open the OHRRPGCE folder on drive C
Double-click on PSTUTOR.HSS
The "Open As" window will appear, asking you what application you want to use for .HSS files
Click "other" and type in the path to HSPEAK.EXE (probably C:\OHRRPGCE\HSPEAK.EXE)
Click "OK", make sure "Always use this program" is checked, and click "OK" again
Next time, all you will have to do is double click on the HSS file
Another Windows trick that gets the same results is to drag and drop your HSS file onto HSPEAK.EXE

Now, you should have a file called PSTUTOR.HS. This is the compiled plotscript.

Importing Your Script into CUSTOM.EXE

Now it is time to import your script into your RPG.

Run CUSTOM.EXE and open PSTUTOR.RPG
From the main menu, choose Script Management
Choose Import Compiled Plotscripts
Find PSTUTOR.HS in the file browser
When you choose PSTUTOR.HS, you will see the name of the script, "helloworld", and it will say "1 script imported sucessfully"
Dont quit CUSTOM.EXE yet, we need to make something call the script

Calling Your Script

So when does your script get run?
There are many ways to call a script in your RPG. You can have a script run automatically when you start a new game, when you enter a map, when you talk to an NPC, when you use an item, when you die in battle, when you use an Inn, and possibly some other places that I havent implemented yet or cant remember :)

for the moment, we will use the autorun script that is run when you start a new game

From the main menu in CUSTOM.EXE, pick Edit General Game Data
Pick Special Plotscripts
For new game script choose helloworld
Exit, and save your changes to PSTUTOR.RPG

Running Your Script

Run GAME.EXE
Open PSTUTOR.RPG
Press any key when prompted
As soon as you start, the script will run, and you will immediately see the "Hello World" text box

Congratulations! You just ran your first plotscript!
"But that is so boring!" you say. Well, read on. Lets make your script more interesting

Making the Hero Walk Around

Showing text boxes is all well and good, but you can do that without plotscripting. Now lets try something that you cant do without plotscripting; making your hero move in a predefined pattern.

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)

script, Hello World, begin
show text box (1)
wait for text box
walk hero (me,north,3)
wait for hero (me)
set hero direction (me,south)
end

Add these four new commands to your "Hello World" script. This is what the commands do:

show text box (1) displays a text box, same as before
wait for text box waits for you to press a key and get rid of the text box
walk hero (me,north,3) makes your hero walk north for three spaces. me is a special name that refers to your main hero
wait for hero (me) waits for the main hero (me) to finish walking
set hero direction (me,south) makes the main hero face south

Save the changes to your script.
Recompile your script.
This time, HSPEAK.EXE will ask you if you want to overwrite the existing PSTUTOR.HS file. Press Y for yes.
Run CUSTOM.EXE and open PSTUTOR.RPG
From the main menu, choose Script Management
Choose Import Compiled Plotscripts
Choose PSTUTOR.HS in the file browser
Exit, and save your changes to PSTUTOR.RPG
Run GAME.EXE and open PSTUTOR.RPG
After you start, the "Hello World" text box will pop up, and after you press a key, the hero will walk north, and then turn to face you.

Stopping Normal Controls

Try running your script again, but this time, press left or right as the robot moves. As you can see, the player can interfere with the plotscript. How do we prevent this?

Go back to your plotscript, and add the following commands:

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)

script, Hello World, begin
suspend player
show text box (1)
wait for text box
walk hero (me,north,3)
wait for hero (me)
set hero direction (me,south)
resume player
end

the suspend player command at the begining prevents the player from moving the hero around or bringign up the menu. It effectively blocks all of the players controls (except that it still allows them to advance text boxes). The resume player command at the end of your script gives control of the hero back to the player. Almost every script you write will start with suspend player, and end with resume player

Now recompile your script, reimport it, and test it again. This time, you will not be able to interfere when the robot walks three spaces north.

Starting a Script with an NPC

Probably the most common way that you will want to start your scripts is by talking to NPCs. Lets add a new script, and show you how to start it with an NPC

Define a new script called "Robot Dance"

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)
define script (2,Robot Dance,none)

script, Hello World, begin
suspend player
show text box (1)
wait for text box
walk hero (me,north,3)
wait for hero (me)
set hero direction (me,south)
resume player
end

Now, lets write the script.

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)
define script (2,Robot Dance,none)

script, Hello World, begin
suspend player
show text box (1)
wait for text box
walk hero (me,north,3)
wait for hero (me)
set hero direction (me,south)
resume player
end

script, Robot Dance, begin
suspend player
walk NPC (0,west,1)
wait for NPC (0)
walk NPC (0,east,2)
wait for NPC (0)
walk NPC (0,west,1)
wait for NPC (0)
set NPC direction (0,north)
wait (4)
set NPC direction (0,east)
wait (4)
set NPC direction (0,south)
resume player
end

Look at the commands this script uses. NPC zero (the first NPC) will walk left, then right, then back to the center, and then spin in a circle. The wait (4) commands are to make sure that he does not spin so fast that you cant see it happen.

Recompile the script, and import it into PSTUTOR.RPG. This time, when you import the .HS file, CUSTOM.EXE will tell you that it successfully imported 2 scripts, and it will show you the names "helloworld" and "robotdance"

Now, go back to the main menu
choose Edit Map Data
choose Map 00
Choose Edit NPCs
I have already created NPC 0 for you. He is the one with green feet. Choose him, and edit his properties
Notice that he has a walking speed of 4 even though his movement type is "stand still". This is because the Walk NPC command will not work on an NPC with 0 speed
Change his Run Script: property from [none] to "robotdance"
Press ESC twice to get out of the NPC editor
Choose Place NPCs and place the green-footed robot somewhere on the platform
Exit, and save your changes to PSTUTOR.RPG
Run GAME.EXE, open PSTUTOR.RPG, and talk to the NPC
The green footed robot should do a dance for you when you talk to him

Making your Script Easyer to Read

as a script gets bigger, it can get hard to read. To make things easyer on yourself, you can add comments, indentation, and spacing to make your script look cleaner.

comments are notes to yourself that remind you how your script works. Comments are ignored by the compiler. To make a comment, just start a line with a #

# This is my practice script. It is for use with PSTUTOR.RPG

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)
define script (2,Robot Dance,none)

#---------------------------------------------
#this script makes the robot say "Hello World"
#and then walk three spaces north

script, Hello World, begin
  suspend player
  show text box       (1)
  wait for text box
  walk hero           (me,north,3)
  wait for hero       (me)
  set hero direction  (me,south)
  resume player
end

#---------------------------------------------
#This script makes an NPC do a dance

script, Robot Dance, begin
  suspend player
  walk NPC            (0,west,1)
  wait for NPC        (0)
  walk NPC            (0,east,2)
  wait for NPC        (0)
  walk NPC            (0,west,1)
  wait for NPC        (0)
  set NPC direction   (0,north)
  wait                (4)
  set NPC direction   (0,east)
  wait                (4)
  set NPC direction   (0,south)
  resume player
end

There. now isnt that easyer to look at?

Giving a Script Arguments

Arguments are a way of passing extra information to a script. I know its a silly name, but its a programming thing, so what do you expect? :)

What if you want to be able to make several different NPCs do the NPC dance? The way we have the Robot Dance written right now, the script only works on NPC number zero. What if we want NPC 1, 2 and 3 to do the very same dance when you talk to them? Do we have to make three copies of the script and give them each new ID numbers and names? Nope. That would be way too much work. What we want to do is give the Robot Dance script an argument.

# This is my practice script. It is for use with PSTUTOR.RPG

include, plotscr.hsd
include, pstutor.hsi

define script (1,Hello World,none)
define script (2,Robot Dance,1,0)
# the Robot Dance has 1 argument that defaults to 0 if it is left out

#---------------------------------------------
#this script makes the robot say "Hello World"
#and then walk three spaces north

script, Hello World, begin
  suspend player
  show text box       (1)
  wait for text box
  walk hero           (me,north,3)
  wait for hero       (me)
  set hero direction  (me,south)
  resume player
end

#---------------------------------------------
#This script makes an NPC do a dance

script, Robot Dance, who, begin
# the name of the argument is "who"
  suspend player
  walk NPC            (who,west,1)
  wait for NPC        (who)
  walk NPC            (who,east,2)
  wait for NPC        (who)
  walk NPC            (who,west,1)
  wait for NPC        (who)
  set NPC direction   (who,north)
  wait                (4)
  set NPC direction   (who,east)
  wait                (4)
  set NPC direction   (who,south)
  resume player
end

Recompile your script, and reimport it into CUSTOM.EXE
Go into the map editor and pick Map 00
Go into the NPC editor, and look at the green-footed robot
Right Below the name of the script that he runs, you will see a number for the Script Argument. Whatever value you put there will be used as the who argument in the script.
The green-footed robot should use 0 as his argument because he is NPC number 0
Edit the second NPC, number 1. Give him the Robot Dance script, and make his argument 1
Put the new NPC on the map
Exit CUSTOM.EXE and save
Load PSTUROR.RPG in GAME.EXE and try out both NPCs. Even though they both use the exact same script, the argument allows that one script to do two slightly different things.

Other Ways to Start a Script

So far you know how to start a script as the "New-game" script for your RPG, and by talking to an NPC, but there are plenty of other ways to trigger plotscripts in your game. here is a list.

New-Game Script
In "Special Plotscripts" in the "General Game Data" editor you can set the script that will be run whenever you begin a new game. This is great for telling the story, showing an intro-sequence, setting up the beginning party, and equiping your heros with their starting equipment

Game-Over Script
In "Special Plotscripts" in the "General Game Data" editor you can set the "Game-over" script. Normally when you die in battle, the game resets back to the title screen, but if you have set a game-over script, then it will be run instead. Perhaps you want to restore the dead heros to life with the set hero stat command. Perhaps you want to show "game over" picture with show backdrop before reseting the game with the game over command (which can be called from ANY plotscript, not just a Game-over plotscript) Or perhaps you want to use if statements and do different things depending on the values of tags.

Load-Game Script
In "Special Plotscripts" in the "General Game Data" editor you can set a script that will be run automatically whenever the player loads a savedgame. If you write your script to accept an argument, it will be passed the slot-number that the player loaded from 0,2,3, or 4. (or -1 if you load a debugging quicksave with F3)

Text Box Scripts
In the text box editor you can select a script that will be run after the text box displays. If you edit the text box's conditionals you get a little more control over this script. You make it run conditionally depending on a tag, and you can make it run instead of the text box rather than after the text box.

Item Scripts
Although you cannot directly call a script from an item, you can call a text box from an item, and attach the script to that text box

NPC Scripts
In the NPC editor you can assign a script to be triggered by an NPC. You also have the option of assigning an argument that will be passed to that script. Also, if your script is defined to accept a second argument, it will be automatically passed an NPC reference

Vehicle Scripts
In the vehicle editor you can assign scipts that will be run when you mount the vehicle, when you dismount the vehicle, or when you press the use or cancel buttons

Inn Script
In the Shop Editor you can set a script that will be run when you sleep at the inn.

Map Autorun Script
In the "General Map Data" menu of the Map editor, you can set a script that will be run automatically whenever you enter a map. You can also assign an argument to be passed to this script

After-Battle Script
In the "General Map Data" menu of the Map editor, you can set a script that will be run automatically after every battle on the map. It will automatically be passed one argument with a value of true if you won the battle and false if you died or ran away

Instead-of-Battle Script
In the "General Map Data" menu of the Map editor, you can set a script that will be run instead whenever a random battle would have been triggered. It automatically gets two arguments passed to it, the first is the formation number of the battle you would have fought (in case you want to go ahead and trigger the battle from your script with the fight formation command), and the second argument is the number of the battle-formation-set that the random battle was chosen from.

Each-Step Script
In the "General Map Data" menu of the Map editor, you can set a script that gets called every single time your hero takes a step on that map. It is automatically passed three arguments, the hero's horizontal position (X), the hero's vertical position (Y), and the hero's current direction, north, south, east, or west. Since this script will get called frequently, it is a good idea not to use any wait type commands in it

On-Keypress Script
In the "General Map Data" menu of the Map editor, you can set a script that gets run every single time the player presses a key on the map. This applies to every key on the keyboard, not just the ones that normally do something. Inside your script you can use the key is pressed command to see if a key you care about has been triggered. Because holding a key down can cause this script to be rapidly and repeatedly called, dont make the script too long or you will see your game slow down. Also, be careful using wait type commands in this kind of script.

Learning More

I hope this is enough to get you started. The next step is to read the Dictionary of PlotScripting Commands and try out some of the commands listed there.