Racalac's eScript Reference and Guide v096
(Last Updated: Feb 19, 2009)

Foreword:
This reference is targeted to be used and understood by scripters who have at least a little experience in other procedural-type languages. If you have never done any type of scripting or programming before, I'd suggest that you look for a class on BASIC or Pascal in your school or college. If you're not in college, think about buying a "dummies" book on programming from your local book store. Any of these methods will make learning and writing eScript easier and quicker for you. And on the other extreme, my apologies if I explain some things in annoyingly simple terms.

Table of Contents

Chapter 1:

• Variable Declaration and Assignment
• Arithmetic
• Comments

Chapter 2: Brief Review of Data Structures

• Arrays
• Structures
• Dictionaries

Chapter 3: Conditionals and Iteration

• If-statements
• Case (switch) statements
• Iteration

Chapter 4:

• Functions and Parameters
• Including Code from Other Files

Chapter 5:

• Scripts
• Compiling

Chapter 6: Built-in Properties and the POL Object Reference

Chapter 7:

• CProps
• CProps on Accounts

Chapter 8: Config File Usage and Access

Chapter 9: Packages

Chapter 10: Debugging

Chapter 11: Advanced Data Types and Functions

• Global Properties
• Arrays
• Structs
• Dictionaries
• Function Calls by Reference

Appendix A: Gump Tag Descriptions

Appendix X: Revision History

Chapter 1

Variable Declaration and Assignment; Arithmetic

There are no strict variable types in eScript, but there are a few types you can cast (convert) to: integer (whole number), real (float; integer with decimal part), and string (text). It is simple to declare a new variable:

var my_variable;

Depending where you declare this in your program depends on when you can have access to that variable. This is called the variable's scope. If you place the above line outside a function block, it is visible to all functions in the program (known as a 'global' variable). If you place that line inside a function block, it is accessable no matter where you currently are in that function. If you delcare it inside a code block (i.e. between if-endif, for-endfor, etc), it is only usable inside that block. Note in older scripts you may see variable declared with 'local' and 'global'. The first is the same as 'var' inside a function and the second is the same as 'var' outside a function. You should always use 'var' instead of these older keywords to declare your variables.

Okay, now we have some variables, but now to put some data into them so we can use them in the script. You can do this either at declaration-time or later in the script. The syntax for this in eScript is:

my_variable := 10;

The ":=" (colon + equals) operator assigns the right-hand-value to the left-hand variable. A lot of different expressions can be used on the right-hand-side. Some of these include numbers (such as above), other variables, mathematical expressions, function calls, and more. You can perform these at declaration-time like: var number_of_pies := 15;

To declare a "constant," or a variable that you can only read its value from, you must do it at the top of the file, before any of the functions, much like declaring a global variable since constants are global themselves. Whenever the compiler sees a constant in an expression, the value of that constant is substituted instead. The syntax for this is:

CONST MY_CONSTANT := 47;

The use of constants is key in well-written, readable code. They remove the ambiguity of having raw numbers thrown around in a script by giving a meaning to them. It is a good idea to use the convention of declaring constants in ALL CAPS since most programmers are used to it.

Example snip of code (doesn't do much but show different ways of declaring variables):

CONST SIZE_OF_TRAY := 15;
var pies_in_tray := SIZE_OF_TRAY;

Arithmetic

This stuff is easy, the expression on the left of the assignment operator is evaluated and placed into the variable on the right side. The math operators in eScript are:

The expressions are evaluated first inside parenthesis then from left-to-right. Such as:

var pies_used := pies_used + 1; // Increment 'pies_used' by 1
var pies_left := number_of_trays * (pies_in_tray – pies_used);

I should mention something about variable types in arithmetic, especially division. If you divide two integers together such that the result would have a decimal part, POL will only look at the whole number part. To make sure the result is a real (integer+decimal part), make sure at least one of the operands is a real. You can make sure of this by using a raw number with a decimal part (such as 100.0), or "cast" it to a real (convert the type). There are a few casting functions in eScript, CInt(), CStr(), CDbl().

CInt(100.3)  	   	// Results in 100
CStr(100); 	  	  // Results in a string of "100"
                  // This now cannot be used in mathematical expressions.
CDbl(100); 	  	  // Results in 100.0

Additional conversion functions in basic.em

Hex(100);  	   	// Results in a string as "0x64"
Bin(100); 	  	// Results in a string as "1100100"
                // CInt() will not properly convert this string to its decimal value.
CAsc("A"); 	  	// Results in an integer of 65
CChr(65); 	  	// Results in a string as "A"

Bonus Topic: Comments

Commenting your code is of utmost importance. Comments allow you to add arbitrary text to explain whatever you need to without disrupting the script's functionality. Comments are also used to remove code from execution without actually deleting it (known as "commenting out code"). In eScript there are a couple ways to comment your code:

1. Any text after "//" will be considered a comment until the end of the line. The next line will not be considered a comment. To make it a comment, add another "//" before your comment. This is the best way to make short comments because it allows you to comment out large block of code using "/* */" (below).

2. Any text after "/*" and before "*/" is considered a comment. Using this, you can comment out large blocks of code just by placing a /* at the beginning and / at the end of the code. You cannot "nest" this type of comment, as the next "*/" signals the end of the comment, even if another "*/" is found after the first. This is why we recommend you comment most things with "//" to avoid this.
    

Chapter 2

Brief Review of Data Structures

Okay, so we can make integer, real, or string variables. To do any sort of useful scripting, we also need some data structures. I will discuss arrays, structures and dictionaries in this chapter.

Arrays

Arrays are one-based, random access collections of objects. That means you can access any place in the array from 1 (the first element) up to X (the last element). Let's first look how you can declare an array.

To create an array variable, declare:

var a := array;                           // empty array
var b := array{5, 32, "hello", "world"};  // initialized array
var c := array{array{1,2}, array{3,4,5}}; // array containing arrays

An array can be assigned to any other variable, even if that variable was not declared an array:

var a := array{2, 4, 6, 8};
var b;
b := a;

Similarly, if a function returns an array (we will discuss this later), no special declaration is needed:

var a;
a := FunctionThatReturnsAnArray();

In some other programming languages, you cannot access (read or write) past the end of the declared size of the array. In eScript, arrays grow automatically without access errors:

var a := array;
a[1] := 4;
a[4] := 7;

Arrays elements can be any type of object, including another array:

var a := array{};
var b := array{};
a[1] := 5;
b[1] := a;
b[2] := 6;

The following are equivalent methods of looping through an array. The 'foreach' method is much more efficient, as well as being more convenient. Note that we will discuss these kind of loops and more next chapter.

var a := array{2,4,6,8};

var i;
for(i:=1; i<=a.Size(); i:=i+1)
  Print(a[i]);
endfor

foreach i in ( a )
  Print(i);
endforeach

You can then use the array for whatever you need, such as passing more than one variable back to a function (functions explained later), or when a core function requires it.
Also, there are a few array-specific functions that are explained later (such as array.Insert() and others).

Structures

Structures are an object-oriented data type with various members or properties that are part of them that contain the actual data.

To access members, use the '.' operator:

Print(a.height);
Print(a.width);

To create an structure variable, declare:

var a := struct;                             // empty struct
var b := struct{"height", "width"};          // struct with members that have no values.
var c := struct{"height":=5, "width":=100};  // struct with members and values.

To add new members, use the '.+' operator:

var a:= struct;
a.+height := 7;
a.+width;

// Assign an existing member
a.width := 5;

Dictionaries

Dictionaries are arrays whose elements are named. They are often referred to as 'associative arrays'

Print(a["height"]);
Print(a["width"]);

To create an structure variable, declare:

var a := dictionary;                         // empty dictionary
var b := dictionary{"height", "width"};          // dictionary with indexes that have no values.
var c := dictionary{"height"->5, "width"->100};  // dictionary with indexes and values.

Dictionaries automatically add new indexes when they are set.

var a:= dictionary;
a["height"] := 7;
a["width"] := 100;

Chapter 3

Conditionals and Iteration

We'll cover two topics in this chapter: IF-statements and loops.

If-statements

If-statements are absolutely needed in every script so it's necessary you understand them. If statements simply let your script make decisions based on the criteria you give it. The general syntax is:

if(statement)
  // code
elseif(statement)
  // code
elseif(statement)
  // code
else
  // code
endif

Notice you can have any number of (optional)"elseif" statements between the "if" and the (optional) "else".
The key part in the syntax above is "statement". When the script runs, it will check the first "statement" to see if it is true.
If it is not, it'll proceed to check the next "statement" until either it finds one that is true, or hits the "else" statement (if any).

The syntax for "statement" is

variable1 {operator variable2} ...

Some examples of evaluating to true expressions are:

var var1 := 10;
var var2 := 5;

if (var1 > var2)  //TRUE

if ((var1 – 5) == var2) //TRUE

if (var2 < var1) //TRUE

if ((var2+5) >= var2) //TRUE<

if (var1 != var2) //TRUE

The logical operators in eScript are (evaluated left-to-right)

== equal-to
!= not-equal-to
> greater-than
< less-than
<= less-or-equal-to
>= greater-or-equal-to

Also, you can use the Boolean operators:

For example:

if ( (var1 > var2) || (var1 == 5) ) 
  // TRUE since at least one of the individual expressions is true. This is inclusive OR so all expressions may
  // be true and the whole statement is true.
  
if ( (var1 > var2) or (var1 ==5) )
  //this is same as above, except using "or" in place of "||" for readability.
  
if ( (var1 > var2) && (var1 == 5) )
  //FALSE, since not ALL expressions are true.
  
if ( (var1 > var2) and (var1 == 10) )
  //TRUE, since both expressions are true. Uses "and" in place of "&&"

You will use If statements in all but the most simple scripts you write. You should understand what you want to do before throwing a conditional statement together, as it is possible to mess it up:

if ( score < 60 )
  Print("You got less than 60");
elseif ( score == 50 )
  Print("You got 50!");
endif

This is poor scripting, as if your score was 50, the first statement would be true (printing "You got less than 60"), and the elseif(score == 50) line would never be printed, even though it is a more specific check than the previous line.

Also, in eScript anything that is zero is considered to be false, and anything non-zero is true. So you can have an if-statement without any logical operators:

var valid := 1;
if( valid )
  // do stuff
else
  // do other stuff
endif

Or:

if ( !valid ) //same as "if valid is non-zero, then false"
  // do stuff
endif

Case (switch) statements

It is a common occurance in scripting when you need to make a equality decision based on a large number of possibilities (and the possibilities are known at compile-time). To do this kind of choice with if-elseif statements would be ugly at best and slow at worst. Luckily, eScript provides a cleaner way to do this:

// declarations:
const BLUE := 1;
const YELLOW := 2;
const RED := 3;
const MAUVE := 4;

// The ugly if-elseif way:

function FunctionOne()
  var answer := WhatIsYourFavoriteColor();
  if ( answer == BLUE )
    // do stuff
  elseif ( answer == YELLOW )
    // do stuff
  elseif ( answer == RED )
    // do stuff
  elseif ( answer == MAUVE )
    // do stuff
  else
    // do something else
endfunction


// The clean case Way:

function FunctionTwo()
  var answer := WhatIsYourFavoriteColor();
  case ( answer )
    BLUE:
      //do stuff
    YELLOW:
      //do stuff
    RED:
      //do stuff
    MAUVE:
      //do stuff
    default:
      //do something else
  endcase
endfunction

The general structure of a case statement is:

case ( expression )
  comparison_value:
    //code
    break;
  comparison_value:
    //code
    break;
  ...
  default:
    //code if no match was found above (optional)
    break;
endcase

"expression" can be determined at run-time, but "comparison_value" cannot. That means a case statement is really only good for making a decision based on equality with any number of constant known values. "comparison_value" may not be any type of expression that must be determined at run time, such as a mathematical expression. Also, case statements cannot be used for non-equality comparisons, such as greater-than, less-than, etc. The breaks are optional, except under one circumstance- an empty case. If you have a comparison value followed by no code (in other words, immediately followed by another comparison value), and that comparison value is followed by code, then both of the cases will execute that code.

For example:

function FunctionThree()
  var answer := WhatIsYourFavoriteColor();
  case ( answer )
    BLUE:
    YELLOW:
      //do stuff
    RED:
      //do other stuff
    default:
      //do something else
  endcase
endfunction

In this situation, the both BLUE and YELLOW will cause it to do stuff. RED will make it do other stuff, and anything else will make it do something else. If you meant BLUE to do nothing at all, you must put break; statements in the sections which you wish to have do nothing- this will tell the program to skip to the end of the case block.

The behavior in the case of an empty block (like BLUE above) is known as fall through.

Iteration

I mentioned "looping through an array" in the previous chapter. This is a very common function is most scripts. There are two popular ways of doing this, here are the code bits I used in the last chapter, one at a time:

var a := array{2,4,6,8};

var i;
for ( i:=1; i<=a.Size(); i:=i+1)
  Print(a[i]);
endfor

2
4
6
8

The "for" loop should be familiar to anyone who has done programming before. The syntax of a for-loop is:

for (initialization statement ; loop-if-true statement ; increment)
  // code
endfor

Though you can add any code you want in the initialization statement and the increment statement, I've named them these because that is their most common function. A for-loop normally is a count-checker. On each go around the loop, it automatically performs the increment statement, and then checks the loop-if-true statement to see if it should stop looping or go again. In the above example, the variable "i" is declared. Before the first loop of the for-loop, i is initialized to 1. If 'i' is less than or equal to the length of the array named "a", the code in the for-block is executed. At the end of the for-loop block, the increment statement is executed, adding 1 to 'i' and storing the new value in 'i'. Then 'i' is again compared against the length of a (which is 4, using the above example). 'i' is still less than that, so the code in the block is executed again. This continues until 'i' is greater than the length of the array. "endfor" signals the end of the for-loop block.

Another, more convenient method is shown in this example:

foreach i in ( a )
  Print(i);
endforeach

Here, we don't need to initialize 'i', as the "foreach" loop does it for us. This loop performs the same function as the for loop above, but in a much more succinct (and efficient) manner. The general syntax is:

foreach counter_variable in ( array_name )
  {code}
endforeach

Bonus Variable:
When you use a foreach loop, you get a _(var)_iter variable with it that tells you what iteration you are on.

var a := array{"A", 1000};
foreach i in ( a )
  Print(_value_iter);
  Print(value);
endforeach

1
A
2
1000

The last type of for loop is the basic-style for loop.

for i:=0 to 3
  Print(i);
endfor

0
1
2
3

Another loop type that eScript supports is the "while" loop (it's a condition-is-true check to loop):

while ( expression )
  // {code}
endwhile

Pretty easy; until the expression is false, {code} is executed. You will probably be changing one or more of the variables in "expression" or you will never exit (there are exceptions to this rule, below).

Another loop type is the "repeat – until" loop. This is very similar to the "while" loop, except that you are guaranteed for the code to be executed at least once, since the conditional check is done at the bottom of the block (it's a condition-is-false check to loop):

repeat
  // {code}
until ( expression );

You can use while-loop in similar style with conditional check after code (it's a condition-is-true check to loop):

do
  // {code}
dowhile ( expression );

There may be times you want to exit a loop before the exit condition is satisfied. To do this, you would put the "break" statement in your {code} block (this works in the "for", "while", and "repeat until" loops). Also, if you want to stop the execution of the code block, but remain in the loop, use the "continue" keyword. This will return make the loop start from the top of the code block again after checking the "condition" statement.

while ( condition != 0 )
  if ( condition == 42 )
    //oh geez! breakout!
    break;
  elseif ( condition == 13 )
    //don't do the code below the if-block
    continue;
  endif
  condition:= condition * something;
endwhile

Chapter 4

Functions and Parameters

So far, all I've shown here is code segments which cannot be used by themselves. All code you write must be placed inside functions. If you are not familiar with the concept of functions, they are one of the fundamental building blocks of programming- potentially reusable sections of code. In eScript, there are two types of functions: "function" and "program". If you have programmed before, we can compare the "program" function to an application's "main" function. This means when the script is executed, the entry-point (first function run) is always the top of the function designated by the keyword "program". Here's a general syntax for both:

program ProgramName(parameter, ...)
  // {yourcode}
endprogram

function FunctionName(parameter, ...)
  // {your code}
endfunction

The "endprogram" and "endfunction" keywords identify the end of that function. These are absolutely necessary and you will get compiler errors if they are not present (more on compiling later).

FunctionName can be anything, as long as it is one word and it starts with a letter.

The parameter list is a little more difficult to explain. These are variable names that were passed to this function from whatever the calling function was. You can have any variable type as a parameter, even arrays and structures. I'll show you some examples below. Note what makes the "program" (main function) special is that you do not choose what gets passed to it. Since the "system" (the POL core in this case) calls the "program" function, it chooses what parameters to pass to it. The actual parameter list differs depending on what type of script it is in (more on that later). But for the sake of showing you the syntax of the program, let's assume nothing is passed to the main function. The parameter list may have zero or more parameters in it.

Here's a simple example of how you can create your own functions:

program Main()
  var var1 := "dudes";
  var var2 := "oingo";
  var var3 := "boingo";
  var var4 := "let's";
  var var5 := 42;
  
  MyFunction(var1, var4); // 1
  MyFunction(var2, var3); // 2
  MyFunction(var5, var1); // 3
  MyFunction(var3);       // 4
  MyFunction();           // 5
endprogram

function MyFunction(a:= "Yo yo", b := "hey hey")
  Print(a + " " + b);
endfunction

Here is the output from the five calls to MyFunction:

dudes let's
oingo boingo
42 dudes
boingo hey hey
Yo yo hey hey

Notice in the declaration of the MyFunction function, we have a couple variable names and an assignment for each. What this does is if no variable is passed for that parameter, the value on the right side of that assignment is used instead, as can be seen the 4th and 5th lines of output.

This is a very simple example, and does not really show why you should use separate functions to do stuff rather in all one big function. It is good programming style to split up tasks into separate functions, and it helps in the areas of readability, code reuse and abstraction.

Functions may return one value to the calling function before they exit. This is done with the "return" key word. The calling function receives this value by having a variable on the left side of an assignment operator and the function call on the right:

program Main()
  var hejaz;
  hejaz := SmellsLike();
  Print(hejaz);
endprogram

function SmellsLike()
  var smell := "Teen Spirit";
  return smell;
endfunction

Teen Spirit

To return more than one value from a function, assign those values to an advanced data type (array, struct, dictionary) in the function and then return the variable.

program Main()
  var hejaz;
  hejaz := SmellsLike();
  Print(hejaz[1]);
  Print(hejaz[2]);
endprogram

function SmellsLike()
  var smell := array{"teen", "spirit"};
  return smell;
endfunction

Teen
Spirit

Including code from other files

Up to this point, all the code we've been messing with has been in one file. To import in code from other files (special files called "include files" whose file extension is ".inc". They're special because they cannot contain a "program" main function, only any number of normal functions), near the top of your script, before any variable declarations or functions add the line:

include "filename_without_.inc";

Then you may call any function that is defined in that include file from your script (.src) file. Note that any variables in the include files that are declared at global scope also are at global scope in your script file. This means you must be careful that you don't try to declare any variables with the same names as those other global variables. If you do, it will result in compiler errors that may be difficult to track down.

The above line will work if the include file is in the same directory as the source file that includes it. If you want to use some of the more standard include files (found in /scripts/include), you'd use the syntax:

include "include/filename";

If you want to include a file that is in a package you would use

include ":pkgName:filename";

Chapter 5

REJOICE! Now for UO and POL stuff: *.em files and functions

I'm glad you stuck through all that syntax discussion and didn't skip ahead to here. If you did skip ahead, good luck, because I won't be reviewing any of that syntax.

Scripts

Okay, this is where we start learning to write real scripts for the UO-POL environment. Up to this point, you can write scripts that do stuff, but probably not anything useful. To be able to write really useful scripts that do something, you need to be able to access data about the game world. POL provides this interface through a number of "core-functions" that are defined in the ".em" files that can be found in your /pol/scripts directory. Note *.em files are often referred to as 'modules'.

But first, I need to talk about the types of scripts in the POL environment, when they are executed and with what parameters. Here is a quick list (note the parameter names I use like 'clicker' are only an example, the actual parameter names can be anything, but I'm trying to be descriptive. Only the order of the parameters below is strictly enforced):

CharRef = Reference to character running the script
MobRef = Reference to a mobile object (NPC, character)
ObjRef = Reference to an item

Use Scripts: Run when the associated item is double clicked in the UO window.
  Parameters: 1: CharRef clicker , 2: ObjRef item_clicked

Walk-on Scripts: Run when a player walks on the associated item.
  Parameters: 1: CharRef walker , 2: ObjRef item_walked_over

Text Command Scripts: Run when the player uses the command ".scriptname" and has the appropriate privileges.
  Parameters: 1: CharRef speaker , 2: Text after the command. i.e. ".command blah" typed would give the text as "blah"

Spell Scripts: Run when the player starts a spell from the spellbook
  Parameters: 1: CharRef caster

Control Scripts: Run on creation of the associated item and on server reboot
  Parameters: 1: ObjRef item_under_control

AI Scripts: Run on an NPC, controls behavior, should never exit
  Parameters: 1: MobRef the_NPC

Skill Scripts: Run when a player clicks on a skill gem in the skills scroll gump
  Parameters: 1: CharRef player_performing_skill

Let's start learning with Text Command scripts since they're the easiest to get running. Text commands are only run if the player speaking the command has the necessary command level. Make sure the player you're testing with has a command level of "gm" (usually 4) or greater. We'll be placing all our scripts in the /scripts/textcmd/gm directory.

Okay, let's start with a simple script. Say you want to write a script that will broadcast a message to all players on the server. Here is the script "bcast.src", I will explain each line:

/*1*/ use uo;
/*2*/
/*3*/ program MyBroadcast(speaker, text)
/*4*/ 
/*4*/   foreach character in ( EnumerateOnlineCharacters() )
/*5*/     SendSysmessage(character,text);
/*6*/   endforeach
/*7*/
/*9*/ endprogram

Line 1: the "use" keyword tells the compiler to look in the following .em file for the definitions of any functions we may use out of that "module" (look there now, you'll see EnumerateOnlineCharacters and SendSysmessage).

Line 3: Since this is a text command script, POL automatically passes a reference to the character speaking the command, and the text after the command. These are here as "speaker" and "text" respectively.

Line 4: The EnumerateOnlineCharacters function returns an array of Character References. for each character logged into the server. The foreach loop gets the next data element from this returned array and sticks it in the "character" variable.

Line 5: The SendSysmessage function will send the "text" string to the lower left hand corner of "character"'s UO window.

Line 6: Signals the end of the foreach block

Line 9: Signals the end of the function.

Here's how it goes in a sample run:

1. The GM player types in .bcast Howdy Everyone!
2. POL looks in the bcast script for a "program" function and passes a reference to the GM player as well as the text "Howdy Everyone!".
3. EnumerateOnlineCharacters returns an array of 3 character references.
4. SendSysmessage will send the text "Howdy Everyone!" to the lower-left-hand corner of each of the 3 character's screens.

But now the GM doesn't like the fact the he receives his own broadcast. You can edit the script so this won't happen by checking to see if the character reference stored in the "character" variable is the same as the "speaker" reference passed to the function by POL:

/*1*/ use uo;
/*2*/
/*3*/ program MyBroadcast(speaker, text)
/*4*/ 
/*5*/   foreach character in ( EnumerateOnlineCharacters() )
/*6*/     if ( character!= speaker )
/*7*/       SendSysmessage(character,text);
/*8*/     endif
/*9*/   endforeach
/*10*/
/*11*/ endprogram

Now the message won't be sent to who sent it.

Compiling

Alright, it's now time to get an actual running script. POL cannot directly read the source code you write, it must be compiled into a readable format before it can be executed.
Note: This also means that if you chance a .inc file, you must compile all *.src files that use it to update them.

The included program "ecompile" is used for just this. I will assume you have experience in the command shell that your operating system of choice uses.
I will use the Windows command line for reference.

First, take that code above and place it in a file called "bcast.src" and place that file in the pol/scripts/textcmd/gm directory. Now go to your command shell and change the directory to the /pol/scripts directory. Type "ecompile /?". You should see it give you a list of usage options.

We don't need any of these fancy flags, just the basic usage of ecompile: "ecompile "

We need to tell ecompile where the file we want to compile is so at your command line, type:

ecompile.exe txtcmd/gm/bcast.src

Since that's where we put the file. You should see something like:

EScript Compiler v1.05
Copyright (C) 1994-2006 Eric N.Swanson
Compiling: D:\pol\scripts\textcmd\gm\bcast.src
Writing: D:\pol\scripts\textcmd\gm\bcast.ecl

When ecompile tells you that it's writing a .ecl file, that means the compiling was successful and the script can now be run.

To run, make sure POL is running and you're logged in with a GM character (or higher, like admin). Now type .bcast . Now, if you did everything right up to here, you should see nothing. That's because we made it so you wouldn't receive your own broadcast. So to test, get a couple friends on your server and ask them if they got the message. If they did, congrats, your very first script.

Chapter 6

Built-in Properties and the POL Object Reference

Everything in POL is an object: characters, accounts, items, corpses, NPCs, etc.

POL uses a class hierarchy to allow inherited properties between objects. For example, in the UO world, everything in the world has an x, y, and z coordinate property. This include both items on the ground, and mobiles (NPCs or characters). You can see from the Object Reference Chart (Appendix A) that both the Mobile object and Item object are children of the UObject Class. Notice in the UObject class that there are a number of properties, including x y z, serial, objtype, color, etc. These properties are inherited by all the other class objects under UObject in the tree, thereby implicitly granting all these basic properties to all objects in the UO world.

Some Classes even have functions as members (methods), an object-oriented type of design, i.e. the Door class has the method door.Open() and door.Close() which open and close the door, respectively. Notice how you access these methods or "member functions" with the dot "." operator. So depending on what type of object you are working with, some members and methods may not exist to access. For example, a door object would not have the "quality" member an Equipment object would have, but you could access both their x-coordinates with object.x. Note that some properties are read-only and some are read-write. The read-only props only allow you to retrieve the value for that property, and not to change it. Read-write props grant you all access to the property. It is for security purposes that some built-in props are read-only. It would mess things up if you were able to write to character.dead or character.acct (account)!

See the POL documenation for the object heirarchy for more information about built-in properties and methods.

Please refer to the POL Object Reference Chart for all the details.

Chapter 7

Much Ado about CProps and Stupid Chapter Names

CProps (Custom Properties) are what makes scripting with eScript so flexible. In addition to all the built-in properties in Appendix A, CProps let you store arbitrary amounts of arbitrary data to any object. This data can be stored by any script and recalled by any script that has a reference to that object. You can store any type of data: string, integer, real, arrays. You should be able to see that this ability to store and retrieve arbitrary data is a powerful one. I'll go through an example of a couple scripts that use CProps and touch on other aspects of scripting.

Let's say you want to create a one-time use item that allows the player to teleport back to their corpse after being resurrected. There are several things that we need to do to make this happen: create the description for the custom item that grants this ability, the script that controls the behavior of the item, code to store the game coordinates of the player's corpse. First, a quick lesson on creating a custom item:

Open up any itemdesc.cfg file you find. This file contains the definitions for all the items that do something in the world. We need to add our item to one of these files. For now, we'll use the file /config/itemdesc.cfg. Here's the definition of our item and the descriptions of each parameter:

Item 0xABCD
{
  Name    ring_of_returning
  Desc    Ring of Returning
  Graphic 0x108A
  Script  return_ring
}

Item 0xABCD :
Starts the definition of the new Item. The objtype number is arbitrary, but must be unique. The range of numbers available for custom items are 0x5000 to 0xFFFF.

Name  ring_of_returning :
his is the internal name of the item, so you could create one using the command ".create ring_of_returning" instead of ".create 0xABCD".

Desc  Ring of Returning
This is the single-click description shown when you click it.

Graphic  0x108A
This is the objtype of the art item to use to represent this item. I got this number by looking in the InsideUO program for the ring graphic and using it's objtype number.

Script  return_ring
This is the name of the script that will run when you double-click the item.

A short description of the CProp functions which we will be using all of, found in the uo.em module header file:

SetObjProperty(object, property_name_string, property_value);

Stores a CProp on "object" of name "property_name_string" and value "property_value".

GetObjProperty(object, property_name_string);

Returns the value of the CProp "property_name_string" that is stored on "object". If that CProp does not exist, returns an error.

EraseObjProperty(object, property_name_string);

Erases the CProp "property_name_string" that is stored on "object". If that CProp was not found, returns an error.

Now, let's write some code that will store the player's position after s/he dies. The script that is run when a player dies is /scripts/misc/chrdeath.src. Let's look a bit at that one. There is probably a bunch of code already in there used for other purposes, but you can ignore that for now. We see that the function parameters looks like this:

program ChrDeath(corpse, ghost)

The 'corpse' parameter is an itemref to the corpse of the dead player. Remember that an Item object inherits all the properties of the UObject class, which includes the x,y,z coordinates. We access these by using the 'dot' operator. We want to store the x,y,z coordinates of that corpse item on the player so the ring item script we will create can read it. The "ghost" parameter here is a mobileref to the character that just died. It doesn't matter that he's a ghost, we can still access and store data as normal. In chrdeath.src, you would add:

SetObjProperty(ghost, "x_corpse", corpse.x);
SetObjProperty(ghost, "y_corpse", corpse.y);
SetObjProperty(ghost, "z_corpse", corpse.z);

Okay, now everything is in place for us to write the ring of returning script. We create a file named "return_ring.src" in the /scripts/items directory. Here is the basic flow of the program:

1. Check to see if those three cprops exist on the player using the ring.
   • if the cprops exist, store the values in three variables.
   • if they don't exist, exit with an error message
2. Move the player to those coordinates
3. Erase the cprops on the player
4. Destroy the ring item.

Here's the code:

use uo;
program ReturnRing(player, ring)
// remember this is a usescript, and the variables 'player' and 'ring'
// are the parameters passed to the script by the POL core.
  var x,y,z;
  
  x := GetObjProperty(player,"x_corpse");
  y := GetObjProperty(player, "y_corpse");
  z := GetObjProperty(player, "z_corpse");
  
  if ( (x== error) or (y == error) or (z == error) )
    SendSysMessage(player,"Could not find your corpse");
    return 0; //exits the script
  endif
  
  
  // Note: Since pol97 MoveCharacterToLocation is depreciated use MoveObjectToLocation instead
  MoveCharacterToLocation(player,x, y, z);
  EraseObjProperty(player, "x_corpse");
  EraseObjProperty(player, "y_corpse");
  EraseObjProperty(player, "z_corpse");
  DestroyItem(ring);
endprogram

Easy stuff right? =) Now you'd just have to compile chrdeath.src and return_ring.src, unload chrdeath if your server was already running (.unload chrdeath), create the new item and test it all out. Now, you might be thinking, "If the player was wearing this ring when he died, it would go on his corpse and wouldn't help him getting back there." You'd be right, so there's a few things you could do, if you wanted:

1. Tell the player how stupid s/he is for not leaving it in his/her bank. Then again, he s/he found a wandering healer, the ring would do no good in the bank.
2. Make the ring a "newbie" item (stays on the player's ghost, would be usable after he resurrected).
3. Change the item to be something non-wearable, to hint to the player that it shouldn't be something to carry around.

It is good to know how POL stored cprops on objects. If you use the ".props" command on an object like our unfortunate player, you'd see something like: cprop x_corpse i300 the important part here is the 'i' before the value. This denotes the type of the data stored. We will revisit this next chapter.

Cprops on accounts

You can also apply properties to accounts themselves (rather than specific characters in them), but you use a different syntax to do so. Rather than SetObjProperty(account, "Propname", value), you use these methods to set and read custom properties:

account.SetProp("PropName",value);
account.GetProp("PropName");

Chapter 8

Config File Usage and Access

Configuration files (cfg files) in POL hold static data that is read at run-time and may be edited on the fly without any restarting or recompiling. Because of this, they are good places to put data that may be changed often, or for the ease of customization as you wouldn't have to edit and recompile the script that uses it. There are two types of cfg files in POL: ones used directly by the core executable, and ones that are read in by scripts. The former we won't go into, but some examples include the system configuration, pol.cfg; spell configurations, spells.cfg; skill configurations, attributes.cfg. There are some cfg files that are used both by the core and other scripts, such as itemdesc.cfg and npcdesc.cfg (both are read by their respective Create core functions, but other scripts can access them for additional data, as we will see).

BowcraftData 0x13B2
{
  Name Bow
  Material 16
  Difficulty 30
  PointValue 20
}

BowcraftData is the element type. It is not used by the system and only serves to give the scripter an idea about what the element is related to.

0x13B2 is the element key or simply key. This must be a string (or number) which is used to find the element of interest in a file with many elements like the one shown above.

Name Bow
Material 16
Difficulty 30
PointValue 20
These above, are all the element's properties. This is where the data you are interested lives.

So the steps to find a specific piece of data is as follows (must use cfgfile.em):

1. Read in the config file where the element is saved using ReadConfigFile(filename).
2. Find the specific element where the data lives by matching its key using
   FindConfigElem(cfgfile, key).
3. Read in the data much like you would a cprop using GetConfigXXXX(elem, propname), where
   XXXX depends if the data is integer, real, or string.

As a quick example, let's suppose that element above is in a file called "bowery.cfg" (in the /config directory) and we want the value of the "Material" property of a normal bow.

use cfgfile;

function GetMaterial(item)
  // assume that 'item' is an itemref to a normal bow item
  var cfgfile, element,propvalue;
  cfgfile := ReadConfigFile("bowery");
  element := FindConfigElem(cfgfile, item.objtype);
  propvalue := GetConfigInt(element,"material");
endfunction

What you put in a config file is up to you, but they are best suited for large amounts of data that differs depending on the element key. The key is often an objtype, or just sequentially numbered, or structured however you want.

For config files that are used by both the core and other scripts, there are properties that are expected to exist for both parts. For example, in an NPC description, the core expects the normal properties of an NPC, like stats, color, graphic, etc. You can also add other properties that are not read by the core, but perhaps are read by the AI script to direct it exactly how to behave (for example, to run away from players or to attack). There is a third option, you can add CProps to config files. Look at this example of an NPC template:

NpcTemplate shade
{
  Name a shade
  script killpcs
  ObjType 0x1a
  Color 0
.
.
.
  lootgroup 29
  Magicitemchance 1
  provoke 67
  CProp Undead i1
}

Please note:

1. 'shade' is the key for this element. If you have a mobileref to a shade, you could get its element in the npcdesc.cfg file by using shade.npctemplate to match the key.
2. The first four properties are used by the core to create the npc.
3. The next three properties are not used by the core, but other scripts. The first two are used by some loot creation script, the last by some provocation script.
4. The last property is a CProp which is added to every instance of this NPC template.

Number 4 is very important; if you define CProps in a config file like npcdesc.cfg or itemdesc.cfg, that CProp is automatically set on every instance of that item that is created. This brings up the age-old dilemma of "Space versus Time". CProps in config files are set on every one of those items, which takes up extra memory, but is faster to access. Reading the same data from a config file takes a little more time to do, but the data is stored in only one place instead of many. Using CProps in a file with those bowery entries, for example, would not do anything, since no item is created from those elements.

Chapter 9

Packages

You'll notice that up until now we've been putting files in the 'standard' places, like /scripts/items for itemuse scripts, /config for config files, etc. That's considered poor practice as it makes upgrading very difficult. To try to help that problem, POL uses a package system where all the files to do a specific purpose can be placed in a directory named for that purpose. For example, if you wrote a system for a new skill, you could place all the files needed for that new skill in a package: all the script source files, the compiled source files, support config files, readme files, etc. In POL, there are two types of packages, the 'standard' packages which are enabled by default (in /pkg/std/), which are normal skill systems, spawner, spells, etc. Then there are the 'optional' packages which are off by default, but can be used if desired (in /pkg/opt/). Normally, enabling an optional package requires some instructions which are normally supplied with the package.

Each package must include a package descriptor file, pkg.cfg, which has the following format (note # denotes a comment):

# Example package definition file

Enabled 1
  #Enabled 0/1 Should this package be enabled?
  
Nam template
  # Name of package,should match directory name
  
Version 1.3
  # Version v0.v1..vn  Version number for this package
    
Requires spawner 1.2
  # Requires pkgname {version}
  #   Other package(s) other than this one are required 
  #   in order to function
  #   More than one of these can occur.
  #   Format: requires package-name {version)
   
Conflicts some-package
  # Conflicts pkgname
  # This package cannot co-exist with a specific package.
  # Note that version cannot be specified
   
### Everything below this line is currently ignored, but are a very
### good idea to include in your pkg.cfg for imformation to users
  
  
CoreRequired 96
  #CoreRequired ver note no leading '0', which would indicate octal
  
Maintainer John Q. Public
  # Your name
 Email johnq@public.com
  # Your email

In the previous examples that use the ReadConfigFile function, the addition of packages complicate things somewhat. How can you know if you want to read the itemdesc.cfg in a specific package, the standard one in /config, or all of the files combined into one (for easy searching) ? This is handled in the filename format you pass to the ReadConfigFile function. The formats are:

ReadConfigFile("cfgname")
  - for a script not in a package, looks for /config/[cfgname].cfg
  - for a script in a package, looks for [cfgname].cfg in the same package

ReadConfigFile(":*:cfgname")
  - Reads in every config file that matches that name.
  
ReadConfigFile(":pkgname:cfgname")
  - looks for [pkgdir]/[cfgname].cfg

ReadConfigFile("::cfgname")
  - always looks in pol/config/[cfgname].cfg

Note for the special files itemdesc.cfg, npcdesc.cfg, attributes.cfg, and spells.cfg, the first of the three formats will return the "composite" config file that includes the concatenation of the contents of all the files in all enabled packages and the standard file.

There are a few other times this format is used, such as the start_script() and the UnloadConfigFile functions. This is why the syntax for the .unloadcfg command is ".unloadcfg :pkgname:cfgname". That brings up another point: config files are cached by the system and must be unloaded for any online change to be seen.

Chapter 10

Debugging

Many books have been written on the subject of finding and fixing software errors and it would be wasteful to repeat their content. This chapter will show some POL/eScript specific ways of finding bugs in your scripts. Let's first look at compile-time scripts. Ecompile, the eScript compiler does well at giving you good hints to where your script's syntax errors are. I say hints because of one of the rules of programming: never trust the compiler's error messages. They are often very useful, but often can lead you astray if you take their messages as gospel. The error message will contain a line number around where the error is. It may be above, on or below that line. The rest of the error message is usually correct, if not sometimes somewhat vague. Here are some examples:

Don't know what to do with Unknown Token: (280,8,'elseif') in SmartParser::parseToken
Error compiling statement at D:\pd\pol\scripts\items\torch.src, Line 4

Warning: Equals test result ignored. Did you mean := for assign?
near: item.graphic = 0xa12;
File: D:\pd\pol\scripts\items\torch.src, Line 5

Warning! possible incorrect assignment.
Near: if(item.graphic := 0x0f64)

- ecompile catches this too, normally you wouldn't want to do an assignment in an if-condition. It is not an illegal statement, so ecompile completes the compile but warns you about it.

Unhandled reserved word: 'endprogram'
Error compiling statement at D:\pd\pol\scripts\items\torch.src, Line 7
Error in IF statement starting at File: D:\pd\pol\scripts\items\torch.src, Line 4

- this error was we forgot an 'endif' keyword. The compile ran into the 'endprogram' keyword before 'endif', which is a syntax error.

Token 'item' cannot follow token ')'
Error compiling statement at D:\pd\pol\scripts\items\torch.src, Line 2

- this error was from an unmatched open-parenthesis in an if statement (on line 4)

Error compiling statement at D:\pd\pol\scripts\items\torch.src, Line 2
Error detected in program body.

- this is a nasty one, because it does not give you any idea what is wrong. I've only come across this error when a variable is declared with the same name as a keyword, in this case, 'for'.

Run-Time errors are much harder to find. These are errors that are syntactically correct, but produce incorrect results. The compiler will not catch these, nor will it help you find them. Your best bet for finding these errors is to notice where and when the script behaves incorrectly and go to that portion of the source code and poke around. To nail down the specific problem, you have several ways to go about it:

1. print() variables that you think are in doubt every now and then. Narrow down the exact spot where the bug is.
2. Many core functions return 'error' if something went wrong (i.e. tried to create an NPC in an illegal location). If you test the return value of these functions against 'error', you can catch them (i.e. if(CreateNPCAtLocation == error)...)
3. Some functions also return an '.errortext' member that gives you additional information. Such as:

var house := CreateMultiAtLocation(...);
if(house == error)
  Print(house.errortext);
endif

4. If none of these work for you, you could build the script with debug turned on. What this does is POL will print each line of code as it executes to the console. This is not always helpful, because if many instances of that script are running, they'll all print to the console. Best bet with this method is to debug on a local server where a minimum of other scripts are running. To turn on debug mode, make sure you 'use os;' before you add the line

set_debug(1);

under the 'use' lines at the top of your function. Then, you need to tell ecompile to compile with debug on. Do this with the '-i' switch. I.e. > ecompile –i test.src .

Chapter 11

Advanced Data Types and Functions

On the variable side, in this chapter we'll go into more detail on structs, describe dictionaries and error types, explain the concept of persistance, and define global properties. On the functions side, we'll describe pass by reference and use of the "parms" array to get past limitations on what can be passed.

Global Properties

By now, you're familiar with CProps- custom properties. You're an old hand at applying them to items, to people, heck, even to accounts. But, what if you don't want to apply it to anything at all? Is there a way to save information and let it just float in space, accessible from everywhere?

Yes, you can, and to do so you use global properties, otherwise known as GProps. You manipulate them in much the same way as you do CProps, except you don't need to tell it where to go. These are the three fundamental functions you'll need to use GProps:

GetGlobalProperty("PropertyName");
SetGlobalProperty("PropertyName","PropertyValue");
EraseGlobalProperty("PropertyName");

And as always, you can use variables to define the name or value of the Global Property.

var globname := "Prop1";
SetGlobalProperty(globname ,"No");

The above code would set the value "No" to the global property "Prop1". You can also but more than just simple variables as the value, for both GProps and CProps. Here's an example:

var propname := "Property1";
var propvalue := array{0 , 1 , "two"};
SetGlobalProperty(propname, propvalue);

And viola, Property1 now has as its value an array containing 0, 1, and "two". Later, if you were to do the following:

var ourprop := GetGlobalProperty("Property1");
Print(outprop[1]);

the output would be "0". This also works for CProps.

So now we have an interesting question- if simple variables and arrays can both be stored in props, what else can? To answer that question, we'll take a look at the concept of persistance.

If a variable type can be stored in a prop, it is said to be Persistable. As of POL090, there are no data types that cannot be persisted, so this section is mostly so you'll know what was meant when you read old changes.txts and see notices that certain things can now be persisted. In POL089, there was one type of data that could not be persisted- the mysterious ERROR type. This was the type you got if you tried to go something that should have returned a value but failed- instead you got or or somesuch. This caused a problem if you then tried to set the variable that just got assigned an error as a CProp- it wouldn't stick. It wouldn't persist. Nowadays, error types do persist, and they do so as though they were a struct.

I'll go into a little more detail on data types you've already seen, now.

Arrays

The prefered way to initialize an empty array is to use:

var a := array;

This works the same as

var a := {};

used to.

Arrays have a couple of methods that go with them- functions you can use to manipulate them directly. They are:

array.Size() - This returns the number of elements in the array.
array.Insert(index , value) - inserts a new element, value, at the specified index.
array.Erase(index) - deletes the element with the specified index.
array.Shrink(nelems) - erases all but the first nelems elements in the array.
array.Append(value) - adds this element to the end of the array.
array.Reverse() - reverses the order of the array.
array.Sort() - sorts the array.

Here's an example:

1  var colours := array;
2  colours[1] := "green";
3  colours[2] := "blue";
4  var csize := colours.Size();
5  colours[5] := "shiny";
6  csize := colours.Size();

So, let's take this step by step. Line 1 defines the array. Lines 2 and 3 put the first elements into it. At line 4, the variables look like this:

  colours[1] = "green"
  colours[2] = "blue"
  csize = 2

Line 5 adds a new elements at position 5, which EScript handles just fine because it's cool like that. So what do the variables look like as of line 6?

  colours[1] = "green"
  colours[2] = "blue"
  colours[3] =     <--- this is one of those error types.
  colours[4] = 
  colours[5] = "shiny"
  csize = 5 

Note that when it counts how many things are in the array, it includes the "empty" spaces! In other words, array.Size() could more accurately be said to return the last valid array index. I'll also point out that if you attempt to look at an array position off the end of the array (colours[10], for instance) it will also return <uninitialized object> on you.

Now, let's continue the previous example.

7 colours.Insert(3, "bronze");
8 csize := colours.Size();

What happens here? We're inserting the value "bronze" at position 3 in the array. Here's what the array looks like after that:

colours[1] = "green"
colours[2] = "blue"
colours[3] = "bronze"
colours[4] = 
colours[5] = 
colours[6] = "shiny"
csize = 6 

Note that an insert pushes the remaining elements down one slot, EVEN IF it is inserted into a position that was empty. If you don't want to push like that, don't use insert, just use an assignment: colours[3] := "bronze".

9 colours.Erase(3);

This will return the array to what it looked like before the insert.

10 colours.Erase(3);

This removes one of the empty slots in the array. Using the erase method pulls everything up one slot- just the opposite of insert. So after line 10, we have:

colours[1] = "green"
colours[2] = "blue"
colours[3] = 
colours[4] = "shiny"
csize = 6 

11 colours.shrink(3);

This will reduce the array to the first 3 elements- in this case,

colours[1] = "green"
colours[2] = "blue"
colours[3] =  

12 colours.Append("brown");
13 colours.Reverse();

This will end up yielding:

colours[1] = "brown"
colours[2] = 
colours[3] = "blue"
colours[4] = "green"

14 colours.shrink(2);
15 colours.reverse();

colours[1] = 
colours[2] = "brown"

Quite frankly, I'm not entirely sure how sort works. I'll provide two examples from my testing and let people experiment with it on their own.

a := array;
a[1] := 4;
a[2] := 7;
a[3] := "show";
a[4] := "tunes";
a.Sort();

printing out the array elements in order yielded:

show tunes 4 7

However...

a := array;
a[1] := 4;
a[2] := 7;
a[3] := "show";
a[5] := "tunes";
a.Sort();

printing this out in order gave me:

printing out the array elements in order yielded:

tunes  show 4 7

Note also that an array element can be any data type- I can hold a number there, or a struct, or an error, or another array. Try to sort an array of arrays at your own risk.

A Quick Review of Structs

A struct is similar to an array in that it contains a collection of values rather than just one. However, rather than an ordered list, structs are stored in, well, a structure. To create one, first you have to initialize it:

var a := struct;

This lets the compiler know that it is going to be of data type struct and treats it accordingly. The nice thing about structs is that they can be treated like a lot of the internal objects. For instance, a player has certain elements, like his position. These are accessed with the '.' - player.x, player.y, and player.z, for instance. Similarly, we can assign the struct elements that are accessed the same way. Here's an example:

var elevator := struct;
elevator.+floor;
elevator.+riders;
elevator.+shaft;

elevator.floor := 1;       // It's on the first floor.
elevator.riders := array;  // We'll keep an array of the people on it, using
                           // append and erase to keep track of them.
elevator.shaft := 3;       // It's in the third shaft from the left.

So, someone gets on and pushes 3.

elevator.riders.Append("John");

elevator.floor := 3;       // Order of precidence on . is left to right, so
elevator.riders.Erase(1);  // first it finds elevator.riders, sees that it is
	                         // an array, and then appends.
	                         // We've gone upstairs.
	                         // John gets off the elevator.

Dictionaries

Dictionaries are similar to both structs and arrays- they are, sort of, a bridge between the two types. You create a dictionary, unsurprisingly enough, with this syntax:

var thing := dictionary;

Then, you treat it like an array except, instead of just ordered numbers, a dictionary can contains words or numbers as its keys.

thing["green"] := "blue";
thing["number"] := 4;
thing[3] := array{1 , 3};

Internally, structs are actually dictionaries- so, basically, these do the same thing:

var thing1 := struct;
thing.+first;
thing.first := "one";

var thing2 := dictionary;
thing2["first"] := "one";

In addition, it means that the dictionary methods work equally well on both. These methods are:

dictionary.Size() - returns the number of elements.
dictionary.Erase(key) - erases an element.

dictionary.Exists(key) - returns true if there that key exists.
dictionary.Keys() - returns a list of all the keys.

Functions, for the most part, return one value if any. Frequently, we want to pass back more than one piece of data, we can return an array, or struct, or dictionary.

This also works the other way. The start_script os method only takes two parameters- the name of the script, and one thing to pass it. What if you want the script to take in multiple variables for information? You send it an array, of course, and custom has it that this array ends up getting named "parms".

Here's an example. Let's say you have a script, called testscript. It wants as parameters who called it as well as two items that the user has clicked on. If you wanted to call it from another script, you could do the following:

start_script("testscript" , array{who, target1, target2});

or,

var parms := array;
parms[1] := who;
parms[2] := target1;
parms[3] := target2;
start_script("testscript" , parms);

Then, in testscript.src:

program testscript(parms)
  if ( parms[2] ) //tests if it got passed an array
    char := parms[1];
    firsttarget := parms[2];
    secondtarget := parms[3];
  else
    char := parms;
  endif
  // do stuff
endprogram

The program knows how to react whether it was simply sent a scalar or if it was sent an array.

Function Calls by Reference

The final section of this chapter will cover passing variables to functions by reference rather than by value. What's the difference?

Normally, we pass variables by value. Which is to say, it sends the contents of the original variable to the new one (copy), and the new one doesn't care anymore about the old one. So, when we have:

var first := "one";
var second := 2;
FallFunction(first ,second);

and...

function CallFunction (this, that)
  print(this);  // will print "one"
  print(that);  // will print "2"
  this := "green";
endfunction

when all is said and done, the values of first and second do not change.

However, if we pass by REFERENCE, what we are actually sending to the function is the location in memory of the variable itself, rather than just sending along its contents. You do this by prefixing the variable name with "byref" in the function declaration. So for instance:

var a := 4;
var b := 6;
var c := 9;
Foo(a, b, c);

function Foo(pa, byref pb, pc)
  pa := 3;
  pb := 5;
  pc := 8;
endfunction

After the call to function foo is completed, a and c are unchanged but the value of b has become 5, because pb is a reference to the variable b itself, not a copy of its contents.

You have to be careful with this, as it is easy to change a variable you didn't intend to, but it is very powerful. It is also more efficient than pass by value, because it does not have to make and store a copy of the variable's value, and then destroy it when the function is done.

Appendix A: GUMP Tag Descriptions

Appendix X: Revision History

v0.1: 6/27/2000
       Initial preliminary document
v0.2: 7/19/2000
       Added sections on Case, built-in props, Object Ref chart
v0.3: 7/21/2000
       Added Gump Tag descriptions, CProp Chapter, Package Chapter
v0.4: 7/22/2000
       Added Debugging Chapter
v0.5: 7/25/2000
       Cleaned up, added contact info, first public version.
v0.6: 11/01/2000
       Turned into HTML. Corrected an error in the CASE section. Added info about CProps and accounts. Added Chapter 11. -Madman
v0.6a: 11/06/2000
       Added Table of Contents, cell borders on some tables. -Madman
v0.6b: 15/06/2006
       Fixed some eScript comparisons and assignments. Removed some 'local's. Added 'do..dowhile()'. -Shinigami
v0.6c: 7/07/2006
       Removed object property/method lists, updated data structures and iterations and trillions of smaller things. -Austin
v0.6d: 19/02/2009
       Reformated. -Turley
v0.6e: 12/10/2015
       Cleaned HTML code. - Bodom