User Interfaces

Easel provides a simple and powerful way to create user interfaces for your games. These can be used to create standalone webpages surround your game, or create the heads up display or control systems within your game itself. In Easel, user interfaces (commonly abbreviated as UI) are defined in a declarative manner, and can be dynamically updated using a streamlined syntax.

Creating user interfaces

To create a user interface, first create a Section. There are two kinds of sections - content and transmissions:

• Content (also Toolbar, Modal and some others) is owned by its entity and will be removed when its owning entity despawns.
• A Transmission (also Print) will automatically disappear after a certain duration.

Within the section, add elements, such as P for paragraphs or Button for buttons.

pub fn Example() {
    Spawn greetingDialog {
        Content {
            P { "Hello, world!" }
        }
    }
}

Displaying text

% statements can be used to display any text into the user interface.

pub fn Example(age) {
    Transmission {
        %("You are " + age + " years old")
    }   
}

The % can be omitted when only a string literal is being displayed, or when displaying a string concatenation that begins with a string literal.

pub fn Example(name) {
    Transmission {
        "Hello, world!"
        "My name is " + name
    }
}

info

The % statement inserts its text into the slot designated by the ui parameter which it finds implicitly from context. You should not need to worry about any of this. As long as you use % inside of a UI function subblock, it should "just work" as expected.

Updating the user interface

In general, the way to update the user interface is to use a loop (or some other construct like a with block) to execute the same code again. The loop will replace the previously-generated user interface elements on each iteration.

pub fn owner.Score = 0

pub fn owner.DisplayScore() {
    TopContent {
        with Score {
            H1 { %(Score) }
        }
    }
}

info

How does Easel know which part of the user interface to update? See Under the Hood to learn more.

Appending elements

Prefix a loop body with %% to append user interface elements on each iteration, rather than replace them.

pub fn Example() {
    Transmission {
        // without %%, we would update rather than append to the user interface
        for i in Range(0,10) %%{
            P { "I am element " + i }
        }
    }
}

Without %%{ ... }, the above loop would first emit "I am element 0" on the first iteration, then replace it with "I am element 1" on the second iteration. Wrapping the loop body with %%{ ... } causes the loop to append to its user interface elements on each iteration, so that "I am element 0", "I am element 1", "I am element 2", etc are all displayed in the user interface at the same time.

This syntax may be used in the same for all forms of loop, behavior and callback blocks.

for i in Range(0,10) %%{ ... }
repeat 5 %%{ ... }
while x < 5 %%{ ... }
once Tick(1s) %%{ ... }
on Tick(1s) %%{ ... }
with Health %%{ ... }
|name, age, ui| %%{ ... }
FunctionWithSubblock %%{ ... }