• Home

Sprite

The Sprite element defines a series of sprite frames within an image for a SpriteSequence. More...

• List of all members, including inherited members

Properties

• duration : alias
• durationVariation : alias
• frameCount : alias
• frameDuration : alias
• frameDurationVariation : alias
• frameHeight : int
• frameRate : alias
• frameRateVariation : alias
• frameSync : alias
• frameWidth : int
• frameX : int
• frameY : int
• name : alias
• randomStart : alias
• reverse : alias
• source : alias
• startFrameColumn : int
• startFrameRow : int
• to : alias

Detailed Description

The Sprite component specifies a single sprite animation. A sprite animation is a series of single images (also called a sprite frame) which get played after each other depending on the frameRate. To fully specify a sprite, at least the following properties are required: frameCount, frameWidth, frameHeight, source and either frameRate, frameDuration or duration.

Note: For sprites with improved performance use TexturePackerSprite instead.

Felgo Additions to Sprite

Sprite enhances the Qt 5 component Sprite 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 frameWidth and frameX properties independent of the used image file.
• Set the initial frameX or frameY with startFrameColumn or startFrameRow for simpler definitions.
• Change frameX, frameY or the source property at runtime which is not possible with the built-in Qt 5 Sprite component.

Sprite Example

A sample image of a sprite looks like this image:

The sprite consists of 4 frames with 32x32 pixels each, which can be played shortly after each other to simulate a fluid movement. After the last frame is reached, the animation starts at the first frame again. So for this image, the Sprite definition looks like the following:

 SpriteSequence {

   Sprite {
     frameCount:4
     frameWidth: 32
     frameHeight: 32
     source: "squaby-sprite-walking.png"

     // update the animation 20 times per second
     frameRate: 20
   }
 }

Note: With the current version of Felgo and current version of Qt 5, the frames of a Sprite must be placed next to each other horizontally in a single image file. Sprite frames can wrap and continue in the next row though, to adhere with texture size limits which is mostly 2048 pixels for low-end devices or 4096 pixels for high-end devices.

For a performance-enhanced Sprite component which does not have this restriction, use TexturePackerSprite.

Sprite and SpriteSequence

A Sprite is not rendered on its own. Instead, a Sprite is part of a SpriteSequence which takes care of the rendering. Multiple Sprites can be part of a SpriteSequence, which allows switching the currently running Sprite animation. For more details see the SpriteSequence documentation.

If your animation of a game entity only consists of a single Sprite animation, use the AnimatedSprite component instead. So if you want to switch between multiple Sprites, use SpriteSequence, otherwise AnimatedSprite.

For example, a game entity could have multiple states: walking, jumping, whirled by a weapon and dying. These states are exclusive, that means at any time the entity can only be in one of them. Thus only one should be played at a time, which makes it a perfect match for a SpriteSequence. The image for the combined states looks like this:

Property Documentation