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

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.

A script is a simple text file, and you can write it in any text editor. If you dont already have a favorite text editor, I suggest that Windows users use notepad.exe and DOS users use edit.com. If you write your script in a word processor like Microsoft Word or Corel WordPerfect make sure that you save as plain ASCII text (DOS text)

Open a new text file in your text 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)

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 number 1 is going to be named "Hello World" and that it doesnt need any arguments. (arguments are only useful for advanced users, and are not discussed in this tutorial. See the HamsterSpeak Specification if you want to know more)

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

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

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

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

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 remeber :)

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

• 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

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 by double-clicking on PSTUTOR.HSS or typing HSPEAK PSTUTOR.HSS at a dos prompt.
• 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.

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.

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

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?

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.

I hope this is enough to get you started this tutorial will be expanding in the future. Untill then, check out the Dictionary of PlotScripting Commands