API Reference

From Open Surge Wiki
Jump to: navigation, search

The legacy scripting system has been replaced by SurgeScript.

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.

Contents

Overview

This is the API Reference of the legacy scripting system of Open Surge. Remember that legacy scripts are .obj files located in the scripts/legacy/ folder. Please read Introduction to objects if you haven't done it yet.

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 - they will be hidden. Example: ".acid bullet". This may be useful for dealing with 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

object "HUD Life Bar"
{
   // ...
   detach_from_camera
   // ...
}

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 (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. Also, after calling this command, you shouldn't change the state of the object (unless you want to destroy it), otherwise the player won't be locked in the given rectangle.

See also: on_camera_lock

Example:

object ".boss.locker"
{
    requires 0.1.4
    always_active
    hide_unless_in_editor_mode
    
    state "main"
    {
        // the size of the screen is 320x240 pixels.
        // we're locking the camera in such a way that the
        // boss area has four times the area of the screen.
        lock_camera -320 -240 320 240

        // notice that we do not change the state
        // of this object
    }
    
    state "@destroy"
    {
        // the camera and the player will be unlocked
        // this state is called by other object
        destroy
    }
}

object "boss"
{
    requires 0.2.0
    always_active
    
    state "main"
    {
        // ...
        create_child ".boss.locker" 0 0 "locker" // spawn the locker object
        change_state "wait_for_opponent"
    }
    
    state "wait_for_opponent"
    {
        on_camera_lock "loop" // my opponent has arrived
    }
    
    state "loop"
    {
        // ...
    }

    // ...
    
    state "defeated"
    {
        // once you defeat the boss,
        // unlock the player and the camera
        change_child_state "locker" "@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.

Example:

state "move"
{
move 64 64
//the object will move at a speed of 64 to the right (x value is positive) and also down (the y value is positive)
}

kill_player

Syntax: kill_player

Available since: 0.2.0

Kills the observed player.


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.


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.


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.


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.


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.


add_rings

Syntax: add_rings number_of_rings

Available since: 0.1.4

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.


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


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.


disable_player_movement

Syntax: disable_player_movement

Available since: 0.1.4

Disables the platform movement of the observed player.


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.


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.


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.


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 = 20"
let "$x += $speed"
set_player_position "$x" "0"

// RIGHT
let "$speed = 20"
let "$x += $speed * 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.


springfy_player

Syntax: springfy_player

Available since: 0.1.4

Sets the player's "springing" animation. Doesn't actually propel the player upwards.

roll_player

Syntax: roll_player

Available since: 0.1.4

Makes the observed player roll.


enable_player_roll

Syntax: enable_player_roll

Available since: 0.2.0

Enables player's ability to roll.


disable_player_roll

Syntax: disable_player_roll

Available since: 0.2.0

Disables player's ability to roll.


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.


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.


player_enter_water

Syntax: player_enter_water

Available since: 0.2.0

Simulates that the player has just entered the water.

player_leave_water

Syntax: player_leave_water

Available since: 0.2.0

After entering the water, this command restores the physics to normal.

player_reset_underwater_timer

Syntax: player_reset_underwater_timer

Available since: 0.2.0

Prevents that the player drowns inside the water.


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.


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.


bullet_trajectory

Syntax: bullet_trajectory speed_x speed_y

Available since: 0.1.4

The same as move.


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.


mosquito_movement

Syntax: mosquito_movement speed

Available since: 0.1.4

Makes the object move like a mosquito towards the observed player.


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


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


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


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



Object management

destroy

Syntax: destroy

Available since: 0.1.4

Deletes this object from the level.


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.


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.


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.


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
set_absolute_position "xpos() + 20" "0"

// RIGHT: move to the right at a rate of 20 pixels per second
set_absolute_position "xpos() + 20 * dt()" "0"

// RIGHT: move to the right at a rate of 20 pixels per second
move 20 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.


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.


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.



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


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.


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.


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.


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.


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.


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.


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.


Camera events

Events related to the camera.

on_camera_focus

Syntax: on_camera_focus new_state_name

Available since: 0.2.0

Will change the state if the camera is focusing the caller object.

on_camera_focus_player

Syntax: on_camera_focus_player new_state_name

Available since: 0.2.0

Will change the state if the camera is focusing the observed player of the caller object.

on_camera_lock

Syntax: on_camera_lock new_state_name

Available since: 0.2.0

Will change the state if the camera has been locked bylock_camera.

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". See also: Characters


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.


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.


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.


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.


on_player_stop

Syntax: on_player_stop new_state_name

Available since: 0.2.0

Changes the state if the observed player stops.


on_player_walk

Syntax: on_player_walk new_state_name

Available since: 0.2.0

Changes the state if the observed player walks.


on_player_run

Syntax: on_player_run new_state_name

Available since: 0.2.0

Changes the state if the observed player runs.


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.


on_player_roll

Syntax: on_player_roll new_state_name

Available since: 0.2.0

Changes the state if the observed player rolls.


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.


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.


on_player_brake

Syntax: on_player_brake new_state_name

Available since: 0.2.0

Changes the state if the observed player brakes.


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.


on_player_drown

Syntax: on_player_drown new_state_name

Available since: 0.2.0

Changes the state if the observed player drowns.


on_player_duck

Syntax: on_player_duck new_state_name

Available since: 0.2.0

Changes the state if the observed player ducks.


on_player_lookup

Syntax: on_player_lookup new_state_name

Available since: 0.2.0

Changes the state if the observed player looks up.


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.


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.


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.


on_player_death

Syntax: on_player_death new_state_name

Available since: 0.2.0

Changes the state if the observed player dies.


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.


on_player_underwater

Syntax: on_player_underwater new_state_name

Available since: 0.2.0

Checks if the player is underwater.


on_player_speedshoes

Syntax: on_player_speedshoes new_state_name

Available since: 0.2.0

Checks if the player is using speed shoes.


on_player_invincible

Syntax: on_player_invincible new_state_name

Available since: 0.2.0

Checks if the player is invincible.


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.


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.


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.


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.


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.


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.


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.



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.


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.


simulate_button_up

Syntax: simulate_button_up button_name

Available since: 0.2.0

Behaves like button_name is not being pressed.


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.


hide_dialog_box

Syntax: hide_dialog_box

Available since: 0.1.4

Hides all message boxes in the screen.


request_camera_focus

Syntax: request_camera_focus

Available since: 0.2.0

Asks the engine to make the camera focus on this object.


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.


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

Tip: in order to display the "you have got through this level" animation while focusing on the sprite of the player, before calling this command, you may want to call

set_absolute_position player_xpos() player_ypos()

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.


restart_level

Syntax: restart_level

Available since: 0.2.0

Restarts the current level.


save_level

Syntax: save_level

Available since: 0.2.0

Saves the current level. Its effect is similar compared to as if you had pressed Ctrl+F12 in the editor. Please avoid using this command inside a loop, since the engine has to write data to the disk.

Note: objects spawned by other objects usually are not included in the level. This command, however, makes the caller object (and its children) be saved on the level, even if it was not created manually by the user in the level editor.

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.


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.

object .pauser
{
    requires 0.2.0
    always_active
    
    state "main"
    {
        // fire3 is usually mapped to ENTER on the keyboard
        on_button_pressed "fire3" "pause_game"
    }
    
    state "pause_game"
    {
        pause
        return_to_previous_state
    }
}

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

...

Quests

It is possible to have multiple quests running at the same time. Open Surge features a quest stack - think of a stack (pile) of plates, where each plate represents a quest. You can add a plate only to the top of the stack, and only the top-most plate can be removed. So, if you want to remove the plate at the bottom, you have to remove all other plates first, so you'll end up with an empty stack. A stack is a LIFO structure (last-in, first-out), handled in a similar fasion how a stack of trays is handled in a café. Unused trays is picked up by customers, and newly washed trays takes it's place.

Adding a quest to the (top of the) stack is known as push. Removing the top-most quest is known as pop. Also, only the top-most quest is active. All others are dormant.

push_quest

Syntax: push_quest path_to_qst_file

Available since: 0.2.0

Launches the given quest. After the given quest is completed (or when it is aborted), the engine will reload the level in which this command was called. This is useful to make menus, bonus levels, and so on. Example:

push_quest "quests/default.qst"

pop_quest

Syntax: pop_quest

Available since: 0.2.0

Aborts the current quest. The game will then fall back to the quest that was running before the current one. If the current one is the only active quest, then the game will exit.


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 is a deprecated parameter that should be set to zero.

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 specifies whether you want to loop the music or not. Set it to 0 to play it once, or -1 to make it loop.


play_level_music

Syntax: play_level_music

Available since: 0.1.4

Restores the music of the level.


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.


stop_sample

Syntax: stop_sample sound_name

Available since: 0.2.0

Stops the specified sample, if it's playing. Example:

stop_sample "samples/creativecommons.ogg"

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.


Control structures & Fast Loops

Sometimes you need to do some advanced processing. Conditional decorators usually change the state of the target object if a given condition is true. For example,

// there is a delay before handle_brick_collision runs
change_state handle_brick_collision

// this line will never be executed, since the line above changes the state
destroy

After changing the state, the code of the object will not be executed until after the next screen redraw, which might take some time. The control structures presented here allows one to overcome these limitations: you can run code from states other than the active one without having to change it; that is, without having to wait for the next redraw.

// no delay: the state is not changed!
execute handle_brick_collision

// this line will always be executed
destroy

Be careful when using these: there are situations in which you can see a deadlock or a crash (example: state A executes state B, which in turn executes state A again, and so on...).

These are very powerful commands, as long as you understand what you're doing.

execute

Syntax: execute state_name

Available since: 0.2.0

Executes the code inside state_name, without effectively changing the state. In a way, executing state_name is the same as copying and pasting the code written inside it. Example:

// ...
state "main"
{
    execute "handle_brick_collision"
}

state "handle_brick_collision"
{
    // ...
}
// ...

execute ... if

Syntax: execute state_name if condition

Available since: 0.2.0

Executes state_name if condition is true (i.e., non-zero).

// ...
state "main"
{
    execute "handle_brick_collision" if "brick_exists(0,0)"
}

state "handle_brick_collision"
{
    // ...
}
// ...

execute ... unless

Syntax: execute state_name unless condition

Available since: 0.2.0

Executes state_name if condition is false.

execute ... while

Syntax: execute state_name while condition

Available since: 0.2.0

Executes state_name while condition is true. Be careful! If condition never gets false, the engine will freeze, since execute doesn't wait for a redraw. In pseudo-code, this command means:

while <condition> is true:
    execute <state_name>

This command may be used to develop what we call fast loops:

// ...
state "main"
{
    execute "adjust_sensor_position" while "brick_exists(0,0)"
}

state "adjust_sensor_position"
{
    // ...
}
// ...

Note: if state_name changes the state while condition is true, the loop will be stopped.

execute ... for

Syntax: execute state_name for <initialize> <condition> <increment>

Available since: 0.2.0

Executes state_name while condition is true. Be careful! If condition never gets false, the engine will freeze. In pseudo-code, this is the same as:

<initialize>
while <condition> is true:
    execute <state_name>
    <increment>

This command may be used to develop what we call fast loops. The example below illustrates how to create 10 rings at once:

object "Instant Ring Creator"
{
    requires 0.2.0

    state "main"
    {
        // $i counts from 1 to 10
        execute ".create_ring_loop" for "$i=1" "$i<=10" "$i+=1"
        change_state "destroy"
    }

    state ".create_ring_loop"
    {
        create_item 0 "$i*50" 0
    }

    state "destroy"
    {
        destroy
    }
}

Note: if state_name changes the state while condition is true, the loop will be stopped.


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
lerp(a,b,t) Linear interpolation. Usually, t is a number between 0 and 1, inclusive. Returns t*a + (1-t)*b. 0.2.0 lerp(0, 14, 0.5) 7
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 atan2(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
Arrays

Array are contiguous blocks of memory that store variables. Think that they are packages that hold lots of variables. Upon creation, an array is defined to store at most L (L means length) variables. Variables are stored in the cells (or elements) of the array. Note, however, that these variables don't have names: they are accessed through their indexes, ranging from 0 to L-1, inclusive.

Important: after using an array you created (i.e., when you no longer need it), you must delete it! Otherwise, you'll run into a memory leak and the engine will refuse to create new arrays for you. Whenever the game is closed, the engine will automatically destroy any remaining arrays.

Name Description Available since Example Result
new_array(length) Returns a handle (an identification code) to the newly created array.

Note: NEVER call this in an infinite loop (the engine will stop you if you do).

0.2.0 $arr = new_array(10) <handle>
delete_array(handle) Deletes an existing array, returning a null handle. 0.2.0 $arr = delete_array($arr) <null_handle>
set_array_element(handle, index, value) Stores value in the array. Returns that same value. 0.2.0 $seven = set_array_element($arr, 0, 7) 7
array_element(handle, index) Retrieves an element of an array. 0.2.0 $seven = array_element($arr, 0) 7
array_length(handle) The length of the array 0.2.0 $len = array_length($arr) 10
is_array(handle) Returns true if handle identifies a valid array 0.2.0 $yes = is_array($arr) 1
resize_array(handle, new_length) Resizes the given array. Returns handle. 0.2.0 $arr = resize_array($arr, 20) <handle>
clone_array(handle) Clones the array identified by handle, returning a different handle. 0.2.0 $clone = clone_array($arr) <handle>
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
number_of_joysticks() Number of connected joysticks 0.2.0 number_of_joysticks() 1
Audio functions
Name Description Available since Example Result
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
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
lives() Returns the current number of lives 0.2.0 lives() 7
initial_lives() Returns the initial (default) number of lives 0.2.0 initial_lives() 5
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
camera_x() The x position of the camera 0.2.0 camera_x() 160
camera_y() The y position of the camera 0.2.0 camera_y() 120
waterlevel() The y position of where the water begins 0.2.0 waterlevel() 6410
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
player_seconds_remaining_to_drown() The amount of time (in seconds) the player has underwater until they drown. 0.2.0 player_seconds_remaining_to_drown() 30
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
Bricks

Due to optimizations on the engine, bricks that are too far away from the visible play area may be considered as non-existent. Passable bricks will also be considered as non-existent.

Name Description Available since Example Result
brick_exists(offset_x, offset_y) Returns 1 if a brick located at an offset from the object exists, or 0 otherwise. 0.2.0 brick_exists(0,0) 1
brick_type(offset_x, offset_y) Returns 1 if a brick at the given offset is an obstacle, 2 if it's a cloud, or 0 if it's passable/non-existent. 0.2.0 brick_type(0,0) 1
brick_angle(offset_x, offset_y) Returns the angle, in degrees (from 0 to 359, inclusive), of a brick at the given offset. 0.2.0 brick_angle(0,0) 45
brick_layer(offset_x, offset_y) Returns 0 if the located brick is on the default layer, 1 if it's on the green layer, or 2 if it's on the yellow layer. 0.2.0 brick_layer(0,0) 0
obstacle_exists(offset_x, offset_y) Returns 1 if, and only if, an obstacle (solid brick, solid item or solid object) located at an offset from the object exists. 0.2.0 obstacle_exists(0,0) 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



Misc

launch_url

Syntax: launch_url url

Available since: 0.2.0

Launches the given URL using the default browser. Remember to change the state after calling this.

Supported protocols: http, https, ftp, mailto.

Example:

object "URL Launcher"
{
    requires 0.2.0
    always_active
    
    state "main"
    {
        launch_url "http://www.wikipedia.org"
        change_state "trap"
    }
    
    state "trap"
    {
    }
    
    // one could also try "mailto:your_email@server.org"
}

reset_globals

Syntax: reset_globals

Available since: 0.2.0

Deletes all arrays and global variables.