Graal NPC Programming

1. Introduction....................................................................................................................................
2. Starting...........................................................................................................................................
3. The Graal script system..................................................................................................................
4. Plain npc commands.......................................................................................................................
4.1. message text;............................................................................................................................
4.2. say signindex;..........................................................................................................................
4.3. lay itemname;..........................................................................................................................
4.4. lay2 itemname,x,y;..................................................................................................................
4.5. take itemname;.........................................................................................................................
4.6. hide;.........................................................................................................................................
4.7. show;........................................................................................................................................
4.8. setgif filename;........................................................................................................................
4.9. hurt halfhearts;.........................................................................................................................
4.10. play filename;........................................................................................................................
4.11. playlooped filename;.............................................................................................................
4.12. stopsound filename;...............................................................................................................
4.13. stopmidi;................................................................................................................................
5. Variables , loops and animations....................................................................................................
5.1 Working with variables............................................................................................................
5.2. Special assignment symbols....................................................................................................
5.3. Loops.......................................................................................................................................
5.4. timeouts/ sleep command........................................................................................................
5.5. timeouts in online mode..........................................................................................................
5.6. 'this'-variables..........................................................................................................................
6. More commands.............................................................................................................................
6.1. Controling the program flow...................................................................................................
6.1.1. else operation;..................................................................................................................
6.1.2. setarray var,size;...............................................................................................................
6.1.3. setstring varname,value;...................................................................................................
6.2. Simple NPC manipulation.......................................................................................................
6.2.1. setgifpart filename,x,y,width,height;.................................................................................
6.2.2. dontblock;.........................................................................................................................
6.2.3. drawoverplayer;................................................................................................................
6.2.4. drawunderplayer;..............................................................................................................
6.2.5. blockagain;.......................................................................................................................
6.2.6. canbecarried;.....................................................................................................................
6.2.7. cannotbecarried;...............................................................................................................
6.2.8. canbepushed;....................................................................................................................
6.2.9. cannotbepushed;...............................................................................................................
6.2.10. canbepulled;....................................................................................................................
6.2.11. cannotbepulled;...............................................................................................................
6.3. Complex NPC operations........................................................................................................
6.3.1. timershow;........................................................................................................................
6.3.2. showcharacter;..................................................................................................................
 6.3.3. setcharprop messagecode,string;......................................................................................
6.3.4. putnpc imgfile,scriptname,x,y;..........................................................................................
6.3.5. destroy;.............................................................................................................................
6.3.6. carryobject objectname;....................................................................................................
6.3.7. throwcarry;.......................................................................................................................
6.3.8. followplayer;.....................................................................................................................
6.3.9. toinventory flag;...............................................................................................................
6.3.10. toweapons weaponname;................................................................................................
6.3.11. showimg index,imgfile,x,y;.............................................................................................
6.3.12. changeimgpart index,x,y,width,height;...........................................................................
6.3.13. hideimg index;................................................................................................................
6.3.14. shootarrow direction;......................................................................................................
6.3.15. shootfireball direction;...................................................................................................
6.3.16. shootfireblast direction;..................................................................................................
6.3.17. shootnuke direction;.......................................................................................................
6.3.18. shootball;........................................................................................................................
6.3.19. hitplayer index,halfhearts,fromx,fromy;.........................................................................
6.3.20. hitnpc index,halfhearts,fromx,fromy;.............................................................................
6.3.21. take2 index;.....................................................................................................................
6.3.22. takehorse index;..............................................................................................................
6.4. Player manipulation.................................................................................................................
6.4.1. setlevel2 filename,x,y;......................................................................................................
6.4.2. seturllevel URL;................................................................................................................
6.4.3. sethead imgfile;.................................................................................................................
6.4.4. setsword imgfile,power;....................................................................................................
6.4.5. setshield imgfile,power;....................................................................................................
6.4.6. setbow imgfile;..................................................................................................................
6.4.7. setplayerdir direction;.......................................................................................................
6.4.8. setskincolor colorname;....................................................................................................
6.4.9. setcoatcolor colorname;....................................................................................................
6.4.10. setsleevecolor colorname;..............................................................................................
6.4.11. setshoecolor colorname;.................................................................................................
6.4.12. setbeltcolor colorname;..................................................................................................
6.4.13. setplayerprop messagecode,string;.................................................................................
6.4.14. takeplayercarry;..............................................................................................................
6.4.15. takeplayerhorse;..............................................................................................................
6.4.16. disableweapons;..............................................................................................................
6.4.17. enableweapons;...............................................................................................................
6.4.18. freezeplayer seconds;......................................................................................................
6.4.19. hideplayer seconds;.........................................................................................................
6.4.20. hidesword seconds;.........................................................................................................
6.5. Level/Game manipulation.......................................................................................................
6.5.1. updateboard x,y,width,height;...........................................................................................
6.5.2. putobject objectname,x,y;.................................................................................................
6.5.3. putbomb power,x,y;..........................................................................................................
6.5.4. putexplosion radius,x,y;....................................................................................................
6.5.5. putleaps leaptype,x,y;........................................................................................................
6.5.6. puthorse imgfile,x,y;.........................................................................................................
 6.5.7. setbackpal imgfile;............................................................................................................
6.5.8. setletters imgfile;...............................................................................................................
6.5.9. setmap imgfile,levelnamesfile,x,y;....................................................................................
6.5.10. setminimap imgfile,levelnamesfile,x,y;...........................................................................
6.5.11. noplayerkilling;...............................................................................................................
6.5.12. removebomb index;........................................................................................................
6.5.13. removearrow index;........................................................................................................
6.5.14. removeitem index;..........................................................................................................
6.5.15. removeexplo index;........................................................................................................
6.5.16. removehorse index;.........................................................................................................
6.5.17. explodebomb index;........................................................................................................
6.5.18. reflectarrow index;..........................................................................................................
6.6. Baddy manipulation.................................................................................................................
6.6.1. putcomp baddyname,x,y;..................................................................................................
6.6.2. putnewcomp baddyname,x,y,imgfile,power;....................................................................
6.6.3. hitcompu index,decrpower,fromx,fromy;..........................................................................
6.6.4. removecompus;.................................................................................................................
6.7. File operations.........................................................................................................................
6.7.1. openurl URL;....................................................................................................................
6.7.2. showfile filename;............................................................................................................
7. Events.............................................................................................................................................
8. Addtional flags...............................................................................................................................
9. Message codes................................................................................................................................
1. Introduction

With npcs you can add more interactivity and fun to your Graal levels. Painting a gif / png image to
define the look and coding a script to specify the behaviour, that's all for giving your levels an unique
touch.

2. Starting

There are two ways if creating npcs. In the editor, click on 'Baddies,Npcs,Chests'. At the lower left
corner you see a figure outline and a figure looking like a player wearing the ‘Fing Si Yun’ head.
When selecting the figure outline and moving it on the board, you will create an npc with an empty
script. Then you will see a window where you can edit the npc (image filename and script). If you
close the window and want to reopen it, then double-click on the npc.
To create an npc with a pre-generated script, select the player figure and place it on the level board. A
window will pop up where you can change the attributes of the npc. Depending on what chooses you
make and what values you type in, the game will create a new npc with a huge script. You don’t need
to change the script, it will do everything what you wanted to have. If you still want to change it,
double-click on the npc to open the normal npc editor window.

In the npc editor window you see a field for the filename and an action button. Specify a gif / png file
that defines the look of the npc. You can do that directly by typing in the name in the edit field or by
using the Windows folder view that will be opened when you click on the 'Browse' button. Some npcs
doesn’t need an image file, especially when the npc uses the ‘showcharacter’ command to look like a
player.
The npc's behaviour can be changed by modifying the action script. To do that, press the 'Action'
button. A new window will be opened. On the left side you see the text area where you can type in the
script. On the right side you see the commands list (scroll right/down to see all). Press the 'Signs'
button to open the signs list for the current level (that will be important for the 'say' command) or press
the 'Test' button to check the script for syntax errors. The error will be
displayed in the yellow line and will contain important informations about how to solve the
problem (the command that caused the error will be highlighted). Only the first error found will be
displayed.
3. The Graal script system

Each npc has its own script. The game loads the scripts when you enter a level that contains npcs. The
scripts (lists of commands) will be translated into an internal format. Each time an event occurs (the
player enters the level, the player touchs the npc, the player lays an item, etc.) the whole command list
will be executed. For each event type there is a special flag that will be set when this type of event
occurs. In dependence of that flags you can decide what to do (we will talk later about what 'flags' in
the Graal script language mean). A simple example for an npc script:

if (playertouchsme) {
lay greenrupee;
hide;
}

The most important command is 'if'. With that command you can check if a flag is set. The flag must
be put into round brackets. If it's set, then the following command or the commands set in brackets will
be executed, otherwise the command following the closing bracket will be executed next (in the
example the script execution will be finished if the flag is not set).
The 'playertouchsme' flag is set if you touch the npc right in this moment. Here are some other
important flags:
- playerenters set when the player currently enters the level
- playertouchsother set when another npc is touched by the player
- playerlaysitem set when an item is layed by the player or another npc
- compusdied set when the last baddy has died
- playerendsreading set when the player ends reading a sign
- timeout set when the npc's timeout runs out
Of course you can set your own flags too:

set myflag;
unset myflag;

These commands set/unset flags. As flag you can use any character string, only that characters that
control the command flow should not be used inside the string
(spaces, '{', '}', etc.) The flag will be stay set in the whole game,
until you do the 'unset' command. The flags will be saved in
savegames / online accounts too. If the flag starts with ‘server.’, then the flag will be server wide (will
be sent to other players).
To make it easier to test your scripts there is the flag icon in the editor, press that icon to edit the list of
the currently set flags. You can also see the set flags when you debug the script using the F6 debugger
window.
Flags can be combined with boolean operations:
! means not
&& means and
|| means or
So you can use combinations like 'playertouchsme && !myflag'.

In the script described above there are only two commands that will be executed if the flag
'playertouchsme' is set. 'lay greenrupee' lays a green ruppee next to the npc, 'hide' will hide the npc. See
the following chapters for these and more commands.
4. Plain npc commands

4.1. message text;

Displays a message above the npc. It looks like the chat text from regular players. To remove the
message, just do the command 'message;' (a text with the length 0). Read chapter 9 for more
informations about the message command.

4.2. say signindex;

Displays the sign with the specified index. To use this command, press the 'Signs' button and add a
sign. Type in a text and set the x/y coordinates to 0. In the signs list you see the index of the added
sign. Close the window and return to the action script. There type in the sign index. You can display
existing signs too, just go to the sign list and look for the index of the sign you want to display.
If you make npcs that can be carried to other levels, then you should not use this command because in
the other levels there are different sign lists.

4.3. lay itemname;

Lays an item. The item will be layed to the right or to the bottom, it depends on where the player
stands. These are the available items:

greenrupee bluerupee redrupee bombs

darts heart bow fireball

fireblast nukeshot bomb superbomb

joltbomb glove1 glove2 fullheart

 shield mirrorshield lizardshield sword

battleaxe lizardsword goldensword

The 'lay' command doesn't change the properties of the npc, so when you lay down a rupee the rupee
count of the npc will not be changed. The npc can lay down as many items as wished, but that
shouldn't be abused.

4.4. lay2 itemname,x,y;

Lays an item to the specified position. See chapter 4.3. for the item names.

4.5. take itemname;

Takes the with 'itemname' described item, when there is currently one laying around. This changes the
properties of the npc, so you can check if the npc got an item by testing the properties (how this works
will be described later in this document).

4.6. hide;

Hides the npc. If this is done, you cannot see the npc anymore. But the npc can still do actions. If you
reenter the level, the npc will be showed again (except in the online mode).

4.7. show;

Makes the npc visible. This only works, when the gif file specified for this npc really exists.

4.8. setgif filename;

Changes the image file assigned to this npc. You can take every gif, even animated gifs will be
accepted. Graal also supports png files with a bit depth of 4bit and 8bit, but doesn’t support alpha
transparency and interlacing. You can also use mng files, but only a little subset of mng is supported.
When you use this command, the npc will be automatically displayed.
4.9. hurt halfhearts;

Hurts the player. The player looses the power that is defined with 'halfhearts' (2 halfhearts are one
fullheart/one shaolin symbol). Additionally the player will be thrown away from the npc. You can also
use a 0 or negative amounts of halfhearts, in this case the player doesn't loose power or will even get
healed.

4.10. play filename;

Plays a wav file through the DirectSound engine. You can also use this command to play midis or
other file types that are supported by the installed Windows media player. Midi files will be played
looped.

4.11. playlooped filename;

Plays a wav file looped until the player leaves the current level, opens the editor or ‘stopsound’ is
called.

4.12. stopsound filename;

Stops playing a (looped) wav sound.

4.13. stopmidi;

Stops playing the currently running midi file.

5. Variables , loops and animations

5.1 Working with variables

With the commands described in the previous chapter you can do some simple actions like laying an
item when the player touchs the npc. You can change the look of the npc too. But when you are
playing with these commands a little bit, then soon you will see that it would be good if you could
even check the player properties or change the npc position. That can be done using variables.

myvar = 1;
if (myvar==1) { ... }

In the first line of the example you see an assignment. If you assign a value to a variable name, then
the game automatically creates a variable and assigns the value to that variable. All variables have
floating point values and can be accessed by every npc in the same level (except 'this.'-variables, they
will be described later).
In the second line there is again an 'if'-command, but this time there is no flag inside the brackets.
Instead of that you see a comparison operation. You can do comparison operations with two variables,
combined through a boolean operation symbol (>,<,>=,<=,==,!=). The double-'=' means equality. So
'myvar==1' is true when myvar is equal to 1.
There are many predefined variables. You can check that variables to get the current position or the
current rupee count, but you can also assign values to them to change them:

board[index] the level board (index = 0..64*64-1) *

x the npc’s horizontal position *

y the npc’s vertical position (top=0) *
timeout the npc’s timeout counter (seconds) *
rupees the npc’s rupees count *
bombs the npc’s bombs count *
darts the npc’s darts count *
hearts the npc’s hearts count *
glovepower the npc’s gloves (1-glove1,2-glove2) *
swordpower the npc’s sword power (1-normal sword,2-axe,3-lizardsword,
4-golden sword) *
shieldpower the npc’s shield power (1-normal sword,2-mirror shield,
3-lizard shield) *
dir the direction of the character **
sprite the sprite of the character **
ap the alignment points of the character (0..100) **
hurtdx will be set when the player uses the sword/npc weapon on the npc
hurtdy (x/y difference, >=-1, <=1) *
save[0],..,save[9] built-in variables that work in online mode (integer values >=0, <=220) *

npcscount the npcs count

npcs[index].id the server id of the npc
npcs[index].x an horses’s horizontal position *
npcs[index].y an horses’s vertical position *
npcs[index].width the width of the npc (in fields)
npcs[index].height the height of the npc (in fields)
npcs[index].timeout the timeout counter of the npc *
npcs[index].rupees the rupees count of the npc *
npcs[index].bombs the bombs count of the npc *
npcs[index].darts the darts count of the npc *
npcs[index].hearts the hearts count of the npc *
npcs[index].glovepower the glove power of the npc *
npcs[index].swordpower the sword power of the npc *
npcs[index].shieldpower the shield power of the npc *
npcs[index].dir the direction of the npc (if it’s a ‘showcharacter’) **
npcs[index].sprite the sprite of the npc (if it’s a ‘showcharacter’) **
npcs[index].ap the alignment of the npc (if it’s a ‘showcharacter’) **
npcs[index].hurtdx will be set when the player hurts the npc (or
npcs[index].hurtdy (hitplayer/hitpnc is called) -> push away difference *
npcs[index].save[0],..,save[9] built-in variables that work in online mode (integer
values >=0, <=220) *

playerscount the player count

players[index].x a player’s horizontal position *
players[index].y a player’s vertical position *
players[index].mp a player’s magic points *
players[index].ap a player’s alignment points *
players[index].hearts a player’s hearts count *
players[index].dir a player’s direction (0-up,1-left,2-down,3-right) *
players[index].headset a player’s head sprites set (“head“+playerheadset+“.gif“) *
players[index].rupees a player’s rupees count *
players[index].bombs a player’s bombs count *
players[index].darts a player’s arrows count *
players[index].fullhearts a player’s max hearts count
players[index].glovepower a player’s glove power (2-glove1,3-glove2) *
3-joltbomb)
players[index].swordpower a player’s sword power (1-normal sword,2-axe,3-lizardsword,
4-golden sword)
players[index].shieldpower a player’s shield power (1-normal sword,2-mirror shield,
3-lizard shield)
players[index].sprite a player’s sprites set (0..38) *
players[index].id a player’s id
players[index].saysnumber the (index+1)th player says that number
(playerx,playery,... = players[0].x,players[0].y,... = current players properties)

compuscount the baddy count

compus[index].x a baddy’s horizontal position
compus[index].y a baddy’s vertical position
compus[index].type a baddy’s type (0..9)
compus[index].dir a baddy’s body direction (0..3)
compus[index].headdir a baddy’s head direction (0..3)
compus[index].power a baddy’s power
compus[index].mode a baddy’s mode

bombscount the bombs count

bombs[index].x a bomb’s horizontal position
bombs[index].y a bomb’s vertical position
bombs[index].power the bomb’s power (1,2,3)
bombs[index].time the time left till explosion (3 .. 0)

arrowscount the arrows count (arrows + balls)

arrows[index].x
arrows[index].y
arrows[index].dx
arrows[index].dy
arrows[index].dir
arrows[index].type
arrows[index].from
an arrow’s horizontal position
an arrow’s vertical position
the horizontal speed per tick (0.05secs)
the vertical speed per tick (0.05secs)
the flying direction (0,1,2,3)
the shottype (-1 -> ball, 0..3 -> arrow with power 1..4)
the shooter (0 -> baddy, 1 -> current player)

itemscount the items count

items[index].x an item’s horizontal position
items[index].y an item’s vertical position
items[index].type the item type (0..24)
items[index].time the time left till the item disappears (8.2 .. 0)

exploscount the explosions count (putexplosion produces 9 explosions

explos[index].x
explos[index].y
explos[index].power
explos[index].time
explos[index].dir
of size 2x2!)
an explosion’s horizontal position
an explosion’s vertical position
the power of the bomb which produced this explosion
the time left till the explosion disappears
the direction from the bomb which produced the explosion

horsescount the horses count

horses[index].x
horses[index].y
horses[index].dir
horses[index].bushes
horses[index].bombs
horses[index].bombpower
horses[index].type
an horses’s horizontal position
an horses’s vertical position
the direction of the horse
bushes eaten by the horse
bombs count in the horse’s mouth
the power of the bombs on the horse’s mouth
the horse type (0 -> riding horse, 1 - boat)

random( a, b ) a random floating point value, a<= value < b

sin( a ) the sinus of a; a is an angle in the radiant system (0...3.14)
cos( a ) the cosinus of a; a is an angle in the radiant system (0...3.14)
arctan( a ) the arcus tangens of var; (some maths: a = arctan( sin(a) / cos(a) ))
int( a ) the integer value of a variable (truncates the floating point part)
abs( a ) the absolute value
arraylen( a ) the size of an array
strtofloat( str ) the value of ‘str’ as number
testcompu( x, y ) the index of the baddy on position (x,y)
testplayer( x, y ) the index of the player on position (x,y)
testnpc( x, y ) the index of the npc on position (x,y)
testitem( x, y ) the index of the item on position (x,y)
testbomb( x, y ) the index of the bomb on position (x,y)
testexplo( x, y ) the index of the explosion on position (x,y)
testhorse( x, y ) the index of the horse on position (x,y)

You can read all that variables, but you can only change values that are marked with a *, and only
attributes of the current player (playerx, playery, ..). The variables marked with ** are only available
for npcs that already used the ‘showcharacter’ command.
To change ‘playerfullhearts’, ’playershieldpower’ and ‘playerswordpower’ you can use the commands
‘lay fullheart’, ’setshield’, and ‘setsword’.
For assignments you can you use brackets and some arithmetical operations (+,-,*,/,%,^).

Hint 1: You can also use some other symbols like ':=' for assignment and a single '=' for checking
equality, but it's not recommended (to keep compability to the Java/C++ syntax).

Hint 2: There are also array variables. Use the command ‘setarray’ to initialize an array. See chapter
6.1.2. for informations about arrays.

Hint 3: ‘playersaysnumber’ only parses the beginning of the player’s chat text. So you can combine it
with ‘strcontains’ like

if (strcontains(#c,arrows)) playerdarts+=playersaysnumber;

When the player says ‘2 arrows’ he will get 2 arrows with this script.
‘playersaysnumber’ also accepts complex mathematical constructs and even variable names. If you do
a money bank with

if (playertouchsme) if (playersaysnumber<=playerrupees)
rupees+=playersaysnumber;

then the player can bank all his money just by saying ‘playerrupees’ and touching the npc.

5.2. Special assignment symbols

For some special assignments there are symbols that make the life a little bit easier:

a += b means a = a+b
a -= b means a = a-b
a *= b means a = a*b
a ++ means a = a+1
a -- means a = a-1
With these kinds of assignment you can save time for typing, it doesn't make the operation faster. Don't
use these assignments inside other commands like 'if (x++>5)'. That's possible in Java/C++, but not in
the Graal script.

5.3. Loops

This chapther only describes loops. If you want to make animations, then read chapter 5.4.
There is the command ‘for’ for doing a simple loop. Here is the definition and a simple example of
how to use it:

for (init-op; flag; incr-op) operation;

for (i=0; i<compuscount; i++) hitcompu i,x,y,1;

This example code pushes all baddies away from the npc.
The first part of the ‘for’ command is ‘init-op’. That is a command that will be executed before the
loop starts. So you can do initializations there. You can only put one command there.
The next part is the checking of if ‘flag’ is true. If yes, then ‘operation’ will be executed.
If that is done, the command ‘incr-op’ will be executed.
That was one step. Now we check ‘flag’ again. If it’s still true, then ‘operation’ and ‘incr-op’ will
again be executed. The loop will be continued until ‘flag’ is false. So you should do something in
‘incr-op’, e.g. increasing a variable, and checking with ‘flag’ if this variable exceeded a limit.
In the example the variable ‘i’ will be initalized to 0 (i=0), increased by 1 (i++), until it’s equal or
greater ‘compuscount’. That way you hurt all baddies with ‘hitcompu’ because ‘i’ takes all values
between 0 and compuscount-1.
Another kind of loops are ‘while’ loops:

while (flag) operation;

It works like ‘for (;flag;) operation’, so there is no initialization or incrementing. ‘operation’ will be
executed while ‘flag’ is true.
To avoid endless loops the loop count is limited to 10000. This limit can only be exceeded when you
do the ‘sleep’ command inside the loop scope.

5.4. timeouts/ sleep command

To do animations or movements, you can use the 'timeout' variable.

If you set the timeout to 1sec, then after one second a 'timeout' event occurs and the npcs action script
will be called with the flag 'timout' set. To show how it works, here a little example:

if (playerenters) timeout = 1;
if (timeout) {
x += 0.5;
timeout = 1;
}

If an npc has that script, then every second it moves 0.5 fields to the right:
1. When the player enters the level, the script will be called with the 'playerenters' flag set
2. So the timeout will be set to 1 (1 second)
3. The game counts the timeout down to 0
4. After 1 second the script will be called again, this time with the 'timeout' flag set
5. So the x variable will be increased and the timeout will be set again to 1
6. continue with step 3.
If you don't set the timeout again, then the timeout event will not occur again.

You can do the same stuff with the ‘sleep’ command:

if (playerenters) {
while (1==1) {
sleep 1;
x += 0.5;
}
}

When doing ‘sleep’, then the script execution will be paused for 1 second. So in this example the npc
will forever do a while loop, in this loop the npc ‘sleeps’ 1 second, then moves to the right, then sleeps
1 second, then moves to the right and so on. Internernally the ‘sleep’ command only uses the ‘timeout’
variable: it sets the timeout variable, then when the ‘timeout’ event occurs the script execution will be
started one line behind the ‘sleep’ command. If you change the timeout variable while doing ‘sleep’
(e.g. when another event occurs), then the next timeout event will start with the first script line, so be
patient with changing ‘timeout’ while another animation loop may be running.

5.5. timeouts in online mode

In the online mode normally only the player who entered the level first (of all players in the current
room) is getting timeout events. With ‘timereverywhere’ you can enable timeout events for all players:
it enables the current player to get timeout events, so you should do it while processing the
‘playerenters’ event.
But if you want to do animations or movements you should only change the npc properties on one
machine, otherwise you produce too much network traffic and strange npc movements. So check if
‘isleader’ is true. That flag is only true when the player is the one who entered the level first and would
always get timeout events.

5.6. 'this'-variables

If you want to add several npcs into the same level, then it's hard to code the movement using normal
variables because you need special scripts for each npc. To prevent that you can use 'this'-variables.
They are only accessable for the current npc, but so different npcs can use the same variable names
without influencing the movement of the other npcs.
Such local variables only start with a 'this.' , that's all. Here an example:

if (playertouchsme) {
this.movex = 5;
 timeout = 1;
}
if (timeout) {
this.movex ++;
x = this.movex;
timeout = 1;
}

In this example the 'this.movex' will be set to 5 when the player touchs the npc. Every second that
variable will be increased and assigned to the x position. That way the npc moves to the right.
You can add several npcs with that script to the same level. Every time you touch an npc it will move
to the right, starting at position 5. If you would use a variable named 'movex' instead of 'this.movex'
then all npcs would be on the same x-position and jump back to position 5 every time you touch
another npc.
6. More commands

6.1. Controling the program flow

6.1.1. else operation;

'else' must follow to an 'if' command. If the flag checked with the 'if' command was false, then the
command (or command list put in {} ) that follows the else command will be executed. Examples:

if (rupees>10) x = 30; else x = 40;

if (rupees>10) {
x = 30;
y = 30;
} else x = 40;

if (rupees>10) x = 30;
else {
x = 40;
y = 40;
}

6.1.2. setarray var,size;

Initializes ‘var’ as an array of the specified size. ‘size’ must be between 0 and 10000. ‘var’ can be any
variable, it doesn’t matter if you have already used it without a [] behind it. You can even use a
variable as normal variable and as an array at the same time (e.g. arr[i]=arr; )
After initializing the array you can access the array values through ‘var[index]’, index must be a value
between 0 and size-1. It is possible to compare arrays with the == operator and to check if a value is
contained in the array with the ‘in’ operator (like if (2 in {1,2,3}) ...).

Hint: arrays can also be initialized by doing following:

var = {value1,value2,...,valueN};
myarr = {1,2,3}; // example

6.1.3. setstring varname,value;

Creates a string variable ‘varname’ with the given value. It just sets the flag ‘varname=value’. To
access the value of a string variable, you can use the strequals operator: strequals(#s(varname), hello)
is true when the string variable with the name ‘varname’ has the value ‘hello’. You can’t use these
string variables for making post offices, but you can use it to save special player properties (the level
where an item was collected, the colors of his coat before he was thrown into prison etc.). The
variables will be saved on the server side, because they will be saved as ‘action flags’. You can delete
the string variable with ‘setstring varname,;’ (empty value).
You can use also some other commands on string variables (strcontains(#s(varname),searchstr),
strtofloat(#s(varname))).

6.2. Simple NPC manipulation

6.2.1. setgifpart filename,x,y,width,height;

Changes the image file assigned to this npc. You can take every gif, even animated gifs will be
accepted. Graal also supports png files with a bit depth of 4bit and 8bit, but doesn’t support alpha
transparency and interlacing. You can also use mng files, but only a little subset of mng is supported.
When you use this command, the npc will be automatically shown/made visible. Only the rectangle
described with (x,y,width,height) will be displayed. A simple example for this command is:

if (created) setgifpart head1.gif,0,64,32,32;

This shows a ‘Nick’ head looking down. Put the ‘setgifpart’ command inside an ‘if (playerenters) {...}’
or ‘if (created) {...}’ statement to make it visible in the editor too.

6.2.2. dontblock;

If you do this command, then the player can walk through the npc until you do the command
'blockagain'.

6.2.3. drawoverplayer;

Should be used together with 'dontblock'.

Normally objects will be drawn in the right Y-order. If you do the command 'drawoverplayer', then the
npc will be drawn last, so it appears over the player if he walks under the npc.
6.2.4. drawunderplayer;

Should be used together with 'dontblock'.

Normally objects will be drawn in the right Y-order. If you do the command 'drawunderplayer', then
the npc will be drawn first, so it appears under the player if he walks over the npc.

6.2.5. blockagain;

The previous three actions will be disabled when using this command.

6.2.6. canbecarried;

If you do this command, then the player can lift the npc and take it away until he throw it back onto the
board. When the npc lands, the script will be called with the flag 'wasthrown' set.

6.2.7. cannotbecarried;

Disables carrying.

6.2.8. canbepushed;

If you do this command, the player can push the npc until there is something in the way.

6.2.9. cannotbepushed;

Disables pushing.

6.2.10. canbepulled;

If you do this command, the player can pull the npc until there is something in the way.
6.2.11. cannotbepulled;

Disables pulling.

6.3. Complex NPC operations

6.3.1. timershow;

When doing this comand the timercount will be displayed over the npc. See chapter 5.4. to learn how
to use timeouts. If the timer runs out, then the timer will not be shown anymore.

6.3.2. showcharacter;

Displays a player character instead of the npc image. So the npc can look like a player and do
animations easily. You can change the properties of the character with the variables ‘dir’, ’sprite’,
’swordpower’, ’shootpower’, ‘shieldpower’ and the command ‘setcharprop’. Some other npc
properties like ‘x’, ’y’ and ‘drawoverplayer’ also affect the appearance of the character.

6.3.3. setcharprop messagecode,string;

Works like ‘setplayerprop’, but changes the properties of the character. You can also change ‘#n’
(nickname) with this command.

6.3.4. putnpc imgfile,scriptname,x,y;

Creates an npc and puts it onto the board. ‘scriptname’ is the name of a text file containing the action
script for this new npc. You can use this command as often as you want, but if you are making levels
for the online mode then you shouldn’t do it too often because it could slow down the game.
You should always add a line with the ‘destroy’ command, otherwise the memory could overflow...

6.3.5. destroy;

Deletes the npc.

6.3.6. carryobject objectname;

By using this command you can let the npc carry an object. It works only in combination with
‘showcharacter’ and only if the sprite is set to a value between 23 and 32. Here is the list of possible
object names:
- bush
- sign
- vase
- stone
- blackstone
- bomb
- hotbomb
- superbomb
 - joltbomb
- hotjoltbomb
- none (use this to remove the object)

6.3.7. throwcarry;

Throws the object carried by the npc (see chapter 6.3.6. for the command ‘carryobject’). When the
object falls onto the ground, then it produces some leaps or a bomb is layed.

6.3.8. followplayer;

Lets the npc follow the player. The script will still work when the npc follows the player. The npc will
be set free when you use the command 'hide', when the player lifts the npc or when you assign values
to the x/y coordinates. ‘followplayer’ doesn’t work yet in the multiplayer mode. ‘followplayer’ works
best in combination with ‘showcharacter’.

6.3.9. toinventory flag;

Transfers the npc to the players inventory. The script will be stopped. 'flag' specifies the flag that
controls the visibility of the inventory item. If you do 'unset flag' then the npc will be removed from
the inventory.

6.3.10. toweapons weaponname;

Adds the npc to the player’s weapon list. The player can select this weapon by opening the
weapon list (‘Q’ or joystick button 9), using the arrow keys to move to the weapon with the
name’weaponname’, closing the list by pressing another key. If he has selected it, he can use it by
pressing ‘D’ (or joystick button 1). If he does so, the npc script will be called with the flags
‘weaponfired’ or ‘firedonhorse’ set.
The npc will not be hidden when you do ‘toweapons’. You can use ‘hide’, ‘hidelocal’ or ‘destroy’ to
make the npc invisible when the player got it.
If there is already a weapon with the name ‘waponname’, then this npc will replace the previous
weapon. You can check if a weapon with this name already exists by doing

if (hasweapon(weaponname)) ...

When an npc is in the weapon list, it gets all events like a normal npc, so the script is called when a
‘playerlaysitem’, ‘playerenters’ etc. happens. You can use timeouts too, so weapons can do
background actions. Check for the flag ‘isweapon’ to see if this npc is already in the weapon list.

6.3.11. showimg index,imgfile,x,y;

Displays an image at the specified position. ‘index’ is for identifying already existing images. If there
is already an image with the same index, then it will be replaced by the new image (if it has the same
filename, then only the position will be updated).
The images displayed with this command will always be drawn last (over other objects). In the online
mode other players can see those images only if you do showimg with an npc weapon.

6.3.12. changeimgpart index,x,y,width,height;

Changes the visible part of the ‘showimg’ image. It will be reset when you do showimg again.

6.3.13. hideimg index;

Hides the image that has the specified index.

6.3.14. shootarrow direction;

Shoots an arrow to the specified direction. 'direction' can be 'up','left','down','right'.

6.3.15. shootfireball direction;

Shoots a fireball (power 2) to the specified direction.

6.3.16. shootfireblast direction;

Shoots a fireblast (power 1, causes explosions) to the specified direction.

6.3.17. shootnuke direction;

Shoots a 'nukebomb' (power 2, causes explosions) to the specified direction.

6.3.18. shootball;

Shoots a ball in the direction of the player. Balls can kill the player easily if you shoot fast enough...
6.3.19. hitplayer index,halfhearts,fromx,fromy;

Hurts a player. ‘index’ must be between 0 and playerscount-1, it says which player should be hurted.
‘fromx,fromy’ specifies from which position the player should be pushed away. The player’s power
will be decreased by halfhearts/2. This command works for npc characters too, see the next chapter for
more about it.

6.3.20. hitnpc index,halfhearts,fromx,fromy;

Hurts an npc. ‘index’ must be between 0 and npcscount-1, it says which npc should be hurted.
‘fromx,fromy’ specifies from which position the npc should be pushed away. Actually the npc will not
be pushed away automatically, only the hearts count and the hurtdx/hurtdy variables are changed.
Hurtdx/hurtdy are variables between -1 and 1 and specify the direction in which the npc should move
to simulate a ‘push away’. See the scripts of the pre-generated npc baddies to see how to check for
those variables. The npc’s hearts count will be decreased by halfhearts/2. If the hurted npc used the
‘showcharacter’, then the sprite of the npc will be changed to 39.
This command doesn’t change the hearts/hurtdx/hurtdy when hearts=0 or hurtdx/hurtdy are already
different than 0.

6.3.21. take2 index;

Takes the item with the specified index. See chapter 4.5. for more informations about the ‘take’
command.

6.3.22. takehorse index;

Takes the horse with the specified horse. This only works in combination with the ‘showcharacter’
command. When calling ‘takehorse’, then the npc will be set onto the horse.

6.4. Player manipulation

6.4.1. setlevel2 filename,x,y;

With 'setlevel' the player will be warped to another level to the specified position.
This command will end the script execution, except when an npc weapon does this command.

6.4.2. seturllevel URL;

With 'setlevel' the player will be warped to another level. Before you use this command, you should set
playerx and playery to the correct values so that the player doesn't appear inside a tree or a inside a
wall.
‘URL’ must be a legal URL, but without the leading ‘http://’. Use this command only for ‘offline’
levels, it’s not supported in online mode because the server must control what is in the levels.
6.4.3. sethead imgfile;

Sets the image for the head of the current player. You can also do that with assigning a value to
‘playerheadset’, but with ‘sethead’ you can use filenames different to ‘headxxx.gif’.

6.4.4. setsword imgfile,power;

Changes the sword of the player. The image file must have the same size as the existing swords that
you can find in the \level\swords\ folder. It's very hard to paint new swords because the sword has
many animation steps and the size cannot be changed. May be I will change the sword system in future
versions so that it's easier to create bigger swords.
'power' specifies the power of the players sword. You can use 0 or negative amounts if you want to
make healing weapons. Don't use 'sword1.gif',...,'sword4.gif' as 'imgfile', this will set the power to the
default value (to prevent irritations in the case that someone has a normal looking sword but having a
different sword power).

6.4.5. setshield imgfile,power;

Changes the shield of the player. The image file should have the default file size of 38x20 pixels, it
shouldn’t be bigger than 76x40 except when you want to do special ‘shields’. You can even use
animated gifs to make the shield better looking.
'power' describes the kind of sword that you want to create: 1 - normal sword, 2 - mirror shield
(reflects arrows), 3 - lizard shield (reflects arrows and makes the player faster).

6.4.6. setbow imgfile;

Sets the bow that should be displayed when playersprite==33.

6.4.7. setplayerdir direction;

You can change the player direction by assigning a value between 0 and 3 to 'playerdir'. But you can
also change the players direction by using the 'setplayerdir' command. For 'direction' you can only use
'up', 'left', 'down' and 'right'.

6.4.8. setskincolor colorname;

Changes the players skin (the hands). Following colors are possible:
- white
- yellow
- orange
- pink
- red
 - darkred
- lightgreen
- green
- darkgreen
- lightblue
- blue
- darkblue
- brown
- cynober
- purple
- darkpurple
- lightgray
- gray
- black
- transparent

6.4.9. setcoatcolor colorname;

Changes the players coat color. See chapter 6.4.8 for a complete list of possible colors.

6.4.10. setsleevecolor colorname;

Changes the players sleeve color. See chapter 6.4.8. for a complete list of possible colors.

6.4.11. setshoecolor colorname;

Changes the players shoe color. See chapter 6.4.8. for a complete list of possible colors.

6.4.12. setbeltcolor colorname;

Changes the players belt color. See chapter 6.4.8. for a complete list of possible colors.

6.4.13. setplayerprop messagecode,string;

Changes the properties of the player. ‘messagecode’ can be ‘#c’, ‘#1’, ‘#2’, ‘#3, ‘#5’,’#7’,‘#C0’,
‘#C1’, ‘#C2’, ‘#C3’, ‘#C4’. See chapter 9 for the meaning of the message codes.

6.4.14. takeplayercarry;

If the player carries something, then this command takes it away. You can test if the player carries
something by checking the flags 'carrying', 'carriesbush', 'carriessign', 'carriesvase', 'carriesstone',
'carriesblackstone', 'carriesnpc'.
6.4.15. takeplayerhorse;

If the player is riding on a horse, then this command takes it away. You can test if the player rides on a
horse by checking the flag 'playeronhorse.

6.4.16. disableweapons;

Disables all player weapons (sword, bow, bombs). If you do this, then the player can only defeat
himself by throwing bushes or reflecting arrows using the miror shield.

6.4.17. enableweapons;

Enables the player weapons if he has weapons.

6.4.18. freezeplayer seconds;

If you this command, then the player can’t move for the specified time. But he can still be attacked by
other players or by baddies, so he can get unfreezed before the timer runs down to zero.

6.4.19. hideplayer seconds;

Hides the player for the specified time. You can still see the sword, weapons, carried objects, your
horse, chat text, and you are visible for a short time when hurted.

6.4.20. hidesword seconds;

Hides the player’s sword for the specified time. This can be usefull if you change the player’s sprite to
9-13 and don’t want the sword to be shown.

6.5. Level/Game manipulation

6.5.1. updateboard x,y,width,height;

After modifying the board by assigning values to board[index], you can make the modifies visible with
this command. Then the modifies will also be sent to other players (in the multiplayer mode). In the
multiplayer mode, this changes will be undone by the server after the ‘respawn time’ set in the server
when width==2 and height==2.

6.5.2. putobject objectname,x,y;

Puts an object onto the board. ‘objectname’ must exist in the ‘predefined objects’ list of the editor.
This command is disabled in online mode because there are security problems (the object list can be
edited by the player). Use ‘board[index] = value;’ instead.
6.5.3. putbomb power,x,y;

Places a (normal) bomb with the specified power (0-normal bomb, 1-super bomb, 2-jolt bomb) at the
defined position.

6.5.4. putexplosion radius,x,y;

Creates an explosion with the specified radius at the defined position.

6.5.5. putleaps leaptype,x,y;

Produces an object 'explosion' at the specified position. 'leaptype' defines the kind of exploded object:
0 - bush, 1 - swamp, 2 - stone, 3 - sign, 4 - ball, 5 - water

6.5.6. puthorse imgfile,x,y;

Places a horse on the board at the specified position.

'imgfile' is the name of an image file that should have the
same size as the existing horses in the folder \levels\horses.
Horses have 3 animation steps and have four different
directions, so you have to paint 12 sprites. The sprites for
up/down have the size 64x48 pixel, the sprites for left/right have the size 96x48 pixel.
You can create boats using the 'puthorse' command, just put a 'horse' onto water. The game then
handles it like a boat, it makes waves when moving and has already full speed. Of course you need a
different image if you want to make a boat.

6.5.7. setbackpal imgfile;

Replaces the color palette of the background image with the color palette of the specified image file.
Follow those steps to make your own background palette image:
- Copy pics1.png to save the original file
- Change the color palette of pics1.png (don’t change the color order!)
- Save & test it
- Crop only one pixel of the image and save it under ‘mypalette.png’
- Copy the original image back to pics1.png
- Add the command ‘setbackpal mypalette.png;’ to the script of one of your npcs .
Please put your palette images into the folder /levels/backpals. I will try to not change the color palette
of pics1.png anymore, but when I do then I will also try to convert all images that are in
/levels/backpals.

6.5.8. setletters imgfile;

Sets the image file that will be used to display signs. The default file is ‘letters.png’. Because the
filename will not be saved when the player quits the game, you should use the ‘setletters’ command in
each level where you want to have display it, not only in the entry level.
The colors of the pixels (254,223) and (255,223) are used for the sign background.

6.5.9. setmap imgfile,levelnamesfile,x,y;

Sets the map. ‘levelnamesfile’ points to a file that contains the level names that belong to the map
squares. Each level takes 56x56 pixel. x/y is the position where the head icon of the player should
appear when entering the map.

6.5.10. setminimap imgfile,levelnamesfile,x,y;

Sets the minimap. ‘levelnamesfile’ points to a file that contains the level names that belong to the map
squares. Each level takes 14x14 pixel. x/y is the position where the head icon of the player should
appear when entering the map.

6.5.11. noplayerkilling;

When this command is executed, players cannot hurt each other anymore with sword / npc weapon.
But this only works in the current level.

6.5.12. removebomb index;

Removes the bomb with the specified index.

6.5.13. removearrow index;

Removes the arrow with the specified index. In the online mode only the current player sees it
disappearing.

6.5.14. removeitem index;

Removes the item / extra with the specified index.

6.5.15. removeexplo index;

Removes the explosion with the specified index. In the online mode only the current player sees it
disappearing.

6.5.16. removehorse index;

Removes the horse with the specified index.

6.5.17. explodebomb index;

Explodes the bomb with the specified index. In the online mode only the current player sees it
exploding.

6.5.18. reflectarrow index;

Reflects the arrow with the specified index like a mirror shield.

6.6. Baddy manipulation

6.6.1. putcomp baddyname,x,y;

Puts a baddy on the board at the specified position. Following names for baddies are possible:
- graysoldier
- bluesoldier
- redsoldier
- shootingsoldier
- swampsoldier
- frog
- octopus (use this name if you want to place a spider)
- goldenwarrior
- lizardon
- dragon

6.6.2. putnewcomp baddyname,x,y,imgfile,power;

Works in the same way as 'putcomp', but you can additionally define an image filename and the power
(the count how often you must hit the baddy). The image must have the same size as the baddy
described with 'baddyname'. You can find the images for the existing baddies in the folder
\levels\baddies. Here you see which image you need for the baddy type that you use:

graysoldier, swampsoldier: baddygray.gif

bluesoldier, shootingsoldier: baddyblue.gif

redsoldier: baddyred.gif
frog: baddyhare.gif
octopus/spider: baddyoctopus
goldenwarrior: baddygold.gif
lizardon: baddylizardon.gif
dragon: baddydragon.gif

With 'punewcomp' you cannot create really new baddies, you can only take existing baddies and give
them a new look.
6.6.3. hitcompu index,decrpower,fromx,fromy;

Hurts a baddy. ‘index’ must be between 0 and compuscount-1, it says which baddy should be hurted.
‘fromx,fromy’ specifies from which position the baddy should be pushed away. The baddy’s power
will be decreased by ‘decrpower’.

6.6.4. removecompus;

Removes all baddies from the board. This will cause a 'compusdied' event which interrupts the current
script execution.
You can check if there are baddies with the 'compsdead' flag,

6.7. File operations

6.7.1. openurl URL;

Opens an URL with the default browser. Before the browser will be opened a dialog pops up where the
user can cancel the action. 'URL' is a normal URL but without the leading 'http://'.

6.7.2. showfile filename;

Opens the file with the program associated with the file extension of ‘filename’. It works like a double-
click on the filename in the windows explorer, so when you do ‘showfile sprites.gif’ then ‘sprites.gif’
will be opened with the default GIF editor (e.g. Paint Shop Pro).
7. Events

Here you will see a list of all events. 'Event' means the npc script will be called and a special flag is set.

playerenters the player enters the level right now

playerouchsme the player touchs the npc
playertouchsother another npc is touched by the player
playerlaysitem an item is layed by the player or another npc
playerchats the player says something
weaponfired this npc is used as weapon (‘D’ or joybutton1 is pressed)
firedonhorse this npc weapon is fired while riding on horse
compusdied the last baddy has died
playerendsreading the player ends reading a sign
exploded a bomb explosion hits the npc
timeout the npc's timeout runs out
washit the npc was slayed with a sword or axe
wasshot the npc was shot with arrows
(shotbyplayer the npc was shot by the player)
(shotbybaddy the npc was shot by a baddy)
waspelt the npc was pelt
(peltwithbush the npc was pelt with a bush)
(peltwithsign the npc was pelt with a sign)
(peltwithvase the npc was pelt with a vase)
(peltwithstone the npc was pelt with a stone)
(peltwithblackstone the npc was pelt with a blackstone)
(peltwithnpc the npc was pelt with another npc)

8. Addtional flags

A list of flags not mentioned yet:

isweapon this npc is a weapon

isonmap the player is on an outside level
weaponsenabled the player weapons are enabled
visible the npc is visible
followsplayer the npc currently follows the player
onwall( x, y ) is true when the specified field is blocked
onwater( x, y ) is true when the specified field is water
compsdead there is no living baddy
playeronhorse the player rides on a horse (or boat)
playerswimming the player is swimming
playerismale the player is male (specified in headsconfig.txt)
playerisfemale the player is female
hasweapon( name ) the player has the weapon specified with ‘name’
canspin the player has spin power (for sword)
strequals( str1, str2 ) str1 = str2 (both strings can contain message codes)
strcontains( str1, str2 ) str1 contains str2
(to check what the player says use: strequals(#c,str), strcontains(#c,str); to check if the player is in a
special guild: strequals(#g,guildname) or strcontains(#n,(guildname)))
9. Message codes

When doing ‘message’, ‘strequals’ or ‘strcontains’ you can use special message codes to put dynamic
data into the strings (it works with almost all commands). These codes start with ‘#’ and will be
replaced by the value when used in the game. So with ‘message’ you can only do a snapshot of the
current value of the variables, the message will not be changed when it will be send to other players.
By appending an ‘(index)’ to the message code you can access the properties of other players too: if
index=-1 then you access the properties of the npc character, with index=1..playerscount-1 you can
access the properties of other client players. These are the existing message codes:

#a the account name of the player

#n, #n(index) the nick name of the player
#g, #g(index) the guild name of the player
#c, #c(index) the current chat text of the player
#v(var) the value of ‘var’ as string
#s(var) the value of the string variable ‘var’
#L the current level filename
#f the image filename of the npc
#w the name of the current npc weapon of the player
#1, #1(index) the sword image filename of the player
#2, #2(index) the shield image filename of the player
#3, #3(index) the head image filename of the player
#5, #5(index) the filename of the player’s horse
#6, #6(index) the image filename of the npc that is carried by the player
#7, #7(index) the bow image filename of the player
#8, #8(index) the body image filename of the player
#C0, #C0(index) the skin color
#C1, #C1(index) the coat color
#C2, #C2(index) the sleeves color
#C3, #C3(index) the shoes color
#C4, #C4(index) the belt color
----------------------
(c) 2000 by Stefan Knorr