Widgets are objects in the game that help us display information (such as the Text widget) or interact with the player (such as the Dialog widget). Unlike the sprites, widgets are not affected by the game’s physics. Also unlike sprites, widgets are fixed to the camera - so no matter how the camera moves, a widget will be displayed in the same place. There are different types of widgets, each with its own properties and functions.

When a widget is added, the definition of its event’s functions already exist in the code. If code is not added to the functions, then nothing will happen when the event occurs.

Widgets available:

Widget Name

Description

Counter

Used to keep count.

Text

Used to display text on the screen.

Timer

Used to time events in the game.

Clock

Used to show the duration of time that has passed.

Button

Used to include buttons in the game.

Dialog

Used to show a message to the player.

General Settings

All widgets have the following settings:

Settings Name

Values

Use To

Name

The default name is the widget type (i.e counter, timer, etc).

Used to reference the widget throughout the game.

Show

Checked - widget is shown (default).

Unchecked - widget is hidden.

Show or hide the widget.

Functions

Function Name

Category

Description

show

Display

Shows the widget.

hide

Display

Hides the widget.


show()

Shows the sprite or the widget.

Example

If this is written in the Timer widget, then the timer is shown.

@show()


hide()

Hides the sprite or the widget.

Example

If this is written in the Timer widget, then the timer is hidden.

@hide()


Counter

The Counter widget is used to keep count. For example the score of the game or the number of lives that the player has left.

Properties

Property Name

Values

Use To

Update

value

0 is the default value.

The property value is displayed on the game’s screen.

The property can only be updated in the code.

Examples

Adds 100 points to a counter named score.

counter.value += 100

Starts the game with a counter that equals 3. This is written in the Counter widget’s code.

@value = 3


Text

The Text widget is used to display labels or texts on the game’s screen.

Properties

Property Name

Type

Use To

Update

text

string

The text to display,

"Hello world!" is the default.

Both, from the settings and code (i.e. text.text = "text to display").

Examples

The string "Lives:" will be displayed on the screen. This text can be used to display a name for a counter on the screen.

text.text = "Lives:"


Timer

The Timer widget is used to time activities in the game. For example, if the game will run and end after x seconds. Or, for example, to set a time limit on a sprite’s special power.

Functions

Function Name

Description

start

Starts the timer.

onEnd

The onEnd function is called when the time of the timer ends.


start numberOfSeconds, mode

Starts running the timer for the numberOfSeconds argument.

The argument mode defines if the timer will restart after it ends (i.e.run in a loop) or run once (default).

Arguments

Name

Type

Description

numberOfSeconds

number

The number of seconds the timer should run for.

mode

Boolean

Optional

The mode defines if the timer will run once or in a loop.

  • no/false - timer runs once (default)

  • yes/true - timer runs in a loop

Example

This will set the timer to run for 3 seconds repeatedly.

@start 3, yes

This will set the timer to run once for 15 seconds.

@start 15

Tip

To control the start of the timer, the start function should be used in a function. Otherwise, it will be executed as the game starts running, like any other code that is not written within a function.


onEnd

The onEnd function is called once the timer is up. When the timer is set to run in a loop, this function is called each time the timer ends.

This function is defined in the widget.

This function is triggered by an event (an end of timer event). It does not need to be called explicitly.

Syntax

@onEnd = () =>

Example

Hide the timer widget once the time ends.

@onEnd = () =>
@hide()


Clock

The Clock widget is used to show the elapsed time. It counts the elapsed seconds starting from 0 (as opposed to the timer that counts backwards until 0).

Functions

Function Name

Description

start

Starts the clock.

getSeconds

Returns the number of seconds that have elapsed.


start()

Starts the clock.

Example

If this is written in the clock’s code, it will start running the clock.

@start()

Tip

To control the start of the clock, the start function should be used in a function. Otherwise, it will be executed as the game starts running, like any other code that is not written within a function.

Calling the start function after the clock has already started will restart the clock to count from zero.


getSeconds()

Returns the number of seconds that have passed since the clock started running.

Returns

Number - number of seconds.

Example

If the player completes the game in less than 10 seconds, then add 100 bonus points to the score (Counter widget).

if clock.getSeconds() < 10
score.value += 100


Button

Use the Button widget to create a simple interface for your game. For example, to start the game by clicking on a Play button.

Properties

Property Name

Type

Values

Use To

Update

image

Checkmark (default)

An arrow

Chose image to use for the button.

From the settings only.

rotation

number

0 - right (default)

90 - down

180 - left

270 - up

The direction in degrees that the image of the button is rotated to.

From the settings only.

Functions

Function Name

Description

onDown

The onDown function is called when the button is pressed.

onClick

The onClick function is called when the button is clicked.


onDown()

The onDown function is called when the button is pressed down. The function will be called for as long as the button is pressed.

This function should be defined in the widget’s code.

This function is triggered by an event. It does not need to be called explicitly.

Syntax

@onDown = () =>

Example

In this example, for as long as the button is pressed down, the monkey will jump.

@onDown = () =>
monkey.jump()


onClick()

The onClick function is called when the button is released (or clicked). This function will be called once.

This function should be defined in the widget’s code.

This function is triggered by an event. It does not need to be called explicitly.

Syntax

@onClick = () =>

Example

In this example, once we "let go" of the mouse button, the function will be called and the timer will start running for 10 seconds.

@onClick = () =>
timer.start 10


Dialog

The Dialog widget is used to display a message to the player. The message is a string.

Properties

Property Name

Type

Use To

Update

text

string

The text to display.

Both, from the settings and code (i.e. dialog.text = "Game Over").

Functions

Function Name

Description

onConfirm

The onConfirm function is called when the player clicks on the button in the dialog.

Examples

Simple text. In this example, the message in the dialog will be "GAME OVER".

dialog.text = "GAME OVER"

Text with a parameter. In this example, when the dialog is displayed the value of score.value is replaced. For example, if score.value is 200, then the message in the dialog will be "Your score is 200!".

dialog.text = "Your score is: #{score.value}!"

onConfirm

The onConfirm function is called when the button on the dialog is clicked on.

This function should be defined in the widget’s code.

This function is triggered by an event. It does not need to be called explicitly.

Syntax

@onConfirm = () =>

Example

Start the timer when the player clicks on a welcome dialog.

@onConfirm = () =>
timer.start 20


Relevant Articles:

Game Builder Guide

Game Builder - Sprites Tab

Game Builder - Additional Features

Game Builder (Text Based) - Coding Concepts

Did this answer your question?