Learn what Felgo offers to help your business succeed. Start your free evaluation today! Felgo for Your Business


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

Import Statement: import Felgo 3.0



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:

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

duration : alias

See Sprite::duration.

durationVariation : alias

See Sprite::durationVariation.

frameCount : alias

See Sprite::frameCount.

frameDuration : alias

See Sprite::frameDuration.

frameDurationVariation : alias

See Sprite::frameDurationVariation.

frameHeight : int

See Sprite::frameHeight.

frameRate : alias

See Sprite::frameRate.

frameRateVariation : alias

See Sprite::frameRateVariation.

frameSync : alias

See Sprite::frameSync.

frameWidth : int

See Sprite::frameWidth.

frameX : int

See Sprite::frameX.

frameY : int

See Sprite::frameY.

name : alias

See Sprite::name.

randomStart : alias

See Sprite::randomStart.

reverse : alias

See Sprite::reverse.

source : alias

See Sprite::source.

startFrameColumn : int

An alternative to defining frameX, the left position of the first frame in the Sprite animation. If set, the frameX property is automatically calculated based on the column number by multiplying it with the frameWidth.

Note: The first colum (so the left-most frame) starts with column 1, not 0.

startFrameRow : int

An alternative to defining frameY, the top position of the first frame in the Sprite animation. If set, the frameY property is automatically calculated based on the row number by multiplying it with the frameHeight.

Note: The first row (so the top-most frame) starts with row 1, not 0.

to : alias

See Sprite::to.

Qt_Technology_Partner_RGB_475 Qt_Service_Partner_RGB_475_padded