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 created by subclassing from BehaviorElementClass script class. This class extends the ElementClass script class with support to add Behavior Definitions. When a 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 definitions are created by subclassing from ECBehavior script class. This stands for Element Class Behavior. Behavior definitions typically contain Composeable Element Class or Element Class Property instances with appropriate parameters set. This has a few nice properties making life simpler.

Element class properties can be used with XML Subclassing. You can created a new element class just using an XML file (*.deeclass) and change the properties added by the behavior definition. This is especially useful for mappers to add variations of Game Objects without needing to touch script code for such a simple task.

Furthermore Element Stubs used to create Game Objects in your game world use the same names as the element class properties. This allows mappers to modify behaviors on a per Game Object basis if required.

You can query BehaviorElementClass if it contains behaviors of a specific type. Some behavior definitions can be used more than once on the same element class. In this case you can assign each instance a unique identifier. This identifier is used to distinguish between the behavior definition instances and acts also as prefix modified of the added element class properties.

Once a BehaviorElement instance is created each behavior definitions adds a subclass of ECBehaviorInstance. These provide the actual behavior to the BehaviorElement instance. Here too you can query the element if it contains instances of a specific behavior.

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 Explained: By Use-Case
• Behaviors Explained: From A to Z

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.

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

pin Dragengine.Gui
pin Dragengine.Scenery
pin Dragengine.Utils

class MyTrainClass extends BehaviorElementClass
    public var ECBehaviorComponent component  // visual appearance
    public var ECBehaviorAnimated animated  // animated the visual appearance
    public var ECBehaviorCollider collider  // physical interaction
    public var ECBehaviorMoveOnRail moveOnRail  // move the collider on along a rail
    public var ECBehaviorLight headLightLeft  // left head light
    public var ECBehaviorLight headLightRight  // right head light
    public var ECBehaviorSpeaker speaker  // engine sound
    
    public func new() super("MyTrainTest")
        // create visual appearance with default model(mesh), skin and rig. the rig is used both for
        // physical interaction and animation purpose. this method assigns the resources located
        // in the common directory "/content/train"
        component.setCommonPath("/content/train", "train.demodel", "train.deskin", "train.derig")
        
        // create collider which is used for physical interaction. in most situations you want to
        // animate the component with the rig. this requires to component behavior to go first
        collider = ECBehaviorCollider.new(this, component)
        
        // create head lights. attached to collider with id "headlightLeft" respectively "headlightRight"
        headLightLeft = ECBehaviorLight.new(this, collider, "headlightLeft")
        headLightLeft.getLight().getColor().setColor(Color.yellow)
        headLightLeft.getAttach().getPosition().setVector(Vector.new(-1, 0.5, 2))
        
        headLightRight = ECBehaviorLight.new(this, collider, "headlightRight")
        headLightRight.getLight().getColor().setColor(Color.yellow)
        headLightRight.getAttach().getPosition().setVector(Vector.new(1, 0.5, 2))
        
        // create engine speaker. attached to the collider
        speaker = ECBehaviorSpeaker.new(this, collider)
        speaker.getSpeaker().getSound().setPath("/content/train/engine.ogg")
        speaker.getAttach().getPosition().setVector(Vector.new(0.0, 0.5, 1.5))
        
        // create behavior animating the visual appearance (component) using an animator
        animated = ECBehaviorAnimated.new(this, component)
        animated.getAnimator().getAnimator().setPath("/content/train/train.deanimator")
        
        // create behavior moving collider on rail. the mapper defines what rail to use.
        // if you assign also the trigger table from the BaseGameApp then the mapper
        // can use triggers to start/stop moving the train. if you want to control this
        // on your own (or by other behaviors only) leave out this argument
        moveOnRail = ECBehaviorMoveOnRail.new(this, collider, BaseGameApp.getApp().getTriggerTable())
   end
end

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

class MyTrainClass extends BehaviorElementClass
    ...
    protected func Element createElement()
        return MyTrain.new(this)
    end
end

class MyTrain extends BehaviorElement
    public func new(MyTrainClass eclass) super(eclass)
        ...
    end
end

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.

Attachable behaviors allow to add temporary behaviors to an element at runtime. They are similar in how the work to regular behaviors but instead of being added to BehaviorElementClass they are added to BehaviorElement directly. Hence while all BehaviorElement belonging to the same BehaviorElementClass own the same behaviors they all can have individual attachable behaviors. Furthermore attachable behaviors can be removed which can not be done with regular behaviors.

Attachable behaviors implement ECAttachableBehavior or subclass DefaultECAttachableBehavior. At runtime script code can attach behaviors using BehaviorElement.addAttachableBehavior() as well as removing it any time using BehaviorElement.removeAttachableBehavior().

Once added attachable behaviors can react to similar events like behaviors if they request it. Usually attachable behaviors react to onAddToElement() and onRemoveFromElement() to add or remove their effect to the parent element.

Attachable behaviors also are required to be persistable the same way as behaviors are. Hence attachable behaviors added to behavior elements are persisted in a future proof way as regular behaviors are.

Important to note is that attachable behaviors do not use the same interface as regular behaviors. This is on purpose since regular behaviors are split into ECBehavior and ECBehaviorInstance working together while ECAttachableBehavior is a standalone instance.

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.

In detail documentation here: XML Element Classes

The GameWorld class supports behaviors too. Game world behaviors are not split into a behavior and instance part but only exist as behaviors. This is because game world behaviors are added to a game world class directly without a meta class. In this sense game world behaviors work similar to attachable behaviors. Using game world behaviors you can add functionality to game worlds without needing to subclass GameWorld.

Similar to attachable behaviors, game world behaviors can access the StubGameWorld properties to configure their workings. These properties can be set in the IGDE World Editor and defined in the IGDE Game Definition Editor so you can easily select them.

Some game world behaviors support being added multiple times a game world. In this case use the behavior identifier to distiguish them (their properties and added features).

• Game World Behaviors Explained: From A to Z

To create your own game world behavior subclass from DefaultGWBehavior and add a new instance to a loaded game world, typically by using GameWorldLoader.

The BaseGameApp class supports behaviors too. Game application behaviors are not split into a behavior and instance part but only exist as behaviors. This is because game application behaviors are added to BaseGameApp instance directly without a meta class. In this sense game application behaviors work similar to attachable behaviors. Using game application behaviors you can add functionality to BaseGameApp without needing to overwrite class functions.

Game application behaviors use BaseGameApp.getConfiguration() parameter tree to configure their workings. These configurations are typically loaded from a configuration.dept file but they can be set also in the BaseGameApp subclass constructor.

Some game application behaviors support being added multiple times to BaseGameWorld. In this case use the behavior identifier to distinguish them (their configuration path and added features).

• Game Application Behaviors Explained: From A to Z

To create your own game application behavior subclass from DefaultGABehavior and add a new instance to BaseGameApp instance.