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.
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
You can create sprite sheet animations in a number of ways:
start from an existing
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 (
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
TCastleViewport and assign scene
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).
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;
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
Cocos2D sprite sheet format (traditionally with
.plist extension, in CGE we advise (but do not require yet) to use
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:
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
By default we use 8 frames per second (see
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
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:
Without the underscore they will be treated as separate animations. So e.g. frames
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.
walk2 will work (resulting in animation name
walk) just like
walk_2 (underscore is optional, but still stripped, so it also results in animation name
Parameters are passed using an anchor separated by a comma, with a colon between the value and the next option name.
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. Using sprite sheets inside
TCastleScene is much more powerful, and also it allows to have simpler CGE API (since you just use
TCastleScene for all animations, sprite sheet or not).
To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.