SpriteSequenceVPlay

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

Import Statement: import VPlay 2.0
Inherits:

Item

Properties

Methods

Detailed Description

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

A SpriteSequenceVPlay 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 SpriteVPlay.

If you only have one state, or a single animated sprite, an AnimatedSpriteVPlay is the better choice. The AnimatedSpriteVPlay 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 TexturePackerSpriteSequenceVPlay instead.

V-Play Additions to SpriteSequence

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

Specifically, it allows you to:

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

SpriteSequenceVPlay 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 SpriteVPlay 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 VPlay 2.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")
       }
     }

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

       SpriteVPlay {
         name: "walk"
         frameWidth: 32
         frameHeight: 32
         frameCount: 4
         startFrameColumn: 1
         frameRate: 20
         // does not exist anymore in qt5, was v-play 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}
       }
       SpriteVPlay {
         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}
       }
       SpriteVPlay {
         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}
       }
       SpriteVPlay {
         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}
       }
       SpriteVPlay {
         name: "dieLastFrame"
         startFrameColumn: 12
         frameWidth: 32
         frameHeight: 32
         // frameCount is set to 1 by default
         to: {"dieLastFrame":1}
       }

     }// SpriteSequenceVPlay
   }// Scene
 }// GameWindow

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

Advanced SpriteSequenceVPlay Usage

The to Property

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

Sprite Scaling

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

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

currentSprite : alias

The name of the Sprite which is currently animating.


defaultSource : url

If this property is set, the source property of all the contained images are assigned this value by default. If a SpriteVPlay child assigned the source property explicitly, this value and not the defaultSource is used.

You can use this property to avoid defining the same source property for all sprites in a SpriteSequenceVPlay when they are the same. The default value is an empty url.


goalSprite : alias

The name of the sprite which the animation should move to. By default, it must be set to an empty string and can be changed after loading.

Note: If you set the goalSprite property to a non-empty string, the app will stall at loading this SpriteSequenceVPlay. This is a Qt 5 issue.

Changing the goalSprite to a target SpriteVPlay referenced with its SpriteVPlay::name property only has an effect if there is a valid path defined with the SpriteVPlay::to property. If the target sprite cannot be reached by transitioning through the to-path, use jumpTo() instead.

See also jumpTo() and SpriteSequence::goalSprite.


interpolate : alias

If true, interpolation will occur between sprite frames to make the animation appear smoother.

Default is false - this is different than the normal SpriteSequence, which has set interpolate to true. In most cases interpolating between sprite frames is not wanted as it makes the animation look blurred, which is why it is set to false by default in V-Play.


mirrorX : bool

This property holds whether the image should be horizontally mirrored.

Note: Mirroring on the horizontal axis is internally achieved by setting the Item::transform property. Thus if you set the transform property explicitly, you need to apply the y-scaling manually.

The default value is false.


mirrorY : bool

This property holds whether the image should be vertically mirrored.

Note: Mirroring on the verical axis is internally achieved by setting the Item::transform property. Thus if you set the transform property explicitly, you need to apply the y-scaling manually.

The default value is false.


running : alias

Whether the active Sprite is animating or not. Default is true.


sprites : SpriteVPlay

The list of SpriteVPlay sprites to draw. Sprites will be scaled to the size of this item. This property is set to the SpriteVPlay children of this SpriteSequenceVPlay item.

As a performance improvement, you can also set it explicitly to the sprites property of another SpriteSequenceVPlay. This avoids creation of multiple SpriteVPlay objects and is thus faster.

Example for shared sprites property:

 import VPlay 2.0
 import QtQuick 2.0

 EntityBase {

   SpriteSequenceVPlay {
     id: s1
     // any SpriteSequence properties

     SpriteVPlay {
       // any sprite properties
     }
     SpriteVPlay {
       // any sprite properties
     }
   }
   SpriteSequenceVPlay {
     // any SpriteSequence properties, can be different than s1

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

This QML property was introduced in V-Play 2.1.1.


Method Documentation

jumpTo(sprite)

This function causes the SpriteSequenceVPlay to jump to the specified sprite immediately, intermediate sprites are not played. The sprite argument is the SpriteVPlay::name of the sprite you wish to jump to.


Videos

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support