SCRIPTING

Introduction

You can add response to events during play with the scripting languaje of Ollvaror Caves. First of all you must assign a tag to an actor who is going to be the trigger of the event.

Then you have to create a text file with the same name of the map with the extension "olsc". For example, if your map's name is "Example map", the file must be named "Example map.olsc".

The following script is an simple "hello world" example triggered on the death of the creature tagged as "miner".

All the scripts go in this ".olsc" file, like in this example:

The list of the events are the following:

The onload event is different because does't need neither admit an actor in declaration.

The onplayerentermodule doesn't admit an actor in declaration, but has a player. It triggers everytime a player enter o reenter the game. Is intended only for mechanical purposes, like sending big textures.

Switches have onturnon and onturnoff events.

Areas have onenter, onexit and onturnonevents.

Actors have ondie and onplayertak events.

Conditionals

You can include conditionals that evaluates the truth of it's assignment each time, for example:

The conditionals must end with an "end;" command.

messagecontains

Checks if a message contains an specific portion of text. Only uses a parameter, the text to check, for example:

Checks the player (or npc) has sent "die" in the message. Will be true if the player says "die bastard" or "do diet".

messageexact

Checks if a message matchs a text. Only uses a parameter, the text to check, for example:

Checks the player (or npc) has sent "die" as an exact message.

conditionalequal

Checks if a local variable has an specific value. Local variables are assigned by the abstract command "assign". Have two parameters, as seen in the example.

conditionaldifferent

Exactly the opossed to conditionalequal.

conditionalplayer

Checks if the actor is a player. Have no parameters.

conditionalfaction

Checks if the actor is in a faction.

The faction can be chaos, players and no.

conditionalfaction:players; and conditionaplayer:; are not the same, as npc have players faction.

conditionaltagequals

Checks if the actor have an especific tag. Never true for players.

conditionalcounterequal, conditionalcounterdifferent, conditionalcountermorethan, conditionalcounterlessthan

Similar to conditionalequal, but with entire numbers. Have a name and a entire value.

conditionalactorequal,conditionalactordifferent

Similar to conditionalequal, but variables are assigned to a specific actor.

conditionalglobalchangeto

Only to be used with "onglobalchange" event.

conditionalsometagalive, conditionalalltagalive, conditionalsometagdead, conditionalalltagdead

Checks the status of tagged actor and furnitures.

playeroptionequal

Cheks if a player choose a particular option on an election. Only in "onplayerchoose" event.

1. Election
2. Option

conditionalaccomplished

Checks the status of an accomplished task.

Look for "accomplish" command.

conditionalif

A "more open" conditional

The sentence is written as a SQL command.

Stupid example (always true, as 3 is always differente from 4):

Check "Coding structures" for not so stupid usages.

Abstract commands

Have no perceptible effect, but are necesary for advanced effects.

assign

Assigns a value on a variable.

actorassign

The same, for an actor.

setcounter

Assign an entire value to a counter

increasecounter, decreasecounter

Increases or decreases the value of a counter, by one or a value

sendtexture

Send a texture skipping the normal flux. Created to be used with "onplayerentersmodule".

Deprecated now: all textures are sent on entering map.

addbackground

Add a background. Only in onload.

SetSight

Stablish the sight range in pixels. The server sends the players objects in their sight range. However only works in 400-pixels cells, so it will round other values.

By default the value is 800, and cannot be reduced.

Actually only makes sense to view moving visuals which begins far away, but would enter de sight range in their moves.

Don't use if you don't need. It overloads the data transmission.

loadrelic

Load each relic individually so the screen knows of its existence.

The loadrelic goes inside the event:onload;

Example:

Perceptible commands

Do a perceptible effect.

accomplish

Finish an objetive of the game. Have a parameter.

It's posible to repeate the name if they're equal.

accomplishsingle

The same, but only for one target. Only for persistant maps.

pause

Pauses de game for a time

message

Sends a message to all player in the chatbox

bigmessage, bigmessageto

Sends a message in a position of the screen. Bigmessage send to all player, and bigmessageto send to the player that triggers the event.

The parameters are (in order):

1. Text
2. Duration
3. X coord
4. Y coord
5. Size
6. Red component
7. Green component
8. Blue component

talkoptions

A reasonable option for dialoging with non-player characters.

First, the necessary variables are declared with #. The .= is used to concatenate the variable.

The parameters are (in order):

1. X coord
2. Y coord
3. X size
4. Y size
5. Background image (optional)
6. Image of the npc's face
7. Text
8. Answers

playeroptions

A reasonable option for responding non-player characters.

It's even possible to make payments to get [x item/thing]. In this case, the payment method is secure. A server cannot cheat players out of their money, as confirmation is always requested from the player, indicating the amount to be paid.

The playeroptions must be inside the messagecontains.

The parameters are (in order):

1. X coord
2. Y coord
3. X size
4. Y size
5. Background image (optional)
6. Image of the npc's face
7. Answer
8. Variable (The normal thing is to use it in the playeroptionequal to do something with it)
9. Confirmation (The hyphen is used to indicate the actual value that the player will have to pay.)

showimage, showimageto

Shows an image to all players, or to a player.

The effect of this line is best seen on this image:

The parameters are (in order):

1. Image. Need to be included in the map.
2. Duration
3. X coord
4. Y coord
5. (optional) X size
6. (optional) Y size
7. (optional) X displacement
8. (optional) Y displacement

visual

Creates a movile (or not) visual effect. It can be animated.

The parameters are (in order):

1. X coord
2. Y coord
3. Duration
4. Direction (left means flip the texture)
5. Disappearing time
6. Angle (for moving)
7. Velocity
8. Texture

We can create a snow falling effect repeting the following line:

changeimage

Changes the texture of an static tagged object.

setalpha

Change the alpha channel.

setlight

Change the light radious.

playcustomsound

Starts a custom sound.

console

Sends a message to the console

Perhaps useful for debugging.

addtrap

The parameters are (in order):

1. Tag
2. Step duration
3. Animation steps
4. Starting damage step
5. End damage step
6. Damage
7. Damage tipe (dark,flesh,cont,perf,cort)
8. Cycles (-1 for infinite)
9. Waiting between cycles
10. Faction (opcional) (chaos,players,no)

starttrap

Start a stopped trap (0 cycles left). Must be prepared previously with "addtrap", but it is not required to start until stopped.

The parameters are (in order):

1. Tag of the trap
2. Cycles

stoptrap

Stops a trap. It will conclude it cycle.

The parameter is:

1. Tag of the trap

Fades to black or other color.

The parameters are (in order):

1. Duration
2. Speed
3. (optional) Red component
4. (optional) Green component
5. (optional) Blue component

move

Moves a tagged tile to a direction.

The parameters are (in order):

1. Tag
2. Direction (up,down,left,right)
3. Distance
4. Speed
5. Type of movement (optional)
   • once (default)
   • simple (same)
   • return
   • cyclic
6. Stop time (optional)

forcemove

The same, but doesnt care about actors trapped.

setswitchoption

Set a parameter on a switch.

The parameters are (in order):

1. Tag of the switch
2. Parameter
   • autoreturn
   • return
   • reuse
3. Value

setreturn

Stablish the return status of an used switch. Only for "onturnon" event of a switch.

Status can be "true" or "false".

actormove

Sends an actor an order to change its home in the X axis.

caoscontagion

Assing a contagion to a tagged object (actor, furniture...)

assignpenalty

Create penalty for actors. Intended for "onenter".

The parameters are (in order):

1. type of penalty:
   • damage
   • resblud (resistance to bludgeoning damage)
   • resshar (resistance to shear damage)
   • respier (resistance to piercing damage)
   • resdark (resistance to darkness damage)
2. Value
3. Mitigation (optional):
   • mitagation_def
   • mitagation_potdef

assignbonus

Create bonus for actors.


assignbonus:damage,1,0;
assignbonus:resblud,2,0;

The parameters are (in order):

1. type of penalty:
   • damage
   • speed (attack speed)
   • life
   • chaos (chaos bar)
   • endurance
   • resblud (resistance to bludgeoning damage)
   • resshar (resistance to shear damage)
   • respier (resistance to piercing damage)
   • resdark (resistance to darkness damage)
2. Value
3. Duration (0 is permanent)

assignlimit

Create limits for actors. Intended for "onenter".


assignlimit:move,30;
assignlimit:jump,125;

The parameters are (in order):

1. Variable
   • Move
   • Jump
2. Value

removelimits, removeeffects

Remove all limits and effects.

removelimits:tag;
removelimits:;

Intended for areas. Tag must be empty when used on "onexit" event.

createarea

Create an area around objets with a tag.

createarea:tag,width/2,height/2;

summon

Summon a creature at a position.

summon:10,100,500;

The parameters are (in order):

1. ID of the creature
2. X cord
3. Y cord
4. Tag (optional)

ID	Name
1	Dormenian soldier
2	Eridian soldier
3	Harrassian soldier
4	Tirtic soldier
5	Chaos eyes
6	Unarmed
7	Oso del caos
8	Perro del caos
9	Caracol del caos
10	Cabra del caos
11	Rapaz del caos
12	Blando menor
13	Falta de personalidad menor
14	Codicia menor
15	Simpleza menor
16	Mezquindad menor
17	NPC
18	Minero corrupto corto
19	Minero corrupto largo
20	Minero corrupto pesado
21	Minero corrupto aura
22	Masa de carne
23	Guardián corrupto guerrero hacha
24	Guardia esclavista
25	Guardia corrupta cadenas
26	Masa de carne voladora
27	Maza de carne mini
28	Masa de carne torreta
29	Crow
30	Temeridad menor
31	Agente corrección
32	Guerrero ollvaror
33	Cobardía menor
34	Falsedad menor
35	Crueldad menor
36	Desidia menor
37	Indecisión menor
38	Desenfreno menor
39	Insistencia menor
40	Individualismo menor
41	Ostentosidad menor
42	Guerrero rebelde ollvaror
43	alma_l
44	alma_c
45	alma_v
46	Inconstancia menor
47	Brusquedad menor
48	Belicosidad menor
49	Agente correción boss
50	Inconstancia menor true
51	Masa de carne voladora enorme

actortalk

An actor sends a message

actortalk:tag,hello world;

heal

Create a healing effect. If not tag wil heal the trigger of the event.

heal:10;
heal:tag,10;

clean

Clean up the consumed chaos. If not tag, will clean up the chaos of the trigger of the event.

clean:10;
clean:tag,10;

cleanneversurrender

The character recovers an amount of 'never surrender'.

cleanneversurrender:1;

In the following example it recovers as many as its power

#pot=character(pow);
cleanneversurrender:evaluate[1*#pot];

teleport

Teleports the event trigger to a position.

teleport:8000,22800;

The parameters are (in order):

1. X coord
2. Y coord

setexit

It establishes that you cannot exit in an area.

Example:

actor:areanoescape;
event:onenter;
setexit:0;
event:onexit;
setexit:1;

equip

Replaces the inventory of the trigger.

equip:103,103,1;

The parameters are (in order):

1. ID of the weapon in right hand
2. ID of the weapon in left hand
3. ID of armor

Any parameter can be 0.

ID	Name	Weight (kg)
1	Leather armor	3
2	Mail armor	7
3	Eridian armor	12
4	Carsij armor	13
5	Ollvaror armor	18
101	Dagger	0.5
102	Short sword	1
103	Long sword	1.5
104	Greatsword	2.5
105	Hand axe	2
106	War axe	3
107	Gunear axe	4
108	Dormenian halberd	2
109	Eridian halberd	3
110	Hammer (not implemented)	3
111	Maul	5
112	Flail	1
113	Mace	1.5
116	Club	0.6
201	Light shield	1
202	Round shield	1.5
203	Heavy shield	2

music

Sends the player the order to preload music.

music:1;

musicmode

Sends the player the order to load a section of the preload music.

musicmode:3;

delay, enddelay

Delays the execution of a portion of script.

delay:300;
...
endelay;

Delays can't be delayed.

actorassignglobal

As actorassign, but the value is stored on the server for further reading.

Global variables are saved on the hard drive when assigned, and read when the player joins game in the server in an individual file for each character.

Shall not be abused.

actorassignglobal:nameofthevariable,value;

conditionalglobalactorequal,conditionalglobalactordifferent

Similar to conditionalactorequal, but stored on a file on the server. The values are read from the program memory, so can be abused.

conditionalglobalactorequal:nameofthevariable,value;

assignglobal

As assign, but the value is stored on the server for further reading.

Global variables are saved on the hard drive when assigned, and read when the server launches.

Triggers onglobalchange in all games in the server.

Shall not be abused.

assignglobal:nameofthevariable,value;

conditionalglobalequal,conditionalglobaldifferent

Similar to conditionalequal, but stored on a file on the server. The values are read from the program memory, so can be abused.

conditionalglobalequal:nameofthevariable,value;

conditionalcheckattribute

Cheks if a character has an attribute.

conditionalchekattribute:str>=3;

You can use basic logic operators (==, >=, <=, < and >) and some attributes:

• str: strength
• agi: agility
• end: endurance
• wil: will
• int: intelligence
• lea: leadership
• pot: otence
• def: defense
• ext: extension
• mut: number of chaos mutations

proyectile

Creates a proyectile.

proyectile:players,1534,451,5,dark,20,20,2,10,180,left,dark;
proyectile:chaos,352,2209,3,dark,40,40,5,20,180,right,pers,./tiles/pers/ball1.png;
1. Faction
2. X coord
3. Y coord
4. Damage
5. Damage type
6. Width
7. Height
8. Speed
9. Lifetime
10. Angle in degrees
11. Direction (left means flip the texture)
12. Texture
13. Personaliced texture (only if Texture is "pers")




createswitch

Creates a switch.

The parameters are (in order):

1. Texture
2. X coord
3. Y coord
4. Reuse time
5. Return time
6. Autoreturn time
7. Tag (optional)

The switch has to be somewhere on the map in the map editor. You can put it hidden outside of accessible areas.

createswitch:./switches/statue_nadruneb.png,character(posx),character(posy),1,0,0,estatuapoder;

Note: with character(posx) and character(posy) you access the character's coordinates.



createfurniture

Creates a furniture.

The parameters are (in order):

1. Texture
2. X coord
3. Y coord
4. Life
5. Tag (optional)

The furniture has to be somewhere on the map in the map editor. You can put it hidden outside of accessible areas.

createfurniture:./furniture/spark-nadruneb.png,200,210,20,chispaverde;




animate

Set the animation of a map surface.

animate:anobject,4;
1. Tag
2. Speed of the movement.

useswitch

Turn a tagged switch, if posible.

useswitch:swtra;
1. Tag

conditionalswitchon

Checks if tagged swith is on.

conditionalswitchon:tagoftheswitch;

If multiple switch are tagged, checks if all are on.

conditionalswitchoff

Same as conditionalswitchon.

conditionalrandom

Checks random circunstances.

conditionalrandom:1,2;
1. Favorable cases.
2. Possible cases.

conditionalswitchon, conditionalswitchon

Cheks if a switch is on a position.

conditionalswitchon:chanswitcha;
1. Tag of the switch.

userelic

It is used to hand over the relic to a character.

Does not work without loadrelic command.

Example:

actor:relic1;
event:onturnon;
userelic:;

actor:relic2;
event:onturnon;
userelic:;

setbehaviour

Change the target's behavior.

In the following example it is used so that chaos creatures have a more limited vision.

actor:areadeffects;
event:onenter;
conditionalfaction:chaos;
setbehaviour:self,8,true;
end;

The parameters are (in order):

1. Objetive
2. Behaviour (They range from 1 to 8)
1. Patrol
2. Fly
3. Still
4. Jump down
5. Limp
6. Never attack air
7. Never strong attack
8. Very limited vision
3. True or false

addcustomitem

Add a custom item to inventory.

Example:

actor:key;
event:onturnon;
addcustomitem:self,key,./tiles/personal/decoration/golden-key.png,0,a golden key made by Iderion;

The parameters are (in order):

1. Objetive
2. Name (will appear in inventory)
3. Image (will appear in inventory)
4. Weight in grams (will appear in inventory)
5. Description (will appear in inventory)

If you want to know if a character has the key you can use ncustomitem(key) to get the number of items named 'key' in the inventory

Example:

actor:door;
event:onturnon;
conditionalif:ncustomitem(key) > 0;
bigmessage:You have the key,100,100,100,20,200,200,200;
end;

turnto

Turn the NPC in the direction of the character. Useful in interactions with them.

Example:

actor:miner;
event:onplayertalk;
turnto:;
messagecontains:hello;
message:hello my friend;
end;

createlightzone

With this command, which goes in the event:onload; we can modify the lights. It's great for adding darkness in caves for example.

Example:

event:onload;
createlightzone:20,0,0,100000,100000;

The parameters are (in order):

1. Percentage of light
2. X coord start
3. Y coord start
4. X coord end
5. Y coord end

actorsetcameraposition

Changes the player's camera to the desired position, or returns the camera to the player.

Example:

actorsetcameraposition:position,150,200;
actorsetcameraposition:return;

The parameters are (in order):

1. Position
   • position
   • return
2. Coord X (only with position)
3. Coord Y (only with position)

actorstun

Stuns the actor

Example:

actorstun:6;
actorstun:6,cast;
actorstun:30,nothing;

The parameters are (in order):

4. Stun force
1. Type of stun (optional):
   • cast
   • nothing

Note: If you put nothing, or put "cast", the value counts as if it were damage. If you put "nothing" the stune force counts as game turns (30 is a second)

actorcleanstun

removes the actor's stun

Example:

actorcleanstun:;

Pending commands

makesourcecurrentvictim

makeindirectcurrentvictim

liberatevictim

listactorsatdistance

listactorsinarea

listactorstag

listfurnituretag

listswitchestag

listcustom

addtolistcustom

removefromlistcustom

conditionalnextobjectvalid

createswitch

encounter

superencounter

eliminateactor

disableencounter

summonrelative

alert

makeactorpeaceful

makeattack

makemegacreature

respite

cleantemporal

musicloadpart

sendtextsecuence

copylist

movelist

eraselist

claimotherserverplayerglobal

servermessage

setserveracces

sendplayer

additem

setitemquality

setzoom

removecustomitem

splittext

randomencounterposition

setplayertilevisibility

setattribute

webmessage

actorglobalsetcounter

conditionalbeinarea

loaddbpower

adddbpower

reservedbenergy

transferdbenergy

Coding structures

Variable parameters

Most of the commands admits variables ad parameters.

Example


conditionalif:character(atr6)>=2;
heal:evaluate(character(atr6)*3);
end;

We spanish people say "To the good understander few words are enough".

Not all commands have implemented variable parameters.

Variables itselfs

Declared an checked with #. Works as text, so expect some problems.

The following example makes the same as the previous one.


#cpower=character(atr6);
conditionalif:#cpower>=2;
heal:evaluate(#cpower*3);
end;

Variables are lost at the end of the event.

Something similar to functions

Declared in the top of the code.

Funtions works as a text replacement, call a function only insert its contents on the calling code.

So the following example is exactly the same as the previous one.


function:healsomeone();
#cpower=character(atr6);
conditionalif:#cpower>=2;
heal:evaluate(#cpower*3);
end;
endfunction;

(other place of the code)

call:healsomeone();

Functions have no parameters (perhaps some day), but as they are code insertions yo can use variables (#) in and out and you have to TAKE CARE not using the same variable names.

Este documento puede ser descargado en versión epub en beta.

Si se decide a hacerlo, tenga paciencia: la creación del archivo se realiza cada vez y puede ser lenta.