• Home

SpriteSequence

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

• List of all members, including inherited members

Properties

• currentSprite : alias
• defaultSource : url
• goalSprite : alias
• interpolate : alias
• mirrorX : bool
• mirrorY : bool
• running : alias
• sprites : SpriteVPlay

Methods

• jumpTo(sprite)

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
           squaby.jumpTo("walk")
         }
       }
       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

 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
   }
 }

Method Documentation