Old Manual Scripting
THIS IS THE SCRIPTING REFERENCE FROM V1.0 MANUAL AUTO-TRANSLATED FROM RUSSIAN TO ENGLISH.
Alot of the stuff in the manual is outdated, and is provided only for reference. Use at your own risk. You can also view the entire Old Manual in Russian.
We are working on updating the scripting reference on this page to reflect what we know has changed and make it current. Eventually the updated stuff will be a part of the Scripting page, the work-in-progress community documentation of EFPSE scripting.
The text below is © JessicoChan. Some modifications have been made by Unofficial EFPSE Wiki contributors (updates to things that have changed, etc.)
Scripts are one of the most complex, but at the same time one of the most interesting features of the engine. With the help of scripts, you can make splash screens consisting of more than one picture, dialogs, change the location of objects, in other words, you can do a lot with the help of scripts. As a result, this chapter is the largest of all.
Attention, incorrect use of scripts can potentially break the entire gameplay, use wisely and always test the correct execution of scripts!
So, you have decided to use scripts. Great. What does it take to make them work? In fact, not so much: just create a text file with the .script extension in the Data / Scripts folder (for this, you will either have to save such a file through, at least, notepad, or enable the display of registered file extensions in the folder settings, and then change it manually). The file name can be:
MapName.script - this script will be used before launching the corresponding map and will replace the splash screen (you don't need to put it in the map settings, respectively)
DecorationName.script - this script will be used if you approach the corresponding decoration and press the use button. Scripts with any other name will be loaded only if they were specified in triggers or terminals (see chapter "Triggers")
But it's not enough just to upload scripts, you also need to write them! To do this, the engine has its own, very simple, scripting language. The principle of scripting is as follows:
There is a set of specific commands that should be written on a separate line. These commands may require parameters to function properly and are written with a space after the command name. In general, everything. All the complexity is only in the correct sequence of commands. If you do not use procedures, then absolutely no problems will arise - the commands are simply executed one after the other from top to bottom.
Simple script 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 an image and name it Character, display it at coordinates 0, 0 in 2 seconds, display text on the screen, and then speed up the image in 2 seconds, after which it will launch the map.
Variables
A variable is a name for which you can store a specific value in order to use it later in commands. There are three kinds of variables:
Global - available throughout the game, regardless of which map the player is on.
Map variables - available only on the current map, after switching to another one they are deleted.
Local variables - available only in the current script, after its completion they are deleted.
To write a variable, it is enough to write its name (with an indication of the type, here - global, maps and local, respectively) and value (without spaces, it can be either a string with quotes or a number):
global.value=10
map.value="Character"
value=10
To use a variable, you must use the $symbol before its name:
text "$global.value"
image $map.value Sprites/Characters/Character.png
text "$value"
If it is necessary to perform arithmetic operations, then the following operators should be used (of course, only if the variable is a number):
value+=2 //Addition
value-=2 //Subtraction
value*=2 //Multiplication
value/=2 //Division
value++ //Increment (increment by 1)
value-- //Decrement (decrement by 1)
Conditional branches
Conditional branches are a very important thing if you need to do, for example, a transition to another level, depending on whether the player went through the trigger or not. They are done as follows (note that spaces are MANDATORY, because technically if is also a command):
if $value == 1 {
map next
} else {
map-goto 3
}
The code in {brackets} after the if will be executed if the variable value is equal to 1, and the code after the else if it is not equal to
1. The entire else block can be omitted if you only need to check if the condition is true:
if $value == 1 {
map next
}
Instead of ==, you can use the following operators:
!= - the condition is met if the variable is not equal to the value
<= - the condition is met if the variable is less than or equal to the value
>= - the condition is met if the variable is greater than or equal to the value
< - the condition is met if the variable is less than the value
> - the condition is met if the variable is greater than the value
Procedures
Procedures are pieces of code that can be executed at any time. In general, their only purpose is to shorten lines of code when the same piece is required in several different places (however, procedures are also used for buttons). The keyword end means the end of the procedure. There may be several procedures, in which case it is necessary to ensure that each of them has a corresponding end:
procedure helloworld
text "Hello World!"
end
procedure helloworld2
text "Hello World 2!"
end
The procedure is called with the call command:
call hello world
call helloworld2
Procedures exist only within a single script file. If the procedure is needed in another file, it will have to be copied manually.
Comments
Comments are explanatory lines that do not participate in any way in the process of executing the code. They are intended only to help you understand the code if you forgot something, or to temporarily disable lines of code without deleting them. To set comments, just put // at the beginning of the line.
//This is a comment
//call helloworld
Import procedures
Importing procedures is necessary in order not to manually copy procedures that are used on several maps. In other words, this is just an insert instead of a procedure command from another file (also in the Data / Scripts folder). To import, just write the # sign and the name of the file with the script:
#Global.script
List of commands (if the command requires tile coordinates the desired coordinates can be found in the editor in the bottom status bar):
Map commands:
map start - [keepmusic] - Starts the map after the splash script completes. The command should only be used in cutscenes before the start of the map. If the keepmusic value is 1 - the music currently playing in the splash screen will also play in the level. If the value is 0 or omitted, the map's music will play. Basically you need to change the music during the game.
map next - Moves to the next map in the list.
map return - Returns to the game. The command should only be used in triggers, terminals, or scenery scripts.
map goto [index] - Jumps to the specified map. index - map number in the list (starting from 0).
Player commands:
player retro [0/1] - Disables vertical aiming and weapon wiggle
player turn [0/1] - Turns on tank mode, turns instead of strafe
player steps [0/1] - Enables or disables the sound of steps
player heal [amount] - Heal the character for the specified amount of health
player hurt [amount] - Hurt the player for the specified amount of health
player teleport [tileX] [tileY] - Moves the character to the tile with the specified coordinates (from 0 to 63)
player move [shiftX] [shiftY] - Shifts the character by the specified number of units, i.e. if you specify 10, then the character will SHIFT by 10 units
player rotation [angleX] [angleY] - Sets the rotation of the camera. angleX - vertically (0 - straight, 90 - up), angleY - horizontally (0 - to the right, if you look at the map, 90 - up).
Entity commands:
entity delete [tilex] [tiley] - Deletes the decoration in the specified tile.
entity delete me - Deletes the decoration that called the script (the decoration the player was using).
entity move [tilex] [tiley] [offsetX] [offsetY] - Moves the decoration in the specified tile by the specified number of "units". One tile is 64 x 64 "units". So if you want to move the decoration by tiles, you need to multiply 64 by the number of tiles on each axis.
entity spawnat [enemyname/decorationname/Key1-3/Hp1-3] [tileX] [tileY] - Spawns a decoration, enemy, key or ammo in the specified tile. (Note: In the current build V1.5 only decorations and enemies can be spawned. Keys or ammo spawning is not working. Also note that in the unmodified old manual the command is "entity spawn" which no longer works. It is now "spawnat".
door [open] [tileX] [tileY] - Opens the door in the specified tile. When opening the door through the script, it will not close itself.
door [close] [tileX] [tileY] - Closes the door.
door [lock] [tileX] [tileY] - Locks the door. You cannot open it from the game, only from the script.
door [unlock] [tileX] [tileY] - Removes the lock from the door.
Sound and music commands: (these only work during cutscenes, not while the map is being played)
sound [name] [path] - Loads a sound and gives it a name. The path can be anything within the Data/ folder (the part with Data/ should be omitted)
play sound [name] - Plays the sound with the specified name.
play music [path] - Plays music along the specified path. The path can be anything within the Data/ folder (the part with Data/ should be omitted)
stop music - Stops the music (only the one that plays in the cutscene. The music of the level cannot be stopped).
Image commands:
image [name] [path] - Loads an image and gives it a name. The path can be anything within the Data/ folder (the part with Data/ should be omitted)
show [imageName] [x] [y] [time] - Displays the image with the specified name at the specified screen coordinates for the specified time. If time is omitted, then the image will be rendered immediately.
bg [imageName] [time] - Displays the background for the specified time (in seconds). It differs from a regular image in that it is stretched (or compressed) to fill the entire screen.
button [imageName] [x] [y] [procedurename] - Sets the button, when clicked, the procedure will be executed. If time is omitted, the button will be rendered instantly. The image should consist of three button images, one after the other horizontally. The first image is a button until it is pressed and the cursor is pointing to it. The second is a button as long as the cursor points to it. The third is the button while it is pressed.
move [imageName] [x] [y] [time] - Moves the image to the specified coordinates, in the specified time. If time is omitted, then the image will move instantly. hide
hide [imageName] [time] - Hides the image with the specified name for the specified time, including the background and buttons. If time is omitted, the image will hide instantly. front
front [imageName] - Moves the image on top of the others. back
back [imageName] - Moves the image under all others.
vn [1/0] - Turns on or off visual novel mode. vn gives you a text box using /HUD/Textbox.png and /HUD/TextboxContinue.png
preload [1/0] - Enables or disables image preloading. Necessary to save memory if the cutscene is very long or requires a large number of images.
Weapon commands:
give [weapon] [slot] - Gives a weapon for the specified slot (1 - 8).
give [ammo] [slot] [amount] - Gives ammo for the specified slot.
take [weapon] [slot] - Takes a weapon from a slot (1 - 8).
take [ammo] [slot] - Takes all the ammo from the slot.
Text commands:
text [string] [rgb] - Displays text on the screen (or in a textbox if visual novel mode is set) with the specified color (if no color is specified, the text will be white).
font
font [size] - Sets the font size for cutscenes.
status [string] [time] - Displays text in the lower left corner of the screen for the specified number of seconds. (Position of status text can be changed in the HUD configurator in Pro version)
Other commands:
auto
auto [0/1] - Enables or disables auto playback.
pause
pause - Pauses script execution until the next mouse or keyboard click.
halt
halt - Completely stops script execution.
timeout
timeout [time] - Sets a timeout during which the player cannot do anything. Upon completion, the next line of the script will be called. bind
bind [button] [scriptname] - Binds a script to a button to execute when the button is clicked. scriptname - the name of the file with the script (without extension) that will be executed when the button is clicked. The file must be in the Data/Scripts folder. The script will be executed only while the player has the ability to move. This command should only be used in the Data/Scripts/Menu.script file (see Customizing Menu Items).
shader
shader set [name] - Sets the shader with the specified name as the current shader. The default shader name is default.
shader set [name] [path] - Loads the shader with the specified name (the vertex and pixel shader files must be in the Data/Shaders folder), gives it a name, and sets it as current.
call
call [procedurename] - Executes a procedure.
cursor
cursor [1/0] - Shows or hides the cursor. Initially, when opening a cutscene, the cursor is hidden and only appears in visual novel mode or after the text has been displayed.