Interpolates an entity along a path and rotates it towards the target points. More...
| Import Statement: | import Felgo 4.0 |
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.
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 Felgo import QtQuick // 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.
|
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.
|
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.
Note: The corresponding handler is onPathCompleted.
|
waypointReached(int waypointIndex) |
This handler is called when a waypoint with the index waypointIndex is reached.
Note: The corresponding handler is onWaypointReached.
|
start() |
|
stop() |
