Difference between revisions of "API Reference"

From Open Surge Engine Wiki
Jump to: navigation, search
(play_level_music)
(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

Stub
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

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

Level-related commands

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.
  • y is a number representing an y-coordinate
  • x is a number representing an x-coordinate
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
Level-related functions
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
Player-related functions

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
Object-related functions
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