Scripting
Warning: incorrect scripts usage might break everything. Use with caution and always test your scripts!
To make use of scripting system you need to create script file in "Data/Scripts". It's a simple text file with ".script" extension (if you don't have extensions enabled in explorer, then you should do it right now. If you're not willing to, you'll have to find an example script file somewhere and edit it). Script file name can be:
- MapName.script - where "MapName" is... well, name of the map you want to bind this script to.
- DecorationName.script - where "DecorationName" is name of decoration you want to bind this script to. This script will be used when player is near decoration and presses use.
- Any other script will be loaded only if it was set in triggers or terminals settings (see "Triggers")
The scripting language is very simple to use:
Commands are written each on its own line. Any argument these commands need should be separated by a single whitespace. That's it, commands are executed in order top to bottom of the file.
Example:
image Character Sprites/Characters/Character.png
show Character 0 0 2
text "Hello World!"
hide Character 2
timeout 2
map start
This script will load image, set it's name as Character, show it at 0, 0 within 2 seconds, show text on screen, hide image within 2 seconds, set timeout for 2 seconds start the map.
Variables
A variable is a name that you can bind a certain value to. There are three kinds of variables:
- Global - available entire game disregarding of map player currently plays.
- Map variables - available during current map. Deleted after it's over.
- Local variables - available only during current script. Deleted after it's done working.
To set a variable you just need to write it's name and a value, separated by "=". "global." prefix is for global variables, "map." is for map variables:
global.value=10
map.value="Character"
value=10
To use a variable you need to put $ symbol before it's name:
text "$global.value"
image $map.value Sprites/Characters/Character.png
text "$value"
If you need to calculate something (and variable is a number) use next operators:
value+=2 //Addition
value-=2 //Subtraction
value*=2 //Multiplication
value/=2 //Subdivision
value++ //Increment (increase by 1)
value-- //Decrement (decrease by 1)
Conditions
Conditions are blocks of code that will be executed only if some conditions are met. Be aware: "if", and comparator are commands as well, so there MUST be whitespace separating them:
if $value == 1 {
map next
} else {
map goto 3
}
Code inside if block will be executed only if value is 1. Code inside "else" block will be executed if value is NOT 1. Else block may be imotted if you don't need it:
if $value == 1 {
map next
}
Instead of "==" you can use:
- != - condition is met if value is NOT equal
- <= - condition is met if value is less or equal
- >= - condition is met if value is greater or equal
- < - condition is met if value is less
- > - condition is met if value is greater
Procedures
Procedures are pieces of code that can be used whenever you want. Key word "end" marks procedure end, so be sure there is enough of these:
procedure helloworld
text "Hello World!"
end; //semicolon in necessary if you have more than one procedure
procedure helloworld2
text "Hello World 2!"
end
Calling a procedure is just a matter of using command "call":
call helloworld call helloworld2
Procedures exist only inside one single file. If you need them in another file, you'll have to copy them.
Commentaries
If you put "//" in front of a line this line will become a commentary - a non-executable code that is just here to set a note for yourself.
//This is a commentary call helloworld
Generic commands list:
Please note that rectangular braces are here just to mark an argument. You do not need to put them yourself.
auto
auto [0/1] - sets auto execution. By default script is executed line-by-line as player presses left mouse button or use button.
timeout
timeout time - sets timeout. Next script line will be executed automatically when timeout is over.
call
call procedureName - calls a procedure.
pause
pause - pauses script until mouse button is pressed or a use key is pressed.
halt
halt - stops script entirely.
Game commands list:
map
map start [keepmusic] - starts map after cutscene script is over. Must only be used in cutscenes at the start of a map! If keepmusic is 1 - music played in the cutscene will be played on map as well. If it's 0 or omitted, map music will be played.
map next - moves to the next map.
map return - return to map. Use only in triggers, terminals or active decorations with scripts.
map goto [index] - moves to a certain map. index - map number in the list (starting from 0).
player
player heal [amount] - heals player.
player hurt [amount] - hurts player.
player teleport [tileX] [tileY] [tileZ] - moves player to tile coordinates (0 to 63). tileY is floor number (0 to 8). TileX and tileZ can be seen in the editor.
player move [offsetX] [offsetY] [offsetZ] - shifts player to a certain number of units.
player rotation [angleX] [angleY] - sets camera rotation. angleX is up-down rotation (0 - front, 90 - up). angleY is sideways (0 is to the right, 90 is up on the map)
player retro [0/1] - if 1, deactivates player and weapon viewbob.
player turn [0/1] - if 1, deactivates mouse usage and strafing.
player steps [0/1] - if 0, deactivates footsteps sound.
player speed [value] - changes player speed.
entity
entity delete [tileX] [tileY] [tileZ] - deletes entity in a certain tile. tileZ is floor number.
entity delete me - deletes entity that called a script (or decoration that player used).
entity move [tileX] [tileY] [tileZ] [offsetX] [offsetY] [offsetZ] - shifts entity.
entity spawnat [enemyname/decorationname/Key1-3/Hp1-3] [tileX] [tileY] [tileZ] - creates entity at tile coordinates (as shown in map editor).
entity spawnatpos [enemyname/decorationname/Key1-3/Hp1-3] [X] [Y] [Z] - creates entity at a certain number of units.
door
door open [tileX] [tileY] [tileZ] - opens a door in a tile. The door will not close by itself.
door close [tileX] [tileY] [tileZ] - closes a door.
door lock [tileX] [tileY] [tileZ] - locks a door. It will not open by player ever, only through script.
door unlock [tileX] [tileY] [tileZ] - unlocks a door.
light
light create [tileX] [tileY] [tileZ] [radius] [r] [g] [b] - creates a light source at tile coordinates (as shown in map editor) with your own preferences.
light move [tileX] [tileY] [tileZ] [offsetX] [offsetY] [offsetZ] - shifts any light source.
light status [on/off] [tileX] [tileY] [tileZ] - turns on/off any light source.
status
status [string] [time] - shows a text for a certain amount of time.
give
give weapon [slot] - gives weapon to a slot (1 - 8).
give ammo [slot] [amount] - giveas ammo for a slot.
take
take weapon [slot] - takes weapon from a slot (1 - 8).
take ammo [slot] - takes ALL ammo from a slot.
cursor
cursor [1/0] - shows or hides a cursor. Not supposed to work while showing text with "vn" on.
shader
shader set [name] - sets current shader. Default shader name is - "default".
shader set [name] [path] - loads a shader, sets it's name and sets it as a current one (vert and frag shaders should be placed in Data/Shaders).
Cutscene commands list:
vn
vn [1/0] - enables or disables visual novel mode.
text
text [string] [r] [g] [b] - places text on screen (or in a textbox of VN mode is enabled) with a set color (if omitted color will be white).
font
font [size] - sets font size.
preload
preload [1/0] - enables or disables images preloading. Disable to save memory. Recommended on long cutscenes.
image
image [name] [path] - loads an image and sets it's name. Path may be anything in scope of your project folder (omit ProjectName/ part. For example "Images/Image.png" will tell engine to look into "ProjectName/Images/Image.png")
sound
sound [name] [path] - loads sound and sets it's name. Path rules are the same as for images.
show
show [imageName] [x] [y] [time] - shows image within set time. imageName is the name that was set to an image when loading. If time is 0 or omitted then image will be shown immediately.
bg
bg [imageName] [time] - shows background within set time. Unlike images bgs are stretched to fill entire screen.
hide
hide [imageName] [time] - hides image within set time. Including backgrounds and buttons. imageName is name of image that was set when loading.
play
play sound [name] - plays sound with a name that was set when loading.
play music [path] - plays music. Path rules are the same as for sounds and images.
stop
stop music - stops cutscene music. You can't stop map music.
button
button [imageName] [x] [y] [procedurename] - shows button that will call procedure upon clicking on it. Button image should consist of three images in a row. The first one is for button when it's not pressed and cursor is not over it. Second is when cursor is over it. Third - when it's pressed.
label
label imageName [x] [y] [string] [size] [r] [g] [b] [center/left/right] - places text on any place of the screen.
move
move [imageName] [x] [y] [time] - moves image to certain coordinates within time.
front
front [imageName] - moves image in front of everything else.
back
back [imageName] - moves image to the back.
There is also exactly one special command that is used only in menu script:
bind
bind [button] [scriptname] - bind a script that will be executed when a button is pressed. Script file should be placed in ProjectName/Scripts.