{{tag>dragonscript behavior}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:abstractions|Abstraction Layers: How you want to build your Game]] >> [[dragengine:modules:dragonscript:behavior_elements|Behavior Elements]] >> **ECBehaviorActorMoverUnstuck**
</WRAP>

  * [[behaviors_use_cases|Behaviors Explained: By Use-Case]]
  * [[behaviors_a_to_z|Behaviors Explained: From A to Z]]

====== ECBehaviorActorMoverUnstuck ======

Behavior adding support to unstuck actors moved by [[behavior_actormover|ECBehaviorActorMover]].

This behavior helps in situations where an actor moving along a path ends up in a stuck position. This can happen due to other behaviors like [[behavior_avoidcollision|ECBehaviorAvoidCollision]] trying to avoid obstacles as well as due to game events pushing the actor into unfavorable positions.

This behavior attaches to [[behavior_actormover|ECBehaviorActorMover]] to track if actor is moving. If the actor is moving the position of the actor is examined after an interval. If the position does not change by a threshold amount relative to the last tracked position the actor is considered stuck and ECBehaviorActorMover.updatePath() is called to calculate a new path.

The default interval is 3 seconds. The threshold is factor multiplied by the distance the actor would travel unobstructed using the movement speed set in [[behavior_actormover|ECBehaviorActorMover]]. The default threshold is 0.2 (20% of expected movement distance).

These parameters can be adjusted to match the actors.

This behavior can be temporarily disabled at runtime if required. By default the behavior is enabled.

====== Instance Counts ======
This behavior can be used only once on an element.

====== Element Class Properties ======
Element class properties have the prefix ''actorMoverUnstuck.'' .

===== interval =====
Set update interval in seconds.
  * Full name: ''actorMoverUnstuck.interval''
  * Type: float
  * Default Value: 3
  * Restriction: At least 0
  * Example (*.deeclass) <code xml><float name='actorMoverUnstuck.interval'>2</float></code>

===== threshold =====
Set distance threshold. Threshold is percentage of distance.
  * Full name: ''actorMoverUnstuck.threshold''
  * Type: float
  * Default Value: 0.2
  * Restriction: At least 0 and at most 1
  * Example (*.deeclass) <code xml><float name='actorMoverUnstuck.threshold'>0.3</float></code>

====== Events ======

This behavior has no events.

====== Required Behaviors ======

  * [[behavior_actormover|ECBehaviorActorMover]]

====== Optional Behaviors ======

This behavior does not support optional behaviors.

====== Persistency ======

This behavior does not required element class to be persistable (setPersistable).

====== API Documentation ======

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorActorMoverUnstuck.html,ECBehaviorActorMoverUnstuck~@#.

Since DragonScript Module Version ''1.19''

====== Use Cases ======

  * Free actor if it manages to get stuck.

====== Element Class Example ======

This example defines an element which can unstuck itself.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorCollider collider
  public var ECBehaviorColliderAI colliderAI
  public var ECBehaviorLocomotion locomotion
  public var ECBehaviorNavigator navigator
  public var ECBehaviorProjectToGround projectToGround
  public var ECBehaviorRideOn rideOn
  public var ECBehaviorActorMover actorMover
  public var ECBehaviorActorMoverUnstuck actorMoverUnstuck
  func new()
    component = ECBehaviorComponent.new(this, null)
    collider = ECBehaviorCollider.new(this, component)
    colliderAI = ECBehaviorColliderAI.new(this, collider)
    locomotion = ECBehaviorLocomotion.new(this, colliderAI)
    navigator = ECBehaviorNavigator.new(this)
    projectToGround = ECBehaviorProjectToGround.new(this, colliderAI)
    rideOn = ECBehaviorRideOn.new(this, locomotion, projectToGround)
    actorMover = ECBehaviorActorMover.new(this, locomotion, navigator, rideOn)
    actorMover.setConversationActor(conversationActor)
    actorMoverUnstuck = ECBehaviorActorMoverUnstuck.new(this, actorMover)
  end
end
</code>

====== Behavior Factory ======

Using element class supporting adding behaviors the behavior can be added like this:
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<elementClass name='MyClass' class='GenericBehaviorElement'>
  <behavior type='ECBehaviorComponent'/>
  <behavior type='ECBehaviorCollider'/>
  <behavior type='ECBehaviorColliderAI'/>
  <behavior type='ECBehaviorLocomotion'/>
  <behavior type='ECBehaviorNavigator'/>
  <behavior type='ECBehaviorProjectToGround'/>
  <behavior type='ECBehaviorRideOn'/>
  <behavior type='ECBehaviorActorMover'/>
  
  <behavior type='ECBehaviorActorMoverUnstuck'>
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <float name='.interval'>2</float>
  </behavior>
</elementClass>
</code>

====== Live Examples ======

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]