Graal Bible - User contributions [en]

Creation/Dev/GScript

2005-12-02T21:04:59Z

Chad:

'''GScript''' is [[Graal]]'s scripting language.

Its syntax and some of its semantics might seem familiar to those who program in [[WikiPedia:C (Programming Language) | C]] or derived languages, although it lacks some of the expressivity of a real programming language and has special constructs that make programming [[Graal]] [[NPC]]s easier.

GScript started as a very limited language and has since kept up with improvements to the game engine and can now be used for pretty sophisticated scripts that greatly customise the gaming experience.

It is used, with minor differences, for [[Clientside]] tasks like [[GUI | GUI programming]], special effects with nifty 3d lighting and custom [[NPC weapon|NPC Weapons]] or "engines", and [[Serverside]] systems like player housing, complex baddies or pets.

[[Old GScript]] has been replaced by a new version (dubbed GScript2 during development) that is rather advanced, in some way object oriented, and thanks to influence from [[WikiPedia:Java programming language| Java]] and [[Torque]]'s scripting language, less brain-damaged in some aspects. No offense intended.

GScript can be discussed in the [[GScript IRC channel]].

[[Script Functions: Client]]

[[Script Functions: NPC Server]]

[[Script Functions: Graal 3D]]

[[Graal v4 IRC|Graal IRC Scripting: Graal v4 IRC Scripting Reference]]

[[Troubleshooting Graal v4 IRC|Graal IRC Scripting: Troubleshooting Scripting Reference]]

[[Particle Engine|Graal v4 Particle Engine]]

[[GS1 To GS2|GS1 To GS2: Guide for fixing scripts to work with the new engine]]

== Introduction ==

=== Why scripts ===

Scripts bring life into objects and make it easy to
customize the game. Instead of just placing a stone
into your world, you can make it so that the stone
can be lifted or kicked. Instead of being limited to
some fixed player movement you can rescript it
to let the player jump, strafe and duck. To let the
player inspect and organize his/her items you can
create some dialogs and display those by script,
e.g. when the player presses a special key.

In Graal the scripting is done in 'Graal Script',
it's looking like Java/C++, but brings some
additional features for making things easier
for game creators, while on the other hand
running in a sandbox and limiting access to
game-related stuff only.

Graal Script is almost fully compatible to
the 'old' Graal script used in Graal v1.0 - 3.0,
and is partially compatible to Torque script.

=== NPCs and 'weapons' ===

There are generally two types of objects in Graal
which have scripts: The first type are the
non-player-characters (NPCs). The name 'NPC' is
actually used for all visible objects in the game:
monsters, stones, bushes, houses, ships, plants etc.
Scripts for npcs are most of the time containing
code for moving the npc or for reacting to
activities of the player, e.g. giving money to
the player when he grabs the npc.
The other type of script-holding objects are the
'weapons'. Those are items in the inventory of
the player, not necessary being weapons. Most of
the time they are actually just scripts which
control the movement of the player, display weapon
graphics, or display menus.

So there are objects in the game which have
their own script, and players which have a set
of scripts in their invisible backpack.

=== Server-side and client-side ===

Graal is an online game, and there are differences
to standard scripting in offline games.
In offline programs you have access to everything,
anytime. In online games everything is divided
into two parts: the server-side which controls
most things in the game, and the client-side which
displays the game to the player.
Since the client only displays things, it is not
possible to cheat by hacking the client. On client-side
you mainly have code for displaying special effects,
for displaying the GUI (windows, status bars, item menus),
playing sound effects and music. Also the player
movement is done on client-side.
On the server-side scripts are used to do the more
secure parts of the game engine,
and things that are the same for all players -
npcs are added, moved, npcs interact with players,
the stats of the players are calculated, the
communication between players is handled.

All scripts for npcs and weapons can contain
server-side code and client-side code. The server-side
code is executed directly on the server, the
client-side code is sent to the client when he/she
logins and executed separately for each player on
their own computer. Usually the two parts of the script
are divided by line that only contains "//#CLIENTSIDE",
like this:

<pre>// Server-side part which is setting the image
// of the npc when it is created
function onCreated() {
setimg("door.png");
}

//#CLIENTSIDE

// Here follows the client-side part,
// which plays a sound effect when the player
// touchs the npc
function onPlayerTouchsme() {
play("chest.wav");
}</pre>

=== Events ===

In general scripts are made for reacting to
events - when the npc is created then the script
initializes the attributes of the npc,
when the player says something then the npc is
moving to the player, when the player grabs the
npc then the npc is giving the player some money etc.
So the script is basicly a collection of actions
that are done when special events are happening.
Events can e.g. be the "created" event when the npc
is created, the "playertouchsme" event when the
player touchs the npc, or the "playerchats" event
when the player says something. To write code that reacts
to one of those event, you define an event
function like this:

<pre>function onEVENTNAME() {
// actions
}</pre>

When the event is happening, then Graal executes
that scripting function and all commands you
have added there.
Sometimes the event gives some parameters to the
event function, then change your function to:

<pre>function onEVENTNAME(parameter1, parameter2, ...) {
// actions
}</pre>

By accessing 'parameter1' etc. (you can name
them differently) you can react to the event more
exactly.

Instead of reacting to events, the npcs and
weapons can also invoke new events. That way
you can let other npcs doing things. You also
need that if you want to coninuously doing things -
use timeout events for that.

<pre>function onCreated() {
setTimer(1);
}

function onTimeout() {
// actions
setTimer(1);
}</pre>

In the onCreated event function the script is
setting the timer to 1 second. When that second is
over, then the "timeout" event is invoked on the
npc and the onTimeout event function is executed.
Because it is setting the timer to 1 second
again, the onTimeout event will occur again after
one second, and so on.

Compatibility note:
In older Graal scripts you will also find the
deprecated way of receiving events:

<pre>if (EVENTNAME) {
// actions
}</pre>

That is an if-command outside of any brackets. If
Graal sees that you use such an if-command, then
it will execute the whole script so that the actions
you have written inside the if-command will be
executed too.

== Basics ==

=== Accessing variables ===

Graal Script variables are 'variant', that means they are objects
that hold values of different types.
When you assign a value to the variable then it automatically
switches to the right type:

Numeric (floating point):
var = 1;
String (text):
var = "hello";
Object link:
var = player;
Array (list of objects):
var = {1,2,3};

You can check the current type with the
type()-function - obj.type() returns
0,1,2,3 for numeric, string, object or array.

=== Operators ===
<pre>
Addition a + b
Substraction a - b
Mulitplication a * b
Division a / b
Modulus a % b
Power a ^ b
String Concationation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b
Bool-And a && b
Bool-Or a || b
Bool-Not !a
Negative -a
Equal a == b
Not-Equal a != b
Less a b
Less-Equal a <= b, a == b, a => b
In-Range a in <b,c>, a in |b,c>, a in <b,c|, a in |b,c|
In-Array a in {b,c,...}, {a,b,...} in {c,d,...}
Bitwise-Or a | b
Bitwise-And a & b
Bitwise-Shift left a <> b
Bitwise-Invert ~a
Bitwise-Xor a xor b (operator ^ already used for power)
Array-Constructor {a,b,...}
Empty Array new [count], new[countdim1][countdim2]...
Array Member a[index]
Function call a(), a(b,c,...)
Object Attribute a.b, a.(b)
Post Increment a++
Post Decrement a--
Pre Increment ++a
Pre Decrement --a
Old String Function #a
Conditional a? b : c
Assignment a = b, a := b
Additive Assignment a += b
Substractive Assignment a -= b
Multiplicative Assignment a *= b
Division Assignment a /= b
Modulus Assignment a %= b
Power Assignment a ^= b
Bitwise-Or Assignment a |= b
Bitwise-And Assignment a &= b
Shift Left Assignment a <<= b
Shift Right Assignment a >>= b
String Append a @= b
</pre>

=== Standard object functions ===

For a complete list of functions and attributes of objects
see docu_graalscriptfunctions.txt. The base type of all
objects is "TGraalVar". You can also get the latest list by
calling the executale with "-listscriptfunctions" as
command-line parameter.
Here only some of the built-in functions:
<pre>
obj.type() - gets the type of the var (float 0, string 1, object 2, array 3)
obj.length() - string length
obj.trim() - removes spaces from the front and back of a string
obj.lower() - converts a string to lower case
obj.upper() - converts a string to upper case
obj.tokenize([delimiters])
obj.charat(pos)
obj.pos(substring)
obj.starts(string)
obj.ends(string)
obj.substring(index[,length])
obj.size() - array length
obj.subarray(index[,length])
obj.addarray(obj2)
obj.insertarray(index,obj2)
obj.index(obj2) - position of obj2 in the array
obj.clear()
obj.add(obj2)
obj.delete(index)
obj.remove(obj2)
obj.replace(index,obj2)
obj.insert(index,obj2)
</pre>

=== Standard functions ===
<pre>
format(format,parameters,...) - formats a "%s %d" string, inserts the parameters, and returns a string
int(a)
abs(a)
random(rangestart,rangeend)
sin(a)
cos(a)
arctan(a)
exp(a)
log(base,a)
min(a,b)
max(a,b)
getangle(delta x,delta y)
getdir(delta x,delta y) - returns 0 for up, 1 for left, 2 for down, 3 for right
vecx(direction)
vecy(direction)
</pre>

== Events ==

=== GUI controls ===
<pre>
onAdd() when added to the parent
onRemove() when removed from the parent
onWake() when activated
onSleep() when deactivated
onResize(w,h)
onMove(x,y)
onMouseEnter(modifier,x,y,clickcount)
onMouseLeave(modifier,x,y,clickcount)
onMouseDown(modifier,x,y,clickcount)
onMouseUp(modifier,x,y,clickcount)
onMouseDragged(modifier,x,y,clickcount)
onMouseMove(modifier,x,y,clickcount)
onRightMouseDown(modifier,x,y,clickcount)
onRightMouseUp(modifier,x,y,clickcount)
onRightMouseDragged(modifier,x,y,clickcount)
onMouseWheelUp(modifier,x,y,clickcount)
onMouseWheelDown(modifier,x,y,clickcount)
onKeyDown(keycode,string)
onKeyUp(keycode,string)
onKeyRepeat(keycode,string)
</pre>
==== GuiMLTextCtrl: ====
<pre>
onReflow(w,h) when the text has changed
onURL(url) when clicked on url
onSelectTag(tagid) when clicked on an image

Text-Tags:
The text of multi-line text controls can contain
a few HTML-tags and Torque-tags, you can use both
of those tag types to define colors and fonts
or to include images. Currently following tags
are available:

HTML:
<a href=url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<body bgcolor=colorname or #rrggbb> - sets the background color
 - line break
<center> text </center> - centers the contained text
 text 
- draws text with a special font, size and color; you only
need to define one of those 3 attributes
<ignorelinebreaks> </ignorelinebreaks> - go into normal HTML mode where
you need to insert to do a linebreak
<img src=filename id=integer> - an image is displayed, you
can also specify a tagid if you want to get onSelectTag-events
for this image
 text - sets the align of the
contained text
 - for
displaying a subpage, you can also specifiy an id for
onSelectTag-events; instead of you can also use <div> tags

Torque:
<a:url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<bitmap:filename> - an image is displayed
<color:rrggbb> - sets the color of the text (hexadecimal value)
<lmargin:pixels> - sets the left margin for the text
<lmargin%:percent> - sets the size of the left margin depending
on the width of the whole control
<linkcolor:rrggbb> - sets the color of links (the <a>-tag)
<linkcolorhl:rrggbb> - sets the highlighted color, when
the user moves the mouse over a link
<just:left/center/right> - sets the align of the following text
<rmargin:pixels> - sets the right margin for the text
<rmargin%:percent> - sets the size of the right margin depending
on the width of the whole control
<sbreak> - line break
<spush> - switches to a new style (like )
<spop> - switches back to the last saved style (like )
<tab:tab1,tab2,..> - sets the position of where tabulators should
be displayed if you have text like 'Apple \t Egg \t Chicken'
<tag:id> - inserts an invisible tag which can be used
for the scrollToTag(id) function (beside image-tags)

</pre>

==== GuiTextEditCtrl: ====
<pre>
onTabComplete()
onAction(text) when return key pressed
</pre>
==== GuiTextListCtrl: ====
<pre>
onSelect(id,text) when row selected
onDblClick(id) when double-click on row or return key pressed
onDeleteKey(id) when delete key pressed
onIconResized(w,h) when setIconSize() called
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiPopUpMenuCtrl: ====
<pre>
onSelect(id,text) when menu option choosen
onCancel() when menu is closed without action
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiMenuBar: ====
<pre>
onMenuSelect(menuid,menutext)
onMenuItemSelect(menuid,menutext,itemid,itemtext)
</pre>
==== GuiTreeViewCtrl: ====
<pre>
onSelect(id,rightmouse) when row selected
onUnselect(id) when row de-selected
onInspect(id) when clicked on the name of an item
onOpenMenu(0,index,text) when an item was right-clicked
onContextMenu("x y",id) when clicked with right-mouse key on row
</pre>

== Old script compatibility ==

=== Removed functionality ===
<pre>
- toinventory
- followplayer
- playersays()
- setbackpal
</pre>
=== Supported old scripting commands and their mapping to new script ===
<pre>
addstring oldstring, oldstring;
addstring(string,string);
addtiledef oldstring, oldstring, float;
addtiledef(string,string,float);
addtiledef2 oldstring, oldstring, float, float;
addtiledef2(string,string,float,float);
attachplayertoobj float, float;
attachplayertoobj(float,float);
blockagain;
blockagain();
blockagainlocal;
blockagainlocal();
callnpc float, oldstring;
callnpc(float,string);
callweapon float, oldstring;
callweapon(float,string);
canbecarried;
canbecarried();
canbepulled;
canbepulled();
canbepushed;
canbepushed();
cannotbecarried;
cannotbecarried();
cannotbepulled;
cannotbepulled();
cannotbepushed;
cannotbepushed();
canwarp;
canwarp();
canwarp2;
canwarp2();
carryobject oldstring;
carryobject(string);
changeimgcolors float, float, float, float, float;
changeimgcolors(float,float,float,float,float);
changeimgmode float, float;
changeimgmode(float,float);
changeimgpart float, float, float, float, float;
changeimgpart(float,float,float,float,float);
changeimgvis float, float;
changeimgvis(float,float);
changeimgzoom float, float;
changeimgzoom(float,float);
deletestring oldstring, float;
deletestring(string,float);
destroy;
destroy();
detachplayer;
detachplayer();
disabledefmovement;
disabledefmovement();
disablemap;
disablemap();
disablepause;
disablepause();
disableselectweapons;
disableselectweapons();
disableweapons;
disableweapons();
dontblock;
dontblock();
dontblocklocal;
dontblocklocal();
drawaslight;
drawaslight();
drawoverplayer;
drawoverplayer();
drawunderplayer;
drawunderplayer();
enabledefmovement;
enabledefmovement();
enablefeatures float;
enablefeatures(float);
enablemap;
enablemap();
enablepause;
enablepause();
enableselectweapons;
enableselectweapons();
enableweapons;
enableweapons();
explodebomb float;
explodebomb(float);
followplayer;
followplayer();
freezeplayer float;
freezeplayer(float);
freezeplayer2;
freezeplayer2();
hide;
hide();
hideimg float;
hideimg(float);
hideimgs float, float;
hideimgs(float,float);
hidelocal;
hidelocal();

hitcompu float, float, float, float;
hitcompu(float,float,float,float);
hitnpc float, float, float, float;
hitnpc(float,float,float,float);
hitobjects float, float, float;
hitobjects(float,float,float);
hideplayer float;
hideplayer(float);
hidesword float;
hidesword(float);
hitplayer float, float, float, float;
hitplayer(float,float,float,float);
hurt float;
hurt(float);
insertstring oldstring, float, oldstring;
insertstring(string,float,string);
join oldstring;
join(string);
lay oldstring;
lay(string);
lay2 oldstring, float, float;
lay2(string,float,float);
loadmap oldstring;
loadmap(string);
message oldstring;
message(string);
move float, float, float, float;
move(float,float,float,float);
noplayerkilling;
noplayerkilling();
openurl oldstring;
openurl(string);
openurl2 oldstring, float, float;
openurl2(string,float,float);
play oldstring;
play(string);
play2 oldstring, float, float, float;
play2(string,float,float,float);
playlooped oldstring;
playlooped(string);
putbomb float, float, float;
putbomb(float,float,float);
putcomp oldstring, float, float;
putcomp(string,float,float);
putexplosion float, float, float;
putexplosion(float,float,float);
putexplosion2 float, float, float, float;
putexplosion2(float,float,float,float);
puthorse oldstring, float, float;
puthorse(string,float,float);
putleaps float, float, float;
putleaps(float,float,float);
putnewcomp oldstring, float, float, oldstring, float;
putnewcomp(string,float,float,string,float);
putnpc oldstring, oldstring, float, float;
putnpc(string,string,float,float);
putnpc2 float, float, oldstring;
putnpc2(float,float,string);
reflectarrow float;
reflectarrow(float);
removearrow float;
removearrow(float);
removebomb float;
removebomb(float);
removecompus;
removecompus();
removeexplo float;
removeexplo(float);
removehorse float;
removehorse(float);
rmeoveitem float;
removeitem(float)
removestring oldstring, oldstring;
removestring(string,string);
removetiledefs oldstring;
removetiledefs(string);
replaceani oldstring, oldstring;
replaceani(string,string);
replacestring oldstring, float, oldstring;
replacestring(string,float,string);
resetfocus;
resetfocus();
savelog oldstring;
savelog(string);
savelog2 oldstring, oldstring;
savelog2(string,string);
say float;
say(float);
say2 oldstring;
say2(string);
sendrpgmessage oldstring;
sendrpgmessage(string);
sendpm oldstring;
sendpm(string);
sendtonc oldstring;
sendtonc(string);
sendtorc oldstring;
sendtorc(string);
serverwarp oldstring;
serverwarp(string);
set oldstring;
set(string);
setani oldstring, oldstring;
setani(string,string);
setarray float, float;
setarray(var,float);
setbeltcolor oldstring;
setbeltcolor(string);
setbow oldstring;
setbow(string);
setcharani oldstring, oldstring;
setcharani(string,string);
setchargender oldstring;
setchargender(string);
setcharprop oldstring, oldstring;
string = string;
setcoatcolor oldstring;
setcoatcolor(string);
setcoloreffect float, float, float, float;
setcoloreffect(float,float,float,float);
setcursor float;
setcursor(float);
setcurcor2 oldstring;
setcursor2(string);
seteffect float, float, float, float;
seteffect(float,float,float,float);
seteffectmode float;
seteffectmode(float);
setfocus float, float;
setfocus(float,float);
setgender oldstring;
setgender(string);
sethead oldstring;
sethead(string);
setlevel oldstring;
setlevel(string);
setlevel2 oldstring, float, float;
setlevel2(string,float,float);
setmap oldstring, oldstring, float, float;
setmap(string,string,float,float);
setminimap oldstring, oldstring, float, float;
setminimap(string,string,float,float);
setmusicvolume float, float;
setmusicvolume(float,float);
setimg oldstring;
setimg(string);
setimgpart oldstring, float, float, float, float;
setimgpart(string,float,float,float,float);
setletters oldstring;
setletters(string);
setplayerdir oldstring;
setplayerdir(string);
setplayerprop oldstring, oldstring;
string = string;
setpm oldstring;
setpm(string);
setshape float, float, float;
setshape(float,float,float);
setshape2 float, float, float;
setshape2(float,float,float);
setshield oldstring, float;
setshield(string,float);
setshoecolor oldstring;
setshoecolor(string);
setshootparams oldstring;
setshootparams(string);
setskincolor oldstring;
setskincolor(string);
setsleevecolor oldstring;
setsleevecolor(string);
setstring oldstring, oldstring;
setstring(string,string);
setsword oldstring, float;
setsword(string,float);
seturllevel oldstring;
seturllevel(string);
setz float, float, float, float, float, float, float, float;
setz(float,float,float,float,float,float,float,float);
setzoomeffect float;
setzoomeffect(float);
shoot float, float, float, float, float, float, oldstring, oldstring;
shoot(float,float,float,float,float,float,string,string);
shootarrow float;
shootarrow(float);
shootball;
shootball();
shootfireball float;
shootfireball(float);
shootfireblast float;
shootfireblast(float);
shootnuke float;
shootnuke(float);
show;
show();
showani float, float, float, float, oldstring;
showani(float,float,float,float,string);
showani2 float, float, float, float, float, oldstring;
showani2(float,float,float,float,float,string);
showcharacter;
showcharacter();
showfile oldstring;
showfile(string);
showimg float, oldstring, float, float;
showimg(float,string,float,float);
showimg2 float, oldstring, float, float, float;
showimg2(float,string,float,float,float);
showlocal;
showlocal();

showpoly float, float;
showpoly(float,array);
showpoly2 float, float;
showpoly2(float,array);
showstats float;
showstats(float);
showtext float, float, float, oldstring, oldstring, oldstring;
showtext(float,float,float,string,string,string);
showtext2 float, float, float, float, oldstring, oldstring, oldstring;
showtext2(float,float,float,float,string,string,string);
sleep float;
sleep(float);
spyfire float, float;
spyfire(float,float);
stopmidi;
stopmidi();
stopsound oldstring;
stopsound(string);
take oldstring;
take(string);
take2 float;
take2(float);
takehorse float;
takehorse(float);
takeplayercarry;
takeplayercarry();
takeplayerhorse;
takeplayerhorse();
throwcarry;
throwcarry();
timereverywhere;
timereverywhere();
timershow;
timershow();
toinventory oldstring;
toinventory(string);
tokenize oldstring;
tokens = string.tokenize();
tokenize2 oldstring, oldstring;
tokens = string.tokenize(" ," @ string);
toweapons oldstring;
toweapons(string);
triggeraction float, float, oldstring, oldstring;
triggeraction(float,float,string,string);
unfreezeplayer;
unfreezeplayer();
unset oldstring;
unset(string);
updateboard float, float, float, float;
updateboard(float,float,float,float);
updateterrain;
updateterrain();
wraptext float, oldstring, oldstring;
tokens = wraptext(float," ," @ string,string);
wraptext2 float, float, oldstring, oldstring;
tokens = wraptext2(float,float," ," @ string,string);
</pre>

=== Supported old string operations ===
<pre>
These old string operators can be used in string parameters
for the old commands, also you can use them directly as operators, e.g.
#c = "hello"
is actually doing
player.chat = "hello"

#a player.account
#a(float) players[float].account
#m player.ani
ani
#m(float) players[float].ani
#K(float) char(float)
#8 player.bodyimg
bodyimg
#8(float) players[float].bodyimg
#c player.chat
chat
#c(float) players[float].chat
#C0 player.colors[0]
colors[0]
#C0(float) players[float].colors[0]
#C1 player.colors[1]
colors[1]
#C1(float) players[float].colors[1]
#C2 player.colors[2]
colors[2]
#C2(float) players[float].colors[2]
#C3 player.colors[3]
colors[3]
#C3(float) players[float].colors[3]
#C4 player.colors[4]
colors[4]
#C4(float) players[float].colors[4]
#C5 player.colors[5]
colors[5]
#C5(float) players[float].colors[5]
#D downloadfile()
#E emoticonchar()
#e(float,float,oldstring)
string.substring(float,float)
#g player.guild
guild
#g(float) players[float].guild
#3 player.headimg
headimg
#3(float) players[float].headimg
#5 player.horseimg
horseimg
#5(float) players[float].horseimg
#k(float) keyname(float)
#L player.level
#I(oldstring,float)
getstring(string)[float]
#n player.nick
nick
#n(float) players[float].nick
#f image
#f(float) npcs[float].image
#F level
#p(float) params[float]
#P(float) player.attr[float]
attr[float]
#P(float_1,float_2)
players[float_2].attr[float_1]
#P1 player.attr[1]
attr[1]
#P1(float) players[float].attr[1]
#P2 player.attr[2]
attr[2]
#P2(float) players[float].attr[2]
#P3 player.attr[3]
attr[3]
#P3(float) players[float].attr[3]
#P4 player.attr[4]
attr[4]
#P4(float) players[float].attr[4]
#P5 player.attr[5]
attr[5]
#P5(float) players[float].attr[5]
#P6 player.attr[6]
attr[6]
#P6(float) players[float].attr[6]
#P7 player.attr[7]
attr[7]
#P7(float) players[float].attr[7]
#P8 player.attr[8]
attr[8]
#P8(float) players[float].attr[8]
#P9 player.attr[9]
attr[9]
#P9(float) players[float].attr[9]
#R(oldstring) string.random()
#2 player.shieldimg
shieldimg
#2(float) players[float].shieldimg
#s(oldstring) getstring(string)
#1 player.swordimg
swordimg
#1(float) players[float].swordimg
#S player.sword.script
#t(float) tokens[float]
#T(oldstring) string.trim()
#v(float) float
#W player.weapon.image
#W(float) weapons[float].image
#w player.weapon.name
#w(float) weapons[float].name
</pre>
Compatibility note:
When you use the command setcharprop then the first parameter
is handled differently: instead of changing 'player.chat' it
is changing 'chat', the chat text of the npc. So 'setcharprop #c,hello'
would be translated into
chat = "hello"
while 'setplayerprop #c,hello' is translated into
player.chat = "hello"
In the list above both possibilities are listed.

Creation/Dev/GScript

2005-12-02T21:00:30Z

Chad:

'''GScript''' is [[Graal]]'s scripting language.

Its syntax and some of its semantics might seem familiar to those who program in [[WikiPedia:C (Programming Language) | C]] or derived languages, although it lacks some of the expressivity of a real programming language and has special constructs that make programming [[Graal]] [[NPC]]s easier.

GScript started as a very limited language and has since kept up with improvements to the game engine and can now be used for pretty sophisticated scripts that greatly customise the gaming experience.

It is used, with minor differences, for [[Clientside]] tasks like [[GUI | GUI programming]], special effects with nifty 3d lighting and custom [[NPC weapon|NPC Weapons]] or "engines", and [[Serverside]] systems like player housing, complex baddies or pets.

[[Old GScript]] has been replaced by a new version (dubbed GScript2 during development) that is rather advanced, in some way object oriented, and thanks to influence from [[Java]] and [[Torque]]'s scripting language, less brain-damaged in some aspects. No offense intended.

GScript can be discussed in the [[GScript IRC channel]].

[[Script Functions: Client]]

[[Script Functions: NPC Server]]

[[Script Functions: Graal 3D]]

[[Graal v4 IRC|Graal IRC Scripting: Graal v4 IRC Scripting Reference]]

[[Troubleshooting Graal v4 IRC|Graal IRC Scripting: Troubleshooting Scripting Reference]]

[[Particle Engine|Graal v4 Particle Engine]]

[[GS1 To GS2|GS1 To GS2: Guide for fixing scripts to work with the new engine]]

== Introduction ==

=== Why scripts ===

Scripts bring life into objects and make it easy to
customize the game. Instead of just placing a stone
into your world, you can make it so that the stone
can be lifted or kicked. Instead of being limited to
some fixed player movement you can rescript it
to let the player jump, strafe and duck. To let the
player inspect and organize his/her items you can
create some dialogs and display those by script,
e.g. when the player presses a special key.

In Graal the scripting is done in 'Graal Script',
it's looking like Java/C++, but brings some
additional features for making things easier
for game creators, while on the other hand
running in a sandbox and limiting access to
game-related stuff only.

Graal Script is almost fully compatible to
the 'old' Graal script used in Graal v1.0 - 3.0,
and is partially compatible to Torque script.

=== NPCs and 'weapons' ===

There are generally two types of objects in Graal
which have scripts: The first type are the
non-player-characters (NPCs). The name 'NPC' is
actually used for all visible objects in the game:
monsters, stones, bushes, houses, ships, plants etc.
Scripts for npcs are most of the time containing
code for moving the npc or for reacting to
activities of the player, e.g. giving money to
the player when he grabs the npc.
The other type of script-holding objects are the
'weapons'. Those are items in the inventory of
the player, not necessary being weapons. Most of
the time they are actually just scripts which
control the movement of the player, display weapon
graphics, or display menus.

So there are objects in the game which have
their own script, and players which have a set
of scripts in their invisible backpack.

=== Server-side and client-side ===

Graal is an online game, and there are differences
to standard scripting in offline games.
In offline programs you have access to everything,
anytime. In online games everything is divided
into two parts: the server-side which controls
most things in the game, and the client-side which
displays the game to the player.
Since the client only displays things, it is not
possible to cheat by hacking the client. On client-side
you mainly have code for displaying special effects,
for displaying the GUI (windows, status bars, item menus),
playing sound effects and music. Also the player
movement is done on client-side.
On the server-side scripts are used to do the more
secure parts of the game engine,
and things that are the same for all players -
npcs are added, moved, npcs interact with players,
the stats of the players are calculated, the
communication between players is handled.

All scripts for npcs and weapons can contain
server-side code and client-side code. The server-side
code is executed directly on the server, the
client-side code is sent to the client when he/she
logins and executed separately for each player on
their own computer. Usually the two parts of the script
are divided by line that only contains "//#CLIENTSIDE",
like this:

<pre>// Server-side part which is setting the image
// of the npc when it is created
function onCreated() {
setimg("door.png");
}

//#CLIENTSIDE

// Here follows the client-side part,
// which plays a sound effect when the player
// touchs the npc
function onPlayerTouchsme() {
play("chest.wav");
}</pre>

=== Events ===

In general scripts are made for reacting to
events - when the npc is created then the script
initializes the attributes of the npc,
when the player says something then the npc is
moving to the player, when the player grabs the
npc then the npc is giving the player some money etc.
So the script is basicly a collection of actions
that are done when special events are happening.
Events can e.g. be the "created" event when the npc
is created, the "playertouchsme" event when the
player touchs the npc, or the "playerchats" event
when the player says something. To write code that reacts
to one of those event, you define an event
function like this:

<pre>function onEVENTNAME() {
// actions
}</pre>

When the event is happening, then Graal executes
that scripting function and all commands you
have added there.
Sometimes the event gives some parameters to the
event function, then change your function to:

<pre>function onEVENTNAME(parameter1, parameter2, ...) {
// actions
}</pre>

By accessing 'parameter1' etc. (you can name
them differently) you can react to the event more
exactly.

Instead of reacting to events, the npcs and
weapons can also invoke new events. That way
you can let other npcs doing things. You also
need that if you want to coninuously doing things -
use timeout events for that.

<pre>function onCreated() {
setTimer(1);
}

function onTimeout() {
// actions
setTimer(1);
}</pre>

In the onCreated event function the script is
setting the timer to 1 second. When that second is
over, then the "timeout" event is invoked on the
npc and the onTimeout event function is executed.
Because it is setting the timer to 1 second
again, the onTimeout event will occur again after
one second, and so on.

Compatibility note:
In older Graal scripts you will also find the
deprecated way of receiving events:

<pre>if (EVENTNAME) {
// actions
}</pre>

That is an if-command outside of any brackets. If
Graal sees that you use such an if-command, then
it will execute the whole script so that the actions
you have written inside the if-command will be
executed too.

== Basics ==

=== Accessing variables ===

Graal Script variables are 'variant', that means they are objects
that hold values of different types.
When you assign a value to the variable then it automatically
switches to the right type:

Numeric (floating point):
var = 1;
String (text):
var = "hello";
Object link:
var = player;
Array (list of objects):
var = {1,2,3};

You can check the current type with the
type()-function - obj.type() returns
0,1,2,3 for numeric, string, object or array.

=== Operators ===
<pre>
Addition a + b
Substraction a - b
Mulitplication a * b
Division a / b
Modulus a % b
Power a ^ b
String Concationation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b
Bool-And a && b
Bool-Or a || b
Bool-Not !a
Negative -a
Equal a == b
Not-Equal a != b
Less a b
Less-Equal a <= b, a == b, a => b
In-Range a in <b,c>, a in |b,c>, a in <b,c|, a in |b,c|
In-Array a in {b,c,...}, {a,b,...} in {c,d,...}
Bitwise-Or a | b
Bitwise-And a & b
Bitwise-Shift left a <> b
Bitwise-Invert ~a
Bitwise-Xor a xor b (operator ^ already used for power)
Array-Constructor {a,b,...}
Empty Array new [count], new[countdim1][countdim2]...
Array Member a[index]
Function call a(), a(b,c,...)
Object Attribute a.b, a.(b)
Post Increment a++
Post Decrement a--
Pre Increment ++a
Pre Decrement --a
Old String Function #a
Conditional a? b : c
Assignment a = b, a := b
Additive Assignment a += b
Substractive Assignment a -= b
Multiplicative Assignment a *= b
Division Assignment a /= b
Modulus Assignment a %= b
Power Assignment a ^= b
Bitwise-Or Assignment a |= b
Bitwise-And Assignment a &= b
Shift Left Assignment a <<= b
Shift Right Assignment a >>= b
String Append a @= b
</pre>

=== Standard object functions ===

For a complete list of functions and attributes of objects
see docu_graalscriptfunctions.txt. The base type of all
objects is "TGraalVar". You can also get the latest list by
calling the executale with "-listscriptfunctions" as
command-line parameter.
Here only some of the built-in functions:
<pre>
obj.type() - gets the type of the var (float 0, string 1, object 2, array 3)
obj.length() - string length
obj.trim() - removes spaces from the front and back of a string
obj.lower() - converts a string to lower case
obj.upper() - converts a string to upper case
obj.tokenize([delimiters])
obj.charat(pos)
obj.pos(substring)
obj.starts(string)
obj.ends(string)
obj.substring(index[,length])
obj.size() - array length
obj.subarray(index[,length])
obj.addarray(obj2)
obj.insertarray(index,obj2)
obj.index(obj2) - position of obj2 in the array
obj.clear()
obj.add(obj2)
obj.delete(index)
obj.remove(obj2)
obj.replace(index,obj2)
obj.insert(index,obj2)
</pre>

=== Standard functions ===
<pre>
format(format,parameters,...) - formats a "%s %d" string, inserts the parameters, and returns a string
int(a)
abs(a)
random(rangestart,rangeend)
sin(a)
cos(a)
arctan(a)
exp(a)
log(base,a)
min(a,b)
max(a,b)
getangle(delta x,delta y)
getdir(delta x,delta y) - returns 0 for up, 1 for left, 2 for down, 3 for right
vecx(direction)
vecy(direction)
</pre>

== Events ==

=== GUI controls ===
<pre>
onAdd() when added to the parent
onRemove() when removed from the parent
onWake() when activated
onSleep() when deactivated
onResize(w,h)
onMove(x,y)
onMouseEnter(modifier,x,y,clickcount)
onMouseLeave(modifier,x,y,clickcount)
onMouseDown(modifier,x,y,clickcount)
onMouseUp(modifier,x,y,clickcount)
onMouseDragged(modifier,x,y,clickcount)
onMouseMove(modifier,x,y,clickcount)
onRightMouseDown(modifier,x,y,clickcount)
onRightMouseUp(modifier,x,y,clickcount)
onRightMouseDragged(modifier,x,y,clickcount)
onMouseWheelUp(modifier,x,y,clickcount)
onMouseWheelDown(modifier,x,y,clickcount)
onKeyDown(keycode,string)
onKeyUp(keycode,string)
onKeyRepeat(keycode,string)
</pre>
==== GuiMLTextCtrl: ====
<pre>
onReflow(w,h) when the text has changed
onURL(url) when clicked on url
onSelectTag(tagid) when clicked on an image

Text-Tags:
The text of multi-line text controls can contain
a few HTML-tags and Torque-tags, you can use both
of those tag types to define colors and fonts
or to include images. Currently following tags
are available:

HTML:
<a href=url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<body bgcolor=colorname or #rrggbb> - sets the background color
 - line break
<center> text </center> - centers the contained text
 text 
- draws text with a special font, size and color; you only
need to define one of those 3 attributes
<ignorelinebreaks> </ignorelinebreaks> - go into normal HTML mode where
you need to insert to do a linebreak
<img src=filename id=integer> - an image is displayed, you
can also specify a tagid if you want to get onSelectTag-events
for this image
 text - sets the align of the
contained text
 - for
displaying a subpage, you can also specifiy an id for
onSelectTag-events; instead of you can also use <div> tags

Torque:
<a:url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<bitmap:filename> - an image is displayed
<color:rrggbb> - sets the color of the text (hexadecimal value)
<lmargin:pixels> - sets the left margin for the text
<lmargin%:percent> - sets the size of the left margin depending
on the width of the whole control
<linkcolor:rrggbb> - sets the color of links (the <a>-tag)
<linkcolorhl:rrggbb> - sets the highlighted color, when
the user moves the mouse over a link
<just:left/center/right> - sets the align of the following text
<rmargin:pixels> - sets the right margin for the text
<rmargin%:percent> - sets the size of the right margin depending
on the width of the whole control
<sbreak> - line break
<spush> - switches to a new style (like )
<spop> - switches back to the last saved style (like )
<tab:tab1,tab2,..> - sets the position of where tabulators should
be displayed if you have text like 'Apple \t Egg \t Chicken'
<tag:id> - inserts an invisible tag which can be used
for the scrollToTag(id) function (beside image-tags)

</pre>

==== GuiTextEditCtrl: ====
<pre>
onTabComplete()
onAction(text) when return key pressed
</pre>
==== GuiTextListCtrl: ====
<pre>
onSelect(id,text) when row selected
onDblClick(id) when double-click on row or return key pressed
onDeleteKey(id) when delete key pressed
onIconResized(w,h) when setIconSize() called
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiPopUpMenuCtrl: ====
<pre>
onSelect(id,text) when menu option choosen
onCancel() when menu is closed without action
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiMenuBar: ====
<pre>
onMenuSelect(menuid,menutext)
onMenuItemSelect(menuid,menutext,itemid,itemtext)
</pre>
==== GuiTreeViewCtrl: ====
<pre>
onSelect(id,rightmouse) when row selected
onUnselect(id) when row de-selected
onInspect(id) when clicked on the name of an item
onOpenMenu(0,index,text) when an item was right-clicked
onContextMenu("x y",id) when clicked with right-mouse key on row
</pre>

== Old script compatibility ==

=== Removed functionality ===
<pre>
- toinventory
- followplayer
- playersays()
- setbackpal
</pre>
=== Supported old scripting commands and their mapping to new script ===
<pre>
addstring oldstring, oldstring;
addstring(string,string);
addtiledef oldstring, oldstring, float;
addtiledef(string,string,float);
addtiledef2 oldstring, oldstring, float, float;
addtiledef2(string,string,float,float);
attachplayertoobj float, float;
attachplayertoobj(float,float);
blockagain;
blockagain();
blockagainlocal;
blockagainlocal();
callnpc float, oldstring;
callnpc(float,string);
callweapon float, oldstring;
callweapon(float,string);
canbecarried;
canbecarried();
canbepulled;
canbepulled();
canbepushed;
canbepushed();
cannotbecarried;
cannotbecarried();
cannotbepulled;
cannotbepulled();
cannotbepushed;
cannotbepushed();
canwarp;
canwarp();
canwarp2;
canwarp2();
carryobject oldstring;
carryobject(string);
changeimgcolors float, float, float, float, float;
changeimgcolors(float,float,float,float,float);
changeimgmode float, float;
changeimgmode(float,float);
changeimgpart float, float, float, float, float;
changeimgpart(float,float,float,float,float);
changeimgvis float, float;
changeimgvis(float,float);
changeimgzoom float, float;
changeimgzoom(float,float);
deletestring oldstring, float;
deletestring(string,float);
destroy;
destroy();
detachplayer;
detachplayer();
disabledefmovement;
disabledefmovement();
disablemap;
disablemap();
disablepause;
disablepause();
disableselectweapons;
disableselectweapons();
disableweapons;
disableweapons();
dontblock;
dontblock();
dontblocklocal;
dontblocklocal();
drawaslight;
drawaslight();
drawoverplayer;
drawoverplayer();
drawunderplayer;
drawunderplayer();
enabledefmovement;
enabledefmovement();
enablefeatures float;
enablefeatures(float);
enablemap;
enablemap();
enablepause;
enablepause();
enableselectweapons;
enableselectweapons();
enableweapons;
enableweapons();
explodebomb float;
explodebomb(float);
followplayer;
followplayer();
freezeplayer float;
freezeplayer(float);
freezeplayer2;
freezeplayer2();
hide;
hide();
hideimg float;
hideimg(float);
hideimgs float, float;
hideimgs(float,float);
hidelocal;
hidelocal();

hitcompu float, float, float, float;
hitcompu(float,float,float,float);
hitnpc float, float, float, float;
hitnpc(float,float,float,float);
hitobjects float, float, float;
hitobjects(float,float,float);
hideplayer float;
hideplayer(float);
hidesword float;
hidesword(float);
hitplayer float, float, float, float;
hitplayer(float,float,float,float);
hurt float;
hurt(float);
insertstring oldstring, float, oldstring;
insertstring(string,float,string);
join oldstring;
join(string);
lay oldstring;
lay(string);
lay2 oldstring, float, float;
lay2(string,float,float);
loadmap oldstring;
loadmap(string);
message oldstring;
message(string);
move float, float, float, float;
move(float,float,float,float);
noplayerkilling;
noplayerkilling();
openurl oldstring;
openurl(string);
openurl2 oldstring, float, float;
openurl2(string,float,float);
play oldstring;
play(string);
play2 oldstring, float, float, float;
play2(string,float,float,float);
playlooped oldstring;
playlooped(string);
putbomb float, float, float;
putbomb(float,float,float);
putcomp oldstring, float, float;
putcomp(string,float,float);
putexplosion float, float, float;
putexplosion(float,float,float);
putexplosion2 float, float, float, float;
putexplosion2(float,float,float,float);
puthorse oldstring, float, float;
puthorse(string,float,float);
putleaps float, float, float;
putleaps(float,float,float);
putnewcomp oldstring, float, float, oldstring, float;
putnewcomp(string,float,float,string,float);
putnpc oldstring, oldstring, float, float;
putnpc(string,string,float,float);
putnpc2 float, float, oldstring;
putnpc2(float,float,string);
reflectarrow float;
reflectarrow(float);
removearrow float;
removearrow(float);
removebomb float;
removebomb(float);
removecompus;
removecompus();
removeexplo float;
removeexplo(float);
removehorse float;
removehorse(float);
rmeoveitem float;
removeitem(float)
removestring oldstring, oldstring;
removestring(string,string);
removetiledefs oldstring;
removetiledefs(string);
replaceani oldstring, oldstring;
replaceani(string,string);
replacestring oldstring, float, oldstring;
replacestring(string,float,string);
resetfocus;
resetfocus();
savelog oldstring;
savelog(string);
savelog2 oldstring, oldstring;
savelog2(string,string);
say float;
say(float);
say2 oldstring;
say2(string);
sendrpgmessage oldstring;
sendrpgmessage(string);
sendpm oldstring;
sendpm(string);
sendtonc oldstring;
sendtonc(string);
sendtorc oldstring;
sendtorc(string);
serverwarp oldstring;
serverwarp(string);
set oldstring;
set(string);
setani oldstring, oldstring;
setani(string,string);
setarray float, float;
setarray(var,float);
setbeltcolor oldstring;
setbeltcolor(string);
setbow oldstring;
setbow(string);
setcharani oldstring, oldstring;
setcharani(string,string);
setchargender oldstring;
setchargender(string);
setcharprop oldstring, oldstring;
string = string;
setcoatcolor oldstring;
setcoatcolor(string);
setcoloreffect float, float, float, float;
setcoloreffect(float,float,float,float);
setcursor float;
setcursor(float);
setcurcor2 oldstring;
setcursor2(string);
seteffect float, float, float, float;
seteffect(float,float,float,float);
seteffectmode float;
seteffectmode(float);
setfocus float, float;
setfocus(float,float);
setgender oldstring;
setgender(string);
sethead oldstring;
sethead(string);
setlevel oldstring;
setlevel(string);
setlevel2 oldstring, float, float;
setlevel2(string,float,float);
setmap oldstring, oldstring, float, float;
setmap(string,string,float,float);
setminimap oldstring, oldstring, float, float;
setminimap(string,string,float,float);
setmusicvolume float, float;
setmusicvolume(float,float);
setimg oldstring;
setimg(string);
setimgpart oldstring, float, float, float, float;
setimgpart(string,float,float,float,float);
setletters oldstring;
setletters(string);
setplayerdir oldstring;
setplayerdir(string);
setplayerprop oldstring, oldstring;
string = string;
setpm oldstring;
setpm(string);
setshape float, float, float;
setshape(float,float,float);
setshape2 float, float, float;
setshape2(float,float,float);
setshield oldstring, float;
setshield(string,float);
setshoecolor oldstring;
setshoecolor(string);
setshootparams oldstring;
setshootparams(string);
setskincolor oldstring;
setskincolor(string);
setsleevecolor oldstring;
setsleevecolor(string);
setstring oldstring, oldstring;
setstring(string,string);
setsword oldstring, float;
setsword(string,float);
seturllevel oldstring;
seturllevel(string);
setz float, float, float, float, float, float, float, float;
setz(float,float,float,float,float,float,float,float);
setzoomeffect float;
setzoomeffect(float);
shoot float, float, float, float, float, float, oldstring, oldstring;
shoot(float,float,float,float,float,float,string,string);
shootarrow float;
shootarrow(float);
shootball;
shootball();
shootfireball float;
shootfireball(float);
shootfireblast float;
shootfireblast(float);
shootnuke float;
shootnuke(float);
show;
show();
showani float, float, float, float, oldstring;
showani(float,float,float,float,string);
showani2 float, float, float, float, float, oldstring;
showani2(float,float,float,float,float,string);
showcharacter;
showcharacter();
showfile oldstring;
showfile(string);
showimg float, oldstring, float, float;
showimg(float,string,float,float);
showimg2 float, oldstring, float, float, float;
showimg2(float,string,float,float,float);
showlocal;
showlocal();

showpoly float, float;
showpoly(float,array);
showpoly2 float, float;
showpoly2(float,array);
showstats float;
showstats(float);
showtext float, float, float, oldstring, oldstring, oldstring;
showtext(float,float,float,string,string,string);
showtext2 float, float, float, float, oldstring, oldstring, oldstring;
showtext2(float,float,float,float,string,string,string);
sleep float;
sleep(float);
spyfire float, float;
spyfire(float,float);
stopmidi;
stopmidi();
stopsound oldstring;
stopsound(string);
take oldstring;
take(string);
take2 float;
take2(float);
takehorse float;
takehorse(float);
takeplayercarry;
takeplayercarry();
takeplayerhorse;
takeplayerhorse();
throwcarry;
throwcarry();
timereverywhere;
timereverywhere();
timershow;
timershow();
toinventory oldstring;
toinventory(string);
tokenize oldstring;
tokens = string.tokenize();
tokenize2 oldstring, oldstring;
tokens = string.tokenize(" ," @ string);
toweapons oldstring;
toweapons(string);
triggeraction float, float, oldstring, oldstring;
triggeraction(float,float,string,string);
unfreezeplayer;
unfreezeplayer();
unset oldstring;
unset(string);
updateboard float, float, float, float;
updateboard(float,float,float,float);
updateterrain;
updateterrain();
wraptext float, oldstring, oldstring;
tokens = wraptext(float," ," @ string,string);
wraptext2 float, float, oldstring, oldstring;
tokens = wraptext2(float,float," ," @ string,string);
</pre>

=== Supported old string operations ===
<pre>
These old string operators can be used in string parameters
for the old commands, also you can use them directly as operators, e.g.
#c = "hello"
is actually doing
player.chat = "hello"

#a player.account
#a(float) players[float].account
#m player.ani
ani
#m(float) players[float].ani
#K(float) char(float)
#8 player.bodyimg
bodyimg
#8(float) players[float].bodyimg
#c player.chat
chat
#c(float) players[float].chat
#C0 player.colors[0]
colors[0]
#C0(float) players[float].colors[0]
#C1 player.colors[1]
colors[1]
#C1(float) players[float].colors[1]
#C2 player.colors[2]
colors[2]
#C2(float) players[float].colors[2]
#C3 player.colors[3]
colors[3]
#C3(float) players[float].colors[3]
#C4 player.colors[4]
colors[4]
#C4(float) players[float].colors[4]
#C5 player.colors[5]
colors[5]
#C5(float) players[float].colors[5]
#D downloadfile()
#E emoticonchar()
#e(float,float,oldstring)
string.substring(float,float)
#g player.guild
guild
#g(float) players[float].guild
#3 player.headimg
headimg
#3(float) players[float].headimg
#5 player.horseimg
horseimg
#5(float) players[float].horseimg
#k(float) keyname(float)
#L player.level
#I(oldstring,float)
getstring(string)[float]
#n player.nick
nick
#n(float) players[float].nick
#f image
#f(float) npcs[float].image
#F level
#p(float) params[float]
#P(float) player.attr[float]
attr[float]
#P(float_1,float_2)
players[float_2].attr[float_1]
#P1 player.attr[1]
attr[1]
#P1(float) players[float].attr[1]
#P2 player.attr[2]
attr[2]
#P2(float) players[float].attr[2]
#P3 player.attr[3]
attr[3]
#P3(float) players[float].attr[3]
#P4 player.attr[4]
attr[4]
#P4(float) players[float].attr[4]
#P5 player.attr[5]
attr[5]
#P5(float) players[float].attr[5]
#P6 player.attr[6]
attr[6]
#P6(float) players[float].attr[6]
#P7 player.attr[7]
attr[7]
#P7(float) players[float].attr[7]
#P8 player.attr[8]
attr[8]
#P8(float) players[float].attr[8]
#P9 player.attr[9]
attr[9]
#P9(float) players[float].attr[9]
#R(oldstring) string.random()
#2 player.shieldimg
shieldimg
#2(float) players[float].shieldimg
#s(oldstring) getstring(string)
#1 player.swordimg
swordimg
#1(float) players[float].swordimg
#S player.sword.script
#t(float) tokens[float]
#T(oldstring) string.trim()
#v(float) float
#W player.weapon.image
#W(float) weapons[float].image
#w player.weapon.name
#w(float) weapons[float].name
</pre>
Compatibility note:
When you use the command setcharprop then the first parameter
is handled differently: instead of changing 'player.chat' it
is changing 'chat', the chat text of the npc. So 'setcharprop #c,hello'
would be translated into
chat = "hello"
while 'setplayerprop #c,hello' is translated into
player.chat = "hello"
In the list above both possibilities are listed.

Creation/Dev/GScript

2005-12-02T20:59:43Z

Chad: I had it backwards!(NPC Weapons)

'''GScript''' is [[Graal]]'s scripting language.

Its syntax and some of its semantics might seem familiar to those who program in [[WikiPedia:C (Programming Language) | C]] or derived languages, although it lacks some of the expressivity of a real programming language and has special constructs that make programming [[Graal]] [[NPC]]s easier.

GScript started as a very limited language and has since kept up with improvements to the game engine and can now be used for pretty sophisticated scripts that greatly customise the gaming experience.

It is used, with minor differences, for [[Clientside]] tasks like [[GUI | GUI programming]], special effects with nifty 3d lighting and custom [[NPC Weapon|NPC Weapons]] or "engines", and [[Serverside]] systems like player housing, complex baddies or pets.

[[Old GScript]] has been replaced by a new version (dubbed GScript2 during development) that is rather advanced, in some way object oriented, and thanks to influence from [[Java]] and [[Torque]]'s scripting language, less brain-damaged in some aspects. No offense intended.

GScript can be discussed in the [[GScript IRC channel]].

[[Script Functions: Client]]

[[Script Functions: NPC Server]]

[[Script Functions: Graal 3D]]

[[Graal v4 IRC|Graal IRC Scripting: Graal v4 IRC Scripting Reference]]

[[Troubleshooting Graal v4 IRC|Graal IRC Scripting: Troubleshooting Scripting Reference]]

[[Particle Engine|Graal v4 Particle Engine]]

[[GS1 To GS2|GS1 To GS2: Guide for fixing scripts to work with the new engine]]

== Introduction ==

=== Why scripts ===

Scripts bring life into objects and make it easy to
customize the game. Instead of just placing a stone
into your world, you can make it so that the stone
can be lifted or kicked. Instead of being limited to
some fixed player movement you can rescript it
to let the player jump, strafe and duck. To let the
player inspect and organize his/her items you can
create some dialogs and display those by script,
e.g. when the player presses a special key.

In Graal the scripting is done in 'Graal Script',
it's looking like Java/C++, but brings some
additional features for making things easier
for game creators, while on the other hand
running in a sandbox and limiting access to
game-related stuff only.

Graal Script is almost fully compatible to
the 'old' Graal script used in Graal v1.0 - 3.0,
and is partially compatible to Torque script.

=== NPCs and 'weapons' ===

There are generally two types of objects in Graal
which have scripts: The first type are the
non-player-characters (NPCs). The name 'NPC' is
actually used for all visible objects in the game:
monsters, stones, bushes, houses, ships, plants etc.
Scripts for npcs are most of the time containing
code for moving the npc or for reacting to
activities of the player, e.g. giving money to
the player when he grabs the npc.
The other type of script-holding objects are the
'weapons'. Those are items in the inventory of
the player, not necessary being weapons. Most of
the time they are actually just scripts which
control the movement of the player, display weapon
graphics, or display menus.

So there are objects in the game which have
their own script, and players which have a set
of scripts in their invisible backpack.

=== Server-side and client-side ===

Graal is an online game, and there are differences
to standard scripting in offline games.
In offline programs you have access to everything,
anytime. In online games everything is divided
into two parts: the server-side which controls
most things in the game, and the client-side which
displays the game to the player.
Since the client only displays things, it is not
possible to cheat by hacking the client. On client-side
you mainly have code for displaying special effects,
for displaying the GUI (windows, status bars, item menus),
playing sound effects and music. Also the player
movement is done on client-side.
On the server-side scripts are used to do the more
secure parts of the game engine,
and things that are the same for all players -
npcs are added, moved, npcs interact with players,
the stats of the players are calculated, the
communication between players is handled.

All scripts for npcs and weapons can contain
server-side code and client-side code. The server-side
code is executed directly on the server, the
client-side code is sent to the client when he/she
logins and executed separately for each player on
their own computer. Usually the two parts of the script
are divided by line that only contains "//#CLIENTSIDE",
like this:

<pre>// Server-side part which is setting the image
// of the npc when it is created
function onCreated() {
setimg("door.png");
}

//#CLIENTSIDE

// Here follows the client-side part,
// which plays a sound effect when the player
// touchs the npc
function onPlayerTouchsme() {
play("chest.wav");
}</pre>

=== Events ===

In general scripts are made for reacting to
events - when the npc is created then the script
initializes the attributes of the npc,
when the player says something then the npc is
moving to the player, when the player grabs the
npc then the npc is giving the player some money etc.
So the script is basicly a collection of actions
that are done when special events are happening.
Events can e.g. be the "created" event when the npc
is created, the "playertouchsme" event when the
player touchs the npc, or the "playerchats" event
when the player says something. To write code that reacts
to one of those event, you define an event
function like this:

<pre>function onEVENTNAME() {
// actions
}</pre>

When the event is happening, then Graal executes
that scripting function and all commands you
have added there.
Sometimes the event gives some parameters to the
event function, then change your function to:

<pre>function onEVENTNAME(parameter1, parameter2, ...) {
// actions
}</pre>

By accessing 'parameter1' etc. (you can name
them differently) you can react to the event more
exactly.

Instead of reacting to events, the npcs and
weapons can also invoke new events. That way
you can let other npcs doing things. You also
need that if you want to coninuously doing things -
use timeout events for that.

<pre>function onCreated() {
setTimer(1);
}

function onTimeout() {
// actions
setTimer(1);
}</pre>

In the onCreated event function the script is
setting the timer to 1 second. When that second is
over, then the "timeout" event is invoked on the
npc and the onTimeout event function is executed.
Because it is setting the timer to 1 second
again, the onTimeout event will occur again after
one second, and so on.

Compatibility note:
In older Graal scripts you will also find the
deprecated way of receiving events:

<pre>if (EVENTNAME) {
// actions
}</pre>

That is an if-command outside of any brackets. If
Graal sees that you use such an if-command, then
it will execute the whole script so that the actions
you have written inside the if-command will be
executed too.

== Basics ==

=== Accessing variables ===

Graal Script variables are 'variant', that means they are objects
that hold values of different types.
When you assign a value to the variable then it automatically
switches to the right type:

Numeric (floating point):
var = 1;
String (text):
var = "hello";
Object link:
var = player;
Array (list of objects):
var = {1,2,3};

You can check the current type with the
type()-function - obj.type() returns
0,1,2,3 for numeric, string, object or array.

=== Operators ===
<pre>
Addition a + b
Substraction a - b
Mulitplication a * b
Division a / b
Modulus a % b
Power a ^ b
String Concationation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b
Bool-And a && b
Bool-Or a || b
Bool-Not !a
Negative -a
Equal a == b
Not-Equal a != b
Less a b
Less-Equal a <= b, a == b, a => b
In-Range a in <b,c>, a in |b,c>, a in <b,c|, a in |b,c|
In-Array a in {b,c,...}, {a,b,...} in {c,d,...}
Bitwise-Or a | b
Bitwise-And a & b
Bitwise-Shift left a <> b
Bitwise-Invert ~a
Bitwise-Xor a xor b (operator ^ already used for power)
Array-Constructor {a,b,...}
Empty Array new [count], new[countdim1][countdim2]...
Array Member a[index]
Function call a(), a(b,c,...)
Object Attribute a.b, a.(b)
Post Increment a++
Post Decrement a--
Pre Increment ++a
Pre Decrement --a
Old String Function #a
Conditional a? b : c
Assignment a = b, a := b
Additive Assignment a += b
Substractive Assignment a -= b
Multiplicative Assignment a *= b
Division Assignment a /= b
Modulus Assignment a %= b
Power Assignment a ^= b
Bitwise-Or Assignment a |= b
Bitwise-And Assignment a &= b
Shift Left Assignment a <<= b
Shift Right Assignment a >>= b
String Append a @= b
</pre>

=== Standard object functions ===

For a complete list of functions and attributes of objects
see docu_graalscriptfunctions.txt. The base type of all
objects is "TGraalVar". You can also get the latest list by
calling the executale with "-listscriptfunctions" as
command-line parameter.
Here only some of the built-in functions:
<pre>
obj.type() - gets the type of the var (float 0, string 1, object 2, array 3)
obj.length() - string length
obj.trim() - removes spaces from the front and back of a string
obj.lower() - converts a string to lower case
obj.upper() - converts a string to upper case
obj.tokenize([delimiters])
obj.charat(pos)
obj.pos(substring)
obj.starts(string)
obj.ends(string)
obj.substring(index[,length])
obj.size() - array length
obj.subarray(index[,length])
obj.addarray(obj2)
obj.insertarray(index,obj2)
obj.index(obj2) - position of obj2 in the array
obj.clear()
obj.add(obj2)
obj.delete(index)
obj.remove(obj2)
obj.replace(index,obj2)
obj.insert(index,obj2)
</pre>

=== Standard functions ===
<pre>
format(format,parameters,...) - formats a "%s %d" string, inserts the parameters, and returns a string
int(a)
abs(a)
random(rangestart,rangeend)
sin(a)
cos(a)
arctan(a)
exp(a)
log(base,a)
min(a,b)
max(a,b)
getangle(delta x,delta y)
getdir(delta x,delta y) - returns 0 for up, 1 for left, 2 for down, 3 for right
vecx(direction)
vecy(direction)
</pre>

== Events ==

=== GUI controls ===
<pre>
onAdd() when added to the parent
onRemove() when removed from the parent
onWake() when activated
onSleep() when deactivated
onResize(w,h)
onMove(x,y)
onMouseEnter(modifier,x,y,clickcount)
onMouseLeave(modifier,x,y,clickcount)
onMouseDown(modifier,x,y,clickcount)
onMouseUp(modifier,x,y,clickcount)
onMouseDragged(modifier,x,y,clickcount)
onMouseMove(modifier,x,y,clickcount)
onRightMouseDown(modifier,x,y,clickcount)
onRightMouseUp(modifier,x,y,clickcount)
onRightMouseDragged(modifier,x,y,clickcount)
onMouseWheelUp(modifier,x,y,clickcount)
onMouseWheelDown(modifier,x,y,clickcount)
onKeyDown(keycode,string)
onKeyUp(keycode,string)
onKeyRepeat(keycode,string)
</pre>
==== GuiMLTextCtrl: ====
<pre>
onReflow(w,h) when the text has changed
onURL(url) when clicked on url
onSelectTag(tagid) when clicked on an image

Text-Tags:
The text of multi-line text controls can contain
a few HTML-tags and Torque-tags, you can use both
of those tag types to define colors and fonts
or to include images. Currently following tags
are available:

HTML:
<a href=url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<body bgcolor=colorname or #rrggbb> - sets the background color
 - line break
<center> text </center> - centers the contained text
 text 
- draws text with a special font, size and color; you only
need to define one of those 3 attributes
<ignorelinebreaks> </ignorelinebreaks> - go into normal HTML mode where
you need to insert to do a linebreak
<img src=filename id=integer> - an image is displayed, you
can also specify a tagid if you want to get onSelectTag-events
for this image
 text - sets the align of the
contained text
 - for
displaying a subpage, you can also specifiy an id for
onSelectTag-events; instead of you can also use <div> tags

Torque:
<a:url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<bitmap:filename> - an image is displayed
<color:rrggbb> - sets the color of the text (hexadecimal value)
<lmargin:pixels> - sets the left margin for the text
<lmargin%:percent> - sets the size of the left margin depending
on the width of the whole control
<linkcolor:rrggbb> - sets the color of links (the <a>-tag)
<linkcolorhl:rrggbb> - sets the highlighted color, when
the user moves the mouse over a link
<just:left/center/right> - sets the align of the following text
<rmargin:pixels> - sets the right margin for the text
<rmargin%:percent> - sets the size of the right margin depending
on the width of the whole control
<sbreak> - line break
<spush> - switches to a new style (like )
<spop> - switches back to the last saved style (like )
<tab:tab1,tab2,..> - sets the position of where tabulators should
be displayed if you have text like 'Apple \t Egg \t Chicken'
<tag:id> - inserts an invisible tag which can be used
for the scrollToTag(id) function (beside image-tags)

</pre>

==== GuiTextEditCtrl: ====
<pre>
onTabComplete()
onAction(text) when return key pressed
</pre>
==== GuiTextListCtrl: ====
<pre>
onSelect(id,text) when row selected
onDblClick(id) when double-click on row or return key pressed
onDeleteKey(id) when delete key pressed
onIconResized(w,h) when setIconSize() called
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiPopUpMenuCtrl: ====
<pre>
onSelect(id,text) when menu option choosen
onCancel() when menu is closed without action
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiMenuBar: ====
<pre>
onMenuSelect(menuid,menutext)
onMenuItemSelect(menuid,menutext,itemid,itemtext)
</pre>
==== GuiTreeViewCtrl: ====
<pre>
onSelect(id,rightmouse) when row selected
onUnselect(id) when row de-selected
onInspect(id) when clicked on the name of an item
onOpenMenu(0,index,text) when an item was right-clicked
onContextMenu("x y",id) when clicked with right-mouse key on row
</pre>

== Old script compatibility ==

=== Removed functionality ===
<pre>
- toinventory
- followplayer
- playersays()
- setbackpal
</pre>
=== Supported old scripting commands and their mapping to new script ===
<pre>
addstring oldstring, oldstring;
addstring(string,string);
addtiledef oldstring, oldstring, float;
addtiledef(string,string,float);
addtiledef2 oldstring, oldstring, float, float;
addtiledef2(string,string,float,float);
attachplayertoobj float, float;
attachplayertoobj(float,float);
blockagain;
blockagain();
blockagainlocal;
blockagainlocal();
callnpc float, oldstring;
callnpc(float,string);
callweapon float, oldstring;
callweapon(float,string);
canbecarried;
canbecarried();
canbepulled;
canbepulled();
canbepushed;
canbepushed();
cannotbecarried;
cannotbecarried();
cannotbepulled;
cannotbepulled();
cannotbepushed;
cannotbepushed();
canwarp;
canwarp();
canwarp2;
canwarp2();
carryobject oldstring;
carryobject(string);
changeimgcolors float, float, float, float, float;
changeimgcolors(float,float,float,float,float);
changeimgmode float, float;
changeimgmode(float,float);
changeimgpart float, float, float, float, float;
changeimgpart(float,float,float,float,float);
changeimgvis float, float;
changeimgvis(float,float);
changeimgzoom float, float;
changeimgzoom(float,float);
deletestring oldstring, float;
deletestring(string,float);
destroy;
destroy();
detachplayer;
detachplayer();
disabledefmovement;
disabledefmovement();
disablemap;
disablemap();
disablepause;
disablepause();
disableselectweapons;
disableselectweapons();
disableweapons;
disableweapons();
dontblock;
dontblock();
dontblocklocal;
dontblocklocal();
drawaslight;
drawaslight();
drawoverplayer;
drawoverplayer();
drawunderplayer;
drawunderplayer();
enabledefmovement;
enabledefmovement();
enablefeatures float;
enablefeatures(float);
enablemap;
enablemap();
enablepause;
enablepause();
enableselectweapons;
enableselectweapons();
enableweapons;
enableweapons();
explodebomb float;
explodebomb(float);
followplayer;
followplayer();
freezeplayer float;
freezeplayer(float);
freezeplayer2;
freezeplayer2();
hide;
hide();
hideimg float;
hideimg(float);
hideimgs float, float;
hideimgs(float,float);
hidelocal;
hidelocal();

hitcompu float, float, float, float;
hitcompu(float,float,float,float);
hitnpc float, float, float, float;
hitnpc(float,float,float,float);
hitobjects float, float, float;
hitobjects(float,float,float);
hideplayer float;
hideplayer(float);
hidesword float;
hidesword(float);
hitplayer float, float, float, float;
hitplayer(float,float,float,float);
hurt float;
hurt(float);
insertstring oldstring, float, oldstring;
insertstring(string,float,string);
join oldstring;
join(string);
lay oldstring;
lay(string);
lay2 oldstring, float, float;
lay2(string,float,float);
loadmap oldstring;
loadmap(string);
message oldstring;
message(string);
move float, float, float, float;
move(float,float,float,float);
noplayerkilling;
noplayerkilling();
openurl oldstring;
openurl(string);
openurl2 oldstring, float, float;
openurl2(string,float,float);
play oldstring;
play(string);
play2 oldstring, float, float, float;
play2(string,float,float,float);
playlooped oldstring;
playlooped(string);
putbomb float, float, float;
putbomb(float,float,float);
putcomp oldstring, float, float;
putcomp(string,float,float);
putexplosion float, float, float;
putexplosion(float,float,float);
putexplosion2 float, float, float, float;
putexplosion2(float,float,float,float);
puthorse oldstring, float, float;
puthorse(string,float,float);
putleaps float, float, float;
putleaps(float,float,float);
putnewcomp oldstring, float, float, oldstring, float;
putnewcomp(string,float,float,string,float);
putnpc oldstring, oldstring, float, float;
putnpc(string,string,float,float);
putnpc2 float, float, oldstring;
putnpc2(float,float,string);
reflectarrow float;
reflectarrow(float);
removearrow float;
removearrow(float);
removebomb float;
removebomb(float);
removecompus;
removecompus();
removeexplo float;
removeexplo(float);
removehorse float;
removehorse(float);
rmeoveitem float;
removeitem(float)
removestring oldstring, oldstring;
removestring(string,string);
removetiledefs oldstring;
removetiledefs(string);
replaceani oldstring, oldstring;
replaceani(string,string);
replacestring oldstring, float, oldstring;
replacestring(string,float,string);
resetfocus;
resetfocus();
savelog oldstring;
savelog(string);
savelog2 oldstring, oldstring;
savelog2(string,string);
say float;
say(float);
say2 oldstring;
say2(string);
sendrpgmessage oldstring;
sendrpgmessage(string);
sendpm oldstring;
sendpm(string);
sendtonc oldstring;
sendtonc(string);
sendtorc oldstring;
sendtorc(string);
serverwarp oldstring;
serverwarp(string);
set oldstring;
set(string);
setani oldstring, oldstring;
setani(string,string);
setarray float, float;
setarray(var,float);
setbeltcolor oldstring;
setbeltcolor(string);
setbow oldstring;
setbow(string);
setcharani oldstring, oldstring;
setcharani(string,string);
setchargender oldstring;
setchargender(string);
setcharprop oldstring, oldstring;
string = string;
setcoatcolor oldstring;
setcoatcolor(string);
setcoloreffect float, float, float, float;
setcoloreffect(float,float,float,float);
setcursor float;
setcursor(float);
setcurcor2 oldstring;
setcursor2(string);
seteffect float, float, float, float;
seteffect(float,float,float,float);
seteffectmode float;
seteffectmode(float);
setfocus float, float;
setfocus(float,float);
setgender oldstring;
setgender(string);
sethead oldstring;
sethead(string);
setlevel oldstring;
setlevel(string);
setlevel2 oldstring, float, float;
setlevel2(string,float,float);
setmap oldstring, oldstring, float, float;
setmap(string,string,float,float);
setminimap oldstring, oldstring, float, float;
setminimap(string,string,float,float);
setmusicvolume float, float;
setmusicvolume(float,float);
setimg oldstring;
setimg(string);
setimgpart oldstring, float, float, float, float;
setimgpart(string,float,float,float,float);
setletters oldstring;
setletters(string);
setplayerdir oldstring;
setplayerdir(string);
setplayerprop oldstring, oldstring;
string = string;
setpm oldstring;
setpm(string);
setshape float, float, float;
setshape(float,float,float);
setshape2 float, float, float;
setshape2(float,float,float);
setshield oldstring, float;
setshield(string,float);
setshoecolor oldstring;
setshoecolor(string);
setshootparams oldstring;
setshootparams(string);
setskincolor oldstring;
setskincolor(string);
setsleevecolor oldstring;
setsleevecolor(string);
setstring oldstring, oldstring;
setstring(string,string);
setsword oldstring, float;
setsword(string,float);
seturllevel oldstring;
seturllevel(string);
setz float, float, float, float, float, float, float, float;
setz(float,float,float,float,float,float,float,float);
setzoomeffect float;
setzoomeffect(float);
shoot float, float, float, float, float, float, oldstring, oldstring;
shoot(float,float,float,float,float,float,string,string);
shootarrow float;
shootarrow(float);
shootball;
shootball();
shootfireball float;
shootfireball(float);
shootfireblast float;
shootfireblast(float);
shootnuke float;
shootnuke(float);
show;
show();
showani float, float, float, float, oldstring;
showani(float,float,float,float,string);
showani2 float, float, float, float, float, oldstring;
showani2(float,float,float,float,float,string);
showcharacter;
showcharacter();
showfile oldstring;
showfile(string);
showimg float, oldstring, float, float;
showimg(float,string,float,float);
showimg2 float, oldstring, float, float, float;
showimg2(float,string,float,float,float);
showlocal;
showlocal();

showpoly float, float;
showpoly(float,array);
showpoly2 float, float;
showpoly2(float,array);
showstats float;
showstats(float);
showtext float, float, float, oldstring, oldstring, oldstring;
showtext(float,float,float,string,string,string);
showtext2 float, float, float, float, oldstring, oldstring, oldstring;
showtext2(float,float,float,float,string,string,string);
sleep float;
sleep(float);
spyfire float, float;
spyfire(float,float);
stopmidi;
stopmidi();
stopsound oldstring;
stopsound(string);
take oldstring;
take(string);
take2 float;
take2(float);
takehorse float;
takehorse(float);
takeplayercarry;
takeplayercarry();
takeplayerhorse;
takeplayerhorse();
throwcarry;
throwcarry();
timereverywhere;
timereverywhere();
timershow;
timershow();
toinventory oldstring;
toinventory(string);
tokenize oldstring;
tokens = string.tokenize();
tokenize2 oldstring, oldstring;
tokens = string.tokenize(" ," @ string);
toweapons oldstring;
toweapons(string);
triggeraction float, float, oldstring, oldstring;
triggeraction(float,float,string,string);
unfreezeplayer;
unfreezeplayer();
unset oldstring;
unset(string);
updateboard float, float, float, float;
updateboard(float,float,float,float);
updateterrain;
updateterrain();
wraptext float, oldstring, oldstring;
tokens = wraptext(float," ," @ string,string);
wraptext2 float, float, oldstring, oldstring;
tokens = wraptext2(float,float," ," @ string,string);
</pre>

=== Supported old string operations ===
<pre>
These old string operators can be used in string parameters
for the old commands, also you can use them directly as operators, e.g.
#c = "hello"
is actually doing
player.chat = "hello"

#a player.account
#a(float) players[float].account
#m player.ani
ani
#m(float) players[float].ani
#K(float) char(float)
#8 player.bodyimg
bodyimg
#8(float) players[float].bodyimg
#c player.chat
chat
#c(float) players[float].chat
#C0 player.colors[0]
colors[0]
#C0(float) players[float].colors[0]
#C1 player.colors[1]
colors[1]
#C1(float) players[float].colors[1]
#C2 player.colors[2]
colors[2]
#C2(float) players[float].colors[2]
#C3 player.colors[3]
colors[3]
#C3(float) players[float].colors[3]
#C4 player.colors[4]
colors[4]
#C4(float) players[float].colors[4]
#C5 player.colors[5]
colors[5]
#C5(float) players[float].colors[5]
#D downloadfile()
#E emoticonchar()
#e(float,float,oldstring)
string.substring(float,float)
#g player.guild
guild
#g(float) players[float].guild
#3 player.headimg
headimg
#3(float) players[float].headimg
#5 player.horseimg
horseimg
#5(float) players[float].horseimg
#k(float) keyname(float)
#L player.level
#I(oldstring,float)
getstring(string)[float]
#n player.nick
nick
#n(float) players[float].nick
#f image
#f(float) npcs[float].image
#F level
#p(float) params[float]
#P(float) player.attr[float]
attr[float]
#P(float_1,float_2)
players[float_2].attr[float_1]
#P1 player.attr[1]
attr[1]
#P1(float) players[float].attr[1]
#P2 player.attr[2]
attr[2]
#P2(float) players[float].attr[2]
#P3 player.attr[3]
attr[3]
#P3(float) players[float].attr[3]
#P4 player.attr[4]
attr[4]
#P4(float) players[float].attr[4]
#P5 player.attr[5]
attr[5]
#P5(float) players[float].attr[5]
#P6 player.attr[6]
attr[6]
#P6(float) players[float].attr[6]
#P7 player.attr[7]
attr[7]
#P7(float) players[float].attr[7]
#P8 player.attr[8]
attr[8]
#P8(float) players[float].attr[8]
#P9 player.attr[9]
attr[9]
#P9(float) players[float].attr[9]
#R(oldstring) string.random()
#2 player.shieldimg
shieldimg
#2(float) players[float].shieldimg
#s(oldstring) getstring(string)
#1 player.swordimg
swordimg
#1(float) players[float].swordimg
#S player.sword.script
#t(float) tokens[float]
#T(oldstring) string.trim()
#v(float) float
#W player.weapon.image
#W(float) weapons[float].image
#w player.weapon.name
#w(float) weapons[float].name
</pre>
Compatibility note:
When you use the command setcharprop then the first parameter
is handled differently: instead of changing 'player.chat' it
is changing 'chat', the chat text of the npc. So 'setcharprop #c,hello'
would be translated into
chat = "hello"
while 'setplayerprop #c,hello' is translated into
player.chat = "hello"
In the list above both possibilities are listed.

Creation/Dev/GScript

2005-12-02T20:58:52Z

Chad:

'''GScript''' is [[Graal]]'s scripting language.

Its syntax and some of its semantics might seem familiar to those who program in [[WikiPedia:C (Programming Language) | C]] or derived languages, although it lacks some of the expressivity of a real programming language and has special constructs that make programming [[Graal]] [[NPC]]s easier.

GScript started as a very limited language and has since kept up with improvements to the game engine and can now be used for pretty sophisticated scripts that greatly customise the gaming experience.

It is used, with minor differences, for [[Clientside]] tasks like [[GUI | GUI programming]], special effects with nifty 3d lighting and custom [[NPC Weapons|NPC Weapon]] or "engines", and [[Serverside]] systems like player housing, complex baddies or pets.

[[Old GScript]] has been replaced by a new version (dubbed GScript2 during development) that is rather advanced, in some way object oriented, and thanks to influence from [[Java]] and [[Torque]]'s scripting language, less brain-damaged in some aspects. No offense intended.

GScript can be discussed in the [[GScript IRC channel]].

[[Script Functions: Client]]

[[Script Functions: NPC Server]]

[[Script Functions: Graal 3D]]

[[Graal v4 IRC|Graal IRC Scripting: Graal v4 IRC Scripting Reference]]

[[Troubleshooting Graal v4 IRC|Graal IRC Scripting: Troubleshooting Scripting Reference]]

[[Particle Engine|Graal v4 Particle Engine]]

[[GS1 To GS2|GS1 To GS2: Guide for fixing scripts to work with the new engine]]

== Introduction ==

=== Why scripts ===

Scripts bring life into objects and make it easy to
customize the game. Instead of just placing a stone
into your world, you can make it so that the stone
can be lifted or kicked. Instead of being limited to
some fixed player movement you can rescript it
to let the player jump, strafe and duck. To let the
player inspect and organize his/her items you can
create some dialogs and display those by script,
e.g. when the player presses a special key.

In Graal the scripting is done in 'Graal Script',
it's looking like Java/C++, but brings some
additional features for making things easier
for game creators, while on the other hand
running in a sandbox and limiting access to
game-related stuff only.

Graal Script is almost fully compatible to
the 'old' Graal script used in Graal v1.0 - 3.0,
and is partially compatible to Torque script.

=== NPCs and 'weapons' ===

There are generally two types of objects in Graal
which have scripts: The first type are the
non-player-characters (NPCs). The name 'NPC' is
actually used for all visible objects in the game:
monsters, stones, bushes, houses, ships, plants etc.
Scripts for npcs are most of the time containing
code for moving the npc or for reacting to
activities of the player, e.g. giving money to
the player when he grabs the npc.
The other type of script-holding objects are the
'weapons'. Those are items in the inventory of
the player, not necessary being weapons. Most of
the time they are actually just scripts which
control the movement of the player, display weapon
graphics, or display menus.

So there are objects in the game which have
their own script, and players which have a set
of scripts in their invisible backpack.

=== Server-side and client-side ===

Graal is an online game, and there are differences
to standard scripting in offline games.
In offline programs you have access to everything,
anytime. In online games everything is divided
into two parts: the server-side which controls
most things in the game, and the client-side which
displays the game to the player.
Since the client only displays things, it is not
possible to cheat by hacking the client. On client-side
you mainly have code for displaying special effects,
for displaying the GUI (windows, status bars, item menus),
playing sound effects and music. Also the player
movement is done on client-side.
On the server-side scripts are used to do the more
secure parts of the game engine,
and things that are the same for all players -
npcs are added, moved, npcs interact with players,
the stats of the players are calculated, the
communication between players is handled.

All scripts for npcs and weapons can contain
server-side code and client-side code. The server-side
code is executed directly on the server, the
client-side code is sent to the client when he/she
logins and executed separately for each player on
their own computer. Usually the two parts of the script
are divided by line that only contains "//#CLIENTSIDE",
like this:

<pre>// Server-side part which is setting the image
// of the npc when it is created
function onCreated() {
setimg("door.png");
}

//#CLIENTSIDE

// Here follows the client-side part,
// which plays a sound effect when the player
// touchs the npc
function onPlayerTouchsme() {
play("chest.wav");
}</pre>

=== Events ===

In general scripts are made for reacting to
events - when the npc is created then the script
initializes the attributes of the npc,
when the player says something then the npc is
moving to the player, when the player grabs the
npc then the npc is giving the player some money etc.
So the script is basicly a collection of actions
that are done when special events are happening.
Events can e.g. be the "created" event when the npc
is created, the "playertouchsme" event when the
player touchs the npc, or the "playerchats" event
when the player says something. To write code that reacts
to one of those event, you define an event
function like this:

<pre>function onEVENTNAME() {
// actions
}</pre>

When the event is happening, then Graal executes
that scripting function and all commands you
have added there.
Sometimes the event gives some parameters to the
event function, then change your function to:

<pre>function onEVENTNAME(parameter1, parameter2, ...) {
// actions
}</pre>

By accessing 'parameter1' etc. (you can name
them differently) you can react to the event more
exactly.

Instead of reacting to events, the npcs and
weapons can also invoke new events. That way
you can let other npcs doing things. You also
need that if you want to coninuously doing things -
use timeout events for that.

<pre>function onCreated() {
setTimer(1);
}

function onTimeout() {
// actions
setTimer(1);
}</pre>

In the onCreated event function the script is
setting the timer to 1 second. When that second is
over, then the "timeout" event is invoked on the
npc and the onTimeout event function is executed.
Because it is setting the timer to 1 second
again, the onTimeout event will occur again after
one second, and so on.

Compatibility note:
In older Graal scripts you will also find the
deprecated way of receiving events:

<pre>if (EVENTNAME) {
// actions
}</pre>

That is an if-command outside of any brackets. If
Graal sees that you use such an if-command, then
it will execute the whole script so that the actions
you have written inside the if-command will be
executed too.

== Basics ==

=== Accessing variables ===

Graal Script variables are 'variant', that means they are objects
that hold values of different types.
When you assign a value to the variable then it automatically
switches to the right type:

Numeric (floating point):
var = 1;
String (text):
var = "hello";
Object link:
var = player;
Array (list of objects):
var = {1,2,3};

You can check the current type with the
type()-function - obj.type() returns
0,1,2,3 for numeric, string, object or array.

=== Operators ===
<pre>
Addition a + b
Substraction a - b
Mulitplication a * b
Division a / b
Modulus a % b
Power a ^ b
String Concationation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b
Bool-And a && b
Bool-Or a || b
Bool-Not !a
Negative -a
Equal a == b
Not-Equal a != b
Less a b
Less-Equal a <= b, a == b, a => b
In-Range a in <b,c>, a in |b,c>, a in <b,c|, a in |b,c|
In-Array a in {b,c,...}, {a,b,...} in {c,d,...}
Bitwise-Or a | b
Bitwise-And a & b
Bitwise-Shift left a <> b
Bitwise-Invert ~a
Bitwise-Xor a xor b (operator ^ already used for power)
Array-Constructor {a,b,...}
Empty Array new [count], new[countdim1][countdim2]...
Array Member a[index]
Function call a(), a(b,c,...)
Object Attribute a.b, a.(b)
Post Increment a++
Post Decrement a--
Pre Increment ++a
Pre Decrement --a
Old String Function #a
Conditional a? b : c
Assignment a = b, a := b
Additive Assignment a += b
Substractive Assignment a -= b
Multiplicative Assignment a *= b
Division Assignment a /= b
Modulus Assignment a %= b
Power Assignment a ^= b
Bitwise-Or Assignment a |= b
Bitwise-And Assignment a &= b
Shift Left Assignment a <<= b
Shift Right Assignment a >>= b
String Append a @= b
</pre>

=== Standard object functions ===

For a complete list of functions and attributes of objects
see docu_graalscriptfunctions.txt. The base type of all
objects is "TGraalVar". You can also get the latest list by
calling the executale with "-listscriptfunctions" as
command-line parameter.
Here only some of the built-in functions:
<pre>
obj.type() - gets the type of the var (float 0, string 1, object 2, array 3)
obj.length() - string length
obj.trim() - removes spaces from the front and back of a string
obj.lower() - converts a string to lower case
obj.upper() - converts a string to upper case
obj.tokenize([delimiters])
obj.charat(pos)
obj.pos(substring)
obj.starts(string)
obj.ends(string)
obj.substring(index[,length])
obj.size() - array length
obj.subarray(index[,length])
obj.addarray(obj2)
obj.insertarray(index,obj2)
obj.index(obj2) - position of obj2 in the array
obj.clear()
obj.add(obj2)
obj.delete(index)
obj.remove(obj2)
obj.replace(index,obj2)
obj.insert(index,obj2)
</pre>

=== Standard functions ===
<pre>
format(format,parameters,...) - formats a "%s %d" string, inserts the parameters, and returns a string
int(a)
abs(a)
random(rangestart,rangeend)
sin(a)
cos(a)
arctan(a)
exp(a)
log(base,a)
min(a,b)
max(a,b)
getangle(delta x,delta y)
getdir(delta x,delta y) - returns 0 for up, 1 for left, 2 for down, 3 for right
vecx(direction)
vecy(direction)
</pre>

== Events ==

=== GUI controls ===
<pre>
onAdd() when added to the parent
onRemove() when removed from the parent
onWake() when activated
onSleep() when deactivated
onResize(w,h)
onMove(x,y)
onMouseEnter(modifier,x,y,clickcount)
onMouseLeave(modifier,x,y,clickcount)
onMouseDown(modifier,x,y,clickcount)
onMouseUp(modifier,x,y,clickcount)
onMouseDragged(modifier,x,y,clickcount)
onMouseMove(modifier,x,y,clickcount)
onRightMouseDown(modifier,x,y,clickcount)
onRightMouseUp(modifier,x,y,clickcount)
onRightMouseDragged(modifier,x,y,clickcount)
onMouseWheelUp(modifier,x,y,clickcount)
onMouseWheelDown(modifier,x,y,clickcount)
onKeyDown(keycode,string)
onKeyUp(keycode,string)
onKeyRepeat(keycode,string)
</pre>
==== GuiMLTextCtrl: ====
<pre>
onReflow(w,h) when the text has changed
onURL(url) when clicked on url
onSelectTag(tagid) when clicked on an image

Text-Tags:
The text of multi-line text controls can contain
a few HTML-tags and Torque-tags, you can use both
of those tag types to define colors and fonts
or to include images. Currently following tags
are available:

HTML:
<a href=url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<body bgcolor=colorname or #rrggbb> - sets the background color
 - line break
<center> text </center> - centers the contained text
 text 
- draws text with a special font, size and color; you only
need to define one of those 3 attributes
<ignorelinebreaks> </ignorelinebreaks> - go into normal HTML mode where
you need to insert to do a linebreak
<img src=filename id=integer> - an image is displayed, you
can also specify a tagid if you want to get onSelectTag-events
for this image
 text - sets the align of the
contained text
 - for
displaying a subpage, you can also specifiy an id for
onSelectTag-events; instead of you can also use <div> tags

Torque:
<a:url> text </a> - when the user clicks on 'text' then
a web browser is opened for the specified url
<bitmap:filename> - an image is displayed
<color:rrggbb> - sets the color of the text (hexadecimal value)
<lmargin:pixels> - sets the left margin for the text
<lmargin%:percent> - sets the size of the left margin depending
on the width of the whole control
<linkcolor:rrggbb> - sets the color of links (the <a>-tag)
<linkcolorhl:rrggbb> - sets the highlighted color, when
the user moves the mouse over a link
<just:left/center/right> - sets the align of the following text
<rmargin:pixels> - sets the right margin for the text
<rmargin%:percent> - sets the size of the right margin depending
on the width of the whole control
<sbreak> - line break
<spush> - switches to a new style (like )
<spop> - switches back to the last saved style (like )
<tab:tab1,tab2,..> - sets the position of where tabulators should
be displayed if you have text like 'Apple \t Egg \t Chicken'
<tag:id> - inserts an invisible tag which can be used
for the scrollToTag(id) function (beside image-tags)

</pre>

==== GuiTextEditCtrl: ====
<pre>
onTabComplete()
onAction(text) when return key pressed
</pre>
==== GuiTextListCtrl: ====
<pre>
onSelect(id,text) when row selected
onDblClick(id) when double-click on row or return key pressed
onDeleteKey(id) when delete key pressed
onIconResized(w,h) when setIconSize() called
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiPopUpMenuCtrl: ====
<pre>
onSelect(id,text) when menu option choosen
onCancel() when menu is closed without action
onOpenMenu(0,index,text) when an item was right-clicked
</pre>
==== GuiMenuBar: ====
<pre>
onMenuSelect(menuid,menutext)
onMenuItemSelect(menuid,menutext,itemid,itemtext)
</pre>
==== GuiTreeViewCtrl: ====
<pre>
onSelect(id,rightmouse) when row selected
onUnselect(id) when row de-selected
onInspect(id) when clicked on the name of an item
onOpenMenu(0,index,text) when an item was right-clicked
onContextMenu("x y",id) when clicked with right-mouse key on row
</pre>

== Old script compatibility ==

=== Removed functionality ===
<pre>
- toinventory
- followplayer
- playersays()
- setbackpal
</pre>
=== Supported old scripting commands and their mapping to new script ===
<pre>
addstring oldstring, oldstring;
addstring(string,string);
addtiledef oldstring, oldstring, float;
addtiledef(string,string,float);
addtiledef2 oldstring, oldstring, float, float;
addtiledef2(string,string,float,float);
attachplayertoobj float, float;
attachplayertoobj(float,float);
blockagain;
blockagain();
blockagainlocal;
blockagainlocal();
callnpc float, oldstring;
callnpc(float,string);
callweapon float, oldstring;
callweapon(float,string);
canbecarried;
canbecarried();
canbepulled;
canbepulled();
canbepushed;
canbepushed();
cannotbecarried;
cannotbecarried();
cannotbepulled;
cannotbepulled();
cannotbepushed;
cannotbepushed();
canwarp;
canwarp();
canwarp2;
canwarp2();
carryobject oldstring;
carryobject(string);
changeimgcolors float, float, float, float, float;
changeimgcolors(float,float,float,float,float);
changeimgmode float, float;
changeimgmode(float,float);
changeimgpart float, float, float, float, float;
changeimgpart(float,float,float,float,float);
changeimgvis float, float;
changeimgvis(float,float);
changeimgzoom float, float;
changeimgzoom(float,float);
deletestring oldstring, float;
deletestring(string,float);
destroy;
destroy();
detachplayer;
detachplayer();
disabledefmovement;
disabledefmovement();
disablemap;
disablemap();
disablepause;
disablepause();
disableselectweapons;
disableselectweapons();
disableweapons;
disableweapons();
dontblock;
dontblock();
dontblocklocal;
dontblocklocal();
drawaslight;
drawaslight();
drawoverplayer;
drawoverplayer();
drawunderplayer;
drawunderplayer();
enabledefmovement;
enabledefmovement();
enablefeatures float;
enablefeatures(float);
enablemap;
enablemap();
enablepause;
enablepause();
enableselectweapons;
enableselectweapons();
enableweapons;
enableweapons();
explodebomb float;
explodebomb(float);
followplayer;
followplayer();
freezeplayer float;
freezeplayer(float);
freezeplayer2;
freezeplayer2();
hide;
hide();
hideimg float;
hideimg(float);
hideimgs float, float;
hideimgs(float,float);
hidelocal;
hidelocal();

hitcompu float, float, float, float;
hitcompu(float,float,float,float);
hitnpc float, float, float, float;
hitnpc(float,float,float,float);
hitobjects float, float, float;
hitobjects(float,float,float);
hideplayer float;
hideplayer(float);
hidesword float;
hidesword(float);
hitplayer float, float, float, float;
hitplayer(float,float,float,float);
hurt float;
hurt(float);
insertstring oldstring, float, oldstring;
insertstring(string,float,string);
join oldstring;
join(string);
lay oldstring;
lay(string);
lay2 oldstring, float, float;
lay2(string,float,float);
loadmap oldstring;
loadmap(string);
message oldstring;
message(string);
move float, float, float, float;
move(float,float,float,float);
noplayerkilling;
noplayerkilling();
openurl oldstring;
openurl(string);
openurl2 oldstring, float, float;
openurl2(string,float,float);
play oldstring;
play(string);
play2 oldstring, float, float, float;
play2(string,float,float,float);
playlooped oldstring;
playlooped(string);
putbomb float, float, float;
putbomb(float,float,float);
putcomp oldstring, float, float;
putcomp(string,float,float);
putexplosion float, float, float;
putexplosion(float,float,float);
putexplosion2 float, float, float, float;
putexplosion2(float,float,float,float);
puthorse oldstring, float, float;
puthorse(string,float,float);
putleaps float, float, float;
putleaps(float,float,float);
putnewcomp oldstring, float, float, oldstring, float;
putnewcomp(string,float,float,string,float);
putnpc oldstring, oldstring, float, float;
putnpc(string,string,float,float);
putnpc2 float, float, oldstring;
putnpc2(float,float,string);
reflectarrow float;
reflectarrow(float);
removearrow float;
removearrow(float);
removebomb float;
removebomb(float);
removecompus;
removecompus();
removeexplo float;
removeexplo(float);
removehorse float;
removehorse(float);
rmeoveitem float;
removeitem(float)
removestring oldstring, oldstring;
removestring(string,string);
removetiledefs oldstring;
removetiledefs(string);
replaceani oldstring, oldstring;
replaceani(string,string);
replacestring oldstring, float, oldstring;
replacestring(string,float,string);
resetfocus;
resetfocus();
savelog oldstring;
savelog(string);
savelog2 oldstring, oldstring;
savelog2(string,string);
say float;
say(float);
say2 oldstring;
say2(string);
sendrpgmessage oldstring;
sendrpgmessage(string);
sendpm oldstring;
sendpm(string);
sendtonc oldstring;
sendtonc(string);
sendtorc oldstring;
sendtorc(string);
serverwarp oldstring;
serverwarp(string);
set oldstring;
set(string);
setani oldstring, oldstring;
setani(string,string);
setarray float, float;
setarray(var,float);
setbeltcolor oldstring;
setbeltcolor(string);
setbow oldstring;
setbow(string);
setcharani oldstring, oldstring;
setcharani(string,string);
setchargender oldstring;
setchargender(string);
setcharprop oldstring, oldstring;
string = string;
setcoatcolor oldstring;
setcoatcolor(string);
setcoloreffect float, float, float, float;
setcoloreffect(float,float,float,float);
setcursor float;
setcursor(float);
setcurcor2 oldstring;
setcursor2(string);
seteffect float, float, float, float;
seteffect(float,float,float,float);
seteffectmode float;
seteffectmode(float);
setfocus float, float;
setfocus(float,float);
setgender oldstring;
setgender(string);
sethead oldstring;
sethead(string);
setlevel oldstring;
setlevel(string);
setlevel2 oldstring, float, float;
setlevel2(string,float,float);
setmap oldstring, oldstring, float, float;
setmap(string,string,float,float);
setminimap oldstring, oldstring, float, float;
setminimap(string,string,float,float);
setmusicvolume float, float;
setmusicvolume(float,float);
setimg oldstring;
setimg(string);
setimgpart oldstring, float, float, float, float;
setimgpart(string,float,float,float,float);
setletters oldstring;
setletters(string);
setplayerdir oldstring;
setplayerdir(string);
setplayerprop oldstring, oldstring;
string = string;
setpm oldstring;
setpm(string);
setshape float, float, float;
setshape(float,float,float);
setshape2 float, float, float;
setshape2(float,float,float);
setshield oldstring, float;
setshield(string,float);
setshoecolor oldstring;
setshoecolor(string);
setshootparams oldstring;
setshootparams(string);
setskincolor oldstring;
setskincolor(string);
setsleevecolor oldstring;
setsleevecolor(string);
setstring oldstring, oldstring;
setstring(string,string);
setsword oldstring, float;
setsword(string,float);
seturllevel oldstring;
seturllevel(string);
setz float, float, float, float, float, float, float, float;
setz(float,float,float,float,float,float,float,float);
setzoomeffect float;
setzoomeffect(float);
shoot float, float, float, float, float, float, oldstring, oldstring;
shoot(float,float,float,float,float,float,string,string);
shootarrow float;
shootarrow(float);
shootball;
shootball();
shootfireball float;
shootfireball(float);
shootfireblast float;
shootfireblast(float);
shootnuke float;
shootnuke(float);
show;
show();
showani float, float, float, float, oldstring;
showani(float,float,float,float,string);
showani2 float, float, float, float, float, oldstring;
showani2(float,float,float,float,float,string);
showcharacter;
showcharacter();
showfile oldstring;
showfile(string);
showimg float, oldstring, float, float;
showimg(float,string,float,float);
showimg2 float, oldstring, float, float, float;
showimg2(float,string,float,float,float);
showlocal;
showlocal();

showpoly float, float;
showpoly(float,array);
showpoly2 float, float;
showpoly2(float,array);
showstats float;
showstats(float);
showtext float, float, float, oldstring, oldstring, oldstring;
showtext(float,float,float,string,string,string);
showtext2 float, float, float, float, oldstring, oldstring, oldstring;
showtext2(float,float,float,float,string,string,string);
sleep float;
sleep(float);
spyfire float, float;
spyfire(float,float);
stopmidi;
stopmidi();
stopsound oldstring;
stopsound(string);
take oldstring;
take(string);
take2 float;
take2(float);
takehorse float;
takehorse(float);
takeplayercarry;
takeplayercarry();
takeplayerhorse;
takeplayerhorse();
throwcarry;
throwcarry();
timereverywhere;
timereverywhere();
timershow;
timershow();
toinventory oldstring;
toinventory(string);
tokenize oldstring;
tokens = string.tokenize();
tokenize2 oldstring, oldstring;
tokens = string.tokenize(" ," @ string);
toweapons oldstring;
toweapons(string);
triggeraction float, float, oldstring, oldstring;
triggeraction(float,float,string,string);
unfreezeplayer;
unfreezeplayer();
unset oldstring;
unset(string);
updateboard float, float, float, float;
updateboard(float,float,float,float);
updateterrain;
updateterrain();
wraptext float, oldstring, oldstring;
tokens = wraptext(float," ," @ string,string);
wraptext2 float, float, oldstring, oldstring;
tokens = wraptext2(float,float," ," @ string,string);
</pre>

=== Supported old string operations ===
<pre>
These old string operators can be used in string parameters
for the old commands, also you can use them directly as operators, e.g.
#c = "hello"
is actually doing
player.chat = "hello"

#a player.account
#a(float) players[float].account
#m player.ani
ani
#m(float) players[float].ani
#K(float) char(float)
#8 player.bodyimg
bodyimg
#8(float) players[float].bodyimg
#c player.chat
chat
#c(float) players[float].chat
#C0 player.colors[0]
colors[0]
#C0(float) players[float].colors[0]
#C1 player.colors[1]
colors[1]
#C1(float) players[float].colors[1]
#C2 player.colors[2]
colors[2]
#C2(float) players[float].colors[2]
#C3 player.colors[3]
colors[3]
#C3(float) players[float].colors[3]
#C4 player.colors[4]
colors[4]
#C4(float) players[float].colors[4]
#C5 player.colors[5]
colors[5]
#C5(float) players[float].colors[5]
#D downloadfile()
#E emoticonchar()
#e(float,float,oldstring)
string.substring(float,float)
#g player.guild
guild
#g(float) players[float].guild
#3 player.headimg
headimg
#3(float) players[float].headimg
#5 player.horseimg
horseimg
#5(float) players[float].horseimg
#k(float) keyname(float)
#L player.level
#I(oldstring,float)
getstring(string)[float]
#n player.nick
nick
#n(float) players[float].nick
#f image
#f(float) npcs[float].image
#F level
#p(float) params[float]
#P(float) player.attr[float]
attr[float]
#P(float_1,float_2)
players[float_2].attr[float_1]
#P1 player.attr[1]
attr[1]
#P1(float) players[float].attr[1]
#P2 player.attr[2]
attr[2]
#P2(float) players[float].attr[2]
#P3 player.attr[3]
attr[3]
#P3(float) players[float].attr[3]
#P4 player.attr[4]
attr[4]
#P4(float) players[float].attr[4]
#P5 player.attr[5]
attr[5]
#P5(float) players[float].attr[5]
#P6 player.attr[6]
attr[6]
#P6(float) players[float].attr[6]
#P7 player.attr[7]
attr[7]
#P7(float) players[float].attr[7]
#P8 player.attr[8]
attr[8]
#P8(float) players[float].attr[8]
#P9 player.attr[9]
attr[9]
#P9(float) players[float].attr[9]
#R(oldstring) string.random()
#2 player.shieldimg
shieldimg
#2(float) players[float].shieldimg
#s(oldstring) getstring(string)
#1 player.swordimg
swordimg
#1(float) players[float].swordimg
#S player.sword.script
#t(float) tokens[float]
#T(oldstring) string.trim()
#v(float) float
#W player.weapon.image
#W(float) weapons[float].image
#w player.weapon.name
#w(float) weapons[float].name
</pre>
Compatibility note:
When you use the command setcharprop then the first parameter
is handled differently: instead of changing 'player.chat' it
is changing 'chat', the chat text of the npc. So 'setcharprop #c,hello'
would be translated into
chat = "hello"
while 'setplayerprop #c,hello' is translated into
player.chat = "hello"
In the list above both possibilities are listed.

2005-07-16T03:08:18Z

Chad:

{{player}}
==Community role==
Chad has mostly played a back seat role in the actual game community of [[Graal]]. He played Classic during the years of 2000-2001, but began to spend much more time as a member of the forums' community. Recently, he has divulged himself from the forums and hangs around the [[GScript IRC channel]] whenever online. 
Guilds: #gscript, VIP

==Development areas==
Being fairly adept at math and physics, Chad has spent a good deal of time applying such topics in [[GScript]]. For one reason or another, he still prefers to script offline, but has quit using the .graal format as of late 2004. He has dabbled in graphics and level design, but found little interest in such areas. Because of his enjoyment and ease of adapting to thinking like a programmer, he has decided to try for a career in game development.

==Staff positions==
Chad does not like to work for servers, but because of his friendly nature he has helped out a little on a few projects, although he will cite different motives for these positions.

==Accounts==
Dach - main account (supposed to be "Chad" spelled backwards, but typos happen) 
NewbieChad - made for fun, but was upgraded at one point for some reason and is now used for testing (when applicable)

==Contact==
email - LyleBarbatuous@gmail.com 
AIM - michaelangelo36 (Chad has been known to block people without warning)

User:Chad

2005-07-16T03:07:11Z

Chad:

{{player}}
==Community role==
Chad has mostly played a back seat role in the actual game community of [[Graal]]. He played Classic during the years of 2000-2001, but began to spend much more time as a member of the forums' community. Recently, he has divulged himself from the forums and hangs around the [[GScript IRC channel]] whenever online. 
Guilds: #gscript, VIP

==Development areas==
Being fairly adept at math and physics, Chad has spent a good deal of time applying such topics in [[gscript]]. For one reason or another, he still prefers to script offline, but has quit using the .graal format as of late 2004. He has dabbled in graphics and level design, but found little interest in such areas. Because of his enjoyment and ease of adapting to thinking like a programmer, he has decided to try for a career in game development.

==Staff positions==
Chad does not like to work for servers, but because of his friendly nature he has helped out a little on a few projects, although he will cite different motives for these positions.

==Accounts==
Dach - main account (supposed to be "Chad" spelled backwards, but typos happen) 
NewbieChad - made for fun, but was upgraded at one point for some reason and is now used for testing (when applicable)

==Contact==
email - LyleBarbatuous@gmail.com 
AIM - michaelangelo36 (Chad has been known to block people without warning)

User:Chad

2005-07-16T02:40:24Z

Chad:

{{player}}
==Community role==
Chad has mostly played a back seat role in the actual game community of Graal. He played Classic during the years of 2000-2001, but began to spend much more time as a member of the forums' community. Recently, he has divulged himself from the forums and hangs around the #gscript channel whenever online. 
Guilds: #gscript, VIP

==Development areas==
Being fairly adept at math and physics, Chad has spent a good deal of time applying such topics in gscript. He has dabbled in graphics and level design, but found little interest in such areas. Because of his enjoyment and ease of adapting to thinking like a programmer, he has decided to try for a career in game development.

==Staff positions==
Chad does not like to work for servers, but because of his friendly nature he has helped out a little on a few projects, although he will cite different motives for these positions.

==Accounts==
Dach - main account (supposed to be "Chad" spelled backwards, but typos happen) 
NewbieChad - made for fun, but was upgraded at one point for some reason and is now used for testing (when applicable)

==Contact==
email - LyleBarbatuous@gmail.com 
AIM - michaelangelo36 (Chad has been known to block people without warning)