User Tools

Site Tools


dragengine:modules:dragonscript:behavior_outline

ECBehaviorOutline

Example usage of outline.* skin texture properties.

Adds outline support to components.

Renders outline around a component.

This is done by creating a new component resource. The model and rig of the existing component is assigned to the new component. The new component resource is attached to an existing collider using rig attachment mode. This makes the new component deform the same way as the existing component. The new component is thus a kind of “copy” of the existing component.

Then an outline skin is assigned to the new component and all textures it contains. This replaces every texture in the new component with the outline skin.

The outline skin is set by the user. To work properly it has to use the “outline.*” skin texture properties to render the outline and “solidity” with value “0” to hide everything but the outline.

A typical outline skin looks like this:

<?xml version='1.0' encoding='UTF-8'?>
<skin>
  <texture name='material'>
    <value property='solidity'>0</value>
    <color property='outline.color' r='0' g='0' b='0' a='1' renderable='color'/>
    <value property='outline.thickness' renderable='thickness'>0.005</value>
    <value property='outline.thickness.screen'>1</value>
    <color property='outline.emissivity' r='0' g='0' b='0' a='1' renderable='color'/>
    <value property='outline.emissivity.intensity' renderable='intensity'>4</value>
  </texture>
</skin>

By default the skin “/shareddata/materials/outlined.deskin” is used which is provided by the shared DragonScript Module data and provides tintable and emissive outlines.

The emissivity is optional and allows to make the outline glow in the dark. Using renderable “color” is also optional but recommended. This allows this behavior to change the outline color using a dynamic skin.

This set up allows to add an outline skin to any ECBehaviorComponent without the need to create skins with built-in support for outline rendering. If you want to use outline for all objects by default better build it into their skins which is faster.

This behavior can be also used to add outer skins in general to an ECBehaviorComponent. You have to adjust the outline skin to achieve the desired result.

This is an effect type behavior and starts out invisible. Use setVisible() to switch the outline on and off. Typically this is done in response to game events or by other behaviors managing outline parameters.

Instance Counts

Multiple instances of ECBehaviorOutline can be used for example to create different outlines to switch on and off or to add multiple outline skins to a single ECBehaviorComponent. Keep in mind though that each instance of ECBehaviorOutline creates a new component and dynamic skin resource which can impact performance if the used model has high polygon count. To use multiple instances use code like this in your subclass constructor:

class MultiInstanceClass extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorCollider collider
  
  public func new() super("MultiInstance")
    component = ECBehaviorComponent.new(this)
    collider = ECBehaviorCollider.new(this, component)
    ECBehaviorOutline.new(this, component, collider)
    ECBehaviorOutline.new(this, component, collider, "secondOutline")
  end
end

Element Class Properties

Element class properties have the prefix outline. or outline(id). if id is not empty.

skin

Path to skin to use to render the outline.

  • Full name: “outline.skin” or “outline(id).skin”
  • Type skin path
  • Default Value “/shareddata/materials/outlined.deskin”
  • Example (*.deeclass)
    <string name='outline.skin'>outline.deskin</string>

model

Path to model to use instead of the model of the dependency component

  • Full name: “outline.model” or “outline(id).model”
  • Type model path
  • Default value null
  • Example (*.deeclass)
    <string name='outline.model'>outline.demodel</string>

rig

Path to rig to use instead of the rig of the dependency component. If null uses the dependency component rig.

  • Full name: “outline.rig” or “outline(id).rig”
  • Type rig path
  • Default value null
  • Example (*.deeclass)
    <string name='outline.rig'>outline.derig</string>

color

Color of the outline. For this property to have any effect the used skin requires to have a renderable named “color”.

  • Full name: “outline.color” or “outline(id).color”
  • Type color
  • Default value black (0, 0, 0)
  • Example (*.deeclass)
    <color name='outline.color' r='1' g='0' b='0'/>

intensity

Emissivity intensity of the outline. For this property to have any effect the used skin requires to have a renderable named “intensity”.

  • Full name: “outline.intensity” or “outline(id).intensity”
  • Type floating point
  • Minimum Value 0
  • Default value 0
  • Example (*.deeclass)
    <float name='outline.intensity'>4</float>

thickness

Thickness of the outline. The measurement unit of this value depends on the outline type in the used skin. For this property to have any effect the used skin requires to have a renderable named “thickness”.

  • Full name: “outline.thickness” or “outline(id).thickness”
  • Type floating point
  • Minimum Value 0
  • Default value 0.005
  • Example (*.deeclass)
    <float name='outline.thickness'>0.005</float>

Required Behaviors

Optional Behaviors

This behavior does not support optional behaviors.

Persistency

This behavior does support element class to be persistable (setPersistable). Saves color, intensity and visiblity state.

API Documentation

ECBehaviorOutline.

Since DragonScript Module Version 1.1

Use Cases

  • Highlight objects player can interact with. Combine this with ECBehaviorLookedAt using a listening to show/hide the highlight if the player looks at the object.
  • Use for Toon-Rendering to draw a black outline on all objects.

Element Class Example

class ExampleElementClass extends BehaviorElementClass
   public var ECBehaviorComponent component
   public var ECBehaviorCollider collider
   public var ECBehaviorOutline outline
   
   public func new() super("ExampleElement")
     // add required behaviors component and collider
     component = ECBehaviorComponent.new(this)
     collider = ECBehaviorCollider.new(this, component)
     
     // create outline behavior and set parameters. the outline will be colored red
     // and has a thickness of 0.0075 using a custom "outline.deskin" skin
     outline = ECBehaviorOutline.new(this, component, collider)
     outline.getSkin().setPath("outline.deskin")
     outline.getColor().setColor(Color.red)
     outline.getThickness().setValue(0.0075)
   end
end
You could leave a comment if you were logged in.
dragengine/modules/dragonscript/behavior_outline.txt · Last modified: 2020/05/24 14:54 by dragonlord