V-Play has a new name, say hi to Felgo!Learn More


The SpriteSequence contains a list of Sprite elements and allows switching between them with only one active at a time. More...

Import Statement: import Felgo 3.0




Detailed Description

SpriteSequence renders and controls a list of sprite animations. It allows defining multiple sprites within a single image and allows switching between the Sprite items with only one active at a time. The first Sprite child is visible and played by default.

A SpriteSequence is useful if you have a game entity that can have multiple exclusive states like walking, jumping and dying. Exclusive state means that only a single state can be active at a single time, and each state should have a different Sprite.

If you only have one state, or a single animated sprite, an AnimatedSprite is the better choice. The AnimatedSprite has a reduced set of properties compared to SpriteSequence because it does not need to switch between the sprites, but it also has finer animation control with the option to advance single frames manually.

Note: For sprites with improved performance use TexturePackerSpriteSequence instead.

Felgo Additions to SpriteSequence

SpriteSequence enhances the Qt 5 component SpriteSequence with Content Scaling and Dynamic Image Switching Support & Density Independence.

Specifically, it allows you to:

  • Use the ideal image for memory and loading times based on the Felgo File Selectors.
  • Always has the same logical size for easy positioning in a Scene. This approach is also called Content Scaling.
  • Set a defaultSource property for all Sprite children.
  • The interpolate property is set to false by default, because at sprite animations interpolations usually looks blurry and should be deactivated by default.
  • Set the mirrorX and or mirrorY property.
  • The width & height properties are set automatically to the currentSprite dimensions. If you explicitly define a width or height, the currentSprite will be scaled to this size as it is done in SpriteSequence. Thus existing Qt 5 SpriteSequence code will work for SpriteSequence, but the added convenience of SpriteSequence cannot be applied back to normal SpriteSequence components.
  • Change frameX, frameY or the source property of a Sprite element at runtime, which is not possible with the built-in Qt 5 Sprite component.

See the Felgo Script for Multi-Resolution Asset Generation how to create sprite sheets from single sprite frames and scale them down automatically.

SpriteSequence Example

Take for example a game entity that has multiple states: walking, jumping, whirling and dying. The game entity can only be in one state at once, and this state is switched by the game logic. Each logical state has a different Sprite animation to be played. You can now pack all the sprites into one texture to gain the maximum performance, that looks like this image:

Because multiple sprites are contained in a single image, this is called a SpriteSheet. The different Sprite animations can then be defined like this:

 import QtQuick 2.0
 import Felgo 3.0

 GameWindow {

   Scene {

     Row {
       spacing: 4
       SimpleButton {
         text: "walk"
         onClicked: {
           // NOTE: setting goalSprite only works if there is a way with the to-property to the target sprite
       SimpleButton {
         text: "whirl"
         onClicked: squaby.jumpTo("whirl")
       SimpleButton {
         text: "jump"
         onClicked: squaby.jumpTo("jump")
       SimpleButton {
         text: "die"
         onClicked: squaby.jumpTo("die")

     SpriteSequence {
       id: squaby

       // NOTE: the goalSprite MUST be an empty string initially, otherwise the app crashes! qt5 issue!
       // so this doesnt work: goalSprite: "walk"
       // the first sprite in the list is the one played initially

       defaultSource: "squabySpritesheet.png"

       // this only must be set for the original Qt 5 SpriteSequence component because otherwise nothing is shown
       // with SpriteSequence this is set to the size of the currentSprite, as convenience compared to SpriteSequence from Qt5
       // if you set a custom width or height, the current sprite is scaled to that dimension
       //width: 32
       //height: 32

       Sprite {
         name: "walk"
         frameWidth: 32
         frameHeight: 32
         frameCount: 4
         startFrameColumn: 1
         frameRate: 20
         // does not exist anymore in qt5, was Felgo specific
         //running: true
         // optionally provide a name to which animation it should be changed after this is finished
         //to: "whirl"
         // if there is no target with to with goalSprite, it wouldnt work! thus a weight of 0 must be set
         to: {"jump":0, "walk": 1}
       Sprite {
         name: "whirl"
         frameWidth: 32
         frameHeight: 32
         frameCount: 2
         startFrameColumn: 14
         // this tests if another sprite source is displayed, by not using the default spriteSheetSource property
         source: "squatanBlue.png"
         frameRate: 20
         // after a while, with 10% probability, switch to die animation
         to: {"die":0.1, "whirl":0.9}
       Sprite {
         name: "jump"
         frameWidth: 32
         frameHeight: 32
         frameCount: 4
         startFrameColumn: 5
         frameRate: 10
         // returns to walking animation after a single jump animation (100% weight moving to walk)
         to: {"walk":1}
       Sprite {
         name: "die"
         frameWidth: 32
         frameHeight: 32
         frameCount: 3
         startFrameColumn: 10
         frameRate: 10
         // play die animation once and then stay at the last frame
         to: {"dieLastFrame":1}
       Sprite {
         name: "dieLastFrame"
         startFrameColumn: 12
         frameWidth: 32
         frameHeight: 32
         // frameCount is set to 1 by default
         to: {"dieLastFrame":1}

     }// SpriteSequence
   }// Scene
 }// GameWindow

This example shows most of the possible interactions with SpriteSequence. The default animation that is played is the walk animation, because it is the first child. All the sprites share the same image (the same SpriteSheet) defined with the defaultSource property. For demonstration purpose, in this example the whirl animation is set to another Sprite::source which is still possible to overwrite the defaultSource with a custom source for a sprite.

To switch between sprite animations, set the goalSprite property to whirl for example, which will start the whirling animation until another goalSprite is set. Another way of changing animations is by calling jumpTo(), which has the same effect as changing goalSprite with the added benefit that no transition to the sprite with the Sprite::to property needs to be defined.

Advanced SpriteSequence Usage

The to Property

If the Sprite::to property is set, the animation will switch to this animation.

Sprite Scaling

The sprites are scaled to the size of SpriteSequence. Note that it is required to define a width & height. You can use the size of SpriteSequence from outside components like in this example:

 EntityBase {
   SpriteSequence {
     id: spriteSequence
     // in here multiple sprites are defined

   MouseArea {
     // anchoring is possible, as the size changes with the current animation
     anchors.fill: spriteSequence

     // onClicked: ...

Property Documentation

currentSprite : alias

The name of the Sprite which is currently animating.

defaultSource : url

If this property is set, the source property of all the contained images are assigned this value by default. If a Sprite child assigned the source property explicitly, this value and not the defaultSource is used.

You can use this property to avoid defining the same source property for all sprites in a SpriteSequence when they are the same. The default value is an empty url.

goalSprite : alias

The name of the sprite which the animation should move to. By default, it must be set to an empty string and can be changed after loading.

Note: If you set the goalSprite property to a non-empty string, the app will stall at loading this SpriteSequence. This is a Qt 5 issue.

Changing the goalSprite to a target Sprite referenced with its Sprite::name property only has an effect if there is a valid path defined with the Sprite::to property. If the target sprite cannot be reached by transitioning through the to-path, use jumpTo() instead.

See also jumpTo() and SpriteSequence::goalSprite.

interpolate : alias

If true, interpolation will occur between sprite frames to make the animation appear smoother.

Default is false - this is different than the normal SpriteSequence, which has set interpolate to true. In most cases interpolating between sprite frames is not wanted as it makes the animation look blurred, which is why it is set to false by default in Felgo.

mirrorX : bool

This property holds whether the image should be horizontally mirrored.

Note: Mirroring on the horizontal axis is internally achieved by setting the Item::transform property. Thus if you set the transform property explicitly, you need to apply the y-scaling manually.

The default value is false.

mirrorY : bool

This property holds whether the image should be vertically mirrored.

Note: Mirroring on the verical axis is internally achieved by setting the Item::transform property. Thus if you set the transform property explicitly, you need to apply the y-scaling manually.

The default value is false.

running : alias

Whether the active Sprite is animating or not. Default is true.

sprites : SpriteVPlay

The list of Sprite sprites to draw. Sprites will be scaled to the size of this item. This property is set to the Sprite children of this SpriteSequence item.

As a performance improvement, you can also set it explicitly to the sprites property of another SpriteSequence. This avoids creation of multiple Sprite objects and is thus faster.

Example for shared sprites property:

 import Felgo 3.0
 import QtQuick 2.0

 EntityBase {

   SpriteSequence {
     id: s1
     // any SpriteSequence properties

     Sprite {
       // any sprite properties
     Sprite {
       // any sprite properties
   SpriteSequence {
     // any SpriteSequence properties, can be different than s1

     // the sprites are shared from s1
     sprites: s1.sprites

This QML property was introduced in Felgo 2.1.1.

Method Documentation

jumpTo( = sprite)

This function causes the SpriteSequence to jump to the specified sprite immediately, intermediate sprites are not played. The sprite argument is the Sprite::name of the sprite you wish to jump to.

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
create apps
create games
cross platform
native performance
3rd party services
game network
level editor
easiest to learn
biggest time saving
best support