Any questions, suggestions, and changes should be sent to racalac@burdell.org.
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.
Chapter 3: Conditionals and Iteration
Chapter 6: Built-in Properties and the POL Object Reference
Chapter 8: Config File Usage and Access
Chapter 11: Advanced Data Types and Functions
Appendix A: POL Object Reference Chart
Appendix B: Gump Tag Descriptions
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;
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:
+ : addition
- : subtraction
* : multiplication
/ : division
The expressions are evaluated first inside parenthesis then from left-to-right. Such as:
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().
|
|
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:
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).
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.
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 and structures in this chapter.
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:
|
|
An array can be assigned to any other variable, even if that variable was not declared an array:
var a := { 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 := function_that_returns_an_array();
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 := {};
a[1] := 4;
a[4] := 7;
Arrays elements can be any type of object, including another array:
Var a := {};
Var b := {};
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.
Local a := { 2,4,6,8 };
Local i;
for( i := 1; i <= len(a);
i := i + 1 )
print( a[i] );
endfor
foreach i in a
print( i
);
endforeach
Structures are just arrays whose elements are named. Normally, structures are only used when a function returns a structure.
To access members, use the '.' operator:
print( a.height );
print( a.width );
The syntax to create a structure is kind of weak, because it looks just like you're declaring an array:
var a:= {};
To add members, use the '.+' operator:
var a:= {};
a.+height;
a.+width;
a.height := 5;
You can then use the structure 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).
Conditionals and Iteration
We'll cover two topics in this chapter: IF-statements and loops.
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
)
.
.
.
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:
|| or "or"
&& or "and"
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"
{ blah }
endif
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
function_one()
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
function_two()
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)
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
function_three()
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.
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:
Local a := { 2,4,6,8 };
Local i;
for( i := 1; i <= len(a);
i := i + 1 )
print( a[i] );
endfor
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.
The output of this code is:
2
4
6
8
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
Another loop type that eScript supports is the "while" 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:
repeat
{code}
until 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! break
out!
break;
elseif(
condition = 13 )
//don't do the code
below the
if-block
continue;
endif
condition
= condition * something;
endwhile
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 Function_Name( parameter, ... )
{your
code}
endprogram
function Function_Name( 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).
Function_Name can be anything, as long as it is one word (you can use underscores like I did to separate words for readability) 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
);
MyFunction( var2, var3 );
Myfunction( var5,
var1 );
MyFunction( var3
);
MyFunction();
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
Prints: Teen Spirit
To return more than one value from a function, assign those values to an array or structure in the function and then return the array or structure name to the calling function.
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";
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.
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.
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" 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*/
/*5*/ var character;
/*6*/ foreach
character in
EnumerateOnlineCharacters()
/*7*/ SendSysmessage(
character, text
);
/*8*/ endforeach
/*9*/
/*10*/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 5: This variable will get the value of each element in the array returned by EnumerateOnlineCharacters().
Line 6: 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 7: The SendSysmessage function will send the "text" string to the lower left hand corner of "character"'s UO window.
Line 8: Signals the end of the foreach block
Line 10: Signals the end of the function.
Here's how it goes in a sample run:
1. The GM player types in ".bcast Howdy Everyone!" (without the
quotes).
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*/ var character;
/*6*/ foreach
character in EnumerateOnlineCharacters()
/*7*/ if(
character != speaker
)
/*8*/ SendSysmessage( character, text
);
/*9*/ endif
/*10*/ endforeach
/*11*/
/*12*/endprogram
Now the message won't be sent to who sent it.
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. 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:
Usage:
ECOMPILE [options] filespec [filespec
...]
Output is :
filename.ecl
Flags:
-i include
debug info in .ecl
file
-l generate
listfile
-r dir recurse
directory
-w display
warnings
-W generate
wordfile
-a compile *.asp
pages also
-b keep building
other scripts after
errors
-u compile only updated
scripts (.src newer than .ecl)
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 txtcmd/gm/bcast.src
Since that's where we put the file. You should see:
EScript Compiler v0.1 Alpha
Copyright (C) 1994-1999 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
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, an object-oriented type of design, i.e. the Door class has the members door.open() and door.close() which open and close the door, respectively. Notice how you access these members or "built-in properties" with the dot "." operator. So depending on what type of object you are working with, some members 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)!
Please refer to the POL Object Reference Chart for all the details.
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:
Here's the code:
use uo;
program return_ring( player, ring ) //remember this is a
usescript, and
//these are the parameters passed
//to the script by
POL
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; //exits the
script
endif
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:
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:
the important part here is the 'i'
before the value. This denotes the type of the data stored. We will revisit this
next chapter.
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 commands to set and read custom properties:
account.setprop("PropName",
value);
account.getprop("PropName");
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, skills.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).
Config files have several pieces to them which you should be familiar with. A configuration file consists of zero or more elements, each element has a type, a key, and zero or more properties. An example follows with the parts labeled: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 nonnegative 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 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):
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 get_material( 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:
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 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.
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?
Name template
# Name of package, must
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 ver note no leading '0', which would indicate octal
CoreRequired
76
# Your name
Maintainer John Q. Public
# Your
email
Email johnq@public.com
The following special files can exist in a package directory:
pkg.cfg | package descriptor file | ||
itemdesc.cfg | item descriptor entries for items | ||
skills.cfg | skills defined in this package | ||
start.ecl | script to be run on system startup |
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(
":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, skills.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. Certain config files are read on server startup and cannot be unloaded, the most annoying being itemdesc.cfg.
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
- this error was from a
missing semicolon in an if-block on line 5
Warning: Equals test result ignored. Did you mean := for
assign?
near: item.graphic = 0xa12;
File:
D:\pd\pol\scripts\items\torch.src, Line 5
- ecompile guesses right
here: we used an equals test when we wanted an assign statement
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 .
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.
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 := { 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
I'll go into a little more detail on data types you've already seen, now.
The prefered way to initialize an empty array is to use:
var a := array;
This works the same as
var a := {};
used to. If you wish to start the array off with some content, however,
var a:= { "one", "two", 3 };
is the way to go.
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:
|
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?
|
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:
|
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:
|
11 colours.shrink(3);
This will reduce the array to the first 3 elements- in this case,
|
12 colours.append("brown");
13 colours.reverse();
This will end up yielding:
|
14 colours.shrink(2);
15 colours.reverse();
|
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:
|
However...
a := array;
a[1] := 4;
a[2] := 7;
a[3] := "show";
a[5] :=
"tunes";
a.sort();
printing this out in order gave me:
|
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 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:
|
|
|
// It's on the first floor. // We'll keep an array of the people on it, using // append and erase to keep track of them. // It's in the third shaft from the left. |
So, someone gets on and pushes 3.
|
|
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] := { 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.insert( key , value ) - | adds an element. Dictionaries are not really ordered, so it's not
entirely accurate to say the item is "inserted". This is the same as doing dictionary["key"] := value; |
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" , {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.
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, and the new one doesn't care anymore about the old one. So, when we have:
var first := "one";
var second := 2;
callfunction( 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.
Todo:
Chapters on the following subjects:
Gumps
Equip & Unequip
Scripts
Login & Logout Scripts
Hit Scripts
AI Scripts
POL Object Reference Class Hierarchy UObject Account PolCore() | | +---------+--------+ | | Mobile Item | | NPC | | +------------------+--------------+-----------+ | | | | Equipment Lockable Map Multi | | | +---+----+ +----+--------+ +----+----+ | | | | | | Armor Weapon Door Container Boat House | +----+----+ | | Spellbook Corpse
Methods: None
Properties:
member | description | type | access | |||
serial | serial number | integer | read-only | |||
objtype | object type | integer | read-only | |||
x | x-location | integer | read-only | |||
y | y-location | integer | read-only | |||
z | z-location | integer | read-only | |||
facing2 | direction facing | integer | read-write | |||
graphic1 | "model" | integer | read-write | |||
color | color | integer | read-write | |||
height | height of object | integer | read-only | |||
weight | weight of object | integer | read-only | |||
name | name if non-default | string | read-write | |||
multi | multi underneath obj | multiref | read-only |
Notes:
Methods:
mobile.setlightlevel( lightlevel, duration_in_seconds );
// set temporary light override
mobile.squelch(
duration_in_seconds );
// shut a character up for a
while
mobile.setstr( new_base_strength );
// set a
character's strength
mobile.setint( new_base_intelligence );
// set a character's intelligence
mobile.setdex(
new_base_dexterity );
// set a character's
dexterity
mobile.enable( privilege );
// activate a
privilege that the mobile has
mobile.disable( privilege );
// deactivate a privilege that the mobile
has
mobile.enabled( privilege );
// true if a mobile
has a privilege and it is enabled.
Properties:
member | description | type | access | |||
warmode | 1=in war mode | integer | read-only | |||
gender | 0=male 1=female | integer | read-only | |||
trueobjtype | original objtype | integer | read-only | |||
truecolor | original color | integer | read-only | |||
hp | current hp | integer | read-write | |||
maxhp | maximum hp | integer | read-only | |||
mana | current mana | integer | read-write | |||
maxmana | maximum mana | integer | read-only | |||
stamina | current stamina | integer | read-write | |||
maxstamina | maximum stamina | integer | read-only | |||
strength | unmodified | integer | read-only | |||
dexterity | unmodified | integer | read-only | |||
intelligence | unmodified | integer | read-only | |||
strength_mod | str modifier | integer | read-write | |||
intelligence_mod | int modifier | integer | read-write | |||
dexterity_mod | dex modifier | integer | read-write | |||
ar_mod | ar modifier | integer | read-write | |||
hidden | 1=hidden | integer | read-write | |||
concealed | GM flag | integer | read-write | |||
frozen | GM flag | integer | read-write | |||
paralyzed | paralyzed flag | integer | read-write | |||
poisoned | poisoned flag | integer | read-write | |||
stealthsteps | stealth steps left | integer | read-write | |||
squelched | 1=cannot talk | integer | read-only | |||
dead | 1=dead | integer | read-only | |||
ar | armor rating | integer | read-only | |||
backpack | (only if exists) | itemref | read-only | |||
weapon | equipped weapon | itemref | read-only | |||
acctname | account name | string | read-only | |||
acct | account obj | acctref | read-only | |||
cmdlevel | command level | integer | read-write | |||
criminal | criminal flag | integer | read-only |
Methods:
npc.setmaster( master );
// sets the NPC's master.
If 0 is passed, clears the NPC master
Properties:
member | description | type | access | |||
script | AI control script | string | read-write | |||
npctemplate | NPC template name | string | read-only | |||
master | controlling PC | mobileref | read-write |
Methods: None
Properties:
member | description | type | access | |||
amount | stack size | integer | read-only | |||
layer | equipment layer | integer | read-only | |||
container | item contained in | itemref | read-only | |||
usescript | dbl-click action script | string | read-write | |||
equipscript | script to be executed to determine if this item can be equipped | string | read-write | |||
unequipscript | script to be executed to determine if this item can be unequipped | string | read-write | |||
desc | single-click description | string | read-write | |||
movable | can the item be moved | integer | read-write | |||
decayat | gameclock when item should decay(0=never) | integer | read-write | |||
sellprice | price to sell item | integer | read-write | |||
newbie | 1=item stays with ghost | integer | read-write |
Notes:
Methods: None
Properties:
member | description | type | access | |||
quality | Quality,1.0 = average | real | read-write | |||
hp | Hit Points | integer | read-write | |||
maxhp | Maximum Hit Points | integer | read-only | |||
maxhp_mod | modifier(to be added) | integer | read-write |
Methods: None
Properties:
member | description | type | access | |||
ar_mod | modification to AR | integer | read-write | |||
ar | modified AR | integer | read-only | |||
ar_base | unmodified AR | integer | read-only |
Methods: None
Properties:
member | description | type | access | |||
skillid | skill number used when wielding weapon | integer | read-only | |||
dmg_mod | damage modifier | integer | read-write | |||
hitscript | script executed on successful hit | string | read-write |
Methods: None
Properties:
member | description | type | access | |||
locked | 1=object is locked | integer | read-write |
Methods:
door.open()
//Opens the door, even if it is
locked
door.close()
//Closes the
door
door.toggle()
//If the door is closed, opens it
(even if it is locked), and vice versa
Note: These methods are somewhat deprecated, in that the default doors package no longer uses them.
Properties:
member | description | type | access | |||
isopen | 1=door is open | integer | read-only |
Note: I do not believe that this member correctly shows whether or not the
door is open. A test that currently works on all doors (but might not, if you
make custom, weird doors) is: if (door.graphic != door.objtype) // door is
open
.
Methods: None
Properties:
member | description | type | access | |||
corpsetype | objtype of the creature killed | integer | read-only |
Methods: None
Properties:
member | description | type | access | |||
xeast | extreme east x-coordinate the map shows | integer | read-write | |||
xwest | same for west-x | integer | read-write | |||
ynorth | same for north-y | integer | read-write | |||
ysouth | same for south-y | integer | read-write | |||
gumpwidth | screen display width in pixels | integer | read-write | |||
gumpheight | screen display height in pixels | integer | read-write |
Methods:
boat.move_offline_mobiles(x,y,z)
//Move any
offline mobiles on the boat to a new location
Properties:
member | description | type | access | |||
tillerman | itemref | read-only | ||||
portplank | itemref | read-only | ||||
starboardplank | itemref | read-only | ||||
hold | itemref | read-only | ||||
items | items on deck | array of itemrefs | read-only | |||
mobiles | mobiles on deck | array of mobilerefs | read-only | |||
has_offline_mobiles | true if any offline mobiles on the deck | integer | read-only |
Methods: None
Properties:
member | description | type | access | |||
components | array of elements that are part of the house – doors, signs, forges, looms, etc. | array of itemrefs | read-only | |||
items | array of non-component items supported by the house | array of itemrefs | read-only | |||
mobiles | array of mobiles supported by the house | array of mobilerefs | read-only |
Methods:
account.ban()
// bans the account, disconnects any
characters online in this
//
account
account.unban()
// unbans the
sccount
account.disable()
// disables the
account
account.enable()
// enables the
account
account.setname( newname )
// Changes the
account name (takes a string)
account.setpassword( newpassword
)
// Changes the account password (takes a string). note
there is
// no way to read an account password
Properties:
member | description | type | access | |||
enabled | true if acct is enabled | integer | read-only | |||
banned | true if acct is banned | integer | read-only | |||
name | account name | string | read-only |
The PolCore object gives access to POL internals. It can be accessed by calling PolCore(), which is defined in the uo.em functionality module.
Methods:
polcore().log_profile( clear )
//Logs script
profiles to pol.log. Clears the script profile
//counters
if 'clear' is nonzero. Script profiles tell how many
//instructions each type of script has
executed
polcore().set_priority_divider( privdev
)
//Sets the script priority divider. If this value is set
high,
//this has the effect that each script will run for
less time
//before being scheduled out to run the next
script. If system
//load is high, this can decrease client
latency.
polcore().clear_script_profile_counters()
//Clears
the script profile counters
Properties:
member | description | type | access | |||
bytes_sent | num of bytes sent to all clients, not including HTTP connections | integer | read-only | |||
bytes_received | TBD | TBD | read-only | |||
compiledate | read-only | |||||
compiletime | read-only | |||||
events_per_min | read-only | |||||
instr_per_min | read-only | |||||
itemcount | read-only | |||||
mobile_count | read-only | |||||
packages | read-only | |||||
priority_divide | read-only | |||||
running_scripts | read-only | |||||
script_profiles | read-only | |||||
sysload | read-only | |||||
sysload_severity | read-only | |||||
systime | read-only | |||||
uptime | read-only | |||||
version | read-only | |||||
verstr | read-only |
Tags | Syntax/Description | |
---- | ------------------ | |
noclose | [NONE] | |
gump can't be closed by clicking the right mousebutton. Selection via an exit enabled button must be made. | ||
nomove | [NONE] | |
The gump can't be moved around the screen. | ||
nodispose | [NONE] | |
The gump can't be closed by hitting ESC. If this setting isn't specified and the user hits ESC, then the dialog is closed but no message is sent to the server. The server never thinks the player is done with the gump. Therefore ALL gump dialogs should specify 'nodispose'. | ||
tilepic | [X] [Y] [T] | |
Displays a tile on the
gump. [X] -> X coord of the tile. [Y] -> Y coord of the tile. [T] -> Tile ( see insideUO ) | ||
resizepic | [X1] [Y1] [G] [X2] [Y2] | |
Defines the gump
layout background. [X1] -> Start X coord of the gump. [Y1] -> Start Y coord of the gump. [G] -> Graphics to be used as gump background. [Y1] -> End X coord of the gump. [Y2] -> End Y coord of the gump. Notes: Be careful, not all gumps 'stretch' and have to be used with the correct sizing. 5100 = stretchable gray background gump. | ||
page | [N] | |
[N] ->
Pagenumber. Notes: Defines the page layout. Page 0 affects all following pages (items will not be removed when moving to other pages), i.e. the 'background' that is always displayed. page 1 is what will be displayed when the gump first opens (on top of what is defined in page 0). | ||
button | [X] [Y] [G1] [G2] [E] [P] [R] | |
X -> X coord of the
button. Y -> Y coord of the button. G1 -> Normal graphics. G2 -> Clicked graphics. E -> Exit? ( 10 ) P -> Pagenumber ( jump to page ) R -> Returnvalue. [EXIT] = button will make a menuexit and return a value. (01) [PAGENUMBER] = button will change to page #. (#) [RETURNVALUE] = Returnvalue of button. (See EXIT) (#) if you have radio buttons on the screen with return values, those return values will be used instead. | ||
radio | [X],[Y],[GUMPGFX],[CLICKGUMPGFX],[PREVALUE],[RETURNVALUE] | |
Only one radio button
can be selected on a page. RETURNVALUE
will be returned when the gump exits. (See also BUTTON). | ||
tilepic | [X],[Y],[TILENUMBER] | |
Display the selected tile (normal item art). | ||
text | [X],[Y],[COLORCODE],[STRINGNUMBER] | |
Display
text The string numbering requires some thought however, UO considers the first string passed to it as 0 (zero) but POL considers the first one in an array to be 1 (one) so this is the way to do it: text 0 0 32 0 <---> array[1] := "This I want printed". | ||
gumppic | [X],[Y],[GUMPGFX] | |
Display the selected gump. | ||
textentry | [X] [Y] [WIDTH] [HEIGHT] [COLOR] [RETURNVALUE] [INITSTRINGNUMBER] | |
Display an editable text
entry line [RETURNVALUE] is the key to use to retrieve the string [INITSTRINGNUMBER] is the initial string to use, usual base 0<>1 stuff | ||
checkbox | [X],[Y],[GUMPGFX],[CLICKGUMPGFX],[PREVALUE],[RETURNVALUE] | |
RETURNVALUE of all the checked boxes can be found in result.keys[]. |
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