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

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

====== ECBehaviorLight ======

Behavior element behavior adding Light resource.

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

====== Element Class Properties ======
Element class properties have the prefix ''light.'' or ''light({id}).'' if id is not empty.

===== type =====
Set light type.
  * Full name: ''light.type'' or ''light({id}).type''
  * Type: enumeration
  * <WRAP>Allowed Values:
^Value^Description^
|''point''|Point light.|
|''spot''|Spot light.|
|''projector''|Projector light.|
</WRAP>
  * Default Value: ''point''
  * Example (*.deeclass) <code xml><string name='light.type'>spot</string></code>

===== color =====
Set light color.
  * Full name: ''light.color'' or ''light({id}).color''
  * Type: 3-component color
  * Default Value: (1,1,1)
  * Example (*.deeclass) <code xml><color name='light.color' r='0.8' g='0.6' b='0.4'/></code>

===== intensity =====
Set value.
  * Full name: ''light.intensity'' or ''light({id}).intensity''
  * Type: float
  * Default Value: 1
  * Restriction: At least 0
  * Example (*.deeclass) <code xml><float name='light.intensity'>2.5</float></code>

===== ambientRatio =====
Set ambient ratio. Percentage of total light to use as ambient light.
  * Full name: ''light.ambientRatio'' or ''light({id}).ambientRatio''
  * Type: float
  * Default Value: 0
  * Restriction: At least 0 and at most 1.
  * Example (*.deeclass) <code xml><float name='light.ambientRatio'>0.2</float></code>

===== range =====
Set range im meters. Beyond this range light has no effect.
  * Full name: ''light.range'' or ''light({id}).range''
  * Type: float
  * Default Value: 10
  * Restriction: At least 0
  * Example (*.deeclass) <code xml><float name='light.range'>2.5</float></code>

===== halfIntensityDistance =====
Set half intensity distance relative to range. 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.
  * Full name: ''light.halfIntensityDistance'' or ''light({id}).halfIntensityDistance''
  * Type: float
  * Default Value: 0.1
  * Restriction: At least 0 and at most 1.
  * Example (*.deeclass) <code xml><float name='light.halfIntensityDistance'>0.2</float></code>

===== spotAngle =====
Set spot angle in degrees (opening angle).
  * Full name: ''light.spotAngle'' or ''light({id}).spotAngle''
  * Type: float
  * Default Value: 30
  * Restriction: At least 0 and at most 179.
  * Example (*.deeclass) <code xml><float name='light.spotAngle'>45</float></code>

===== spotRatio =====
Set spot ratio as height divided by width. Hence this is the aspect ratio of the spot light.
  * Full name: ''light.spotRatio'' or ''light({id}).spotRatio''
  * Type: float
  * Default Value: 1
  * Restriction: At least 0
  * Example (*.deeclass) <code xml><float name='light.spotRatio'>1.5</float></code>

===== spotSmoothness =====
Set spot smoothness. 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.
  * Full name: ''light.spotSmoothness'' or ''light({id}).spotSmoothness''
  * Type: float
  * Default Value: 1
  * Restriction: At least 0 and at most 1.
  * Example (*.deeclass) <code xml><float name='light.spotSmoothness'>0.2</float></code>

===== spotExponent =====
Set spot exponent. 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.
  * Full name: ''light.spotExponent'' or ''light({id}).spotExponent''
  * Type: float
  * Default Value: 2
  * Restriction: At least 0
  * Example (*.deeclass) <code xml><float name='light.spotExponent'>1.5</float></code>

===== shape =====
Set shape.
  * Full name: ''light.shape'' or ''light({id}).shape''
  * Type: string (shape format). See "Shape List Encoding" in CodecPropertyString.
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='light.shape'>box:position,0,0.5,0:extends,2,1,0.5</string></code>

===== lightSkin =====
Set path of skin resource to use.
  * Full name: ''light.lightSkin'' or ''light({id}).lightSkin''
  * Type: string
  * Default Value: empty string
  * Expected File Type: ''*.deskin''
  * Example (*.deeclass) <code xml><string name='light.lightSkin'>spot.deskin</string></code>

===== hintMovement =====
Set movement hint.
  * Full name: ''light.hintMovement'' or ''light({id}).hintMovement''
  * Type: enumeration
  * <WRAP>Allowed Values:
^Value^Description^
|''stationary''|Light remains static for the entire lifetime.|
|''jittering''|Light remains mostly static jittering in a small area.|
|''dynamic''|Light moves around freely.|
</WRAP>
  * Default Value: ''stationary''
  * Example (*.deeclass) <code xml><string name='light.hintMovement'>dynamic</string></code>

===== hintParameter =====
Set parameter hint.
  * Full name: ''light.hintParameter'' or ''light({id}).hintParameter''
  * Type: enumeration
  * <WRAP>Allowed Values:
^Value^Description^
|''initial''|Light parameters never change.|
|''activation''|Light parameters never change except activation.|
|''flicker''|Geometric light parameters never change but others can.|
|''dynamic''|All light parameters can change at will any time.|
</WRAP>
  * Default Value: ''initial''
  * Example (*.deeclass) <code xml><string name='light.hintParameter'>dynamic</string></code>

===== hintShadowImportance =====
Set hint shadow importance. Can be used by graphics module to decide which shadows can be reduced in quality or omitted if performance is low. A value of ''100'' indicates this shadow is important and should always be shown if possible. A value of ''0'' marks the shadow as unimportant which can be quickly reduced if required.
  * Full name: ''light.hintShadowImportance'' or ''light({id}).hintShadowImportance''
  * Type: float
  * Default Value: 100
  * Restriction: At least 0 and at most 100
  * Example (*.deeclass) <code xml><float name='light.hintShadowImportance'>75</float></code>

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

===== castShadows =====
Set light cast shadows.
  * Full name: ''light.castShadows'' or ''light({id}).castShadows''
  * Type: boolean
  * Default Value: true
  * Example (*.deeclass) <code xml><boolean name='light.castShadows'>false</boolean></code>

===== position =====
Set position to attach resource to collider.
  * Full name: ''light.position'' or ''light({id}).position''
  * Type: 3-component float vector
  * Default Value: (0,0,0)
  * Example (*.deeclass) <code xml><vector name='light.position' x='0' y='0' z='0.1'/></code>

===== orientation =====
Set orientation to attach resource to collider in degrees.
  * Full name: ''light.orientation'' or ''light({id}).orientation''
  * Type: 3-component float vector
  * Default Value: (0,0,0)
  * Example (*.deeclass) <code xml><vector name='light.orientation' x='30' y='0' z='0'/></code>

===== bone =====
Set bone to attach resource to. If empty string attach to collider.
  * Full name: ''light.bone'' or ''light({id}).bone''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='light.bone'>attach</string></code>

===== trigger =====
Set trigger activate. If no trigger is set the state of ''activated'' property is used.
  * Full name: ''light.trigger'' or ''light({id}).trigger''
  * Type: string
  * Default Value: state of ''activated''
  * Example (*.deeclass) <code xml><string name='light.trigger'>@switchOnLight & @powerEnabled</string></code>

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

This behavior provides these events:

===== lightActivated =====

Light has been activated.

===== lightDeactivated =====

Light has been deactivated.

===== lightParametersChanged =====

Light parameters have been changed.

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

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

===== light.set =====

Set one or more light parameters.

^Parameter^Value^Description^
|activated|true,false|Activate light|

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

===== light.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^
|activated|true,false|Light is activated or not|
|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='light.check'>
    <parameter name='activated'>true</parameter>
  </action>
  <!-- actions here run only if light is activated -->
</sequence>
</code>

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

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

===== light.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^
|light.activated|true,false|Light is activated or not|

This is an example of using this condition:
<code xml>
<action name='myAction' id='doing something'>
  <parameter name='light.activated'>true</parameter>
  <condition>light.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 these state machine events. If behavior has non-empty identifier replace ''light'' with ''light(id)''.

===== light.activated =====

Light has been activated.

===== light.deactivated =====

Light has been deactivated.

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

This behavior requires no other behaviors.

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

  * [[behavior_collider|ECBehaviorCollider]]. Attach to collider.
  * [[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). Saves these states:
  * activated

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorLight.html,ECBehaviorLight~@#.

Since DragonScript Module Version ''1.0''

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

  * Add light shining from element.

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

This example defines an element which contains a light.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorCollider collider
  public var ECBehaviorLight light
  func new()
    collider = ECBehaviorCollider.new(this, component)
    light = ECBehaviorLight.new(this, collider)
    light.getLight().getColor().setColor(Color.blue)
    light.getAttach().getPosition().setVector(Vector.new(0, 0, 0.3))
  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='ECBehaviorCollider'/>
  
  <behavior type='ECBehaviorLight'>
    <!-- optional: set layer mask as list of bits to set. default is '0 1' which means
                   BaseGameApp.WorldLayerBit.default, BaseGameApp.WorldLayerBit.envmap -->
    <string name='layerMask'>0 1</string>
    
    <!-- optional: set shadow layer mask. default is same as 'layerMask' -->
    <string name='layerMaskShadow'>0 1</string>
    
    <!-- optional: use BaseGameApp trigger table. game can add more supported values.
                  default value is 'default' -->
    <string name='triggerTable'>default</string>
    
    <!-- optional: sync trigger with light matching identifier -->
    <string name='syncTrigger'>second</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: component behaviors not casting shadows. list of behavior identifiers -->
    <list name='shadowIgnoreComponents'>
      <string>first</string>
      <string>second</string>
    </list>
    
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <color name='.color' r='0.8' g='0.6' b='0.4'/>
  </behavior>
  
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorLight' id='second'/>
</elementClass>
</code>

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

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

User Tools

Site Tools

Page Tools
