Difference between revisions of "API Reference"
Jobromedia (Talk | contribs) (→play_level_music) |
Jobromedia (Talk | contribs) (→set_music_volume) |
||
Line 1,776: | Line 1,776: | ||
* ''volume'' is a value between 0.0 (quiet) and 1.0 (loud), inclusive. | * ''volume'' is a value between 0.0 (quiet) and 1.0 (loud), inclusive. | ||
+ | {{No-example}} | ||
---- | ---- | ||
Revision as of 07:07, 7 January 2012
This article needs better formatting. We ask users to improve the layout of this page in order to make it more human readable. Thank you.
Contents
- 1 Overview
- 2 Object properties
- 3 State decorators
- 3.1 Basic decorators
- 3.2 Cooperative play
- 3.3 Player interaction
- 3.3.1 lock_camera
- 3.3.2 move_player
- 3.3.3 kill_player
- 3.3.4 hit_player
- 3.3.5 burn_player
- 3.3.6 shock_player
- 3.3.7 acid_player
- 3.3.8 add_lives
- 3.3.9 add_rings
- 3.3.10 add_collectibles
- 3.3.11 add_to_score
- 3.3.12 set_player_animation
- 3.3.13 enable_player_movement
- 3.3.14 disable_player_movement
- 3.3.15 set_player_xspeed
- 3.3.16 set_player_yspeed
- 3.3.17 bounce_player
- 3.3.18 set_player_position
- 3.3.19 attach_to_player
- 3.3.20 springfy_player
- 3.3.21 roll_player
- 3.3.22 strong_player
- 3.3.23 weak_player
- 3.4 Moving the object
- 3.5 Object management
- 3.6 Object children
- 3.7 State Machine
- 3.8 Events
- 3.8.1 Generic events
- 3.8.2 Object events
- 3.8.3 Player events
- 3.8.3.1 on_observed_player
- 3.8.3.2 on_level_cleared
- 3.8.3.3 on_player_collision
- 3.8.3.4 on_player_attack
- 3.8.3.5 on_player_rect_collision
- 3.8.3.6 on_player_stop
- 3.8.3.7 on_player_walk
- 3.8.3.8 on_player_run
- 3.8.3.9 on_player_jump
- 3.8.3.10 on_player_spring
- 3.8.3.11 on_player_roll
- 3.8.3.12 on_player_push
- 3.8.3.13 on_player_gethit
- 3.8.3.14 on_player_brake
- 3.8.3.15 on_player_ledge
- 3.8.3.16 on_player_drown
- 3.8.3.17 on_player_duck
- 3.8.3.18 on_player_lookup
- 3.8.3.19 on_player_wait
- 3.8.3.20 on_player_win
- 3.8.3.21 on_player_breathe
- 3.8.3.22 on_player_death
- 3.8.3.23 on_player_in_the_air
- 3.8.3.24 on_no_shield
- 3.8.3.25 on_shield
- 3.8.3.26 on_fire_shield
- 3.8.3.27 on_thunder_shield
- 3.8.3.28 on_water_shield
- 3.8.3.29 on_acid_shield
- 3.8.3.30 on_wind_shield
- 3.9 User input
- 3.10 Level-related commands
- 3.11 Audio commands
- 3.12 Text output
- 3.13 Variables and arithmetic
Overview
This is the API Reference of the object scripting system of the Open Surge Engine. Remember that object scripts are .obj files located in the objects/ folder.
- Definition
- A command is a word followed by zero or more parameters. They're used to describe decorators.
- Observation
- Parameters written inside [ and ] are optional.
- Tip
- Objects whose name start with "." will not be available in the level editor. Example: ".acid bullet". This may be useful for temporary objects that are created by other objects.
Object properties
The commands below can be used in a object { ... } block, but not in a state { ... } block.
requires
Syntax: requires required_version
Available since: 0.1.4
This commands specifies that the minimum version of the game engine that the object requires is required_version. It's a good practice to always specify this property, setting it to the engine version you use, otherwise people running old versions of the engine may get into trouble when using the objects you make.
You can discover the engine version you use by paying attention to the main menu. Running opensurge --version in a command line will also work.
Example:
object "my object" { requires 0.1.4 // ... }
annotation
Syntax: annotation "your annotation here"
Available since: 0.2.0
Use this command to define an annotation for your object. The annotation you write will appear in the level editor. This is particularly useful if you want to say something to the people using the object you make.
Example:
object "Rain effect" { requires 0.2.0 annotation "Put only one instance of this object in your level.\nUse '\\n' to get a newline." // ... }
category
Syntax: category "category 1" [ "category 2" ... [ "category n" ] ... ]
Available since: 0.2.0
Use this command to define one or more categories to the object - you may define as many categories as you wish. This is useful for organization, since it provides easy access to related objects. In the level editor, you may use Shift+N/Shift+B or Shift+Mouse wheel to filter objects of a specific category. Still in the level editor, the special category "*" selects objects of all categories - i.e., no filtering is applied.
Example:
object "Water tornado" { requires 0.2.0 // Water tornado will be used in Waterworks Zone and in Crystal Temple. // It's also an object related to Water, so we'll add three categories. category "Water" "Level: Waterworks Zone" "Level: Crystal Temple" // ... }
destroy_if_far_from_play_area
Syntax: destroy_if_far_from_play_area
Available since: 0.1.4
Disposable objects should have this property. If this command is used, then the object will be destroyed (i.e., deleted from the level) if it gets too far away from the screen. In the example shown below, the object will be destroyed after a few seconds (supposing that it starts inside the screen):
Example:
object "bullet" { // ... destroy_if_far_from_play_area state "main" { // ... bullet_trajectory 1000.0 0.0 // move to the right } }
always_active
Syntax: always_active
Available since: 0.1.4
In order to save processing power, objects that are too far away from the screen will not be updated by the game engine. This property will force the object to be updated every frame, regardless of its position.
Example:
object "my persistent object" { // ... always_active // ... }
hide_unless_in_editor_mode
Syntax: hide_unless_in_editor_mode
Available since: 0.1.4
This property specifies that the object must be invisible unless the built-in level editor is active. This is useful to make special objects.
Example:
object "special object" { // ... hide_unless_in_editor_mode // ... }
detach_from_camera
Syntax: detach_from_camera
Available since: 0.2.0
This property specifies that the object must not follow the camera (scrolling). This is particularly useful to make HUD (Heads-Up Display) objects.
Note: if you use detach_from_camera, you can't put the object anywhere in the level and expect it to be displayed. It must be within the (0,0) x (319,239) rectangle. See also: set_absolute_position
State decorators
The commands below can only be used inside state { ... } blocks.
Basic decorators
set_animation
Syntax: set_animation sprite_name animation_id
Available since: 0.1.4
This decorator changes the animation of the object. It will look for animation animation_id of a sprite named sprite_name defined in some .spr file of the sprites/ folder. set_animation is persistent, meaning that if you change the state, the animation will not be affected.
Example:
object "my ring" { // ... state "main" { set_animation "SD_RING" 0 // ... } }
set_animation_frame
Syntax: set_animation_frame frame
Available since: 0.2.0
Forces the frame of the current animation, previously set with set_animation, to be frame. frame must be an integer between 0 and n-1, where n is the number of frames of the current animation (defined in the data command of the .spr file)
set_animation_speed_factor
Syntax: set_animation_speed_factor multiplier
Available since: 0.2.0
In the .spr, one specifies the fps (frames per second) rate of a given animation, which controls its speed. This decorator allows you to change the speed of the animation by a given factor. If multiplier is equal to 1.0, the animation will run having its default speed (fps). multiplier equals to 2.0 means twice that speed, 0.5 means half that speed, and so on.
set_obstacle
Syntax: set_obstacle boolean_value [angle]
Available since: 0.1.4
This object is converted into an obstacle brick (meaning that it behaves like a wall) with angle angle if, and only if, boolean_value equals to TRUE. If not specified, angle defaults to zero. set_obstacle is persistent, meaning that if you change the state, this property will not be affected.
Example:
object "fake brick" { // ... state "obstacle" { set_obstacle TRUE // ... } // ... state "not an obstacle" { set_obstacle FALSE // ... } // ... }
set_alpha
Syntax: set_alpha value
Available since: 0.1.4
Sets a transparency factor to the object. value is a number between 0.0 (transparent) and 1.0 (opaque). set_alpha is persistent, meaning that if you change the state, this property will not be affected.
set_angle
Syntax: set_angle degrees
Available since: 0.2.0
Defines a new value for the rotation angle of the object. degrees should be a value such that 0 <= degrees < 360. set_angle is persistent, meaning that if you change the state, this property will not be affected.
set_scale
Syntax: set_scale scale_x scale_y
Available since: 0.2.0
Scales the object horizontally by scale_x and vertically by scale_y. A value of 0.5 means half size; 1.0 means regular size; 2.0 means double size, and so on... set_scale is persistent, meaning that if you change the state, this property will not be affected.
Note: collision detection won't be affected by set_scale. Also, resizing the object while it's translucid or rotated won't work at this time.
hide
Syntax: hide
Available since: 0.1.4
Makes the object become invisible. hide is persistent, meaning that if you change the state, this property will not be affected.
show
Syntax: show
Available since: 0.1.4
Makes the object become visible. Objects are visible by default. show is persistent, meaning that if you change the state, this property will not be affected.
enemy
Syntax: enemy score
Available since: 0.1.4
Makes the object behave like an enemy, that is, touching it may destroy it or cause ring loss/death, depending if the player is in attacking state or not. score is the value that is added to the score counter if the enemy gets killed.
It's possible to reproduce the behavior of this decorator by using a sequence of other commands, but this one was designed to make things simpler.
Example:
object "fake ring" { state "main" { set_animation "SD_RING" 0 enemy 100 } }
Cooperative play
Open Surge supports cooperative play, i.e., playing with more than one character simultaneously. Objects may interact with the playable characters. However, they are limited to interacting with only one character at a time. This character is called the observed player. The observed player does not change if the active state of the object changes.
By default, the observed player is the active character, that is, the one that is being controlled by the user at the moment. However, you can change this behavior if you want to. If you want to interact with some other non-active character, or with all of them, the commands below will be useful:
observe_player
Syntax: observe_player player_name
Available since: 0.1.4
Observes a specific player of your choice.
- player_name should usually be: "Surge", "Neon" or "Charge".
observe_current_player
Syntax: observe_current_player
Available since: 0.1.4
Makes the object observe the current player, that is, the one that is active at this moment. Even if the active character gets changed three seconds from now, the observed player will not change. Note that this is different from observing the active player.
observe_active_player
Syntax: observe_active_player
Available since: 0.1.4
Makes the object always observe the active player. This is the default behavior of any object.
observe_all_players
Syntax: observe_all_players
Available since: 0.1.4
In short: makes the object observe all players, not just one.
... but this is not what happens. We have defined above that only one character can be observed at a time. In fact, this decorator gives the illusion that all players are being observed. Under the hood, it will just check who is the observed player at the moment and, on the next frame, observe the next one.
Suppose that the observed character is Surge. On the next cycle, Neon will become the observed player. Things will run normally, but the observed player has just changed. On the next cycle, Charge will be observed. After that, Surge will become the observed player again, and so on...
Surge -> Neon -> Charge -> Surge -> Neon -> Charge -> Surge -> ...
observe_next_player
Syntax: observe_next_player
Available since: 0.1.4
The same as observe_all_players.
Player interaction
The decorators below act on the observed player only. Read the Cooperative play section for more information.
lock_camera
Syntax: lock_camera x1 y1 x2 y2
Available since: 0.1.4
This command is useful to make bosses, but it can also be used in a wide range of situations. Facts:
- All parameters are given in pixels, relative to the position of the object.
- (x1, y1, x2, y2) describe a rectangle in the screen.
- x1 < x2 and y1 < y2
- If the observed player gets inside the above rectangle, then the camera will no longer be able to focus on any other area. If the camera gets locked, then the player gets locked as well.
Please note that if you want to unlock the camera, then you must destroy the object.
Example:
object "my boss: locker" { requires 0.1.4 hide_unless_in_editor_mode always_active state "main" { on_player_rect_collision -320 -120 320 120 } state "locked" { // the size of the screen is 320x240 pixels. // we're locking the camera in such a way that the // boss area has twice the area of a screen. lock_camera -320 -120 320 120 } state "destroyed" { // the camera will be unlocked destroy } } object "my boss" { requires 0.1.4 state "main" { // ... } // ... state "defeated" { // the camera will be unlocked change_closest_object_state "my boss: locker" "destroyed" // destroy the object destroy } }
move_player
Syntax: move_player speed_x speed_y
Available since: 0.1.4
Moves the player at a rate of (speed_x, speed_y) pixels per second.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
kill_player
Syntax: kill_player
Available since: 0.2.0
Kills the observed player.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
hit_player
Syntax: hit_player
Available since: 0.1.4
This decorator causes ring loss or death, depending whether the ring counter is zero or not.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
burn_player
Syntax: burn_player
Available since: 0.1.4
This decorator causes ring loss or death, unless the observed player is protected by a fire shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
shock_player
Syntax: shock_player
Available since: 0.1.4
This decorator causes ring loss or death, unless the observed player is protected by a thunder shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
acid_player
Syntax: acid_player
Available since: 0.1.4
This decorator causes ring loss or death, unless the observed player is protected by an acid shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
add_lives
Syntax: add_lives number_of_lives
Available since: 0.2.0
Adds number_of_lives to the number of lives of the player. number_of_lives may be positive or not.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
add_rings
Syntax: add_rings number_of_rings
Available since: 0.1.4
This section is deprecated due to newer versions. We ask that you don't use the information provided in this section, but read up on the most recent information available on this wiki or in the forum.
Obsolete. Use add_collectibles instead.
add_collectibles
Syntax: add_collectibles number_of_collectibles
Available since: 0.2.0
Adds number_of_collectibles to the collectible counter. number_of_collectibles may be positive or not. Example:
// add 10 to collectible counter add_collectibles 10 ... // set collectible counter to one add_collectible "-collectibles() + 1"
add_to_score
Syntax: add_to_score score
Available since: 0.1.4
Adds score to the score counter. score may be positive or not.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_player_animation
Syntax: set_player_animation sprite_name animation_id
Available since: 0.1.4
Changes the animation of the observed player. Works the same way as set_animation (for objects).
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
enable_player_movement
Syntax: enable_player_movement
Available since: 0.1.4
If you have disabled the movement of the observed player, use this command to enable it again.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
disable_player_movement
Syntax: disable_player_movement
Available since: 0.1.4
Disables the platform movement of the observed player.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_player_xspeed
Syntax: set_player_xspeed speed
Available since: 0.1.4
Defines a new horizontal speed to the observed player. speed is given in pixels per second.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_player_yspeed
Syntax: set_player_yspeed speed
Available since: 0.1.4
Defines a new vertical speed to the observed player. speed is given in pixels per second.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
bounce_player
Syntax: bounce_player
Available since: 0.1.4
Makes the observed player bounce. If you kill an enemy or hit a boss, you usually want to bounce.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_player_position
Syntax: set_player_position offset_x offset_y
Available since: 0.1.4
Sets the position of the observed player to the position of the object translated by (offset_x, offset_y) pixels.
Note: if you're trying to move the player with this command, since the fps rate is not constant on all computers, you must not do it with set_player_position unless you multiply the speed by dt(), the variation of time between two consecutive steps of the game.
// WRONG let "$speed = 2" let "$x += 2" set_player_position "$x" "0" // RIGHT let "$speed = 2" let "$x += 2 * dt()" set_player_position "$x" "0"
attach_to_player
Syntax: attach_to_player offset_x offset_y
Available since: 0.1.4
Sets the position of the object to the position of the observed player translated by (offset_x, offset_y) pixels.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
springfy_player
Syntax: springfy_player
Available since: 0.1.4
Makes the observed player behave like it has just touched a spring.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
roll_player
Syntax: roll_player
Available since: 0.1.4
Makes the observed player roll.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
strong_player
Syntax: strong_player
Available since: 0.2.0
Makes the observed player becomes strong: he/she will defeat enemies, crush item boxes, etc even when he/she is not jumping or rolling.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
weak_player
Syntax: weak_player
Available since: 0.2.0
The opposite of strong_player. The observed players needs to be jumping, rolling or invincible in order to defeat the enemies. This is the default behavior.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
Moving the object
walk
Syntax: walk speed
Available since: 0.1.4
This decorator makes the object walk with a speed of speed pixels per second.
Example:
object "walkable floating ring" { // ... state "main" { set_animation "SD_RING" 0 walk 100.0 // ... } }
gravity
Syntax: gravity
Available since: 0.1.4
This decorator makes the object be affected by gravity.
Example:
object "walkable ring" { // ... state "main" { set_animation "SD_RING" 0 walk gravity // ... } }
jump
Syntax: jump jump_strength
Available since: 0.1.4
Makes the object jump.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
move
Syntax: move speed_x speed_y
Available since: 0.1.4
Moves this object by a rate of (speed_x, speed_y) pixels per second.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
bullet_trajectory
Syntax: bullet_trajectory speed_x speed_y
Available since: 0.1.4
The same as move.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
elliptical_trajectory
Syntax: elliptical_trajectory amplitude_x amplitude_y angularspeed_x angularspeed_y [initialphase_x [initialphase_y]]
Available since: 0.1.4
This decorator makes the object describe a Simple Harmonic Motion in both x and y axis.
- amplitude is the amplitude of the oscillation, given in pixels.
- angularspeed is how fast the object should move. 1.0 means one cycle per second, 2.0 means two cycles per second, 0.5 means half cycle per second, and so on...
- initialphase is a value between 0 and 359 inclusive. If not specified, it defaults to zero.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
mosquito_movement
Syntax: mosquito_movement speed
Available since: 0.1.4
Makes the object move like a mosquito towards the observed player.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
look_left
Syntax: look_left
Available since: 0.1.4
Makes the object look left. Note: for this command to work properly, your sprites must be facing LEFT in the .png
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
look_right
Syntax: look_right
Available since: 0.1.4
Makes the object look right. Note: for this command to work properly, your sprites must be facing LEFT in the .png
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
look_at_player
Syntax: look_at_player
Available since: 0.1.4
Makes the object look at the observed player. Note: for this command to work properly, your sprites must be facing LEFT in the .png
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
look_at_walking_direction
Syntax: look_at_walking_direction
Available since: 0.1.4
If this object is moving, then this decorator makes it look to the direction it is moving. Note: for this command to work properly, your sprites must be facing LEFT in the .png
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
Object management
destroy
Syntax: destroy
Available since: 0.1.4
Deletes this object from the level.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
change_closest_object_state
Syntax: change_closest_object_state object_name new_state_name
Available since: 0.1.4
Let X be the object you're decorating. Define Y as the closest object to X called object_name. This decorator changes the state of Y to new_state_name.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
create_item
Syntax: create_item item_id offset_x offset_y
Available since: 0.1.4
Creates the specified built-in item at the position of this object translated by (offset_x, offset_y) pixels.
You must change the active state after you call this. If you don't, you may see an explosive number of items in your level.
See the item ID reference for more details.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_zindex
Syntax: set_zindex value
Available since: 0.2.0
Defines a new value for the zindex of this object. value should be a number between 0.0 and 1.0, inclusive. By default, objects have zindex = 0.5.
The zindex property affects the order objects are rendered to the screen. Objects with a low zindex will be rendered behind other level elements, and objects with a high zindex will be rendered in front of them.
Objects with zindex greater than 1.0 are HUD (Heads-Up Display) objects. They will not be displayed in the level editor.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_absolute_position
Syntax: set_absolute_position xpos ypos
Available since: 0.2.0
Sets the absolute position (in level coordinates) of this object to (xpos,ypos). (0,0) is the upper-left corner of the level.
Note: since the fps rate is not constant on all computers, you must not move the object with set_absolute_position unless you multiply the speed by dt(), the variation of time between two consecutive steps of the game. A simpler approach would be using the move command, which already does the hard work for you.
// WRONG let "$speed = 2" set_absolute_position "xpos() + 2" "0" // RIGHT: move to the right at a rate of 2 pixels per second let "$speed = 2" set_absolute_position "xpos() + 2 * dt()" "0" // RIGHT: move to the right at a rate of 2 pixels per second move 2 0
Object children
Objects can create other objects. If object P creates object C, then we say that:
- P is the parent of C
- C is a child of P
When creating objects, a parent can give names to its children.
create_child
Syntax: create_child object_name [offset_x [offset_y [child_name]]]
Available since: 0.1.4
Creates a child at the position of this object translated by (offset_x, offset_y) pixels. object_name is the name of the object to be created.
- The child_name parameter should be specified if you want to interact with the child from the script of this object (i.e., the parent).
- If the offset_x parameter is not specified, it defaults to zero. Same about offset_y. If you're using the 0.1.4 version of the game engine, you must specify both offsets.
You must change the active state after you call this. If you don't, you may see an explosive number of objects in your level.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
change_child_state
Syntax: change_child_state child_name new_state_name
Available since: 0.1.4
Changes the state of the child named child_name to new_state_name. If the child does not exist, then nothing will be done.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
change_parent_state
Syntax: change_parent_state new_state_name
Available since: 0.1.4
Changes the state of the parent of this object to new_state_name. If this object does not have a parent (i.e., it was created by the level editor), then nothing will be done.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
State Machine
Objects can contain many states. You can jump from one state to another at will.
change_state
Syntax: change_state new_state_name
Available since: 0.1.4
Changes the active state of the object to new_state_name.
return_to_previous_state
Syntax: return_to_previous_state
Available since: 0.2.0
Returns to the state you were before. Warning: a history of the previous 5 states is kept. If you insist to return to the previous state after this, the engine will complain that it can't go back anymore. Example:
... state "foo" { ... change_state "foobar" } state "bar" { ... change_state "foobar" } state "foobar" { ... // changes the state to "foo" or to "bar" // it depends which one was the active state before "foobar" return_to_previous_state } ...
Events
Events are decorators composed by a condition and a state name. If the condition holds true, then the active state of the object will be changed accordingly. This allows a huge set of combinations, making users free to explore their creativity.
Commands specified after an event that holds true will not be executed, as the state will be changed before they get the chance to run.
Generic events
General purpose events.
on_timeout
Syntax: on_timeout timeout new_state_name
Available since: 0.1.4
After timeout seconds, the active state of the object will be changed to new_state_name. Example:
object "ticking clock" { // ... state "idle" { on_timeout 0.5 "tick" } state "tick" { // tick.wav will be played every half of a second play_sample "samples/tick.wav" change_state "idle" } }
on_random_event
Syntax: on_random_event probability new_state_name
Available since: 0.1.4
Let p = probability. With a probability of p, change the active state to new_state_name.
- probability is a value between 0.0 and 1.0, inclusive. 0.0 means 0%, 1.0 means 100%, 0.57 means 57%, and so on...
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
Object events
These events are related to the object itself.
on_collision
Syntax: on_collision object_name new_state_name
Available since: 0.1.4
If this object collides with some other object whose name is object_name, then change the active state to new_state_name.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_animation_finished
Syntax: on_animation_finished new_state_name
Available since: 0.1.4
If the animation of this object has finished, then change its active state to new_state_name.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_brick_collision
Syntax: on_brick_collision new_state_name
Available since: 0.1.4
This event is triggered if the object collides with a brick.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_floor_collision
Syntax: on_floor_collision new_state_name
Available since: 0.1.4
This event is triggered if the object collides with the floor.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_ceiling_collision
Syntax: on_ceiling_collision new_state_name
Available since: 0.1.4
This event is triggered if the object collides with the ceiling.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_left_wall_collision
Syntax: on_left_wall_collision new_state_name
Available since: 0.1.4
This event is triggered if the left sensor of the object collides with a wall.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_right_wall_collision
Syntax: on_right_wall_collision new_state_name
Available since: 0.1.4
This event is triggered if the right sensor of the object collides with a wall.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
Player events
Events related to the observed player. See also: Cooperative play.
on_observed_player
Syntax: on_observed_player player_name new_state_name
Available since: 0.2.0
If the observed player is called player_name, then the state will be changed to new_state_name.
- player_name should usually be "Surge", "Neon" or "Charge".
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_level_cleared
Syntax: on_level_cleared new_state_name
Available since: 0.2.0
This event will be triggered when the player touches an end flag or when the command clear_level is executed.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_collision
Syntax: on_player_collision new_state_name
Available since: 0.1.4
This event is triggered if this object collides with the observed player.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_attack
Syntax: on_player_attack new_state_name
Available since: 0.1.4
This event is triggered if the observed player is attacking. We say that a player is attacking if it is either: jumping, rolling, charging, etc.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_rect_collision
Syntax: on_player_rect_collision offset_x1 offset_y1 offset_x2 offset_y2 new_state_name
Available since: 0.1.4
(offset_x1, offset_y1, offset_x2, offset_y2) is a rectangle. If the observed player touches this rectangle, then the event will be triggered.
- offset_x1, offset_y1, offset_x2 and offset_y2 are relative to the position of the object. These values are given in pixels.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_stop
Syntax: on_player_stop new_state_name
Available since: 0.2.0
Changes the state if the observed player stops.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_walk
Syntax: on_player_walk new_state_name
Available since: 0.2.0
Changes the state if the observed player walks.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_run
Syntax: on_player_run new_state_name
Available since: 0.2.0
Changes the state if the observed player runs.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_jump
Syntax: on_player_jump new_state_name
Available since: 0.2.0
Changes the state if the observed player jumps.
on_player_spring
Syntax: on_player_spring new_state_name
Available since: 0.2.0
Changes the state if the observed player gets launched by a spring.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_roll
Syntax: on_player_roll new_state_name
Available since: 0.2.0
Changes the state if the observed player rolls.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_push
Syntax: on_player_push new_state_name
Available since: 0.2.0
Changes the state if the observed player pushes a wall.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_gethit
Syntax: on_player_gethit new_state_name
Available since: 0.2.0
Changes the state if the observed player gets hit by a hazard.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_brake
Syntax: on_player_brake new_state_name
Available since: 0.2.0
Changes the state if the observed player brakes.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_ledge
Syntax: on_player_ledge new_state_name
Available since: 0.2.0
Changes the state if the observed player steps on a ledge.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_drown
Syntax: on_player_drown new_state_name
Available since: 0.2.0
Changes the state if the observed player drowns.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_duck
Syntax: on_player_duck new_state_name
Available since: 0.2.0
Changes the state if the observed player ducks.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_lookup
Syntax: on_player_lookup new_state_name
Available since: 0.2.0
Changes the state if the observed player looks up.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_wait
Syntax: on_player_wait new_state_name
Available since: 0.2.0
Changes the state if the observed player gets no input for a few seconds.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_win
Syntax: on_player_win new_state_name
Available since: 0.2.0
Changes the state if the observed player clears the level.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_breathe
Syntax: on_player_breathe new_state_name
Available since: 0.2.0
Changes the state if the observed player breathes an air bubble underwater.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_death
Syntax: on_player_death new_state_name
Available since: 0.2.0
Changes the state if the observed player dies.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_player_in_the_air
Syntax: on_player_in_the_air new_state_name
Available since: 0.2.0
Changes the state if the observed player is not touching the ground. The movement of the player needs to be enabled in order to make this work.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_no_shield
Syntax: on_no_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is not protected by a shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_shield
Syntax: on_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is protected by a normal shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_fire_shield
Syntax: on_fire_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is protected by a fire shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_thunder_shield
Syntax: on_thunder_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is protected by a thunder shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_water_shield
Syntax: on_water_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is protected by a water shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_acid_shield
Syntax: on_acid_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is protected by an acid shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
on_wind_shield
Syntax: on_wind_shield new_state_name
Available since: 0.1.4
This event is triggered if the observed player is protected by a wind shield.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
User input
Use these commands to detect (or interact with) input events. Whenever button_name appears, keep in mind that it must assume one, and only one, of the following values:
Button name | Suggested task | Default key |
---|---|---|
up | look up | up arrow key |
right | walk right | right arrow key |
down | duck | down arrow key |
left | walk left | left arrow key |
fire1 | jump | space bar |
fire2 | switch character | left ctrl |
fire3 | pause game | enter |
fire4 | leave game | esc |
fire5 | - | w |
fire6 | - | a |
fire7 | - | s |
fire8 | - | d |
Note: Open Surge's architecture is device-independent. As long as the gamepad has been enabled in the options screen, it doesn't really matter whether the user is playing with a keyboard or with a joypad.
Note #2: Whatever appears in the middle column are suggestions of use. You can use these buttons for whatever purpose you wish, but Open Surge uses the above conventions by default. You may reconfigure these keys (i.e., use different ones) by changing the input mappings defined in config/input.def.
on_button_down
Syntax: on_button_down button_name new_state_name
Available since: 0.2.0
Changes the state if the user is holding button_name. Example:
// unlimited lives cheat: hold UP and gain one life per second! ;-) object "Unlimited lives" { requires 0.2.0 always_active state "main" { on_button_down "up" "increment_lives" } state "increment_lives" { add_lives "1" change_state "cooldown" } state "cooldown" { on_timeout "1.0" "main" } }
on_button_pressed
Syntax: on_button_pressed button_name new_state_name
Available since: 0.2.0
Changes the state if the user was not holding button_name, but he/she is holding it now. This is an instantaneous event. Example:
// unlimited lives (reloaded) cheat: gain a life each time you press JUMP! ;-) object "Unlimited lives reloaded" { requires 0.2.0 always_active state "main" { on_button_pressed "fire1" "increment_lives" } state "increment_lives" { add_lives "1" change_state "main" } }
on_button_up
Syntax: on_button_up button_name new_state_name
Available since: 0.2.0
Changes the state if the user was holding button_name, but he/she is not holding it anymore. This is an instantaneous event.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
simulate_button_down
Syntax: simulate_button_down button_name
Available since: 0.2.0
Every character has its own input system. Whenever the user holds a button of his/her keyboard/joypad, this fact will be redirected to the input system of the active character, which will react accordingly. This command increases the flexibility of the engine: it tells the input system of the observed player (who is not necessarily the active character) that the user is holding button_name.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
simulate_button_up
Syntax: simulate_button_up button_name
Available since: 0.2.0
Behaves like button_name is not being pressed.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_player_inputmap
Syntax: set_player_inputmap inputmap_name
Available since: 0.2.0
Defines a new input mapping for the observed player. Input mappings are defined in config/input.def. You may use this command to make local multiplayer games (for example, a 2-player fighting game).
If you set inputmap_name to default, you'll be using Open Surge's default input mapping.
// player1 and player2 will throw a magic attack when fire7 is pressed. However, // fire7 may be translated to different things in each of the objects: maybe // just different keys, or perhaps even different devices (keyboard x joystick, // two different joysticks, or anything else you come up with) object "Surge Fighters: Player 1" { requires 0.2.0 always_active state "main" { observe_player "Surge" set_player_inputmap "player 1" change_state "loop" } state "loop" { on_button_pressed "fire7" "throw magic" // ... } } object "Surge Fighters: Player 2" { requires 0.2.0 always_active state "main" { observe_player "Neon" set_player_inputmap "player 2" change_state "loop" } state "loop" { on_button_pressed "fire7" "throw magic" // ... } }
show_dialog_box
Syntax: show_dialog_box title message
Available since: 0.1.4
Shows a message box using the given parameters.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
hide_dialog_box
Syntax: hide_dialog_box
Available since: 0.1.4
Hides all message boxes in the screen.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
request_camera_focus
Syntax: request_camera_focus
Available since: 0.2.0
Asks the engine to make the camera focus on this object.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
drop_camera_focus
Syntax: drop_camera_focus
Available since: 0.2.0
If you have requested the camera focus, this will make the camera focus the active player again.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
clear_level
Syntax: clear_level
Available since: 0.1.4
If this decorator is called, then the engine will understand that the observed player has just got through the level. This does not make it jump to the next level, however. See also: on_level_cleared, next_level
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
next_level
Syntax: next_level
Available since: 0.2.0
Jumps "immediately" to the next level in the running quest. This is different from clear_level, since you can't capture a "next_level" event.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
restart_level
Syntax: restart_level
Available since: 0.2.0
Restarts the current level.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
load_level
Syntax: load_level level_filepath
Available since: 0.2.0
Loads the specified level. Example:
state "warp" { load_level "levels/template.lev" }
ask_to_leave
Syntax: ask_to_leave
Available since: 0.2.0
Asks if the user wants to leave the level.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
pause
Syntax: pause
Available since: 0.2.0
Asks politely the engine to pause the game. The engine may refuse to do so - for example, when the player is dying.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
switch_character
Syntax: switch_character [player_name [force_switch]]
Available since: 0.2.0
Asks politely the engine to switch the active character to player_name. The engine may refuse your request if the player is dying, falling in an abyss, fighting against a boss, etc.
- if player_name is not specified, the observed player will become the active character
- if specified, player_name should be the name of any of the Characters. Usually, it will be Surge, Neon or Charge.
- you should not specify force_switch. If you do set it to TRUE, however, the engine will accept your request even if it does not want to. Don't use that unless you have a very good reason.
Example:
... state "listen" { on_button_press "fire2" "switch" } state "switch" { switch_character "Neon" ... } ...
Audio commands
play_sample
Syntax: play_sample sound_name [volume [pan [frequency [loops]]]]
Available since: 0.1.4
Plays a sample at the specified volume, pan position, and frequency. You need to change the state of the object (or destroy it) after you call this command, otherwise the engine will try to play your sample at each cycle, causing weird results.
- sound_name can be the name of a sample described in config/samples.def or the path of a .wav/.ogg file;
- volume is a value between 0.0 (quiet) and 1.0 (loud). If not specified, it defaults to 1.0.
- pan is a value between -1.0 (left) and 1.0 (right). If not specified, it defaults to 0.0 (middle).
- frequency is relative rather than absolute: 1.0 is the frequency that the sample was recorded at, 2.0 is twice this, etc. If not specified, it defaults to 1.0.
- loops represents how many times you want the sample to be looped. If not specified, it defaults to zero. Set it to -1 to make the sample loop forever.
Example:
object "Speed Booster" { // ... state "main" { // ... on_player_collision "triggered" } state "triggered" { play_sample "samples/boost.wav" change_state "active" } state "active" { // ... } // ... }
play_music
Syntax: play_music music_name [loops]
Available since: 0.1.4
Plays the specified music. Only one music can be played at a time. You need to change the state of the object (or destroy it) after you call this command, otherwise the engine will try to play your music at each cycle, causing weird results.
- music_name is the path of an .ogg file. Musics are in the musics/ folder.
- loops represents how many times you want the specified music to be looped. If not specified, it defaults to zero. Set it to -1 to make the music loop forever.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
play_level_music
Syntax: play_level_music
Available since: 0.1.4
Restores the music of the level.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
set_music_volume
Syntax: set_music_volume volume
Available since: 0.1.4
Sets the volume of the music.
- volume is a value between 0.0 (quiet) and 1.0 (loud), inclusive.
This section needs a properly formatted example to show how to use this command. We ask users to improve the layout of this segment in order to make it more human readable. Thank you.
Text output
textout
Syntax: textout font_name xpos ypos text [max_width [index_of_first_char [length]]]
Available since: 0.2.0
Prints a text to the screen.
- font_name is the name of a font specified in a .fnt file in the fonts/ folder (example: default). See also: Fonts
- xpos and ypos are the offset of the text relative to the position of the object. So, if (xpos,ypos) = (10,20) and the object is positioned at (110,130), the top-left of the text will appear at (110+10, 130+20) = (130,150).
- text is the text you want to print
- if you want wordwrap, set max_width to the maximum width, in pixels, that the text can assume. It defaults to infinity (i.e., no wordwrap).
- index_of_first_char defaults to zero, meaning that the printed text would start in the first character of text. If it was equal to 1, it would start in the second character of text, and so on.
- length means: how many characters do you want to print, starting from index_of_first_char. If you don't specify it, the length will be the maximum it's possible to be.
// ... state "main" { // ... let "$the_time = elapsed_time()" textout "default" 0 0 "Hello world! <color=ffff00>THE TIME:</color> $the_time" // ... } // ...
Tip: immediately after you call textout, a global variable called $_STRLEN will be set to the length of the text passed to this command.
textout_centre
Syntax: textout_centre font_name xpos ypos text [max_width [index_of_first_char [length]]]
Available since: 0.2.0
The same as textout, but considers xpos as the center of the text.
textout_right
Syntax: textout_right font_name xpos ypos text [max_width [index_of_first_char [length]]]
Available since: 0.2.0
The same as textout, but considers xpos as the right corner of the text.
Variables and arithmetic
Since version 0.2.0, the scripting system supports variables and basic arithmetic.
Variables
Variables are entities that store approximations of real numbers. Example:
... let "$a = 7" let "$b = 70" // result: $c is equal to 707 let "$c = $a + $b * 10" // result: $d is equal to 770 let "$d = ($a + $b) * 10" // result: $e is equal to 7 let "$e = 2^3 * 0.5 + 3" ...
Naming
Variable names start with '$', followed by a letter or '_', followed by a sequence of zero or more characters that may be: letters, digits or '_'.
- GOOD: $variable, $lives, $_globalvar, $_my_global_variable, $i, $j, $HelloWorld, $hello_world, $a12
- BAD: $1, $7a, $hello world, $!!, $no_symbols!!, $test?%
Variable names are case-sensitive (that is, the following variables are different: $HelloWorld, $helloworld, $HELLOWORLD)
Scope
If object A has a variable called $var and object B has also a variable named $var, these two variables are different. They don't affect each other.
Variables whose name start with "$_" are global. If object A modifies a variable called $_global and object B also modifies a variable named $_global, the two are modifying the same variable. Global variables are useful to share data between objects.
Decorators
The following decorators are available:
let
Syntax: let expression
Available since: 0.2.0
Evaluates expression. Example:
object "test" { requires 0.2.0 state "main" { let "$speed_x = 50" let "$speed_y = $speed_x / 5" set_animation "SD_RING" "0" change_state "go" } state "go" { move "$speed_x" "$speed_y" } }
if
Syntax: if expression new_state_name
Available since: 0.2.0
If the given expression is true (i.e., different than zero), change the state to new_state_name. Example:
object "test" { requires 0.2.0 state "main" { let "$x = 30" if "$x > 20" "go" // since 30 is greater than 20, the expression $x > 20 is true. // therefore, the state will be changed to "go" } state "go" { // ... } }
unless
Syntax: unless expression new_state_name
Available since: 0.2.0
If the given expression is false (i.e., zero), change the state to new_state_name. Example:
object "test" { requires 0.2.0 state "main" { let "$x = 30" unless "$x > 20" "go" // this is the same as: if "not($x > 20)" "go" // since 30 is greater than 20, the expression $x > 20 is true. // therefore, the state will NOT be changed to "go" } state "go" { // ... } }
Operators
From lower to higher precedence, the following operators are available:
- Note: you may use parenthesis to enforce an expression to be evaluated first
- Note 2: expressions may be chained with a comma (','). The result of the whole expression is the result of the last expression of the chain (example: 1, 2, 3+7 returns 10)
- Note 3: an expression whose value is different than zero is considered true. Conversely, zero is considered false.
Assignment operators
Operator | Description | Example | Result |
---|---|---|---|
= | $var = <expression> changes the value of the variable $var to <expression>. The value of $var = <expression> is <expression> | $twoTimesFive = 2*5 | 10 |
+= | $x += <expression> is the same as $x = $x + <expression> | $x = 1, $x += 10 | 11 |
-= | $x -= <expression> is the same as $x = $x - <expression> | $x = 1, $x -= 10 | -9 |
*= | $x *= <expression> is the same as $x = $x * <expression> | $x = 1, $x *= 10 | 10 |
/= | $x /= <expression> is the same as $x = $x / <expression>. Make sure that <expression> is not zero! | $x = 1, $x /= 10 | 0.1 |
^= | $x ^= <expression> is the same as $x = $x ^ <expression> | $x = 2, $x ^= 1+4 | 32 |
Binary logic operators
Operator | Description | Example | Result |
---|---|---|---|
and | an expression "x and y" returns true (1) if, and only if, both x and y are true. If x is false, then y is not evaluated | (1 < 2) and (3 > 4) | 0 |
or | an expression "x or y" returns true (1) if, and only if, x or y (or both) are true. If x is true, then y is not evaluated | (1 < 2) or (3 > 4) | 1 |
Binary comparsion operators
Operator | Description | Example | Result |
---|---|---|---|
== | an expression "x == y" returns true (1) if, and only if, x is equal to y. Otherwise, returns false (0). | 1 == 2 | 0 |
<> | different from | 1 <> 2 | 1 |
> | greater than | 7 > 7 | 0 |
>= | greater than or equal to | 7 >= 7 | 1 |
< | lower than | 3.14159 < 3.14159 | 0 |
<= | lower than or equal to | 3.14159 <= 3.14159 | 1 |
Binary arithmetic operators
Operator | Description | Example | Result |
---|---|---|---|
+ | addition | 1 + 2 | 3 |
- | subtraction | 1 - 2 | -1 |
* | multiplication | 7 * 8 | 56 |
/ | division (the parameter on the right must not be zero!) | 25 / 2 | 12.5 |
mod | division remainder (the parameter on the right must not be zero!) | 25 mod 2 | 1 |
^ | raise to a power | 2^3 | 8 |
Unary operators
Operator | Description | Example | Result |
---|---|---|---|
not | If x is true, not(x) is false. Conversely, if x is false, not(x) is true | not(1 <= 2 and 1 > 2) | 1 |
unary '-' | If x is an expression, -x is the additive opposite of x | 2 * -7 | -14 |
Functions
You may also call functions in your expressions. In the Open Surge Scripting Engine, functions are mathematical entities that receive zero or more parameters (expressions) and return a single number. Example:
... // result: $x is equal to 10 let "$y = sqrt(4) + 1" let "$x = 6.3 + max(3.7, $y)" ...
Mathematical functions
Name | Description | Available since | Example | Result |
---|---|---|---|---|
Constants | ||||
pi() | Returns an approximation of Pi | 0.2.0 | pi() | 3.1415926535 |
infinity() | Returns "infinity". In reality, all it does is to return a huge number | 0.2.0 | infinity() | huge number |
Utilities | ||||
cond(expression, true_val, false_val) | If expression is true, returns true_val. Otherwise, returns false_val | 0.2.0 | cond(1 > 2, 77, 11) | 11 |
clamp(expression, min_val, max_val) | Clamps expression to the given interval.
If expression is lower than min_val, returns min_val. Otherwise, if expression is greater than max_val, returns max_val. Otherwise, returns expression. Note: make sure that min_val <= max_val |
0.2.0 | clamp(88*10 + 2^3, 100, 800) | 800 |
max(a,b) | Returns the maximum between a and b | 0.2.0 | max(2,3) | 3 |
min(a,b) | Returns the minimum between a and b | 0.2.0 | min(2,3) | 2 |
sign(x) | Returns 1 if x >= 0, or -1 otherwise | 0.2.0 | sign( pi() / 2 ) | 1 |
abs(x) | Returns the absolute value of x | 0.2.0 | abs(-7) | 7 |
random(n) | Given a positive integer n, returns a random integer between 0 and n-1, inclusive (each one with a probability of 1/n) | 0.2.0 | random(10) | 7 |
floor(x) | Returns the floor of x (rounds down the value) | 0.2.0 | floor(7.9) | 7 |
ceil(x) | Returns the ceiling of x (rounds up the value) | 0.2.0 | ceil(5.2) | 6 |
round(x) | Rounds x to the nearest integer | 0.2.0 | round(1821.6) | 1822 |
Common real functions | ||||
sqrt(x) | Returns the square root of x | 0.2.0 | sqrt(4) | 2 |
exp(x) | Returns e raised to the x-th power | 0.2.0 | exp(0) | 1 |
log(x) | Returns the natural (base-e) logarithm of x | 0.2.0 | log( exp(7) ) | 7 |
log10(x) | Returns the common (base-10) logarithm of x | 0.2.0 | log10(1000) | 3 |
Trigonometry | ||||
sin(x) | Given x in radians, returns the sine of x | 0.2.0 | sin( pi()/2 ) | 1 |
cos(x) | Given x in radians, returns the cosine of x | 0.2.0 | cos( pi()/2 ) | 0 |
tan(x) | Given x in radians, returns the tangent of x | 0.2.0 | tan(0) | 0 |
asin(x) | Returns the arc sine of x in the interval [-pi/2,pi/2] radians | 0.2.0 | asin(0) | 0 |
acos(x) | Returns the arc cosine of x in the interval [-pi/2,pi/2] radians | 0.2.0 | acos(0.5) * 180 / pi() | 60 |
atan(x) | Returns the arc tangent of x in the interval [-pi/2,pi/2] radians.
Notice that because of the sign ambiguity, this function cannot determine with certainty in which quadrant the angle falls only by its tangent value. You can use atan2 if you need to determine the quadrant. |
0.2.0 | atan(1) * 180 / pi() | 45 |
atan2(y,x) | Returns the arc tangent of y/x, in the interval [-pi/2, pi/2] radians.
|
0.2.0 | atan(10,-10) * 180 / pi() | 135 |
sinh(x) | Returns the hyperbolic sine of x | 0.2.0 | sinh(log(2)) | 0.75 |
cosh(x) | Returns the hyperbolic cosine of x | 0.2.0 | cosh(log(2)) | 1.25 |
tanh(x) | Returns the hyperbolic tangent of x | 0.2.0 | tanh(log(2)) | 0.6 |
deg2rad(x) | Converts from degrees to radians | 0.2.0 | deg2rad(90) | 1.5707963267 |
rad2deg(x) | Converts from radians to degrees | 0.2.0 | rad2deg(1.5707963267) | 90 |
Engine functions
Name | Description | Available since | Example | Result |
---|---|---|---|---|
elapsed_time() | Returns the elapsed number of seconds since the application has started | 0.2.0 | elapsed_time() | 365.1821555 |
dt() | Also known as delta_t or delta_time, returns the time difference, in seconds, between two consecutive frames of the application | 0.2.0 | dt() | 0.0166667 |
fps() | Returns the FPS rate (frames per second) | 0.2.0 | fps() | 60 |
screen_width() | The width of the screen, in pixels | 0.2.0 | screen_width() | 320 |
screen_height() | The height of the screen, in pixels | 0.2.0 | screen_height() | 240 |
music_volume() | Returns the volume of the music, ranging from 0.0 (quiet) to 1.0 (loud) | 0.2.0 | music_volume() | 1 |
music_is_playing() | Returns true (1) if a music is playing, false (0) otherwise | 0.2.0 | music_is_playing() | 1 |
music_duration() | The duration (length) of the playing music, in seconds | 0.2.0 | music_duration() | 7.25 |
number_of_joysticks() | Number of connected joysticks | 0.2.0 | number_of_joysticks() | 1 |
Name | Description | Available since | Example | Result |
---|---|---|---|---|
collectibles() | Returns the number of collectibles | 0.2.0 | collectibles() | 5 |
score() | Returns the score | 0.2.0 | score() | 10750 |
act() | Returns the current act number | 0.2.0 | act() | 1 |
gravity() | Returns the gravity of the level, in pixels per second^2 | 0.2.0 | gravity() | 787.5 |
These functions are related to the observed player.
Name | Description | Available since | Example | Result |
---|---|---|---|---|
player_xpos() | x position of the player | 0.2.0 | player_xpos() | 714 |
player_ypos() | y position of the player | 0.2.0 | player_ypos() | 1997 |
player_spawnpoint_x() | x coordinate of the spawn point of the player | 0.2.0 | player_spawnpoint_x() | 127 |
player_spawnpoint_y() | y coordinate of the spawn point of the player | 0.2.0 | player_spawnpoint_y() | 721 |
player_xspeed() | horizontal speed of the player | 0.2.0 | player_xspeed() | 120 |
player_yspeed() | vertical speed of the player | 0.2.0 | player_yspeed() | 0 |
player_angle() | angle of the player, in degrees | 0.2.0 | player_angle() | 0 |
player_direction() | 1 if the player is facing right; -1 otherwise | 0.2.0 | player_direction() | 1 |
Name | Description | Available since | Example | Result |
---|---|---|---|---|
xpos() | x position of the object | 0.2.0 | xpos() | 714 |
ypos() | y position of the object | 0.2.0 | ypos() | 1997 |
alpha() | alpha value (transparency) | 0.2.0 | alpha() | 0.5 |
angle() | rotation angle, in degrees | 0.2.0 | angle() | 0 |
scale_x() | horizontal scale of the object (the default value is 1.0) | 0.2.0 | scale_x() | 1.0 |
scale_y() | vertical scale of the object (the default value is 1.0) | 0.2.0 | scale_y() | 1.0 |
zindex() | z-index of the object | 0.2.0 | zindex() | 0.5 |
hotspot_x() | x position of the hotspot (animation) | 0.2.0 | hotspot_x() | 16 |
hotspot_y() | y position of the hotspot (animation) | 0.2.0 | hotspot_y() | 16 |
width() | The width, in pixels, of the object | 0.2.0 | width() | 160 |
height() | The height, in pixels, of the object | 0.2.0 | height() | 120 |
animation_id() | number of the current animation | 0.2.0 | animation_id() | 0 |
animation_frame() | current frame of the animation | 0.2.0 | animation_frame() | 0 |
animation_frame_count() | number of frames of the current animation | 0.2.0 | animation_frame_count() | 2 |
animation_speed_factor() | returns the speed multiplier of the current animation (see set_animation_speed_factor) | 0.2.0 | animation_speed_factor() | 1 |
animation_repeats() | true (1) if the current animation repeats, false (0) otherwise | 0.2.0 | animation_repeats() | 1 |
animation_fps() | fps rate of the current animation, defined in the .spr file | 0.2.0 | animation_fps() | 8 |
spawnpoint_x() | x coordinate of the spawn point | 0.2.0 | spawnpoint_x() | 127 |
spawnpoint_y() | y coordinate of the spawn point | 0.2.0 | spawnpoint_y() | 721 |
direction() | 1 if the object is facing right; -1 otherwise | 0.2.0 | direction() | 1 |
Calendar
Name | Description | Range | Available since |
---|---|---|---|
date_sec() | Seconds after the minute | 0-59 | 0.2.0 |
date_min() | Minutes after the hour | 0-59 | 0.2.0 |
date_hour() | Hours since midnight | 0-23 | 0.2.0 |
date_mday() | Days of the months | 1-31 | 0.2.0 |
date_mon() | Months since January | 0-11 | 0.2.0 |
date_year() | Years since 1900 | - | 0.2.0 |
date_wday() | Days since Sunday | 0-6 | 0.2.0 |
date_yday() | Days since January 1st | 0-365 | 0.2.0 |