Sprite Sheets | Manual | Castle Game Engine

Sprite Sheets

Table of Contents

1. Introduction
2. Video Tutorial
3. Example projects
4. Using sprites
5. Notes for pixel-art games
6. Alternative: Reading Starling and Cocos2d sprite sheet files
- 6.1. URL Parameters (for Starling and Cocos2d formats)
7. Deprecated: TSprite class

1. Introduction

Sprite sheet is a technique for rendering animations:

Each animation is a sequence of still images (aka "frames")
All the frames are packed into one big image (aka "texture atlas")

It is a standard 2D animation technique for pixel-art games.

Note that it is not the only way to make 2D animations. In Castle Game Engine you can also create smooth 2D animations, using bones or even bones+skinning, by creating 2D animations in Spine or even Blender or many other typically-3D authoring software. Creating sprite sheets has a different workflow and achieves a different result. For sprite sheet, you need to create a large set of still frames, which is sometimes easier / sometimes harder than creating an animation in Spine/Blender. Ultimately it results in an animation where you control every pixel of every frame.

2. Video Tutorial

3. Example projects

Platformer demo in examples/platformer/ is a complete platformer demo using this technique.
The template "2D Game" that you can use to create a new project using the CGE editor contains some sprite sheet animations.
Simple demo is also in examples/sprite_sheets/sprite_sheets_demo.

4. Using sprites

The most advised way to use sprite sheets is to create and edit them using our dedicated editor.

Our Sprite Sheet Editor as part of our CGE editor. Just right-click within the "Files" browser at the bottom and use New Sprite Sheet command, or double-click on an existing .castle-sprite-sheet file.

You can create sprite sheet animations in a number of ways:

start from an existing .castle-sprite-sheet file,
or add animation from a series of images,
or import a ready image atlas,
or import a sprite sheet in Starling XML format.

Each animation has its own speed (number of frames per second). You can freely create, modify and rename animations, and move images (frames) between them.

The editor saves sprite sheets in our Castle Game Engine format (.castle-sprite-sheet extension).

The sprite sheet file:

points to a texture atlas (which can be any 2D image that Castle Game Engine can read, like PNG or JPG; see castle-view-image docs for the full list)
and describes frames within the file, and how they compose the final animation.

To add the sprite sheet to a TCastleViewport (see viewports and scenes documentation) create a TCastleScene inside TCastleViewport and assign scene URL, AutoAnimation etc. All standard methods to load and play animations work. You can do this by code (at run-time) or in the CGE editor (at design-time).

5. Notes for pixel-art games

By default, textures have filtering applied, to make them look smooth when scaled.

If you want to have a pixel-art look, you can disable it easily, by

Scene.RenderOptions.MinificationFilter := minNearest;
Scene.RenderOptions.MagnificationFilter := magNearest;

6. Alternative: Reading Starling and Cocos2d sprite sheet files

In addition to our Castle Game Engine format (.castle-sprite-sheet extension), we can also read sprite sheet in these formats:

Starling sprite sheet format (traditionally with .xml extension, in CGE we require you rename them to .starling-xml).
Cocos2D sprite sheet format (traditionally with .plist extension, in CGE we advise (but do not require yet) to use .cocos2d-plist).

Note	Our `.castle-sprite-sheet` format is just an extended version of the Starling XML format, adding features like FPS value that is saved inside `.castle-sprite-sheet` file, and can vary for each animation.

6.1. URL Parameters (for Starling and Cocos2d formats)

When you load a sprite sheet, you can use a special URL syntax to indicate additional parameters. Instead of loading just my_sprite_sheet.starling-xml you can use URLs like this:

my_sprite_sheet.starling-xml#fps:10

my_sprite_sheet.starling-xml#fps:10,anim-naming:strict-underscore

The available parameters now are:

fps:<float> (only for the Starling and Cocos2d formats)

Frames per second, determine the default animation speed. Note that you can later adjust the time at runtime using TCastleSceneCore.TimePlayingSpeed, just like with any TCastleScene.

By default we use 8 frames per second (see DefaultSpriteSheetFramesPerSecond).

Note that this feature is not available for .castle-sprite-sheet files, as there the FPS is stored in the file (and can even be different for each animation). So there’s no point in specifying FPS by an URL.

Note that, regardless of the sprite sheet format, you can always scale time by adjusting MyScene.TimePLayingSpeed.
anim-naming:strict-underscore|trailing-number (only for the Starling format)

Frames in Starling file can be named freely, and it is up to the loader to determine what constitutes an animation. Two values are possible:
- strict-underscore: The default behavior, strict according to the Starling format specification. To recognize subsequent frames of the animation, the animation name and frame number must be separated by an underscore, like this: walk_01, walk_02.
  
  Without the underscore they will be treated as separate animations. So e.g. frames tree1, tree2 would result in 2 animations, each with a single frame. This sometimes make sense, and indeed it is used, when someone wants to employ sprite sheet as a simple way to access a texture atlas with still images.
- trailing-number: The consecutive animation frames do not need any character between animation name and the frame number. So e.g. walk1 and walk2 will work (resulting in animation name walk) just like walk_1 and walk_2 (underscore is optional, but still stripped, so it also results in animation name walk).

Parameters are passed using an anchor separated by a comma, with a colon between the value and the next option name.

7. Deprecated: TSprite class

You can also use TSprite class in CGE to load a sprite, in which case you will have to draw it explicitly. See How to render 2D images/sprites.

We do not advise this approach and it is deprecated now. Reasons:

Using TSprite requires manual code for drawing (you need to know when to draw and manage drawing order yourself). Also UI scaling needs to be manually applied.
TSprite is not affected by physics.
TSprite is not part of the viewport, so there’s no ready concept of camera that sees it.
TSprite is not a component you can visually design in the CGE editor.

Using sprite sheets inside TCastleScene is much more powerful. Also it allows to have simpler CGE API — there’s no new API to move, play animation etc. for sprite sheets this way, you just use TCastleScene API.

To improve this documentation just edit this page and create a pull request to cge-www repository.