MoveToPointHelper

Provides information for a MovementAnimation or a ColliderBase about the direction and rotation when moving towards a target. More...

Import Statement: import

Properties

Signals

Detailed Description

This component provides information about the direction and rotation when moving towards a target. This is a frequent requirement in games. Moving towards a fixed point, or to a moving entity is possible.

The strength of this component is, that it does all the calculations how far the target is away (distanceToTarget), how many degrees it is away considering the current rotation (absoluteRotationDifference) and in which direction (to the right or to the left) the target is (when outputXAxis is >0 it is to the right, if <0 it is to the left).

This component alone does not move the owningEntity towards the target, but it sets the output properties outputXAxis and outputYAxis. You can connect these to a movement component. Examples for movement components (i.e. components that move an entity) are MovementAnimation, CircleCollider or BoxCollider. In other words, you can simulate what the player would do when moving towards a target. So this component allows using the same game logic for human players and for AI controlled entities.

Output Properties outputXAxis and outputYAxis

The output properties of this component can be used to achieve the desired game logic. In most cases, connecting the outputXAxis and outputYAxis with a movement component is sufficient.

You can compare the outputXAxis and outputYAxis with the outputs of 2-axis controllers used by players, like the thumbstick on a gamepad. In case of the analog thumbstick, the normalized values range from -1 (on the very left) to +1 (on the right side). If the outputXAxis is -1, this means the connected movement component should rotate left, and to the right when outputXAxis is +1. A value of 0 means, there is no need for rotating, because the owningEntity already is rotated towards the target.

Similarly, pressing the Up/Down/Left/Right buttons for player input could also be abstracted with a 2-axis controller, which is exactly what the TwoAxisController provides for player-controlled entities. It has the same output properties like this component, so it is possible to connect the same game logic with different input controllers. For example, one instance of a car entity might be controlled by the user with a TwoAxisController from keyboard or with a JoystickControllerHUD, whereas an AI controlled instance of the car gets controlled by a MoveToPointHelper.

You can add arbitrary complex game logic based on the outputs of this component, like the rotation towards the target or the distance to it. In summary, writing AI logic gets easier with the MoveToPointHelper.

Setting the Target

You have 2 options to define the target of your entity: Setting a point or an object. If you accidentally set both, the target object's position is used and the targetPoint is ignored.

Setting a Target Object

One use-case in games is to move towards another game entity. The other game entity might be moving as well, so the MoveToPointHelper also considers position updates of the target entity. You can set the targetObject property to any object with a position, so it needs not to be a game entity derived from EntityBase, but any QML Item.

Setting a Target Point

When you do not want to follow a moving game entity, you can also set the targetPoint property to a fixed point. This point can then be changed, however, which might come handy for setting the targetPoint to the touch position for instance. So for a game entity to move towards the position where the user tapped onto, the following code can be used:

 Scene {

   MouseArea {
     anchors.fill: parent
     onClicked: {
       moveToPointHelper.targetPoint = Qt.point(mouseX, mouseY)
     }
   }

   GameEntity {
     id: followerEntity

     MoveToPointHelper {
       id: moveToPointHelper
       // the targetPoint gets set from MouseArea
     }

     BoxCollider {
       width: 30; height:20

       // move forwards and backwards, with a multiplication factor for the desired speed
       force: Qt.point(moveToPointHelper.outputYAxis*1000, 0)
       // rotate left and right
       torque: moveToPointHelper.outputXAxis*300
     }
   }
 }

Example Usage

For example, you might have a game entity that can rotate around its axis. It should always rotate towards a moving game entity. To achieve this, the following code can be used:

 Scene {

   GameEntity {
     id: targetEntity
     // this entity moves around, and the followerEntity should follow it
   }

   GameEntity {
     id: followerEntity

     MoveToPointHelper {
       id: moveToPointHelper
       // the entity to move towards
       targetObject: targetEntity
     }

     MovementAnimation {
       target: followerEntity
       property: "rotation"

       // outputXAxis is +1 if target is to the right, -1 when to the left and 0 when aiming towards it
       velocity: 300*moveToPointHelper.outputXAxis
       // alternatively, also the acceleration could be set, depends on how you want the followerEntity to behave

       // start rotating towards the target immediately
       running: true

       // this avoids over-rotating, so rotating further than allowed
       maxPropertyValueDifference: moveToPointHelper.absoluteRotationDifference
     }
   }
 }

If your movement should be done with a physics collider like BoxCollider or CircleCollider, you can set the input values for ColliderBase::force and ColliderBase::torque also by connecting it with the MoveToPointHelper:

 Scene {

   GameEntity {
     id: targetEntity
     // this entity moves around, and the followerEntity should follow it
   }

   GameEntity {
     id: followerEntity

     MoveToPointHelper {
       id: moveToPointHelper
       // the entity to move towards
       targetObject: targetEntity

       // the following all are optional properties for customization:

       // when the distance to the target gets below this value, the targetReached signal is emitted, default is 20
       distanceToTargetThreshold: 20

       // this allows getting the outputYAxis bigger than 0, which is the default
       allowSteerForward: true

       // if this is set and the target is more than 90 away, allow to move backwards, default is false
       allowSteerBackward: false


       // if this is set, the follower would only rotate and not move backwards when the target is more than 90 degrees away, default is false
       stopForwardMovementAtDifferentDirections: false

     }

     BoxCollider {
       width: 30; height:20

       // move forwards and backwards, with a multiplication factor for the desired speed
       force: Qt.point(moveToPointHelper.outputYAxis*1000, 0)
       // rotate left and right
       torque: moveToPointHelper.outputXAxis*300
     }
   }
 }

Property Documentation

[read-only] absoluteRotationDifference : real

This property holds the absolute value of the rotation difference between the owningEntity and the target. It is always bigger or equal than 0 and smaller than 180. If it is bigger than 90 degrees, that means the target is in the different direction. To find out if the target is on the right (clockwise) or on the left (counterclockwise) side of the current direction of the owningEntity, check if outputXAxis is positive or negative. If it is positive, it is on the right side, otherwise on the left.


allowSteerBackward : bool

Set this property to allow the the outputYAxis property to become -1 when the target is back of the owningEntity. You can set it false, if you do not want the owningEntity to move forward, so limit the output properties to only rotating. The default value is true.

This QML property was introduced in Qt 1.5.1.

See also outputYAxis.


allowSteerForward : bool

Set this property to allow the the outputYAxis property to become 1 when the target is in front of the owningEntity. You can set it false, if you do not want the owningEntity to move forward, so limit the output properties to only rotating. The default value is true.

See also outputYAxis.


[read-only] distanceToTarget : real

This property holds the current distance from owningEntity to the target. The distance is the pythagorean distance of the x and y difference. For example, when the owningEntity position is (0/0) and the targetEntity position is (30/40), the distance will be 50 because Math.sqrt((30-0)^2 + (40-0)^2 ) = 50.

When the distanceToTarget gets below distanceToTargetThreshold, the targetReached() signal is emitted.

This property is always positive, so no negative distances can occur.

See also distanceToTargetThreshold.


distanceToTargetThreshold : real

When the distanceToTarget gets below this threshold, the targetReached() signal is emitted. You can handle that in onTargetReached() and perform game code when that happens. The default value is 20.

See also distanceToTarget.


enabled : bool

This property holds whether the output properties are updated. By default, this property is true. You can set it to false to avoid calculating the output properties in order to improve performance.


[read-only] outputXAxis : real

This property holds the imaginary x axis value of a 2-axis controller which can be connected to a rotation input property of supported components. When it is 0, that is equal to no required rotation, similar to no key being pressed on the keyboard. When it is +1, a clockwise rotation should be performed similar to a right key press. When it is -1, a counterclockwise rotation should be performed similar to a left key press.

Currently, outputXAxis will not take values in between -1 and 0 or 0 and +1. If you want to use different output properties based on the absoluteRotationDifference, you can set your own properties based on the rotation difference value.

This property should be connected with a movement component like BoxCollider, CircleCollider or MovementAnimation. This example shows how to connect the outputXAxis property with the rotation property of a MovementAnimation:

 Scene {

   GameEntity {
     id: targetEntity
     // this entity moves around, and the followerEntity should follow it
   }

   GameEntity {
     id: followerEntity

     MoveToPointHelper {
       id: moveToPointHelper
       // the entity to move towards
       targetObject: targetEntity
     }

     MovementAnimation {
       target: followerEntity
       property: "rotation"

       // outputXAxis is +1 if target is to the right, -1 when to the left and 0 when aiming towards it
       velocity: 300*moveToPointHelper.outputXAxis
       // alternatively, also the acceleration could be set, depends on how you want the followerEntity to behave

       // start rotating towards the target immediately
       running: true

       // this avoids over-rotating, so rotating further than allowed
       maxPropertyValueDifference: moveToPointHelper.absoluteRotationDifference
     }
   }
 }

[read-only] outputYAxis : real

This property holds the imaginary y axis value of a 2-axis controller which can be connected to the velocity or force input property of supported components. When it is 0, that is equal to no required movement, similar to no key being pressed on the keyboard. When it is +1, a forward movement should be performed similar to an up key press. When it is -1, a backward movement should be performed similar to a down key press.

Currently, outputYAxis will not take values in between -1 and 0 or 0 and +1. If you want to use different output properties based on the distanceToTarget, you can set your own properties based on the distanceToTarget value.

This property should be connected with a movement component like BoxCollider, CircleCollider or MovementAnimation. This example shows how to connect the outputYAxis property with the force property of a BoxCollider:

 Scene {

   GameEntity {
     id: targetEntity
     // this entity moves around, and the followerEntity should follow it
   }

   GameEntity {
     id: followerEntity

     MoveToPointHelper {
       id: moveToPointHelper
       // the entity to move towards
       targetObject: targetEntity
     }

     BoxCollider {
       width: 30; height:20

       // move forwards and backwards, with a multiplication factor for the desired speed
       force: Qt.point(moveToPointHelper.outputYAxis*1000, 0)

       // rotate left and right, optional
       torque: moveToPointHelper.outputXAxis*300
     }
   }
 }

owningEntity : Object

The object whose current position and rotation is used for calculating the rotation difference and distance to the target. By default, this is set to the parent object where the component is added. But it can be set to any object.


rotationThreshold : real

This property holds when the owningEntity should stop rotating. When the absoluteRotationDifference gets below this threshold, the outputXAxis property is set to 0. This is handy to avoid tiny constant rotations in one direction and then the other, if the angle just changes slightly.

If the movement component with which you connect this property supports to avoid overrotating, then you do not need to set this property because the connected component handles this issue. The MovementAnimation for example supports the overrotation avoidance, by setting the MovementAnimation::maxPropertyValue property to absoluteRotationDifference.

By default, this is set to 5 degrees. If you want to make the owningEntity aim narrower, decrease this value.


stopForwardMovementAtDifferentDirections : bool

Set this property to set the outputYAxis to 0 when the target is more than 90 degrees away from the owningEntity. An absoluteRotationDifference bigger than 90 means the owningEntity points in a different direction than the target. So when set to true, the owningEntity will rotate without moving forward, and start moving forward again when the absoluteRotationDifference gets below 90 degrees.

By default, this is set to false. That means the owningEntity will always move forwards by default, also when the target is in the different direction. So the default setting leads to a bigger distance to travel.


targetObject : Object

The target object to which position the owningEntity should move to. Based on this position, the output properties are set.

This property or targetPoint must be set for this component to work.


targetPoint : point

The point where the owningEntity should move to. Based on this position, the output properties are set.

This property or targetPoint must be set for this component to work. If both targetObject and targetPoint are set, the targetPoint is ignored.


Signal Documentation

onTargetReached()

This handler is called when the distanceToTarget property gets smaller than distanceToTargetThreshold. You can use this function to implement game logic when the target is reached, for example steering towards the next point in a path. That can be done with this code:

 GameWindow {

   property variant waypoints: [
         { x:16,  y:48},
         { x: 112, y: 48 },
         { x: 112, y: 144},
         { x: 16, y: 144 },
         { x: 16, y: 240 },
         { x: 144, y: 240 },
         { x: 144, y: 176 },
         { x: 208, y: 176 },
         { x: 208, y: 16 },
         { x: 336, y: 16 },
         { x: 336, y: 80 },
         { x: 432, y: 80 },
         { x: 432, y: 112 },
         { x: 304, y: 112 },
         { x: 304, y: 208 },
         { x: 464, y: 208 }
     ]

   function getPointFromIndex(index) {
       var wp = waypoints[index];
       return Qt.point(wp.x, wp.y);
   }

   // this can be increased
   property int currentWaypointIndex: 0

   EntityBase {
     // the visual representation of the entity, just for demo purposes
     Rectangle { id: rectangle; width: 20; height: 20}

     MoveToPointHelper {
       id: movetoPointHelper
       // this gets updated automatically, when currentWaypointIndex changes
       targetPoint: waypoints[currentWaypointIndex]

       onTargetReached: {
         // when the waypoint is reached, increase the index

         // check if we have reached the last waypoint
         // if so, move to the first again
         if(currentWaypointIndex+1 == waypoints.length)
           currentWaypointIndex = 0
         else
           currentWaypointIndex++
       }
     }

     BoxCollider {
       width: rectangle.width; height:rectangle.height

       // move forwards and backwards, with a multiplication factor for the desired speed
       force: Qt.point(moveToPointHelper.outputYAxis*1000, 0)

       // rotate left and right
       torque: moveToPointHelper.outputXAxis*300
     }
   } // end of EntityBase

 }

This is essentially what the PathMovement does.


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