A beginner's guide - Appendix 2

Appendix Two: Scripting Rules

Scripts are the fundamental mechanics that drive the game forward.

They have much in common with computer languages, in that they use commands, functions, parameters, and syntax. However they are unique to the game and can only be run from within the game. The script language includes hundreds of functions which allow you to do amazing things, but you can't do everything. The language is limited to what the existing functions can do. You cannot define new functions.

The game uses scripts in five different places and these give us 5 types of Script (Object, Quest, Dialogue, Results and Magic Effects. We have already seen four of these. We will look at magic effect Scripts later in the series)

The Wiki classifies scripts in two ways:

• First, scripts can be classified as reference or non-reference scripts
• Second, they can be classified as named or result scripts

Okay, what on Earth does that mean?

Reference V Non-Reference

Imagine three children playing in a park: Adam, Bob, and Christine. Adam has a football. Christine wants Adam to give the ball to Bob. She can simply say "Give him the ball."

Adam has the ball so it's obvious who she is referring to. This is a reference example.

We will see an example later where a door is opened using the simple function.

Activate

The game knows that since this bit of script is attached to a door that we want to activate the door.

Now suppose that instead of Christine being in the park, she is in a radio studio broadcasting to the whole of the world. She still wants Adam to give the ball to Bob. But now "Give him the ball" won't work.

Even if she said "Give Bob the ball", Bobs across the world will find themselves being given a football for no good reason.

Now we need "Adam - who is in the Smithfield Park, Much Haddem, Lancashire with your friend Bob who is wearing a blue jersey and green pants - give Bob the ball."

This is a non-reference example. You have to be very precise about the command you are using.

Dialogue and Object Script are examples of Reference Script. They can use shorthand ways to get functions to work.

Result and Quest Script cannot, and must use the longhand method.

Both can pretty much do the same job, it just takes more words in the non-reference method. If you're in doubt, use the non-reference method as it works in both.

Another way to classify is to look at the format a script can take.

Quest and Objects require NAMED scripts.
Result and Dialogue do not. They can be fragments (although they require variables to be declared in quest script to work).

Named Script Format

A script has four elements:

• a script name,
• a begin statement,
• a script block,
• and an end statement.

eg:
ScriptName MyScript

Begin (some begin condition)
 ; block of the script that does cool stuff
End

A script can have many begin-end blocks. However, the Begin - End blocks can not be nested

Begin (some begin condition)
 ; 1^st block of script that does cool stuff
End

Begin (some begin condition)
 ; 2^nd block of script that does cool stuff
End

- is OK.

Begin (some begin condition)
Begin (some other begin condition)
;1^st block of script that does cool stuff
End
;2^nd block of script that does cool stuff
End

- is not OK. IT IS NOT ALLOWED

The ScriptName or scn command sets the name of the script. It is required, and the name must be unique.

Begin

All script commands, except for variable declarations, must be inside a begin-end block.

Each time the script runs, each block will be evaluated to see if it is true. If it's not true, the script inside the block will not be run.

The most common begin conditions are:

Begin onActivate
Begin GameMode

(We will look at others as we examine the scripts.)

Declaring variables

All local variables that are used in a script must be declared prior to their use. They can be declared anywhere but by convention are usually listed prior to the first begin-end block.

You can declare four types of variables through scripts and as global variables. Variable names are not case sensitive.

Declare with type and name:

short myShortVariable
Can take values -32,768 to 32,767

long myLongVariable
Can take value -2,147,483,648 to 2,147,483,647

float myFloatVariable
can take values 1.18E-38 to 3.40E38 (precision = 7 digits)

Ref myrefVariable
Used to set objects as variables

End

End is used to end a script block. The most common mistake beginners make is to assume that the script

Begin (some begin condition)
 ; 1^st block of script that does cool stuff
End

is run once and terminates at END. This is not the case, scripts are repeatedly processed.

How often scripts are processed

Quest scripts:
These are processed every 5 seconds (by default) when the quest is running.
You can change how often quest scripts are processed by changing a default variable in the quest's script. (See fQuestDelayTime)

Scripts on actors(Creatures and NPC's):
These are processed every time the actor's AI is processed. In high process (the loaded area around the player), this is every frame.

When the actor is not in high, this is much less often (down to once every 15 minutes of game time at the lowest process level). But these are still the only scripts (aside from quest scripts) that are processed when the player is not around.

Scripts on references:
These are processed every frame when its cell is loaded, and not at all when the cell is not loaded. So these scripts run only when the player is nearby (which means these are often a good place to put relatively expensive scripts, doing things like distance checks).

Scripts on objects in containers:
These are processed when the container's script is processed -- so, items on actors are processed when the actor is processed. Items in other containers are processed every frame when the cell is loaded.

Scripts on doors:
A bit of a special case, these scripts are processed like other scripts on references (every frame when loaded), but they will also be processed once any time an actor activates the door.