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

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

====== ECBehaviorBillboard ======

Behavior element behavior adding billboard support.

Billboards place a flat image in the game world optionally rotated towards the camera position.

====== Instance Counts ======
This behavior can be added multiple times to an element. Use the behavior identifier to tell them apart.

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

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

===== axis =====
Set billboard axis. The billboard will be oriented along this axis if locked.
  * Full name: "billboard.axis" or "billboard({id}).axis"
  * Type: 3-component float vector
  * Default Value: (0,1,0)
  * Example (*.deeclass) <code xml><vector name='billboard.axis' x='0' y='1' z='0'/></code>

===== offset =====
Set billboard offset. The billboard will be placed with this offset relative to the origin. This is useful for elements like trees that should rotate along their base not their center. The offset is relative to the billboard size. Hence a value of 0.5 moves the billboard half its size.
  * Full name: "billboard.offset" or "billboard({id}).offset"
  * Type: 2-component float vector
  * Default Value: (0,0)
  * Example (*.deeclass) <code xml><vector2 name='billboard.offset' x='0' y='0.5'/></code>

===== locked =====
Set if billboard rotation is locked to billboard axis.
  * Full name: "billboard.locked" or "billboard({id}).locked"
  * Type: boolean
  * Default Value: true
  * Example (*.deeclass) <code xml><boolean name='billboard.locked'>false</boolean></code>

===== spherical =====
Set if billboard rotation is spherical. If spherical the billboard rotates to face the camera origin. If not spherical the billboard is aligned with the camera looking direction. Spherical billboards get sheared near the border of the screen while non-spherical ones keep stay aligned with the screen.
  * Full name: "billboard.spherical" or "billboard({id}).spherical"
  * Type: boolean
  * Default Value: true
  * Example (*.deeclass) <code xml><boolean name='billboard.spherical'>false</boolean></code>

===== sizeFixedToScreen =====
Set if billboard size is fixed to the screen size. This causes the size of the billboard to stay the same relative to the screen no matter at what distance the billboard is seen. This is useful for billboards showing information to the player like status icons above a player. By fixing the size to the screen the status icons do not get larger and smaller if the actor approaches the screen or moves away from it.
  * Full name: "billboard.sizeFixedToScreen" or "billboard({id}).sizeFixedToScreen"
  * Type: boolean
  * Default Value: false
  * Example (*.deeclass) <code xml><boolean name='billboard.sizeFixedToScreen'>true</boolean></code>

===== renderEnvMap =====
Set if billboard is rendered to environment maps.
  * Full name: "billboard.renderEnvMap" or "billboard({id}).renderEnvMap"
  * Type: boolean
  * Default Value: true
  * Example (*.deeclass) <code xml><boolean name='billboard.renderEnvMap'>false</boolean></code>

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

This behavior has no events.

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

This behavior requires no other behaviors.

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

  * [[behavior_collider|ECBehaviorCollider]]: Attaches billboard to collider if set.

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

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

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorBillboard.html,ECBehaviorBillboard~@#.

Since DragonScript Module Version **1.0**

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

  * Show distant objects using an image instead of complex model.
  * Show status icons above actor heads that are screen aligned and at fixed size.
  * Show comic like speech bubbles near actors that are screen aligned.

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

This example defines an element which contain a billboard.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorCollider collider
  public var ECBehaviorBillboard billboard
  public func new()
    collider = ECBehaviorCollider.new(this)
    billboard = ECBehaviorBillboard.new(this, collider)
    billboard.getBillboard().getSkin().setPath("/content/billboards/tree.deskin")
    billboard.getBillboard().getOffset().setVector2(Vector2.new(0, 0.5))
  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='ECBehaviorBillboard'>
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.skin'>billboard.deskin</string>
    <vector2 name='.offset' x='0' y='0.5'/>
  </behavior>
  
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorBillboard' id='second'/>
</elementClass>
</code>

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

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