Case study 1: Simple Enemy

From Open Surge Wiki
Jump to: navigation, search

Introduction

We'll use the Open Surge scripting system to create a simple enemy that can be used in the game. The graphics of the enemy are essentially the same as Celdecea's Lady Bugsy, but we have simplified and recolored the sprite.

Before we create any object, we have to clearly define what do we want to make. In our particular case, what will this object do?

  • It will behave like an enemy
  • It will be affected by gravity
  • It will just keep walking left and right (no Artificial Intelligence at this time)

Making the sprites

Before we code the object itself, we must create the sprites. Luckily, an image containing the animation of our enemy has already been made. Since this is very similar to Celdecea's Lady Bugsy, but has a blue color, let's call it Sir Bugsy. ;)

Save the following image to images/sir_bugsy.png

Sir bugsy.png

Notice that every frame of our animation has 52x30 pixels. We have four frames in the same row, extending from position (0,0) to (208,30) of the image. This is the walking animation, and it's everything we need.

Using a simple text editor such as Notepad or Vim, create the file sprites/sir_bugsy.spr . Add the following contents to it:

// Sir Bugsy sprite
sprite "Sir Bugsy"
{
    source_file             "images/sir_bugsy.png"
    source_rect             0 0 208 30
    frame_size              52 30
    hot_spot                26 30

    // walking animation
    animation 0
    {
        repeat              TRUE
        fps                 8
        data                0 1 2 3
    }
}

This simple text tells the game engine what the "Sir Bugsy" sprite is. If you're unsure what some of these commands mean, please check out the Sprites page.

Writing the script

Basic sketch

Let's code the enemy. Using the same simple text editor as before, create the file objects/sir_bugsy.obj . Add the following contents to it:

// Sir Bugsy
object "Sir Bugsy"
{
    requires 0.1.4

    state "main"
    {
    }
}

This is a basic sketch valid for any object. What does it do?

  • This object has a name, Sir Bugsy.
  • It requires engine version greater or equal than 0.1.4 to run.
  • The initial active state of the object, main, is blank. Every object must have a main state.

If you launch the game and run the built-in level editor, you'll see that the object is already there. But it does nothing, in fact:

Sir bugsy e1.png

Adding animation

The first thing to do is to add the correct animation to the object. Change the contents of objects/sir_bugsy.obj to:

// Sir Bugsy
object "Sir Bugsy"
{
    requires 0.1.4

    state "main"
    {
        set_animation "Sir Bugsy" 0
    }
}

Remember that we have just created sprites/sir_bugsy.spr? set_animation is a decorator that tells the game engine to import the animation we have defined in the .spr file (more details on this can be found in the API Reference). If you launch the built-in level editor again, you'll see that the object looks different already:

Sir bugsy e2.png

However, putting it into the level is not very useful right now. The object does nothing.

Adding the behavior

Let's make Sir Bugsy behave the way we want it to behave. Remember the list from above?

  • It will behave like an enemy
  • It will be affected by gravity
  • It will just keep walking left and right

We can achieve that by adding the corresponding decorators to the main state. In fact, we'll add the following decorators:

  • enemy, which receives one parameter: score. This makes the object behave like an enemy that may be killed or may hurt the player, depending whether the user is attacking or not.
  • gravity, which makes this object be affected by gravity
  • walk, which receives one parameter: speed, in pixels per second. This makes the object walk left and right.
  • look_at_walking_direction. This is just to make the enemy look nice. It's self explanatory.

More details on this can be found in the API Reference.

Now, just change the object script to:

// Sir Bugsy
object "Sir Bugsy"
{
    requires 0.1.4

    state "main"
    {
        set_animation "Sir Bugsy" 0
        enemy 100
        gravity
        walk 100.0
        look_at_walking_direction
    }
}

That's it. Sir Bugsy is now an enemy that, if killed, adds 100 to the score counter. The object is affected by gravity and walks around at a speed of 100.0 pixels per second.

Launch the built-in level editor again. You're now able to put Sir Bugsy in your levels. It will behave just like you expect it to. Congratulations!

Distributing your object

You're proud of your work and now you want to share it with others, so other people will be able to use Sir Bugsy in the levels they make. You can just create a .zip file containing:

  • images/sir_bugsy.png
  • sprites/sir_bugsy.spr
  • objects/sir_bugsy.obj

That's all.

While this is a simple case, people are in fact sharing custom objects at the community forums.

Conclusion

We hope that the reader has now a better understanding of the object scripting system. We have designed it to be very simple to create and to distribute objects.

Basically, objects are composed by an image (containing the animations), a .spr file (containing the definition of the sprite) and a .obj file (containing the object script). Objects may play audio as well, but that's for another tutorial.

The API Reference contains the complete documentation of the commands of the object scripting system.

Have fun scripting! Thank you for reading!