The Basics of Scripting

by alexp

<< All Articles | Print

Overview & Prerequisites

This article will introduce you to the concept and basics of Scripting, a tool available in the Advanced Editor that allows you, as an author, to have more precise control over what happens in your storygames. In order to use Scripting, you will need to know how to use the Advanced Editor and be familiar with Variables.

Scripting Defined

The first thing to keep in mind about scripting is that, virtually everything you can do with a script you can do with other things in the editor, such as Variable Changes and Item Drops. The key difference is that, in some circumstances, scripting can make these things much easier to do. In this article, we will focus on only one thing -- Variable Changes -- something you should already be familiar with doing.

Enabling Scripting in the Advanced Editor

Before getting started, you'll want to make sure that you have enabled Scripting in your storygame. To do this, go to the Properties page in the Advanced Editor, and scroll down to the "Editor Features" heading. Click on the [change editor features] link and, on that page, change Scripting to Basic. As you get more familiar with Scripting, you can increase the level to Advanced.

Once Scripting has been set to Basic on your storygame, you'll notice a few new things:

  • A "Scripts" navigation item appears
  • Numbers appear next to Items and Pages
  • A new button (Edit Link Script) will appear next to each link
  • A new option ([Edit Item Script]) will appear on the Edit Item page

These new options will allow you to create Link Scripts and Item Scripts within your storygames.

Link Scripts

Changing A Variable

Similar to Variable Changes and Item Drops, a Link Script is processed whenever the player clicks on its corresponding link. The global link script is simply a link script that processes on every link. Since you're already familiar with Variable Changes, we'll start by doing that: changing variables. Consider, for example, if you wanted to add 10 to the value of POINTS when the player clicked on a link. Using Variable Changes, you would follow a process like this:

  1. Open the Page with the Link that will cause this change to occur
  2. Click on the Variable Changes (Variable Changes) icon
  3. Enter "10" in the text box associated with the POINTS variable
  4. Click Save Changes

Using a Link Script, the process is similar:

  1. Open the Page with the Link that will cause this change to occur
  2. Click on the Variable Changes (Edit Link Script) icon
  3. Enter the following in the Text Box:  %POINTS := %POINTS + 10
  4. Click Save Changes

In both cases, when the player clicks on the link, 10 is added to the value of POINTS. Note, however, in the script how this is achieved. The above script consists of two different parts:

  • %POINTS :=  -- this translates in English to, "set the value of POINTS to." Note that the variable is prefixed with a percent symbol (%). In Script Code, all variables must be prefixed with this symbol.
  • %POINTS + 10 -- this translates in English to, "the value of POINTS plus 10."

When the two parts are combined, we are left with the following English translation: "set the value of POINTS to / the value of POINTS plus 10" A bit more awkward and confusing than "Add 10 to POINTS", but so is common with Script Code. This is why that, if all you want to do is increase the value of variables, you should stick with Variable Changes. They are much easier to use.

Changing Multiple Variables

As with Variable Changes, you can change the value of multiple variables with one click. If, for example, you wanted to Add 10 to POINTS,  Add 100 to MONEY, and Subtract 1 from HEALTH, you would use the following script:

%MONEY := %MONEY + 100

Beyond Basic Variable Changes

Of course, Scripting is not designed to do things so simple as the examples presented above. With Scripting, you can do things otherwise impossible, such as add the value of one variable to the value of another variable. Consider, for example, if you wanted set the value of DAMAGE equal to the value of STRENGTH plus the value of WEAPON:


It doesn't stop there, either. You can make the expressions as complex as needed, using any combination of addition, subtraction, multiplication, division, and parenthesis. You can also use Random Expressions if you'd like, too. Here's a fairly complex script using all of these concepts:

%ATTACK := (%WEAPON + %STRENGTH) * 1D4 #note: 1D4 is a random number between 1 and 4
%DAMAGE := 20 - (%DEFENSE / 2) - %ATTACK

If you're having a hard time following the script, don't worry; you can break it down into its components. Just as they do in arithmetic: evaluate parenthesis first, then multiplication/division, then addition/subtraction.

Item Scripts

Now that you've got a good idea on how to change variables using Script, let's take a look at how you can use Item Scripts to do the same. Without using scripting, if you wanted to change a variable when an item was used, you'd have to create a page that had a Previous Page link that changed the variable for you. There's nothing wrong with that approach; in fact, it may be preferred simply so that the player may see a detailed explanation of what happens. However, it's not the only way.

Item Scripts work very similarly as Link Scripts: they are evaluated every single time an item is used. Keep that "every single time" in mind as you use them: even if the item does not have an effect defined on the page, the Item Script is still evaluated. To edit an item script, simply edit that item and click on the [edit link script] button.

To give you an idea of what you might use an item script for, consider that the item "MAG Clip" is an item that can be used on any page. You could have the item script work as follows:


Item Scripts, however, are most useful when combined with more advanced scripting techniques that you can learn about by reading further articles on the topic. For now, we'll just leave it at that.

Conditional Statements

One of the most powerful aspects of Scripting is the ability to conditionally evaluate a statement. For example, consider the example script from way about that sets the value of DAMAGE. If, for whatever reason, the variable DEFENSE or ATTACK were too high, DAMAGE could be set to a negative number. To make sure that this doesn't happen, you can use a simple IF-THEN statement:

%DAMAGE := 20 - (%DEFENSE / 2) - %ATTACK

The first line sets the value of DAMAGE: nothing too new there. The second line checks to see if DAMAGE is less than (<) zero and, if it is, sets it to 0.

One popular scenario is the need to "flip" a "switch" variable (i.e., a variable that you only give a value of 0 or 1). What used to take two Links, two Link Restrictions, and two Variable Changes can now be done with a single link and a single link script using an IF-THEN-ELSE statement:


So, in the above statement, if FLASHLITE represents whether the player's flashlite is on (1) or not (0), this would "flip" the flashlite's state.

Of course, you could use the IF-THEN or IF-THEN-ELSE statement for anything else you'd like to do. One thing to keep in mind is that if you want to have several statements evaluated by the same condition, you can use a BEGIN-END block, as follows:

  %MONEY := %MONEY + 10
  %TURN := %TURN + 1

In the above script, MONEY and TURN are set a value only if DICEROLL is equal to (=) 7.

Further Resources

Hopefully this has been enough to give you a basic idea of what scripting is all about. We've only touched on a small amount of what's possible with scripting, so once you're comfortable with these basics, feel free to look at these other articles:

  • Intermediate Scripting - [coming soon] Building off of the knowledge learned in The Basic of Scripting, this article introduces the concept of Destination Testing & Setting, Random Numbers, and Inventory Manipulation.
  • Random Encounters/Events: A Scripting Scenario - [coming soon]
  • Various Scripting Scenarios - [coming soon]
  • Advanced Scripting - [coming soon]  Builds off of Intermediate, covers everything else, including setting Link Text, Page Text, etc, and offers some advanced ideas and techniques.
  • Scripting Reference Guide - [coming soon]  A boring Reference Guide designed for experts to use as a reference to the Scripting Code language.