• Home
• Felgo
• GameSpriteSequence

GameSpriteSequence

The GameSpriteSequence contains a list of GameSprite 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 : GameSprite

Methods

• jumpTo(sprite)

Detailed Description

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

A GameSpriteSequence 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 GameSprite.

If you only have one state, or a single animated sprite, an GameAnimatedSprite is the better choice. The GameAnimatedSprite has a reduced set of properties compared to GameSpriteSequence 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.

Felgo Additions to SpriteSequence

GameSpriteSequence enhances the Qt component SpGameSpriteSequenceith 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 GameSprite 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 GameSpriteSequence. Thus existing Qt SpriteSequence code will work for SpGameSpriteSequencebut the added convenience of SpGameSpriteSequenceannot be applied back to normal SpriteSequence components.
• Change frameX, frameY or the source property of a GameSprite element at runtime, which is not possible with the built-in Qt 5 GameSprite component.

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

GameSpriteSequence 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 GameSprite 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 GameSprite animations can then be defined like this:

 import QtQuick
 import Felgo

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

     GameSpriteSequence {
       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 GameSpriteSequence component because otherwise nothing is shown
       // with GameSpriteSequence this is set to the size of the currentSprite, as convenience compared to GameSpriteSequence from Qt5
       // if you set a custom width or height, the current sprite is scaled to that dimension
       //width: 32
       //height: 32

       GameSprite {
         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}
       }
       GameSprite {
         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}
       }
       GameSprite {
         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}
       }
       GameSprite {
         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}
       }
       GameSprite {
         name: "dieLastFrame"
         startFrameColumn: 12
         frameWidth: 32
         frameHeight: 32
         // frameCount is set to 1 by default
         to: {"dieLastFrame":1}
       }

     }// GameSpriteSequence
   }// Scene
 }// GameWindow

This example shows most of the possible interactions with GameSpriteSequence. 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 GameSprite::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 GameSprite::to property needs to be defined.

Advanced GameSpriteSequence Usage

The to Property

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

GameSprite Scaling

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

 EntityBase {
   GameSpriteSequence {
     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
 import QtQuick

 EntityBase {

   GameSpriteSequence {
     id: s1
     // any GameSpriteSequence properties

     GameSprite {
       // any sprite properties
     }
     GameSprite {
       // any sprite properties
     }
   }
   GameSpriteSequence {
     // any GameSpriteSequence properties, can be different than s1

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

Method Documentation