Sprites

From Open Surge Wiki
Revision as of 18:55, 12 January 2013 by MatheusRRR (Talk | contribs) (Case study: the ring sprite)

Jump to: navigation, search

Introduction

All objects with an animation are referred to as sprites. A sprite is a picture sheet with all the frames needed to be displayed in an animation. In Open Surge, a sprite is composed by two things:

  • A picture sheet (also known as spritesheet), usually in the PNG format. These files are placed in the images/ folder.
  • A SPR file, which is a textual file telling the engine how to display the sprite properly. These files are placed in the sprites/ folder and they can be opened with any simple text editor like Notepad.

All picture sheets have a transparent color. They differ between games, but Open Surge uses magenta (RGB 255,0,255) as the transparent color.

Case study: the ring sprite

We'll learn by example. Consider the following spritesheet:

images/rings.png (click to resize)

Let's see how Open Surge reads data from your images so that it can be displayed in-game. We will look at the ring sprite file included with the game (sprites/rings.spr).

...

// Ring
sprite "SD_RING"
{
   source_file     "images/rings.png"
   source_rect     0 128 176 16
   frame_size      16 16
   hot_spot        8 12
   
   // spinning
   animation 0
   {
       repeat      TRUE
       fps         16
       data        0 1 2 3 4 5 6 7
   }
   
   // disappearing
   animation 1
   {
       repeat      FALSE
       fps         8
       data        8 9 10
   }
}

...

In the above file, there are several things you will notice:

  • There are lines that begin with //. These lines are there merely for your convenience and are ignored by the engine.
  • sprite "SD_RING": This is what this definition is called. You must make sure that no two sprites have the same name.
  • source_file: This is where the image you are reading from is located. The engine assumes that images are located somewhere in the game directory folder, so you do not need to specify the full file path. Instead, you just have to specify where the images are located in the game folder.
  • source_rect: The first two numbers give the X and Y coordinate, respectively, of the top left corner of the image you are defining. The second two numbers, width and height, respectively, give how big of a rectangle it would take to completely enclose every frame of the animation. These numbers are given in pixels.
  • frame_size: Defines the size of each frame of your animation. In this example, the size of the source rectangle is 176 by 16 pixels, but each piece of the animation is only 16 by 16 pixels.
  • hot_spot: Hot_spot is related to the point where he is in level. Example: If the frame_size is (18,16) and hot_spot (9,8) at the position (0,0) in level, due to its hot_spot, Sprite will is in position (-9, -8).
  • animation <NUMBER>: These are the animations your object can perform. Assuming that your object has N animations, <NUMBER> must vary from 0 to N-1. For example, if you're creating an object with five animations, you would need to specify animation 0, animation 1, ... and animation 4. There are three different things that animations need to be fully defined.
    • repeat: this tells the engine if you want it to keep doing the animation as long as it is the selected one. In this case, while the ring is inactive it will continuously spin because repeat is set to TRUE in animation 0. However, when the active animation changes to 1 (when a player touches it), it will play the animation only one time before disappearing.
    • fps: This defines how fast the engine will cycle through your frames. In this case it plays 16 frames every second for animation 0 and 8 frames per second for animation 1. The higher the fps, the faster the animation.
    • data: This defines which frame you want to play at any particular moment. In this case it plays frames 0-7 and then repeats under animation 0, and plays frames 8-10 and doesn't repeat under animation 1.

Case study: modifying the ring sprite

Now that we've examined a sprite file and determined what each of the components do, we'll modify it so that we replace the standard rings in the game with our own.

Warning: Changing sprite files makes a major change to the game. Make sure to backup your sprite files before you change them, so if something goes wrong, you will be able to restore the original functionality to the game.

images/my_collectibles.png (design by lunarrush)

We'll now edit sprites/rings.spr and modify the SD_RING sprite:

...

// Ring
sprite "SD_RING"
{
   source_file     "images/my_collectibles.png"
   source_rect     1 1 176 16
   frame_size      16 16
   hot_spot        9 12
   
   // idle
   animation 0
   {
       repeat      TRUE
       fps         16
       data        0 1 2 3 4 5 2 6
   }
   
   // end
   animation 1
   {
       repeat      FALSE
       fps         8
       data        7 8 9 10
   }
}

...

Here are some things you should notice right off the bat:

  • We use different lines that start with //, because they help us to keep track of what our sprite is doing. Remember, these are entirely up to the individual user and they aren't required - but they are helpful.
  • sprite "SD_RING", located at the top, remains the same. This is so we don't have to modify any game code to replace all rings with our modified rings. It also means that we must remove the old SD_RING sprite definition from the sprites folder, so the engine won't try to define what a ring is twice. Since we're modifying the original .spr file itself, this shouldn't be a concern.
  • The source_file is different. This is because we have created a new image and it has a different file name than the original.
  • The source_rect is different, since the frames of the new sprite are at a different places inside the new image than the originals were.
  • The frame_size is the same. We have used a standard size rectangle to create our rings, so that they can seamlessly replace the built in rings.
  • The hot_spot is the same. This is because we didn't see any need to change this from what it already was.
  • The animation <NUMBER> lines are the same. As in the original ring sprite, animation 0 specifies the spinning animation and animation 1, the disappearing one.
    • The repeat entries are set to the same values, since the modified ring acts in a similar way compared to the original one.
    • The fps values are the same. This could be modified if we wanted to speed up or slow down the animation.
    • The data values are different. This is because the frames of our modified ring must be presented in a different order to be a complete animation.

Now that we understand how the engine reads these files, it is easier to know what input we need to give it in order for our sprites to be displayed correctly.