{{tag>dragonscript behavior}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[abstractions#behavior_elementsquick_and_easy_development|Behavior Elements: Quick and Easy Development]] >> **ECBehaviorActorCutscene**
</WRAP>

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

====== ECBehaviorActorCutscene ======

Behavior adding cutscene support to actors.

Allows actor to perform cutscene actions controlled by conversation scripts.

Loads a custom animator and applies it to ECBehaviorConversationActor. Controller mappings assigned to ECBehaviorConversationActor do affect the loaded animator so cutscene animators can integrate into switched animators. In addition this behavior adds a controller named ''cutscene'' which is used to play back the cutscene.

Upon starting the animation captures the current animation state into state number 0. This allows cutscenes to blend over from the current state if required.

Supports adding break points to interrupt playing back a cutscene until the conversation script decides to continue. This allows for special configurations and requires the used animator to support playing back an idle animation (for example using ''idle'' controller) while the cutscene controller is frozen at the break point value.

Also supports loading a sound or synthesizer to play back while the cutscene is running.

When using this behavior make sure the BaseActorAction subclass used supports changing animator assigned to [[behavior_actoranimated|ECBehaviorActorAnimated]] while the action is in used. If this is not the case the BaseActorAction subclass can access AnimatorController of the previous animator causing problems.

See also:
  * [[gamedev:animators|Animators and Animation]]
  * [[gamedev:deigde:editors:animator|IGDE Animator Editor]]
  * [[tools:blenderexportscripts|Blender3D Export Scripts]]
====== Instance Counts ======
This behavior can be used only once on an element.

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

===== controllerName =====
Set name of playback controller.
  * Full name: ''cutscene.controllerName''
  * Type: string
  * Default Value: ''cutscene''
  * Example (*.deeclass) <code xml><string name='cutscene.controllerName'>playback</string></code>

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

This behavior has these events:

===== cutsceneStarted =====
Cutscene started.

===== cutsceneStopped =====
Cutscene stopped.

===== cutscenePaused =====
Cutscene hit break point and is now waiting.

===== cutsceneResumed =====
Cutscene continues after waiting at a break point.

====== Conversation Commands ======
This behavior adds these conversation commands.

===== cutscene =====

Control cutscene. The following syntax is supported:

''cutscene start [path] {[breakPoint1] ... [breakPointN]}''

Start playing cutscene.
^Parameter^Description^
|path|Path to animator to load.|
|breakPoint*|Break points to wait on in seconds in ascending order.|

''cutscene resume''

Resume cutscene if paused (hence waiting at a break point).

''cutscene stop''

Stop cutscene if running.

''cutscene synthesizer [path] [range] {[positionX] [positionY] [positionZ] {[bone]}}''

Loads synthesizer and starts playing it back. Attaches the speaker to the actor.
^Parameter^Description^
|path|Absolute path to synthesizer to load.|
|range|Range in meters of speaker.|
|position*|Position relative to actor origin to attach speaker to.|
|bone|Attach relative to bone instead of actor origin.|

====== Conversation Conditions ======
This behavior adds these conversation conditions.

===== cutscene =====

''cutscene playing''

Cutscene is playing.

''cutscene paused''

Cutscene is paused (hence waiting at a break point).

''cutscene stopped''

Cutscene is stopped.

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

  * [[behavior_collider|ECBehaviorCollider]]
  * [[behavior_conversationactor|ECBehaviorConversationActor]]

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

This behavior does not support optional behaviors.

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

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

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorActorCutscene.html,ECBehaviorActorCutscene~@#.

Since DragonScript Module Version ''1.0''

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

  * Allow actor to be used in cutscenes playing back a special cutscene animator.

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

This example defines an element which supports cutscenes.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorCollider collider
  public var ECBehaviorConversationActor conversationActor
  public var ECBehaviorActorCutscene actorCutscene
  func new()
    component = ECBehaviorComponent.new(this, null)
    collider = ECBehaviorCollider.new(this, component)
    conversationActor = ECBehaviorConversationActor.new(this)
    actorCutscene = ECBehaviorActorCutscene.new(this, collider, conversationActor)
  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='ECBehaviorConversationActor'/>
  
  <behavior type='ECBehaviorActorCutscene'>
    <!-- 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]]