{{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]] >> **ECBehaviorConversationActor**
</WRAP>

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

====== ECBehaviorConversationActor ======

Behavior adding conversation actor support to actors.

Provides ConversationActor with basic properties set depending on what behaviors are present before this behavior. In addition supports for other behaviors to modify and extend the ConversationActor namely adding game and condition commands or modify sub title boxes using istener support.

Basic ConversationActor is set up like this:
  * SubtitleTheme: Set to null to use playback sub title box gui theme
  * Name: Set from element class property ''convoActor.name''
  * setVoiceSpeaker: Assign a speaker used for voice acting
  * [[#optional_behaviors|Optional behaviors]]

This behavior does not update itself automatically during thinking because locomotion handling in actors needs a specific order to work correctly:
  * ECBehaviorConversationActor.updateLocomotion(elapsed)
  * update locomotion using actor action, player input and other means
  * ECBehaviorConversationActor.updateAnimator(elapsed, actor.getAnimatorInstance())
  * apply actor animator instance to component
  * ECBehaviorConversationActor.applyAnimations()

ECBehaviorConversationActor.updateLocomotion() has to be called before calling Locomotion.update() since the HeadLookAtPlayback modifies the locomotion goal parameters.

ECBehaviorConversationActor.updateAnimator() has to be called before applying animations since playback instances use the base animator instance controllers as input.

It is possible to use this behavior on non-actor elements. In this case add first a behavior providing animator support and assign it to the behavior. Then this behavior will register and update in the right time. Supports [[behavior_actoranimated|ECBehaviorActorAnimated]], [[behavior_animated|ECBehaviorAnimated]] or [[behavior_twostateanimated|ECBehaviorTwoStateAnimated]] for this use-case.

//Bone Name Remapping//

Behavior supports re-mapping bone names in response to ConversationActor.getMatrix() and ConversationActor.getInverseMatrix() . Define bone mappings using setBoneMapping(). The mappings are persistent until changed. Bone mappings are useful for various situations including the following ones:
  * Use element with mismatching bone names. Using bone mapping the required conversation bone names are mapped to the actual rig bone name without needing to change the conversation scripts.
  * Dynamically change the meaning of a target bone. This can be used to refer to either the left or right hand of an actor by using a virtual bone name. Script code can change the mapping for the bone at any time to make conversation scripts always refer to the right actor hand.

See also:
  * [[gamedev:deigde:editors:conversation|IGDE Conversation Editor]]
  * [[dragengine:modules:dragonscript:guitheme|Gui Themes]]

====== Instance Counts ======
This behavior can be used multiple times on an element to add multiple custom colors to mainpulate. Use the behavior identifier to tell them apart.

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

===== id =====
Set unique identifier of conversation actor.
  * Full name: ''convoActor.id''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='convoActor.id'>merchant</string></code>

===== aliasId =====
Set alias identifier of conversation actor. Has to be unique inside the same conversation playback. Allows to add any actor with a known alias. For example the game can have conversation actors with id ''merchant1'' and ''merchant2''. While talking to one of the two they can be added with the alias ''npc''. This way conversation scripts can refer to this actor using id ''npc'' without needing to know which actor it is actually or they can use the actual id of the actor. Game scripts can use custom alias instead of this one.
  * Full name: ''convoActor.aliasId''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='convoActor.aliasId'>npc</string></code>

===== name =====
Set unicode display name.
  * Full name: ''convoActor.name''
  * Type: unicode string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='convoActor.name'>Tools Merchant</string></code>

===== subtitleSelector =====
Set subtitle selector. This allows to add designer selector to the game gui theme to style conversation panels shown for this conversation actor.
  * Full name: ''convoActor.subtitleSelector''
  * Type: unicode string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='convoActor.subtitleSelector'>ConvoActor.Merchant.Tools</string></code>

===== headRotatorBone =====
Set head rotator bone. Using a head rotator bone improves the head and eye look-at handling. Typically this is the head bone.
  * Full name: ''convoActor.headRotatorBone''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='convoActor.headRotatorBone'>head</string></code>

===== headRotatorOffset =====
Set head rotator offset. If ''headRotatorBone'' is used the offset is relative this bone. Otherwise the offset is relative to the element coordinate system.
  * Full name: ''convoActor.headRotatorOffset''
  * Type: 3-component float vector
  * Default Value: (0,-1.65,0)
  * Example (*.deeclass) <code xml><vector name='convoActor.headRotatorOffset' x='0' y='-1.65' z='0.2'/></code>

===== registerConvoActor =====
Set to register conversation actor in game world. Allows game scripts to locate conversation actors by identifier without needing to know which element they belong to.
  * Full name: ''convoActor.registerConvoActor''
  * Type: boolean
  * Default Value: ''false''
  * Example (*.deeclass) <code xml><boolean name='convoActor.registerConvoActor'>true</boolean></code>

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

This behavior has these events:

===== wait ======

Return true if actor is doing something blocking if conversation actions wait for this actor.

===== enterConversation ======

Actor entered conversation.

===== leaveConversation ======

Actor left conversation.

===== modifySubTitleText ======

Modify sub title text created by behavior. Multiple listeners can modify sub title text by either modifying the widget pass to the listener or creating a new one.

====== Behavior Tree Actions ======

This behavior adds these behavior tree actions.

====== Behavior Tree Conditions ======

This behavior adds these behavior tree conditions.

===== conversationActor.inConversation =====

Determines if conversation actor is in a conversation.

This is an example of an action that can only run if the actor is in a conversation:
<code xml>
<action name='myAction' id='doing something'>
  <condition>conversationActor.inConversation</condition>
</action>
</code>

===== conversationActor.notInConversation =====

Determines if conversation actor is not in a conversation.

This is an example of an action that can only run if the actor is not in a conversation:
<code xml>
<action name='myAction' id='doing something'>
  <condition>conversationActor.notInConversation</condition>
</action>
</code>

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

This behavior requires no other behaviors.

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

  * [[behavior_component|ECBehaviorComponent]]: Adds these support linked to component to conversation actor:
    * SpeechAnimationPlayback
    * GesturePlayback
    * FacePosePlayback
    * HeadLookAtPlayback
    * EyesLookAtPlayback
  * [[behavior_locomotion|ECBehaviorLocomotion]]: Use locomotion for HeadLookAtPlayback if present.
  * [[behavior_parametertable|ECBehaviorParameterTable]]: Makes parameter table of element available to conversation actor.
  * [[behavior_actoranimated|ECBehaviorActorAnimated]], [[behavior_animated|ECBehaviorAnimated]] or [[behavior_twostateanimated|ECBehaviorTwoStateAnimated]]: Listen to behavior updating animations accordingly.
  * [[behavior_behaviortree|ECBehaviorBehaviorTree]]: Add actions and conditions.

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

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

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorConversationActor.html,ECBehaviorConversationActor~@#.

Since DragonScript Module Version ''1.0''

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

  * Add ConversationActor to element.

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

This example defines an element which has a conversation actor.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorCollider collider
  public var ECBehaviorColliderAI colliderAI
  public var ECBehaviorLocomotion locomotion
  public var ECBehaviorParameterTable parameterTable
  public var ECBehaviorActorAnimated actorAnimated
  public var ECBehaviorBehaviorTree behaviorTree
  public var ECBehaviorConversationActor conversationActor
  func new()
    component = ECBehaviorComponent.new(this, null)
    collider = ECBehaviorCollider.new(this, component)
    colliderAI = ECBehaviorColliderAI.new(this, collider)
    locomotion = ECBehaviorLocomotion.new(this, colliderAI)
    parameterTable = ECBehaviorParameterTable.new(this)
    behaviorTree = ECBehaviorBehaviorTree.new(this)
    actorAnimated = ECBehaviorActorAnimated.new(this, component, locomotion)
    conversationActor = ECBehaviorConversationActor.new(this)
    conversationActor.setActorAnimated(actorAnimated)
    conversationActor.setLocomotion(locomotion)
    conversationActor.setParameterTable(parameterTable)
    conversationActor.addBehaviorTree(behaviorTree)
  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='ECBehaviorParameterTable'/>
  <behavior type='ECBehaviorActorAnimated'/>
  <behavior type='ECBehaviorBehaviorTree'/>
  
  <behavior type='ECBehaviorConversationActor'>
    <!-- optional: use actor animated with id instead of empty string -->
    <string name='actorAnimated'>second</string>
    
    <!-- optional: use animated with id instead of empty string -->
    <string name='animated'>second</string>
    
    <!-- optional: use two state animated with id instead of empty string -->
    <string name='twoStateAnimated'>second</string>
    
    <!-- optional: add behavior trees. default adds behavior tree with empty string if present. -->
    <list name='behaviorTrees'>
      <!-- add behavior with empty identifier -->
      <string/>
      
      <!-- add behavior with 'default' identifier -->
      <string>default</string>
    </list>
    
    <!-- optional: use BaseGameApp subtitle theme. game can add more supported values.
                   default is 'default'. also supported is value 'path:/path/to/theme.guitheme' -->
    <string name='subtitleTheme'>default</string>
    
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.name'>value</string>
  </behavior>
</elementClass>
</code>

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

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