Introduction to objects

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.

Overview

Objects are elements that allow users to greatly extend the original Open Surge Engine. They are entities that can be put in levels and that can interact with the player in a way that is specified by the user. This interaction is specified in a text file containing commands.

Objects are composed by a script (an .obj file), a sprite (an .spr file), an image and optionally by sound effects and other resources. Objects can be made by you or by other people. You can download extra objects at the community forums. They usually come in a package (like a .zip file), and installing them is as simple as placing the files in the right folders (example: moving the .obj file to the scripts/legacy/ folder, the .spr file to the sprites/ folder, the .png file(s) to the images/ folder, and so on).

The possibility of creating objects was introduced on version 0.1.4 of the game engine.

Object scripts

This page focuses on the basics of developing object scripts. We assume the reader already knows how to script sprites (i.e., .spr files located in the sprites/ folder).

Object scripts are .obj files located in the scripts/legacy/ folder. Every object described in an object script will be available on the built-in level editor.

The Decorated State Machine Method

Definition
A Decorated State Machine (DSM) is a mathematical abstraction that can be used to describe the behavior of objects. It is composed by a finite number of states and by transitions between these states. Each state can be decorated with decorators, which are actions that the object must perform, or events that it must detect. Only one state can be active at a time, and the initial active state is called "main".

Example

Example of a state machine

Suppose that you want to create a door. Imagine that there are two switches (buttons) nearby: a green one and a red one. If the player touches the green button, the door will be opened. On the other hand, if the player touches the red one, the door will be closed.

That is said to be an informal description of the problem. We need to transform it in something more rigorous. What is a door? We'll show one solution here, but it is not necessarily unique.

A door has two states:

  • Open
  • Closed

If the door is closed, then we associate the following decorators to it:

  • The door must not be passable. Make it behave like an obstacle brick. This is said to be an action.
  • If the player touches the green switch, then the state must be changed to Open. This is said to be an event.

Conversely, if the door is open, we shall associate the following decorators to it:

  • The door must be passable. Make it behave like a passable brick. This is, again, an action.
  • If the player touches the red switch, then the state must be changed to Closed. This is an event.

You may notice that events have a condition and a transition. For any event, if its condition holds true, then its transition will be activated (i.e., the state of the object will be changed). Decorators specified after an event will not be evaluated if the event holds true.

Syntax

Definition
A state is composed by a name and by a sequence of decorators.
Definition
An object description is composed by a name, by zero or more properties and by one or more states.
Definition
An object script is a .obj text file located in the scripts/legacy/ folder that contain one or more object descriptions.

Here's an example of an object script: (comments start with // and end with newline; comments are not taken into consideration when the engine reads the scripts - they're just there for human readability)

// ------------------------------------------------------------------------
// File: power_ring.obj
//
// Here we'll model a (very) simple ring. If the active player touches it,
// then the collectibles counter will be incremented by seven.
//
// We assume that the animation 0 of a sprite called "Power Ring" exists.
// ------------------------------------------------------------------------

object "Power Ring" // Power Ring is the object name.
{
    requires 0.1.4 // this is a property. It specifies that this object requires engine version 0.1.4 or greater to run.
    
    state "main" // main is the initial active state.
    {
        // this is a decorator used to set the animation of this object. This decorator is classified as an action.
        set_animation "Power Ring" 0
        
        // this also a decorator, but unlike the above, this one is classified as an event. If the active player
        // touches this object, then its state will be changed to end.
        on_player_collision "end"
    }
    
    state "end"
    {
        // this decorator adds seven to the collectibles counter. It's an action.
        add_collectibles 7
        
        // destroy is a decorator that tells the game engine to destroy this object from the level. This is also an action.
        destroy
    }
}

In human terms, what is going on?

  • First, we set the animation of this object to the 0th animation of the sprite called "Power Ring". Then we create an event: if the player touches the power ring, the state must be changed to end.
  • If end is the active state, then the ring counter must be incremented by seven and the object must be deleted from the level.

Hopefully this is simple to understand. We can simplify the script to:

object "Power Ring"
{
    requires 0.1.4
    
    state "main"
    {
        set_animation "Power Ring" 0
        on_player_collision "end"
    }
    
    state "end"
    {
        add_collectibles 7
        destroy
    }
}

Note: if you want to try that object out, please note that the "Power Ring" sprite does not exist by default on the game. You may replace it by SD_BLUERING, for example. Please take a look at the Sprites page if you haven't yet.

Questions

How does one know the list of available decorators and their syntax?
By checking the API Reference.
How can I transform my idea into a decorated state machine (DSM)?
This process is called modelling, and this is the whole challenge. There's no "right" or "wrong" answer - how you're going to do it is entirely up to you. You may want to take a look at the Case studies for inspiration.