Introduction to objects

From Open Surge Engine Wiki
Revision as of 21:43, 1 September 2010 by Alexandre (Talk | contribs) (Questions)

Jump to: navigation, search

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 objects folder, the .spr file to the sprites folder, the .png file(s) to the images folder, and so on).

If you develop your own objects, we encourage you to contribute to the Open Surge community by sharing them at the forums.

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 objects/ folder. Every object described in an object script will be available on the built-in level editor.

The Decorated State Machine Method

Example of a state machine
Definition
A decorated state machine 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 small actions that the object must perform, or events that this object must detect. Only one state can be active at a time, and the initial active state is called "main".
Problem
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. 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. 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 unless the event holds false.

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 objects/ 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: objects/power_ring.obj
//
// Here we'll model a (very) simple ring. If the active player touches it,
// then the ring 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 ring counter. It's an action.
        add_rings 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 animation and create an event: if the player touches the power ring, then the state must be changed to end.
  • If the player touches the power ring, then the ring counter must be incremented by seven and the object must be deleted from the level.

Hopefully this is simple to understand.

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. This is closely related to abstraction. 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 (links at the main page).