An Introduction to Behaviors in Quorum

In this tutorial, we will learn how to use Behaviors in the Quorum Game Engine. Behaviors are critical to GUI tools because they typically define what action is taken when a tool is activated.

There are four actions in the Behavior class:
  1. Run, which is called when an action is taken with the Behavior.
  2. Update, which is called on each frame of the program while the Behavior is active.
  3. Dispose, which is used for cleanup actions when the Behavior is finished.
  4. IsFinished, which states if a Behavior is finished.

For this tutorial, we will create a simple Behavior that causes a Drawable to rotate for five seconds, and then change color. To start, create a new Game Application project.

Rotating a Drawable

Since we'll be using a Drawable and we will be altering its Color, we must include the Drawable and Color libraries. This is done by adding the following Use statements:
use Libraries.Game.Drawable
use Libraries.Game.Graphics.Color

First, we will create a Drawable object and a Color object. For the purposes of this tutorial, we want the Drawable to use its Behavior as soon as the game begins, so we'll add it to the game in the CreateGame action. Below are our declarations:

Drawable box
Color color

Next, let's load a rectangle shape using the Drawable's LoadFilledRectangle action. We are going to make it red for this tutorial. Next, we'll give it a position with the SetPosition action. Finally, we'll add it to the game using "Add(box)". This gives us the following lines of code:

box:LoadFilledRectangle(300, 200, color:Red())
box:SetPosition(250, 250)
Add(box)

For more information on using Drawables, check out the tutorial on Drawing in 2D.

So far, our Main class looks like this:

use Libraries.Game.Game
use Libraries.Game.Graphics.Drawable
use Libraries.Game.Graphics.Color

class Main is Game
    action Main
        StartGame()
    end

    action CreateGame
        Drawable box
        Color color
        box:LoadFilledRectangle(300, 200, color:Red())
        box:SetPosition(250, 250)
        Add(box)
    end

    action Update(number seconds)
    end
end

Now, we can add a Behavior to our Drawable. To begin, create a new Quorum class, which we will name "RotationBehavior.quorum". To create a Behavior, we must include the Behavior and BehaviorEvent libraries. Additionally, we will be using the Color, Drawable, and Speech libraries, giving us the following use statements:

use Libraries.Interface.Behaviors.Behavior
use Libraries.Interface.Events.BehaviorEvent
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Drawable
use Libraries.Sound.Speech

The RotationBehavior class itself will inherit the Behavior class, and we will override the actions for Run, Update, Dispose, and IsFinished. Additionally, we need to create a Drawable class variable to store our rectangle for use in all actions, and we must also create a timer so that we can make our Behavior last for five seconds, giving the following template:

use Libraries.Interface.Behaviors.Behavior
use Libraries.Interface.Events.BehaviorEvent
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Drawable
use Libraries.Sound.Speech

class RotationBehavior is Behavior
    Drawable item = undefined
    Number timer = 0

    action Run(BehaviorEvent event)
    end

    action Update(number seconds)
    end

    action Dispose
    end

    action IsFinished returns boolean
    end
end

For more information on inheritance and overriding actions, see the tutorial on Inheritance.

In the Run action, we must first obtain the Drawable we want to rotate. Since the RotationBehavior will later be added to the Drawable itself in the main class, we can use the BehaviorEvent's GetItem action to get the object associated with the Behavior. However, this action returns an Item, not a Drawable, so we must cast it. This gives us the following line:

item = cast(Drawable, event:GetItem())

Next, for the program to say "Rotate," we will need to use the Speech class's Say action, giving us the following lines:

Speech speech
speech:Say("Rotate")

For more information on the Speech class, see the documentation on the Speech class.

This gives the following complete Run action:

action Run(BehaviorEvent event)
    item = cast(Drawable, event:GetItem())
    Speech speech
    speech:Say("Rotate")
end

Moving on to the Update action, we want our rectangle to rotate, and we want to keep track of the time elapsed. Therefore, we need to increment the timer and call the Drawable's Rotate action. Since the Update action will be used for five seconds, a rotation of 72 degrees per second will result in a full 360 degrees rotation, giving us the following Update action:

action Update(number seconds)
    timer = timer + seconds
    if item not= undefined
        item:Rotate(72 * seconds)
    end
end

Note that the conditional if statement checks if the item variable is defined. If we did not include this, then the program could potentially crash by attempting to rotate an object that does not exist.

In the Dispose action, we want our rectangle to change color to indicate that the Behavior is finished. As such, we need to create a Color variable and call the Drawable's SetColor action. Lastly, for the program to say "Rotation complete," we will once again need to use the Speech class's Say action. This gives the following Dispose action:

action Dispose
    if item not= undefined
        Color color
        item:SetColor(color:Green())
        Speech speech
        speech:Say("Rotation complete")
    end
end

With this, once the Behavior is finished, the rectangle will change from Red to Green, and the program will say "Rotation complete."

In the IsFinished action, we need to set the action to return true once five seconds have passed. Thus, we simply add the line "return timer >= 5" to get the following action:

action IsFinished returns boolean
    return timer >= 5
end

Altogether, the resulting RotationBehavior class looks like this:

use Libraries.Interface.Behaviors.Behavior
use Libraries.Interface.Events.BehaviorEvent
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Drawable
use Libraries.Sound.Speech

class RotationBehavior is Behavior

    Drawable item
    number timer = 0

    action Run(BehaviorEvent event)
        item = cast(Drawable, event:GetItem())
        Speech speech
        speech:Say("Rotate", false)
    end

    action Update(number seconds)
        timer = timer + seconds

        if item not= undefined
            item:Rotate(72 * seconds)
        end
    end

    action Dispose
        if item not= undefined
            Color color
            item:SetColor(color:Green())
            Speech speech
            speech:Say("Rotation complete", false)
        end
    end

    action IsFinished returns boolean
        return timer >= 5
    end
end

Lastly, we must return to the main class and give a RotationBehavior to our Drawable. At the end of the CreateGame action, this can be done creating a RotationBehavior variable and calling the Drawable's AddBehavior action, giving us the following lines:

RotationBehavior rotate
box:AddBehavior(rotate)

The resulting final version of the Main class is as follows:

use Libraries.Game.Game
use Libraries.Game.Graphics.Drawable
use Libraries.Game.Graphics.Color

class Main is Game

    action Main
        StartGame()
    end

    action CreateGame
        Drawable box
        Color color
        box:LoadFilledRectangle(300, 200, color:Red())
        box:SetPosition(250, 250)
        Add(box)

        RotationBehavior rotate
        box:AddBehavior(rotate)
    end

    action Update(number seconds)
    end
end

Now, when the program is run, the rectangle will start as red, the program will say "Rotate," the rectangle will make one full rotation over five seconds, and then turn green while the program says "Rotation complete." The following images show a sample of the beginning, middle, and end of the Behavior's execution.

This is an image of initial position of the Drawable.This is an image of a position of the Drawable mid-Behavior.This is an image of end position of the Drawable.

Next Tutorial

In the next tutorial, we will discuss Buttons, which describes how to use Buttons.