Plotscripting Tutorial

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 first learn simple plotscripting, and move on to more complex scripts gradually.

Getting Started

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 but if you already have an RPG file in progress, you may want to adapt these instructions for your own game.

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. There are a number of suitable editors, including dedicated plotscript editors such as Hamster Whisper, listed on the Plotscripting Tools page, but you do not have to use them. Any editor that can save plain text is okay (Don't use Microsoft Word. .doc files are not text!)

Open a new text file in your editor, and save it in the same folder where you saved PSTUTOR.RPG and name it pstutor.hss

The .hss extension stands for HamsterSpeak Script. You don't have to use the .hss extension; .txt is fine as well.

Your First Script

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

plotscript, Hello World, begin
end

This tells the compiler that your script is going to be named "Hello World"

now, you write the body of the script.

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

Importing & Compiling your Script

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 (or alternatively press F5 to skip the next two steps)
• Choose Export names for scripts
• Choose Compile and/or Import scripts
• Find PSTUTOR.HSS in the file browser
• When you choose PSTUTOR.HSS, the script will be compiled, and it will say "1 script imported successfully"
• Don't quit CUSTOM.EXE yet, we need to make something call the script

Other Ways to Compile

Choosing your script from the Compile and/or Import scripts is not the only way to compile your script. You can learn about other methods in a separate article: Other Ways to Compile A Plotscript

Calling your Script

So when does your script get run?

There are many ways to call a script in your RPG, but 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. Let's 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 let's try something that you can't do without plotscripting; making your hero move in a predefined pattern.

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

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

• show text box (1) displays text box 1, 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

Now 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. Now import your script again

• 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, walk left and right, 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:

plotscript, Hello World, begin
  suspend player
  show text box (1)
  wait for text box
  walk hero (me,north,3)
  wait for hero (me)
  walk hero (me,west,1)
  wait for hero (me)
  walk hero (me,east,2)
  wait for hero (me)
  walk hero (me,west,1)
  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 bringing 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.

Starting a Script with an NPC

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

Add a new script called "Robot Dance"

plotscript, Hello World, begin
  suspend player
  show text box (1)
  wait for text box
  walk hero (me,north,3)
  wait for hero (me)
  walk hero (me,west,1)
  wait for hero (me)
  walk hero (me,east,2)
  wait for hero (me)
  walk hero (me,west,1)
  wait for hero (me)
  set hero direction (me,south)
  resume player
end
 
plotscript, 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 can't 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
• PSTUTIR.RPG already has an 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 Easier 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. Spaces are also ignored. To make a comment, just start a line with a #

# This is my practice script. It is for use with PSTUTOR.RPG
 
#-----------------------------------------------------
#this script makes the robot say "Hello World"
#and then walk three spaces north, then side-to-side

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

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

plotscript, 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 isn't that easier to look at?

Giving a Script Arguments

Arguments are a way of passing extra information to a script. You can read a full length article about script arguments at What is a script argument for?

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

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

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

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

plotscript, Robot Dance, who=0, begin
  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 are some of the ways to start a script.

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 equipping your heroes with their starting equipment.

Normally the new-game script receives no arguments, but if you pass any to reset game, they get passed on to the new-game script.

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 resetting 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 saved game. If you write your script to accept an argument, it will be filled with the slot-number that the player loaded from 0,1,2,3... up to 31. (or -1 if you load a debugging quicksave with F3)

If you pass any extra arguments to load from slot, they get passed on to the load-game script after the save slot number.

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 filled with an NPC reference to the NPC.

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 or the battle ended due to a an attack with the "Force battle exit" bit. (The "Force victory" bit counts as winning, of course.)

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, don't 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.

Menu Script

Menu items that you define in the Edit Menus screen can trigger scripts. The arguments to the script depend on whether the menu bitset Allow gameplay and scripts is turned on:

• If OFF, the menu will be gone before the script gets a chance to run, so in that case the script will get three arguments containing the "extra" data fields for the menu item.
• If ON, the first argument to the script will be a menu item handle for the menu item that triggered the script. Note that if you want access to the "extra" data, you should get it using the menu handle. Also note that if the menu item is set to close the menu when used, then the menu item handle is invalid and useless

Menu On-Close Script

Menus can have a script that is run when the menu closes. It is only run when the player closes the menu, not when the menu is closed using the close menu plotscript command. No arguments are passed to a menu on-close script (the menu handle would not make sense, because the menu is already gone when the script starts)

Learning More

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