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

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

====== ECBehaviorCustomColor ======

<WRAP center 100%>
<WRAP center box 450px>
{{youtube>Gte74Jte8A0?medium}}
<WRAP centeralign>Behavior in action</WRAP>
</WRAP>
</WRAP>

Behavior element behavior adding custom color support.

Custom colors are typically used to allow players to customize the look of their player actor by altering the color of individual body parts. This behavior allows to define custom color slots the player or artist can manipulate. This behavior does not define how custom colors are applied. This is left for other behaviors or game scripts to do.

Custom colors compose of a display name and the currently assigned color. This color can be null to use the assigned default color. An optional list of colors can be used to restrict the colors the player can select. If the list is empty the player can choose the color unrestricted. In addition a display description can be added in case the game developer would like to communicate additional information about the custom color.

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

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

===== name =====
Sets the name to show for the custom color in UI.
  * Full name: "customColor.name" or "customColor({id}).name"
  * Type: unicode string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='customColor(body).name'>Body Color</string></code>

===== description =====
Sets the optional description to show for the custom color in UI. This can be used to add additional information beyond the name of the color. Often this is though not used.
  * Full name: "customColor.description" or "customColor({id}).description"
  * Type: unicode string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='customColor(body).description'>Color of scales along the back of the body</string></code>

===== allowedColors =====
Optional list of allowed colors. If this list is not empty the player is only allowed to select one of the colors from this list. If the list is empty all colors are allowed. Typically this means the UI shows a list or combo box instead of a set of sliders for each color component. In XML Element Class files this is defined as a list-tag containing color-tag entries. In Stub Properties this is encoded in the form "r1,g1,b1 r2,g2,b3 ..." with rX,gX,bX defining the Xth color (you can use also newline instead of spaces).
  * Full name: "customColor.allowedColors" or "customColor({id}).allowedColors"
  * Type: list of color (3-component)
  * Default Value: empty list
  * Example (*.deeclass) <code xml><list name='customColor(body).allowedColors'>
  <color r='1' g='0' b='0'/>
  <color r='0' g='1' b='0'/>
  <color r='0' g='0' b='1'/>
</list></code>

===== defaultColor =====
Sets the default color for the custom color. If the user selects no color (null value) then the default color is used. This can also be used to reset the color to the default color.
  * Full name: "customColor.defaultColor" or "customColor({id}).defaultColor"
  * Type: color (3-component
  * Default Value: white (1,1,1)
  * Example (*.deeclass) <code xml><color name='customColor(body).defaultColor' r='0' g='0.5' b='0'/></code>

===== color =====
Sets the initial selected color. This can be null to used the default color.
  * Full name: "customColor.color" or "customColor({id}).color"
  * Type: color (3-component
  * Default Value: white (1,1,1)
  * Example (*.deeclass) <code xml><color name='customColor(body).color' r='0' g='0.5' b='0'/></code>
  * Example (*.deeclass) <code xml><null name='customColor(body).color'/><!-- force no color set --></code>

===== Events =====

Since this behavior provides no support to apply the chosen color listening is used. Behaviors knowing how to apply the color add a listener and are notified if the color changes. These events can be received:

==== colorChanged ====

Selected color changed. Use behavior to get the newly set color.

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

This behavior requires no other behaviors.

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

This behavior does not support optional behaviors.

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

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

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorCustomColor.html,ECBehaviorCustomcolor~@#.

Since DragonScript Module Version **1.5**

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

  * Allow actor to style his player actor using custom colors for individual body parts.
  * Create variations of NPCs by adding color slots that can be modified in XML Element Classes or using Stub Properties.

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

This example defines an element which contains two custom colors the player can choose at will. You can now define the parameters to use for both custom colors using for example the properties "customColor(color1).color" for the first custom color and "customColor(color2).color" for the second custom color.

<code>
class MyElement extends BehaviorElementClass
  public func new()
    ECBehaviorCustomColor.new(this, "color1", "Color 1", Color.blue)
    ECBehaviorCustomColor.new(this, "color2", "Color 2", Color.red)
  end
end
</code>

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

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]: Element class adding 5 custom color slots to a box model. Player can interact with box to bring up a dialog to change the colors.
    * [[https://github.com/LordOfDragons/deexamples/blob/master/exampleApp/data/scripts/CustomColorExampleClass.ds|CustomColorExampleClass.ds]]. Element class using 5 color slots
    * [[https://github.com/LordOfDragons/deexamples/blob/master/exampleApp/data/scripts/PlayerActionCustomColor.ds|PlayerActionCustomColor.ds]]. Player action showing dialog to select color.
    * [[https://github.com/LordOfDragons/deexamples/tree/master/exampleApp/data/content/models/customColor|customColor]]. Directory containing images to define the locations on the skin where each individual color applies to.