Drag[en]gine Wiki

User Tools

Site Tools

Trace:
dragengine:modules:dragonscript:behavior_elements

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
dragengine:modules:dragonscript:behavior_elements [2025/03/10 10:44] – created dragonlorddragengine:modules:dragonscript:behavior_elements [2025/03/13 23:15] (current) – [XML Element Classes] dragonlord
Line 7: Line 7:
  
 **Behavior Elements** are build on top of the **Scenery Elements** and provide a **composeable** way to build game logic. This is the fastest way to build your game by befitting elements with reusable **behavior** while still retaining all the powerful coupling to other script classes. **Behavior Elements** are build on top of the **Scenery Elements** and provide a **composeable** way to build game logic. This is the fastest way to build your game by befitting elements with reusable **behavior** while still retaining all the powerful coupling to other script classes.
 +
 +===== Basics =====
  
 Behavior elements are created by subclassing from #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElementClass.html,BehaviorElementClass~@# script class. This class extends the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ElementClass.html,ElementClass~@# script class with support to add **Behavior Definitions**. When a #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElement.html,BehaviorElement~@# instance is created these **behavior definitions** are used to befit the element with all the required functionality. All this can be done manually by using **Scenery Elements** but using **Behavior Elements** this boils down to just adding the **behavior definitions** you like to use. Behavior elements are created by subclassing from #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElementClass.html,BehaviorElementClass~@# script class. This class extends the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ElementClass.html,ElementClass~@# script class with support to add **Behavior Definitions**. When a #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElement.html,BehaviorElement~@# instance is created these **behavior definitions** are used to befit the element with all the required functionality. All this can be done manually by using **Scenery Elements** but using **Behavior Elements** this boils down to just adding the **behavior definitions** you like to use.
Line 19: Line 21:
  
 Once a #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElement.html,BehaviorElement~@# instance is created each behavior definitions adds a subclass of #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Scenery_1_1ECBehaviorInstance.html,ECBehaviorInstance~@#. These provide the actual behavior to the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElement.html,BehaviorElement~@# instance. Here too you can query the element if it contains instances of a specific behavior. Once a #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElement.html,BehaviorElement~@# instance is created each behavior definitions adds a subclass of #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Scenery_1_1ECBehaviorInstance.html,ECBehaviorInstance~@#. These provide the actual behavior to the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorElement.html,BehaviorElement~@# instance. Here too you can query the element if it contains instances of a specific behavior.
 +
 +===== Behavior Compendium =====
  
 Behaviors are split in two groups: **Basic Behaviors** and **Complex Behaviors**. **Basic Behaviors** add a small basic building block of game logic like for example a component showing the visual appearance of a game object. These are highly reusable. **Complex Behaviors** on the other hand typically expect one or more **Basic Behaviors** to be present in the element class to provide a complex behavior for example animating the visual appearance. Behaviors are split in two groups: **Basic Behaviors** and **Complex Behaviors**. **Basic Behaviors** add a small basic building block of game logic like for example a component showing the visual appearance of a game object. These are highly reusable. **Complex Behaviors** on the other hand typically expect one or more **Basic Behaviors** to be present in the element class to provide a complex behavior for example animating the visual appearance.
Line 26: Line 30:
  
 Many more complex behaviors can be created either just for this game project or to be shared with other projects. Behaviors can extend other behaviors by subclassing or by using other behaviors present in the behavior element class. Many more complex behaviors can be created either just for this game project or to be shared with other projects. Behaviors can extend other behaviors by subclassing or by using other behaviors present in the behavior element class.
 +
 +===== Examples =====
  
 This is an example of an element class which which has a visual appearance, physical interaction, is animated, has two lights, has a speaker and moves along a rail. Basically this describes a kind of train running on a rail between two destinations. This is an example of an element class which which has a visual appearance, physical interaction, is animated, has two lights, has a speaker and moves along a rail. Basically this describes a kind of train running on a rail between two destinations.
  
 +++++ Show Example|
 <code> <code>
 pin Dragengine.Gui pin Dragengine.Gui
Line 79: Line 86:
 end end
 </code> </code>
 +++++
  
 The above script code creates a working element class which adds instances of BehaviorElement to the game world set up with the defined behaviors. If you want to have a unique element instance for your class to work with you can modify the code like this: The above script code creates a working element class which adds instances of BehaviorElement to the game world set up with the defined behaviors. If you want to have a unique element instance for your class to work with you can modify the code like this:
 +
 +++++ Show Example|
 <code> <code>
 class MyTrainClass extends BehaviorElementClass class MyTrainClass extends BehaviorElementClass
Line 95: Line 105:
 end end
 </code> </code>
 +++++
  
 Using unique instances allows to add run-time features to your class on top of what BehaviorElement provides without creating an own behavior. In general it is recommended to work with behaviors only and creating your own ones. This way you can reuse game logic across different projects easily. Using unique instances allows to add run-time features to your class on top of what BehaviorElement provides without creating an own behavior. In general it is recommended to work with behaviors only and creating your own ones. This way you can reuse game logic across different projects easily.
  
 ====== XML Element Classes ====== ====== XML Element Classes ======
-TODO 
  
-====== Behavior Factories ====== +<WRAP center 100%> 
-TODO+<WRAP center box 1050px> 
 +{{ youtube>heBLyt3b6G0?1000x591 }} 
 +<WRAP centeralign>\\ 
 +Video explaining what behavior factories are, what they can be used for and how they are created. Shown using ExampleApp which contains an example for this.</WRAP> 
 +</WRAP> 
 +</WRAP>
  
 +XML Element classes allow to create new element classes using an XML file (''*.deeclass'') instead of writing script code. XML element classes always subclass from an existing script class or XML element class. Using an XML element class you can change properties added by the behavior definitions.
 +
 +Element class properties are typically in the form ''behavior.property'' or ''behavior(id).property''. The identifier is omitted if it is empty string. For example the ECBehaviorComponent behavior uses the prefix ''component.''. Hence ''component.model'' would set the _model_ property. The same for an ECBehaviorComponent with the identifier ''second''. Here the name would be ''component(second).model''.
 +
 +Behaviors can be complex and nested. This allows behaviors to add other behaviors to achieve their goals. Such nested behaviors need to be differentiated from other behaviors of the same kind. The rule is to prefix the property names of the behaviors with their parent prefix to make them unique. For example if you have a fictional behavior MyBehavior with the prefix ''mybehavior.'' which adds one or more ECBehaviorComponent then the property names of those component behaviors would look like ''mybehavior.component.model'' or ''mybehavior.component(second).model''. This nesting can go deeper depending on how complex of a behavior you are designing. In general it is favorable to keep the nesting as little as possible as this is easier to use for team members and modders.
 +
 +===== Behavior Factories =====
 +
 +Scripted element classes can be also assigned a list of #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1BehaviorFactor.html,Behavior Factories~@#. This allows the user to add behaviors to XML element classes if they are in the list of allowed behavior factories. The DragonScript module provides the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1GenericBehaviorElementClass.html,GenericBehaviorElementClass~@# which contains the factories of all DragonScript module provided behavior factories. You can create your own behaviors and make them available to the generic behavior element class by extending #@LinkApiDocDEDS2_HTML~classDragengine_1_1BaseGameApp.html,BaseGameApp.createAndAddBehaviorFactories()~@#.
 +
 +Adding behaviors is done using the ''behavior'' tag. Some behaviors require additional parameters during construction time. These parameters can be defined inside the ''behavior'' tag using the same tags as you use to define element properties. The behavior documentation list the supported parameters. After adding a behavior you can set the element properties outside the ''behavior'' tag as you usually would do.
 +
 +To simplify the adding of behaviors properties of a just added behavior can be also defined by moving the property tags inside the ''behavior'' tag. If you do this you have to remove the behavior property prefix from the property names leaving being only the ''.'' as first character in the name. This way the DragonScript module prepends the behavior property prefix while setting the property values. This is easier to write, increases readability and has less possibility for errors. It is thus recommended to set properties of just added behaviors in this way.
 +
 +(TODO: add video of behavior factories)
 +
 +===== XML File Structure =====
 +<uml>
 +@startuml
 +object "elementClass" as elementClass {
 +  <#transparent,#transparent>|behavior||
 +  |string|  <color:gray>string|
 +  |float|  <color:gray>float|
 +  |integer|  <color:gray>int|
 +  |boolean|  <color:gray>bool|
 +  |vector|  <color:gray>vector3|
 +  |vector2|  <color:gray>vector2|
 +  |point|  <color:gray>point2|
 +  |point3|  <color:gray>point3|
 +  |borderSize|  <color:gray>borderSize|
 +  |rectArea|  <color:gray>rectArea|
 +  |floatRectArea|  <color:gray>floatRectArea|
 +  |color|  <color:gray>color4|
 +  |null|  <color:gray>null|
 +  |list||
 +  |map||
 +}
 +
 +object "behavior" as behavior {
 +  <#transparent,#transparent>|string|  <color:gray>string|
 +  |float|  <color:gray>float|
 +  |integer|  <color:gray>int|
 +  |boolean|  <color:gray>bool|
 +  |vector|  <color:gray>vector3|
 +  |vector2|  <color:gray>vector2|
 +  |point|  <color:gray>point2|
 +  |point3|  <color:gray>point3|
 +  |borderSize|  <color:gray>borderSize|
 +  |rectArea|  <color:gray>rectArea|
 +  |floatRectArea|  <color:gray>floatRectArea|
 +  |color|  <color:gray>color4|
 +  |null|  <color:gray>null|
 +  |list||
 +  |map||
 +}
 +elementClass --> behavior
 +
 +
 +object "list" as list {
 +  <#transparent,#transparent>|string|  <color:gray>string|
 +  |float|  <color:gray>float|
 +  |integer|  <color:gray>int|
 +  |boolean|  <color:gray>bool|
 +  |vector|  <color:gray>vector3|
 +  |vector2|  <color:gray>vector2|
 +  |point|  <color:gray>point2|
 +  |point3|  <color:gray>point3|
 +  |borderSize|  <color:gray>borderSize|
 +  |rectArea|  <color:gray>rectArea|
 +  |floatRectArea|  <color:gray>floatRectArea|
 +  |color|  <color:gray>color4|
 +  |null|  <color:gray>null|
 +  |list||
 +  |map||
 +}
 +elementClass --> list
 +
 +object "map" as map {
 +  <#transparent,#transparent>|string|  <color:gray>string|
 +  |float|  <color:gray>float|
 +  |integer|  <color:gray>int|
 +  |boolean|  <color:gray>bool|
 +  |vector|  <color:gray>vector3|
 +  |vector2|  <color:gray>vector2|
 +  |point|  <color:gray>point2|
 +  |point3|  <color:gray>point3|
 +  |borderSize|  <color:gray>borderSize|
 +  |rectArea|  <color:gray>rectArea|
 +  |floatRectArea|  <color:gray>floatRectArea|
 +  |color|  <color:gray>color4|
 +  |null|  <color:gray>null|
 +  |list||
 +  |map||
 +}
 +elementClass --> map
 +
 +@enduml
 +</uml>
 +
 +===== Tags =====
 +
 +==== elementClass ====
 +^Attribute^Description^Required^Default^
 +|name|Unique name of the element class to create.|true|-|
 +|class|Name of the element class to subclass.|true|-|
 +
 +^Tag^Description^Occurance^Default^
 +|behavior|Add behavior to element class.|0..N|-|
 +|string|<WRAP>Set named element property to string type value. Tag content is string value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|empty string|
 +|float|<WRAP>Set named element property to float type value. Tag content is float value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|0|
 +|integer|<WRAP>Set named element property to integer type value. Tag content is integer value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|0|
 +|boolean|<WRAP>Set named element property to boolean type value. Tag content is boolean value where ''true'', ''yes'', ''1'' are true values and ''false'', ''no'', ''0'' are false values. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|false|
 +|vector|<WRAP>Set named element property to floating point vector type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|vector2|<WRAP>Set named element property to floating point vector2 type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point|<WRAP>Set named element property to integer point type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point3|<WRAP>Set named element property to integer point3 type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|borderSize|<WRAP>Set named element property to integer borderSize type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * left: Left value. Optional. Defaults to ''0''.
 +  * top: Top value. Optional. Defaults to ''0''.
 +  * right: Right value. Optional. Defaults to ''0''.
 +  * bottom: Bottom value. Optional. Defaults to ''0''.
 +  * all: Set left, top, right and bottom to the same value. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|rectArea|<WRAP>Set named element property to integer rectArea type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|floatRectArea|<WRAP>Set named element property to floating point rectArea type value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|color|<WRAP>Set named element property to floating point color4 type value. Color can be defined either using hex, r/g/b/a or ir/ig/ib/ia. Mixing is not possible. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +  * r: Red value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * g: Green value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * b: Blue value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * a: Alpha value in the range 0..1 with values outside range allowed. Optional. Defaults to ''1''.
 +  * hex: Set color using hex notation. Value can be ''#rrggbb'' or ''#rrggbbaa'' with components in the range from ''00'' to ''ff''. Both upper and lower case are valid. Optional. Convenience attribute.
 +  * ir: Red value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ig: Green value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ib: Blue value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ia: Alpha value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|null|<WRAP>Set named element property to null value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|-|
 +|list|<WRAP>Set named element property to Array value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|-|
 +|map|<WRAP>Set named element property to Dictionary value. Attributes:
 +  * name: Name of the property to set. Same name as used for stub properties in world editor. Required.
 +</WRAP>|0..N|-|
 +
 +==== behavior ====
 +^Attribute^Description^Required^Default^
 +|type|Unique name of the behavior to add to the element class. Only names matching behavior factories added to the super element class can be used.|true|-|
 +|id|Unique identifier of behavior. Required to be used if multiple behaviors of the same type are added.|false|empty string|
 +
 +^Tag^Description^Occurance^Default^
 +|string|<WRAP>Set named element property to string type value. Tag content is string value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|empty string|
 +|float|<WRAP>Set named element property to float type value. Tag content is float value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|0|
 +|integer|<WRAP>Set named element property to integer type value. Tag content is integer value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|0|
 +|boolean|<WRAP>Set named element property to boolean type value. Tag content is boolean value where ''true'', ''yes'', ''1'' are true values and ''false'', ''no'', ''0'' are false values. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|false|
 +|vector|<WRAP>Set named element property to floating point vector type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|vector2|<WRAP>Set named element property to floating point vector2 type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point|<WRAP>Set named element property to integer point type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point3|<WRAP>Set named element property to integer point3 type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|borderSize|<WRAP>Set named element property to integer borderSize type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * left: Left value. Optional. Defaults to ''0''.
 +  * top: Top value. Optional. Defaults to ''0''.
 +  * right: Right value. Optional. Defaults to ''0''.
 +  * bottom: Bottom value. Optional. Defaults to ''0''.
 +  * all: Set left, top, right and bottom to the same value. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|rectArea|<WRAP>Set named element property to integer rectArea type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|floatRectArea|<WRAP>Set named element property to floating point rectArea type value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|color|<WRAP>Set named element property to floating point color4 type value. Color can be defined either using hex, r/g/b/a or ir/ig/ib/ia. Mixing is not possible. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +  * r: Red value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * g: Green value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * b: Blue value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * a: Alpha value in the range 0..1 with values outside range allowed. Optional. Defaults to ''1''.
 +  * hex: Set color using hex notation. Value can be ''#rrggbb'' or ''#rrggbbaa'' with components in the range from ''00'' to ''ff''. Both upper and lower case are valid. Optional. Convenience attribute.
 +  * ir: Red value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ig: Green value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ib: Blue value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ia: Alpha value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|null|<WRAP>Set named element property to null value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|-|
 +|list|<WRAP>Set named element property to Array value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|-|
 +|map|<WRAP>Set named element property to Dictionary value. Attributes:
 +  * name: Name of the parameter/property to set. If the name begins with with ''.'' the element property is set using name with behavior property prefix prepended. Otherwise construction parameter is set with the given name. Required.
 +</WRAP>|0..N|-|
 +
 +==== list ====
 +^Tag^Description^Occurance^Default^
 +|string|String type value. Tag content is string value.|0..N|empty string|
 +|float|Float type value. Tag content is float value.|0..N|0|
 +|integer|Integer type value. Tag content is integer value.|0..N|0|
 +|boolean|Boolean type value. Tag content is boolean value where ''true'', ''yes'', ''1'' are true values and ''false'', ''no'', ''0'' are false values.|0..N|false|
 +|vector|<WRAP>Floating point vector type value. Attributes:
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|vector2|<WRAP>Floating point vector2 type value. Attributes:
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point|<WRAP>Integer point type value. Attributes:
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point3|<WRAP>Integer point3 type value. Attributes:
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|borderSize|<WRAP>Integer borderSize type value. Attributes:
 +  * left: Left value. Optional. Defaults to ''0''.
 +  * top: Top value. Optional. Defaults to ''0''.
 +  * right: Right value. Optional. Defaults to ''0''.
 +  * bottom: Bottom value. Optional. Defaults to ''0''.
 +  * all: Set left, top, right and bottom to the same value. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|rectArea|<WRAP>Integer rectArea type value. Attributes:
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|floatRectArea|<WRAP>Floating point rectArea type value. Attributes:
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|color|<WRAP>Floating point color4 type value. Color can be defined either using hex, r/g/b/a or ir/ig/ib/ia. Mixing is not possible. Attributes:
 +  * r: Red value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * g: Green value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * b: Blue value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * a: Alpha value in the range 0..1 with values outside range allowed. Optional. Defaults to ''1''.
 +  * hex: Set color using hex notation. Value can be ''#rrggbb'' or ''#rrggbbaa'' with components in the range from ''00'' to ''ff''. Both upper and lower case are valid. Optional. Convenience attribute.
 +  * ir: Red value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ig: Green value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ib: Blue value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ia: Alpha value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|null|Null value.|0..N|-|
 +|list|Array value.|0..N|-|
 +|map|Dictionary value.|0..N|-|
 +
 +==== map ====
 +^Tag^Description^Occurance^Default^
 +|string|<WRAP>Set string value. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|empty string|
 +|float|<WRAP>Set float type value. Tag content is float value. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|0|
 +|integer|<WRAP>Set integer type value. Tag content is integer value. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|0|
 +|boolean|<WRAP>Set boolean type value. Tag content is boolean value where ''true'', ''yes'', ''1'' are true values and ''false'', ''no'', ''0'' are false values. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|false|
 +|vector|<WRAP>Set floating point vector type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|vector2|<WRAP>Set floating point vector2 type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point|<WRAP>Set integer point type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|point3|<WRAP>Set integer point3 type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * x: X coordinate of vector. Optional. Defaults to ''0''.
 +  * y: Y coordinate of vector. Optional. Defaults to ''0''.
 +  * z: Z coordinate of vector. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|borderSize|<WRAP>Set integer borderSize type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * left: Left value. Optional. Defaults to ''0''.
 +  * top: Top value. Optional. Defaults to ''0''.
 +  * right: Right value. Optional. Defaults to ''0''.
 +  * bottom: Bottom value. Optional. Defaults to ''0''.
 +  * all: Set left, top, right and bottom to the same value. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|rectArea|<WRAP>Set integer rectArea type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|floatRectArea|<WRAP>Set floating point rectArea type value. Attributes:
 +  * key: Key to assign value to. Required.
 +  * x1: Left value. Optional. Defaults to ''0''.
 +  * y1: Top value. Optional. Defaults to ''0''.
 +  * x2: Right value. Optional. Defaults to ''0''.
 +  * y2: Bottom value. Optional. Defaults to ''0''.
 +</WRAP>|0..N|-|
 +|color|<WRAP>Set floating point color4 type value. Color can be defined either using hex, r/g/b/a or ir/ig/ib/ia. Mixing is not possible. Attributes:
 +  * key: Key to assign value to. Required.
 +  * r: Red value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * g: Green value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * b: Blue value in the range 0..1 with values outside range allowed. Optional. Defaults to ''0''.
 +  * a: Alpha value in the range 0..1 with values outside range allowed. Optional. Defaults to ''1''.
 +  * hex: Set color using hex notation. Value can be ''#rrggbb'' or ''#rrggbbaa'' with components in the range from ''00'' to ''ff''. Both upper and lower case are valid. Optional. Convenience attribute.
 +  * ir: Red value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ig: Green value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ib: Blue value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +  * ia: Alpha value in the range 0..255 with values outside range allowed. Optional. Convenience attribute.
 +</WRAP>|0..N|-|
 +|null|<WRAP>Set null value. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|-|
 +|list|<WRAP>Set Array value. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|-|
 +|map|<WRAP>Set Dictionary value. Attributes:
 +  * key: Key to assign value to. Required.
 +</WRAP>|0..N|-|
 +
 +===== Examples =====
 +
 +This example creates a simple XML element class based on the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1SimpleElementClass.html,SimpleElementClass~@#. It modifies some element properties to use a specific model, skin and rig resource. The path are either absolute path (if starting with ''/'') or relative to the directory the ''*.deeclass'' file is located in.
 +
 +++++ Show Example|
 +<code xml>
 +<?xml version='1.0' encoding='UTF-8'?>
 +<elementClass name='PropBox' class='SimpleElement'>
 + <string name='component.model'>box.demodel</string>
 + <string name='component.skin'>/content/materials/concrete/material.deskin</string>
 + <string name='component.rig'>box.derig</string>
 + <string name='component.audioModel'>box.demodel</string>
 + <string name='navigationSpace.blockerShape'>box:position,0,0.3,-0.05:extends,1.3,0.5,1.3</string>
 +</elementClass>
 +</code>
 +++++
 +
 +This example creates a complex XML element class which is based on the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1GenericBehaviorElementClass.html,GenericBehaviorElementClass~@#. This allows adding behaviors inside the ''*.deeclass'' file avoiding the need to write an explicit script class to do the same. This is the example file used in the behavior factory video above.
 +
 +++++ Show Example|
 +<code xml>
 +<?xml version='1.0' encoding='ISO-8859-1'?>
 +<elementClass name='ExtendedCustomColor' class='GenericBehaviorElement'>
 + <!--
 + Example element class creating a similar element class as CustomColorExampleClass
 + but using GenericBehaviorElement as base class and adding behaviors in XML.
 + Furthermore some additional behaviors are added to show the flexibility of this approach.
 + -->
 +
 + <!--
 + Add component behavior. This adds a visible presence to the element. Also set some of
 + the parameters of the behavior. This could be done later in the XML file but it helps
 + to group the behavior and it's parameters to improve the readability.
 + -->
 + <behavior type='ECBehaviorComponent'>
 + <string name='.model'>/content/models/box/box.demodel</string>
 + <string name='.rig'>/content/models/box/box.derig</string>
 + <string name='.skin'>customColor.deskin</string>
 + </behavior>
 +
 + <!--
 + Add collider behavior. This adds physical presence to the element. Adding this behavior
 + automatically attaches to the component behavior previously added.
 + -->
 + <behavior type='ECBehaviorCollider'/>
 +
 + <!--
 + Add navigation space behavior. This adds support for adding navigation space and blockers.
 + We do not need navigation space but blockers. The behavior automatically uses the previously
 + added collider behavior.
 + -->
 + <behavior type='ECBehaviorNavigationSpace'/>
 +
 + <!--
 + In SimpleElementClass used as base class for CustomColorExampleClass the behaviors
 + ECBehaviorNavigationSpace and ECBehaviorAttachToParent are present too. We do not need
 + them in this class so we can skip them.
 + -->
 +
 + <!--
 + Add a couple of custom color behaviors. In SimpleElementClass 5 such behaviors are added.
 + We do the same thing here. Each behavior requires a unique identifier.
 + -->
 + <behavior type='ECBehaviorCustomColor' id='color1'>
 + <string name='.name'>Background</string>
 + <color name='.defaultColor' r='0' g='0' b='0.5'/>
 +
 + <!--
 + In SimpleElementClass there is also an example to define allowed colors. As mentioned
 + in the element class limiting to these colors is not implemented. Nevertheless it is
 + shown here how such a list of colors would be defined.
 + -->
 + <list name='.allowedColors'>
 + <color r='0' g='0' b='0.5'/> <!-- darkBlue -->
 + <color r='0.25' g='0.25' b='0.25'/> <!-- darkGray -->
 + <color r='0' g='0.5' b='0'/> <!-- darkGreen -->
 + <color r='0.5' g='0' b='0'/> <!-- darkRed -->
 + <color r='1' g='1' b='1'/> <!-- white -->
 + <color r='0' g='0' b='0'/> <!-- black -->
 + </list>
 + </behavior>
 +
 + <behavior type='ECBehaviorCustomColor' id='color2'>
 + <string name='.name'>Dragoness</string>
 + <color name='.defaultColor' r='0.85' g='0.3' b='1'/>
 + </behavior>
 +
 + <behavior type='ECBehaviorCustomColor' id='color3'>
 + <string name='.name'>Text Left</string>
 + <color name='.defaultColor' r='0.33' g='0.44' b='0.7'/>
 + </behavior>
 +
 + <behavior type='ECBehaviorCustomColor' id='color4'>
 + <string name='.name'>Text Right</string>
 + <color name='.defaultColor' r='0.8' g='0.8' b='0.8'/>
 + </behavior>
 +
 + <behavior type='ECBehaviorCustomColor' id='color5'>
 + <string name='.name'>Text Center</string>
 + <color name='.defaultColor' r='0.65' g='0.65' b='0.65'/>
 + </behavior>
 +
 + <!--
 + Add dynamic skin behavior. This allows the textures of the component behavior to be
 + modified dynamically at runtime. The behavior automatically uses the previously added
 + component behavior.
 + -->
 + <behavior type='ECBehaviorDynamicSkin'/>
 +
 + <!--
 + Add renderable canvas behavior. This modifies the "customColor" renderable defined
 + in the skin file. You need one per renderable you want to modify. Since we use only
 + one renderable canvas here we are not required to set an identifier. It is though
 + good practice to set one. This behavior automatically uses the previously added
 + dynamic skin behavior.
 + -->
 + <behavior type='ECBehaviorRenderableCanvas' id='customColor'>
 + <string name='.renderable'>customColor</string>
 + <point name='.size' x='512' y='512'/>
 + <color name='.backgroundColor' r='1' g='1' b='1'/>
 + </behavior>
 +
 + <!--
 + Add behaviors to apply the custom colors to the renderable canvas. These behaviors
 + automatically use the previously added renderable canvas behavior. Here we have
 + something new. Some behaviors support (or require) parameters at construction time.
 + This is done by adding parameter definitions inside the behavior tag. In general the
 + parameters required to be placed inside the behavior tag can not be changed later on
 + using regular property definition tags outside the behavior tag. See the respective
 + Factory inner classes inside the behavior of interest for information on such parameters.
 + In the case of the ECBehaviorRenderableCustomColor behavior we have to define which
 + ECBehaviorCustomColor behavior to use.
 +
 + Because we created above a renderable canvas behavior with a non-empty identifier
 + we have to define below which renderable canvas we want to use. If the identifier
 + would be empty (not set) we could remove the renderCanvas string tag and the factory
 + would use the renderable canvas with the empty identifier.
 + -->
 + <behavior type='ECBehaviorRenderableCustomColor' id='color1'>
 + <string name='customColor'>color1</string>
 + <string name='renderableCanvas'>customColor</string>
 +
 + <string name='.image'>color1.png</string>
 + </behavior>
 +
 + <behavior type='ECBehaviorRenderableCustomColor' id='color2'>
 + <string name='customColor'>color2</string>
 + <string name='renderableCanvas'>customColor</string>
 +
 + <string name='.image'>color2.png</string>
 + </behavior>
 +
 + <behavior type='ECBehaviorRenderableCustomColor' id='color3'>
 + <string name='customColor'>color3</string>
 + <string name='renderableCanvas'>customColor</string>
 +
 + <string name='.image'>color3.png</string>
 + </behavior>
 +
 + <behavior type='ECBehaviorRenderableCustomColor' id='color4'>
 + <string name='customColor'>color4</string>
 + <string name='renderableCanvas'>customColor</string>
 +
 + <string name='.image'>color4.png</string>
 + </behavior>
 +
 + <behavior type='ECBehaviorRenderableCustomColor' id='color5'>
 + <string name='customColor'>color5</string>
 + <string name='renderableCanvas'>customColor</string>
 +
 + <string name='.image'>color5.png</string>
 + </behavior>
 +
 + <!--
 + Add behavior for player to interact with this element. Adjust the interaction zone
 + to work with the box. This is a behavior specific to the example application. For this
 + reason it uses the prefix "Behavior" instead of "ECBehavior" as the behaviors provided
 + by the Drag[en]gine. Another typical prefix is "ECB". This prefix can be used to avoid
 + confusion with game world behaviors which use prefix "GWBehavior".
 + -->
 + <behavior type='BehaviorChooseColors'>
 + <vector name='.interactionSpot.position' x='0' y='0' z='3'/>
 + <vector name='.interactionSpot.lookAt' x='0.5' y='1' z='1'/>
 + </behavior>
 +
 + <!--
 + At this point we have replicated the behaviors present in the SimpleElementClass but
 + using an XML element class instead of a DragonScript class. The advantage of using
 + the XML element class way is that no script changes are required. It is also possible
 + to use automated tools to produce or modify such files.
 + -->
 +
 + <!--
 + Let's add some more behaviors to extend the element class, even if it is silly. Let's first
 + add a light near the front side which is red and strong enough against the sun.
 + -->
 + <behavior type='ECBehaviorLight'>
 + <float name='.intensity'>50</float>
 + <float name='.halfIntensityDistance'>0.5</float>
 + <float name='.range'>1</float>
 + <color name='.color' r='1'/>
 + <vector name='.position' x='0' y='0.25' z='1.1'/>
 + </behavior>
 +
 + <!--
 + And just because we can also add two particle emitters on top of it. The first one produces
 + a flame and the second one the smoke. Actually this can be done using a single particle
 + emitter emitting two types of particles but for this example two emitters are used.
 + -->
 + <behavior type='ECBehaviorParticleEmitter' id='flame'>
 + <string name='.path'>/content/emitters/flame1.depemit</string>
 + <vector name='.position' y='2.05' z='0.75'/>
 + <vector name='.orientation' x='90'/>
 + </behavior>
 +
 + <behavior type='ECBehaviorParticleEmitter' id='smoke'>
 + <string name='.path'>/content/emitters/smoke.depemit</string>
 + <vector name='.position' y='2.3' z='0.75'/>
 + <vector name='.orientation' x='90'/>
 + </behavior>
 +
 + <!--
 + And where there is fire should be also sound. Add a speaker behavior with some sound playing.
 + -->
 + <behavior type='ECBehaviorSpeaker'>
 + <string name='.sound'>/content/sound/crackle.ogg</string>
 + <float name='.range'>15</float>
 + <float name='.volume'>0.5</float>
 + <vector name='.position' y='2.5' z='0.75'/>
 + </behavior>
 +</elementClass>
 +</code>
 +++++
  
dragengine/modules/dragonscript/behavior_elements.1741603472.txt.gz · Last modified: 2025/03/10 10:44 by dragonlord

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
CC Attribution-Noncommercial-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki