PathMovement

Interpolates an entity along a path and rotates it towards the target points. More...

Import Statement: import VPlay 2.0

Properties

Signals

Methods

Detailed Description

This component allows to move an object along waypoints of a path and automatically rotating towards the next waypoint. After the end of the path is reached, a pathCompleted() signal is emitted.

The required properties for the PathMovement are waypoints and velocity. The velocity defines with how many pixels per second the owningEntity moves. By default, the target of the position interpolations is the parent item, but it can be set manually with the property owningEntity. The completePathAnimationDuration gets calculated based on the waypoints and the defined velocity.

The entity is automatically rotated towards the next waypoint within rotationAnimation milliseconds. The rotation is not applied physically correct, i.e. the animated target will not move in the direction of its previous rotation, but it stays on the direct lines between the waypoints. If you want the animation behave realistically correct, you can use the MoveToPointHelper and a BoxCollider or CircleCollider. For such an example see the MoveToPointHelper::onTargetReached documentation.

You can start, stop and pause the path movement similar to normal Animation elements. Also looping is possible.

Example Usage

The following example moves the EntityBase along the waypoints. The entity moves with 100 px per second along each path line segment, and rotates towards the next waypoint within 200 milliseconds. After the last waypoint is reached, the entity is removed.

 import VPlay 2.0
 import QtQuick 2.0 // a QtQuick import is required for loops: Animation.Infinite

 EntityBase {
     id: entity

   PathMovement {
       velocity: 100
       rotationAnimationDuration: 200

       waypoints: [
         {x:0, y:0},
         {x:100, y:0},
         {x:100,  y:100},
         {x:0, y:100}
       ]

       onPathCompleted: {
           console.debug("last waypoint reached, destroy the entity");
           entity.removeEntity();
       }
   }
 }

You could also set the loops property to Animation.Infinite, to endlessly move along the waypoints. If loops is set, the entity is moved from the last waypoint to the first automatically.

As an alternative to the PathMovement, you could also use the QML PathView element. Its disadvantage is that you cannot rotate the entity towards the next waypoint. But it allows you to define different paths like Bezier curves.

Property Documentation

completePathAnimationDuration : int

This property holds the duration in milliseconds for the path movement from the first to the last waypoint. It is automatically calculated based on the velocity and the waypoints and is read-only.

If the PathMovement is set up like in the following example, the completePathDuration will be 1 second. Each of the 2 path segment is 50 px long, so with the velocity of 100 px per second, the result is 1 second.

 EntityBase {
     id: entity

   PathMovement {
       velocity: 100

       waypoints: [
         { x:0, y:0},
         { x:50, y:0},
         { x: 50, y: 50 }
       ]

       onPathCompleted: {
           console.debug("last waypoint reached, destroy the entity");
           entity.removeEntity();
       }
   }
 }

currentWaypointIndex : int

This read-only property holds the current index of the path waypoints. It starts with 0 when the owningEntity is in between the first and the second waypoint. When the second waypoint is reached, it gets set to 1 and so on.

When onPathCompleted() is called, the value is waypoints.length-1.


loops : int

This property holds the number of times the path movement will repeat from the first to the last waypoint.

By default, loops is 1: the path movement starts to interpolate from the first waypoint, and stops at the last waypoint.

If set to Animation.Infinite, the animation will continuously repeat until it is explicitly stopped - either by setting the running property to false, or by calling the stop() method.

If loops is set to anything else than the default value 1, the movement will interpolate from the last waypoint to the first.


paused : bool

This property holds whether the path movement interpolation is paused. By default, it is not paused.


rotationAnimationDuration : int

This property holds the duration how long it takes to rotate towards the next waypoint in ms. The default is 200.


rotationAnimationEnabled : bool

This property holds whether the rotation animation towards the next waypoint is applied. By default, it is true.


running : bool

This property holds whether the path movement interpolation is running. By default, the component will start with running set to true.


velocity : real

The pixels per second how fast the owningEntity moves along the path. If the velocity is set to 50 for example and the first waypoint is set to {x:50, y:0}, the waypoint will be reached after 1 second. If the first waypoint is set to {x:30, y:40}, the waypoint will also be reached after 1 second, because the distance from the origin point 0/0 to the first waypoint is 50 pixels.

The completePathAnimationDuration is automatically calculated based on the velocity and the waypoints. It is the sum of durations for each individual waypoint.

The default velocity is 100.


waypoints : variant

An array of waypoints of the path, which the owningEntity moves along. The entity moves straight from one point to the next, and gets rotated towards it within rotationAnimationDuration milliseconds.

The completePathAnimationDuration is calculated based on this property and the velocity - the longer the distance between the waypoints, the longer the duration will be.

Note: The position of the owningEntity is set to the first waypoint position.

This is an example of a rectangular movement, which will last 4 seconds to complete and then start from the beginning:

 EntityBase {

   PathMovement {
     velocity: 100
     loops: Animation.Infinite

     waypoints: [
       {x:0, y:0},
       {x:100, y:0},
       {x:100, y:100},
       {x:0, y:100}
       ]
   }
 }

You can also change the waypoints during the animation. In that case, the currently running path movement will be stopped if there is one running, and the movement starts with the first waypoint again.


Signal Documentation

pathCompleted()

This handler is called when the last waypoint of the path is reached. The position of owningEntity will be the position of the last waypoint.

When loops is set to Animation.Infinite, this will never be called. When loops is set to a value bigger than 1, this handler is only called once, not every time it reaches the first waypoint again.


waypointReached(int waypointIndex)

This handler is called when a waypoint with the index waypointIndex is reached.


Method Documentation

start()

Call this function to start the path movement.

If the path movement is already running, calling this method has no effect. The running property will be true following a call to start().

See also running.


stop()

Call this function to stop the path movement.

If the path movement is not running, calling this method has no effect. The running property will be false following a call to stop().

See also running.


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