Drag[en]gine Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{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]] >> **ECBehaviorLightAnimation**
</WRAP>

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

====== ECBehaviorLightAnimation ======

Behavior element behavior adding animation support to [[behavior_light|ECBehaviorLight]]

This behavior modifies the light parameters of [[behavior_light|ECBehaviorLight]] instances present in the element using move keyframes stored in an ''Animation'' or [[behavior_component|ECBehaviorComponent]] state. Animation playback starts when the light becomes activated and stops (and resets) if reactivated.

To use this behavior add first an [[behavior_light|ECBehaviorLight]]. Adding ''ECBehaviorLightAnimation'' will then register itself as listener to the [[behavior_light|ECBehaviorLight]] and also set it to use custom light handling.

Using ''Animation'' keyframes from a move is used to animate the light parameters.

Using [[behavior_component|ECBehaviorComponent]] the animated state is used to animate the light parameters. In this case the play time is 0 since the component state is typically driven by an animator or manually.

The input values obtained either from animation keyframes or component state is remapped before applying to the light parameter. This linearly maps the lower remap value (default ''0'') to ''0'' output value and the upper remap value (default ''1'') to ''1'' output value. Values outside the remap range are extrapolated.

Remapping is applied before scaling.

====== Instance Counts ======

Multiple ''ECBehaviorLightAnimation'' instances can be added to affect individual [[behavior_light|ECBehaviorLight]] instances like this example below.

<code dragonscript>
class MyElement extends BehaviorElementClass
    func new()
        var ECBehaviorLight light1 = ECBehaviorLight.new(this)
        ECBehaviorLightAnimation.new(this, light1)
        
        var ECBehaviorLight light2 = ECBehaviorLight.new(this, "subLight")
        ECBehaviorLightAnimation.new(this, light2)
    end
end
</code>

====== Element Class Properties ======

Element class properties have the prefix ''lightAnimation.'' or ''lightAnimation({id}).'' if id is not empty.

===== animation =====

Set path to animation to use. Animation move based animation is used only if animation is set.

  * Full name: ''lightAnimation.animation'' or ''lightAnimation({id}).animation''
  * Type: string
  * Default Value: empty string
  * Expected File Pattern: ''*.deanim'' (all supported animation type modules)
  * Example (*.deeclass) <code xml><string name='lightAnimation.animation'>light.deanim</string></code>

===== move =====

Set move name to use. Animation move based animation is used only if move is set.

  * Full name: ''lightAnimation.move'' or ''lightAnimation({id}).move''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='lightAnimation.move'>flicker</string></code>

===== enabled =====

Set if animation playback is enabled.

  * Full name: ''lightAnimation.enabled'' or ''lightAnimation({id}).enabled''
  * Type: boolean
  * Default Value: true
  * Example (*.deeclass) <code xml><boolean name='lightAnimation.enabled'>false</boolean></code>

===== playSpeed =====

Set playback speed. Value of ''1'' plays back at normal speed. Values larger than 1 play back faster. Values less then 1 play back slower.

  * Full name: ''lightAnimation.playSpeed'' or ''lightAnimation({id}).playSpeed''
  * Type: float
  * Default Value: 1
  * Example (*.deeclass) <code xml><float name='lightAnimation.playSpeed'>0.5</float></code>

===== trigger =====

Set enabled trigger. If no trigger is set the state of ''enabled'' property is used.

  * Full name: ''lightAnimation.trigger'' or ''lightAnimation({id}).trigger''
  * Type: string
  * Default Value: state of ''enabled''
  * Example (*.deeclass) <code xml><string name='lightAnimation.trigger'>@switchOnLight & @powerEnabled</string></code>

===== light parameters =====

For each light parameter a set of properties can be defined. Replace ''<parameter>'' with one of the values from the following list:

^Value^Description^
|''colorRed''|Red light color.|
|''colorGreen''|Green light color.|
|''colorBlue''|Blue light color.|
|''intensity''|Light intensity.|
|''range''|Light range in meters. Beyond this range light has no effect.|
|''halfIntensityDistance''|Light half intensity distance (0 to 1). At this position the light dropped to 50% strength. Allows to shape fall-off curve. A value of ''0.1'' is natural fall-off. Values larger than 0.1 make light fall off faster near the light source. Values smaller than 0.1 make light fall off faster near the light range.|
|''ambientRatio''|Light ambient ratio (0 to 1). Percentage of total light to use as ambient light.|
|''spotAngle''|Light spot angle in degrees (opening angle).|
|''spotRatio''|Light spot ratio as height divided by width (0 to 1). Hence this is the aspect ratio of the spot light.|
|''spotSmoothness''|Light spot smoothness (0 to 1). Percentage distance from border to center where light fall-off begins. A value of ''0'' produces constant light intensity across the entire spot cone. A value of ''1'' produces linear fade across the entire spot cone.|
|''spotExponent''|Light spot exponent (0 or greater). Shape of light fall-off from spot center to spot border. A value of ''1'' is linear fall-off. Values larger than 0.1 make light fall off faster near the spot center. Values smaller than 0.1 make light fall off faster near the spot border.|

==== <parameter>.target ====

Set target to obtain value from. If ''<parameter>.parameter'' is ''weight'' target is the name of the vertex position set to use. Otherwise target is the name of the bone to use.

  * Full name: ''lightAnimation.<parameter>.target'' or ''lightAnimation({id}).<parameter>.target''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='lightAnimation.colorRed.target'>color red</string></code>

==== <parameter>.parameter ====

Set which value to use of ''<parameter>.target''.

  * Full name: ''lightAnimation.<parameter>.parameter'' or ''lightAnimation({id}).<parameter>.parameter''
  * Type: enumeration
  * <WRAP>Allowed Values:
^Value^Description^
|''positionX''|Bone local position X coordinate.|
|''positionY''|Bone local position Y coordinate.|
|''positionZ''|Bone local position Z coordinate.|
|''rotationX''|Bone local rotation X coordinate in degrees.|
|''rotationY''|Bone local rotation Y coordinate in degrees.|
|''rotationZ''|Bone local rotation Z coordinate in degrees.|
|''scaleX''|Bone local scale X coordinate.|
|''scaleY''|Bone local scale Y coordinate.|
|''scaleZ''|Bone local scale Z coordinate.|
|''weight''|Vertex position set weight.|
</WRAP>
  * Default Value: ''positionZ''
  * Example (*.deeclass) <code xml><string name='lightAnimation.colorRed.parameter'>positionZ</string></code>

==== <parameter>.remapLower ====

Set lower remap value. Input values obtained from target is remapped before applying to the light parameter. This linearly maps the lower remap value (default 0) to 0 output value and the upper remap value (default 1) to 1 output value. Values outside the remap range are extrapolated.

  * Full name: ''lightAnimation.<parameter>.remapLower'' or ''lightAnimation({id}).<parameter>.remapLower''
  * Type: float
  * Default Value: ''0''
  * Example (*.deeclass) <code xml><float name='lightAnimation.colorRed.remapLower'>0.5</float></code>

==== <parameter>.remapUpper ====

Set upper remap value. Input values obtained from target is remapped before applying to the light parameter. This linearly maps the lower remap value (default 0) to 0 output value and the upper remap value (default 1) to 1 output value. Values outside the remap range are extrapolated.

  * Full name: ''lightAnimation.<parameter>.remapUpper'' or ''lightAnimation({id}).<parameter>.remapUpper''
  * Type: float
  * Default Value: ''1''
  * Example (*.deeclass) <code xml><float name='lightAnimation.colorRed.remapUpper'>1.5</float></code>

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

This behavior provides no events:

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

This behavior adds these behavior tree actions if behavior tree is present. If behavior has non-empty identifier replace ''lightAnimation'' with ''lightAnimation(id)''.

===== lightAnimation.set =====

Set one or more light parameters.

^Parameter^Value^Description^
|enabled|''true'', ''false''|Set if animation is enabled|
|time|float|Set animation time in seconds|
|time.relative|float|Set animation time in percentage from 0 (begin) to 1 (end)|

This is an example of using this action:
<code xml>
<action name='lightAnimation.set'>
  <parameter name='enabled'>true</parameter>
</action>
</code>

===== lightAnimation.check =====

Check one or more light parameters. Action succeeds if all parameter value matches their respective light parameter otherwise action fails. This action is typically used as first action in a sequence to run the sequence only if a light parameter matches (or not).

^Parameter^Value^Description^
|enabled|''true'', ''false''|Animation is enabled|
|time.less|float|Animation time is less than value in seconds|
|time.greater|float|Animation time is greater than value in seconds|
|time.relative.less|float|Relative animation time (0=begin, 1=end) is less than value in seconds|
|time.relative.greater|float|Relative animation time (0=begin, 1=end) is greater than value in seconds|
|wait| |If present action returns BTResult.running instead of BTResult.failed to wait until the checks are all fulfilled|

This is an example of using this action:
<code xml>
<sequence>
  <action name='lightAnimation.check'>
    <parameter name='enabled'>true</parameter>
    <parameter name='time.less'>3</parameter>
  </action>
  <!-- actions here run only if animation is enabled and playback time is less than 3 seconds -->
</sequence>
</code>

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

This behavior adds these behavior tree conditions if behavior tree is present. If behavior has non-empty identifier replace ''lightAnimation'' with ''lightAnimation(id)''.

===== lightAnimation.check =====

Check one or more light parameters. Conditions returns true if all parameter value match their respective light parameter. This condition is typically used to run an action or sequence of actions as long as light conditions are true.

^Parameter^Value^Description^
|lightAnimation.enabled|''true'', ''false''|Animation is enabled|
|lightAnimation.time.less|float|Animation time is less than value in seconds|
|lightAnimation.time.greater|float|Animation time is greater than value in seconds|
|lightAnimation.time.relative.less|float|Relative animation time (0=begin, 1=end) is less than value in seconds|
|lightAnimation.time.relative.greater|float|Relative animation time (0=begin, 1=end) is greater than value in seconds|

This is an example of using this condition:
<code xml>
<action name='myAction' id='doing something'>
  <parameter name='lightAnimation.enabled'>true</parameter>
  <parameter name='lightAnimation.time.less'>3</parameter>
  <condition>lightAnimation.check</condition>
</action>
</code>

====== State Machine Actions ======

Same as [[#behavior_tree_actions|Behavior Tree Actions]].

====== State Machine Conditions ======

Same as [[#behavior_tree_conditions|Behavior Tree Conditions]].

====== State Machine Events ======

This behavior sends no state machine events.

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

  * [[behavior_light|ECBehaviorLight]]. Light to animate.

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

  * [[behavior_component|ECBehaviorComponent]]. Use component state if no animation and move is set.
  * [[behavior_behaviortree|ECBehaviorBehaviorTree]]: Add actions and conditions for behavior trees to use.
  * [[behavior_statemachine|ECBehaviorStateMachine]]: Add actions and conditions for state machine to use and events to send to the state machine.

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

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

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorLightAnimation.html,ECBehaviorLightAnimation~@#.

Since DragonScript Module Version ''1.28''

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

  * Animate light parameters for example to create a flickering light bulb.
  * Animate light parameters depending on the animation state of a component for example a robot arm location.

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

This example defines an element which contains a light which is animated.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorLight light
  public var ECBehaviorLightAnimation lightAnimation
  func new()
    light = ECBehaviorLight.new(this, null)
    light.getLight().getColor().setColor(Color.white)
    light.getLight().getIntensity().setValue(10)
    
    lightAnimation = ECBehaviorLightAnimation.new(this, light)
    lightAnimation.getAnimation().setPath("/content/light/bulb.deanim")
    lightAnimation.getMove().setValue("flicker")
    lightAnimation.getLightParameter(ECBehaviorLightAnimation.LightParameter.intensity).getTarget().setValue("light.intensity")
  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='ECBehaviorLight'>
    <color name='.color' r='1' g='1' b='1'/>
    <float name='.intensity'>10</float>
  </behavior>
  
  <behavior type='ECBehaviorLightAnimation'>
    <!-- optional: use BaseGameApp trigger table. game can add more supported values.
                  default value is 'default' -->
    <string name='triggerTable'>default</string>
    
    <!-- optional: identifier of ECBehaviorTriggered to synchronize with or empty
                   string to not synchronize. default is empty string. -->
    <string name='trigger.synchronize'>other</string>
    
    <!-- optional: use behavior tree with id instead of empty string -->
    <string name='behaviorTree'>second</string>
    
    <!-- optional: use state machine with id instead of empty string -->
    <string name='stateMachine'>second</string>
    
    <!-- optional: light behavior to use instead of default one -->
    <string name='light'>other</string>
    
    <!-- optional: component behavior to use instead of default one if present -->
    <string name='component'>second</string>
    
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.animation'>/content/light/bulb.deanim</string>
    <string name='.move'>flicker</string>
    <string name='.intensity.target'>intensity</string>
  </behavior>
  
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorLightAnimation' id='second'/>
</elementClass>
</code>

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

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]
Drag[en]gine Wiki

User Tools

Site Tools

Page Tools
