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.

conditionalbeinarea

Check if a character is within the area

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.

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.

conditionalcheckattribute

Cheks if a character has an attribute.

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

conditionalswitchon

Checks if tagged swith is on.

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

conditionalswitchoff

Same as conditionalswitchon.

conditionalrandom

Checks random circunstances.

1. Favorable cases.
2. Possible cases.

conditionalswitchon, conditionalswitchon

Cheks if a switch is on a position.

1. Tag of the switch.

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.

setlocalactor

Creates an alias for an actor, allowing access to its internal variables.

The parameters are (in order):

1. objetive:
• self
• indirect
2. Name of the alias

removelocalactor

Removes the alias created by the setlocalactor

The parameters are (in order):

1. Name of the alias

setcounter

Assign an entire value to a counter

actorglobalsetcounter

Assign an entire value to an actor. 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.

claimotherserverplayerglobal

Read a global variable from a server.

The parameters are (in order):

1. Server name
2. Variable name

increasecounter, decreasecounter

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

makelocalactorcurrentvictim

Makes the "selected" actor the one passed by parameter.

makeactorpeaceful

Turns the target actor into a peaceful one.

makemegacreature

Turns the target actor into their enhanced version.

Takes a single argument. This can be selected in different ways.

1. Objetive:
• self
• indirect
• Tag

makeattack

The target actor makes a strong attack with the strength passed by parameter.

1. Strength

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.

The parameters are (in order):

1. Image (It has to be in the map editor)
2. Start X coordinate
3. Start Y coordinate
4. End X coordinate
5. End Y coordinate
6. Extra X coordinate
7. Extra Y coordinate
8. parallax X coordinate
9. parallax Y coordinate

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:

loaddbpower

Load each divine bond power individually so the screen knows of its existence.

The loaddbpower goes inside the event:onload;

Example:

addtolistcustom

If it doesn't exist, create a list and add the target.

If it already exists, just add the target.

removefromlistcustom

Remove the target from the list.

listcustom

Used to traverse lists. Useful for doing something to all targets in a list.

To iterate through lists you must use "while" together with "conditionalnextobjectvalid".

listactorsinarea

Same as listcustom but with all actors within an area.

To iterate through lists you must use "while" together with "conditionalnextobjectvalid".

listactorsatdistance

Same as listcustom but with all actors within a distance.

To iterate through lists you must use "while" together with "conditionalnextobjectvalid".

The parameters are (in order):

1. Objetive:
• self
• indirect
2. Name of the list
3. Distance
4. Tag (optional)

listactorstag

Same as listcustom but with all actors with the same tag.

To iterate through lists you must use "while" together with "conditionalnextobjectvalid".

listswitchestag

Same as listcustom but with all switches with the same tag.

To iterate through lists you must use "while" together with "conditionalnextobjectvalid".

listfurnituretag

Same as listcustom but with all furnitures with the same tag.

To iterate through lists you must use "while" together with "conditionalnextobjectvalid".

customlistsize

Returns the number of items in the list.

Useful to use together with a conditional for example.

copylist

Copies a list with all its elements to another list.

movelist

Moves a list with all its elements to another list. The origin list is deleted.

eraselist

Delete the list.

conditionalnextobjectvalid

Used to traverse lists.

To iterate through lists you must use "while" together with a list.

In the following example all targets in the list are healed:

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

messageto

Sends a message to a player in the chat.

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. Perfect if you want to hide a solid color by changing the alpha channel to zero.

setplayertilevisibility

Changes the alpha channel of a tile for a single player. Perfect if you want to hide a tile from a single player.

setlight

Change the light radious.

playcustomsound

Starts a custom sound.

console

Sends a message to the console

Perhaps useful for debugging.

sendtextsecuence

Allows button sequences to be made to achieve some behavior.

You probably need to use it in the onplayerentermodule event. This event is without an actor.

The parameters are (in order):

1. Secuence:
• b (back)
• d (down)
• f (forward)
• u (up)
• [ (block)
• ] (release block)
2. Message in chat

You can combine keys to create multiple combinations. Example: dbu or [ddd]

The message is sent via chat, so if you want to give it any function you need to use the onplayertalk event without an actor. The hidde- makes the message not visible in the chat.

setfaction

Sets the target character's faction. Factions can be chaos, players and no. You can also use whole numbers to create more factions, perfect for PVP.

addtrap

The parameters are (in order):

1. Tag of the trap
2. Tag
3. Step duration
4. Animation steps
5. Starting damage step
6. End damage step
7. Damage
8. Damage tipe (dark,flesh,cont,perf,cort)
9. Cycles (-1 for infinite)
10. Waiting between cycles
11. 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

fade

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

fadeto

Same as "fade" but aimed at the target player.

hideinterface

Hides all interface elements, such as the health bar or chat.

showinterface

Shows all interface elements, such as the health bar or chat.

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)
7. Character displacement on collision (optional)
• left
• right
• sides (the closest)

forcemove

The same, but doesnt care about actors trapped.

alert

Alert an actor. In the game each character has stealth. If an actor is alerted, the character loses stealth.

The parameters are (in order):

1. Tag

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.

actormoveto

Sends an actor an order to go to the X coordinate.

caoscontagion

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

The parameters are (in order):

1. Tag
2. Contagion
3. Distance

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.

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

The parameters are (in order):

1. Variable
• Move
• Jump
2. Value

removelimits, removeeffects

Remove all limits and effects.

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

createarea

Create an area around objets with a tag.

summon

Summon a creature at a position.

The parameters are (in order):

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

encounter

Brings up all actors with the encounter name.

In the map editor, a box appears for each actor to enter the name of the encounter.

superencounter

Same as the encounter but the actors appear enhanced.

In the map editor, a box appears for each actor to enter the name of the encounter.

disableencounter

Makes all actors with the name encounter disappear.

In the map editor, a box appears for each actor to enter the name of the encounter.

eliminateactor

Eliminate an actor, if this is not a player.

The parameters are (in order):

1. Objetive:
• self
• indirect

actortalk

An actor sends a message

heal

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

respite

The target gains as much stamina as the amount passed by parameter.

The parameters are (in order):

1. Amount

clean

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

cleanneversurrender

The character recovers an amount of 'never surrender'.

In the following example it recovers as many as its power

damage

It does as much damage as the past parameter to an actor

teleport

Teleports the event trigger to a position.

The parameters are (in order):

1. X coord
2. Y coord

setexit

It establishes that you cannot exit in an area.

Example:

equip

Replaces the inventory of the trigger.

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.

music

Sends the player the order to preload music.

musicmode

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

delay, enddelay

Delays the execution of a portion of script.

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.

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.

proyectile

Creates a proyectile.

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.

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.

animate

Set the animation of a map surface.

1. Tag
2. Speed of the movement.

useswitch

Turn a tagged switch, if posible.

1. Tag

userelic

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

Does not work without loadrelic command.

It has no parameters

Example:

adddbpower

It is used for the character to learn the power.

Does not work without loaddbpower command.

It has no parameters

Example:

reservedbenergy

It is used to give the screen a certain amount of energy. If the screen has no energy, the characters will not be able to obtain it.

For this to work, the server needs to have energy.

The parameters are (in order):

1. Amount

In the following example, only five energy points are reserved. If the characters obtain less than this amount, the remaining energy is returned to the server.

transferdbenergy

It is used to give a single energy to the character.

It has no parameters. You are always given one energy.

setbehaviour

Change the target's behavior.

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

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

addcustomitem

Add a custom item to inventory.

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)

Example:

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:

removecustomitem

Remove an item from the target's inventory.

The parameters are (in order):

1. Objetive:
• self
• indirect
2. Name of the item

turnto

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

Example:

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.

The parameters are (in order):

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

actorsetcameraposition

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

The parameters are (in order):

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

Example:

actorstun

Stuns the actor

The parameters are (in order):

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

Example:

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:

setzoom

zoom in on a target.

A 50 zoom brings the camera very close to the target.

A 200 zoom takes the camera very far from the target.

A zoom of 100 is the default for characters.

You can change this value to suit your needs.

The parameters are (in order):

1. Objetive
• self
• indirect
2. Zoom

Example:

setascend

The target character ascends.

If the value is equal to one the character is ascended to fighter.

For this command to work, your server must have ascend permissions. Contact us to get them.

The parameters are (in order):

1. Value

Example:

setattribute

Changes a character attribute

The parameters are (in order):

1. Attribute:
• 0 (Strength)
• 1 (Agility)
• 2 (Endurance)
• 3 (Willpower)
• 4 (Inteligence)
• 5 (Lidership)
• 6 (Potence)
• 7 (Defense)
• 8 (Extension)
2. Value

Example:

Pending commands

makesourcecurrentvictim

makeindirectcurrentvictim

liberatevictim

summonrelative

autouseswitch

useswitchon

cleantemporal

musicloadpart

servermessage

setserveracces

sendplayer

additem

setitemquality

splittext

randomencounterposition

webmessage

setbodytype

Coding structures

Variable parameters

Most of the commands admits variables ad parameters.

Example

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.

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.

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.