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


The GameSprite element defines a series of sprite frames within an image for a GameSpriteSequence. More...

Import Statement: import Felgo 4.0



Detailed Description

The GameSprite 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.

Felgo Additions to GameSprite

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

Specifically, it allows you to:

GameSprite 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 GameSprite definition looks like the following:

 GameSpriteSequence {

   GameSprite {
     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 GameSprite must be placed next to each other horizontally in a single image file. GameSprite 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 GameSprite component which does not have this restriction, use TexturePackerSprite.

GameSprite and GameSpriteSequence

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

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

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 GameSpriteSequence. The image for the combined states looks like this:

Property Documentation

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

An alternative to defining frameX, the left position of the first frame in the GameSprite 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 GameSprite 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