Ollvaror Caves

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".

actor:miner;
event:ondie;
message:hello world;

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

actor:miner;
event:ondie;
message:hello world;
event:onplayertalk;
message:hello you;
actor:minertwo;
event:ondie;
bye world;

The list of the events are the following:

event:onturnon
event:onturnoff;
event:onenter;
event:onexit;
event:onplayertalk;
event:onload;
event:onplayerentermodule;
event:onglobalchange;
event:onbesummoned;
event:onplayerchoose;
event:onplayertrueexits;
event:ondeadplayerdie;
event:onservermessage;
event:onwebmessage;
event:onloseattention;
event:onpersistantplayerenters;

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:

actor:miner;
event:onplayertalk;
messagecontains:hello;
message:hello you;
end;

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:

messagecontains:die;

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:

messagecontains:die;

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.

conditionalequal:nameofthevariable,valuechecked;

conditionaldifferent

Exactly the opossed to conditionalequal.

conditionalplayer

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

conditionalplayer:;

conditionalfaction

Checks if the actor is in a faction.

conditionalfaction:chaos;

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.

conditionaltagequals:nameofthetag;

conditionalcounterequal,conditionalcounterdifferent,conditionalcountermorethan,conditionalcounterlessthan

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

conditionalcounterequal:nameofthecounter,10;

conditionalactorequal,conditionalactordifferent

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

conditionalactorequal:nameofthevariable,value;

conditionalglobalchangeto

Only to be used with "onglobalchange" event.

conditionalglobalchangeto:nameofthevariable,value;

conditionalsometagalive, conditionalalltagalive, conditionalsometagdead, conditionalalltagdead

Checks the status of tagged actor and furnitures.

conditionalalltagalive:tag;

conditionalaccomplished

Checks the status of an accomplished task.

Look for "accomplish" command.

conditionalaccomplished:stones,4;

conditionalif

A "more open" conditional

conditionalif:sentence;

The sentence is written as a SQL command.

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

conditionalif:3<>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.

assing:nameofthevariable,value;

actorassign

The same, for an actor.

actorassign:nameofthevariable,value;

setcounter

Assign an entire value to a counter

setcounter:nameofthecounter,10;

increasecounter, decreasecounter

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


increasecounter:nameofthecounter,1;

sendtexture

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

Deprecated now: all textures are sent on entering map.

sendtexture:./tiles/decoration/personal/clouds.png;

addbackground

Add a background. Only in onload.

addbackground:start_x,start_y,end_x,end_y,extra_x,extra_y,par_x,par_y;

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.

setsight:1600;

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

Perceptible commands

Do a perceptible effect.

accomplish

Finish an objetive of the game. Have a parameter.

accomplish:nameoftheobjetive;

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

accomplishsingle

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

accomplishsingle:nameoftheobjetive;

pause

Pauses de game for a time

pause:300;

message

Sends a message to all player in the chatbox

message:text of the message;

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.

bigmessage:this is a big message,50,10,10,20,200,200,200;

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

showimage, showimageto

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

showimageto:./tiles/decoration/personal/kristlam_map.png,250,20,40,253,350;

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:

visual:rand(2626-3926),10,500,0,0,rand(220-230),rand(20-30),./tiles/decoration/personal/snow.png;

changeimage

Changes the texture of an static tagged object.

changeimage:tag,image;

setalpha

Change the alpha channel.

setalpha:tag,alpha;

setlight

Change the light radious.

setlight:tag,radious;

playcustomsound

Starts a custom sound.

playcustomsound:sound,volume; playcustomsound:sound,volume,x,y;

console

Sends a message to the console

Perhaps useful for debugging.

console:message;

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)
addtrap:trapinc,2,10,3,6,1,no,-1,rand(20-50);

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
fade

Fades to black or other color.

fade:75,15; fade:75,15,20,20,20;

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.

move:tag,down,100,10;

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.

setswitchoption:swaa,autoreturn,1760;

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.

setreturn:status;

Status can be "true" or "false".

actormove

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

actormove:tag,200; actormove:tag,-200;

caoscontagion

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

caoscontagion:tag,400,100;

assignpenalty

Create penalty for actors. Intended for "onenter".


assignpenalty:damage,1;
assignpenalty:resblud,2;

assignbonus

Create bonus for actors.


assignpenalty:damage,1;
assignpenalty:resblud,2;

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)

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;

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")


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 conditionalswitchoff.

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.

playeroptionequal

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

playeroptionequal:chaoscoin,take two;
  1. Election
  2. Option

Pending commands

makesourcecurrentvictim

makeindirectcurrentvictim

liberatevictim

listactorsatdistance

listactorsinarea

listactorstag

listfurnituretag

listswitchestag

listcustom

addtolistcustom

removefromlistcustom

conditionalnextobjectvalid

createfurniture createswitch encounter superencounter eliminateactor disableencounter summonrelative alert setbehaviour makeactorpeaceful makeattack makemegacreature cleanneversurrender teleport respite clean cleantemporal turnto talkoptions playeroptions musicloadpart sendtextsecuence createlightzone loadrelic userelic setexit copylist movelist eraselist claimotherserverplayerglobal servermessage setserveracces sendplayer addcustomitem additem setitemquality setzoom removecustomitem splittext randomencounterposition setplayertilevisibility setattribute webmessage

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.