The sprites are game objects that can be considered the lifeblood of the game. Add as many sprites as needed (different sprites or the same ones). The sprites have speed and scale. The world’s gravity can apply on sprites.

Each sprite has a sprite sheet. The sprite sheet is made up of frames. When an animation runs, for example animation of "step", the frames of the sprite sheet are shown in a specified order to cause the illusion that the sprite is moving.

Setting Properties from the Sprites' Setting Icon

The following properties can be updated from the settings button of each sprite. A sprite is added with all the default values. When the settings change, the sprite is affected immediately. For example, if the Show option is unchecked, the sprite is hidden from the screen. The sprite starts with these settings when the game first runs.

Some sprites’ properties can only be set from the Sprites settings icon, some can only be set in the code, while others can be set in both places.

In the table below, the column "See Also", names the function that can be used in the code, to set the property.

You can also drag a sprite on the screen to set its x,y values.

Name

Values

Used For

See Also

Name

The default name is the spritesheet’s name (i.e monkey, frog, etc).

Name the sprite. Refer to the sprite with this name in different parts of the code.

X

Based on world’s size.

Default: 300

The sprite’s x position.

setX

Y

Based on world’s size.

Default: 200

The sprite’s y position.

setY

Rotation

0 - right (default)

90 - down

180 - left

270 - up

The direction in degrees that the sprite points to (which way the sprite is looking).

setRotation

Allow Gravity

Checked - gravity affects the sprite.

Unchecked - gravity doesn’t affect the sprite.

This option applies only when the game has gravity.

If the sprite should "stand in the air" and not let gravity affect it, then uncheck this option.

Immovable

Checked - sprite will not move during a collision event.

Unchecked - sprite will move during a collision event (default).

This option applies when two sprites collide.

Check this option when a sprite should not move during a collision with another sprite.

Collide world bounds

Checked - sprite cannot move beyond world bounds (default).

Unchecked - sprite can move beyond world bounds.

This option defines whether the sprite collides with the world’s bounds or if it can move beyond it.

Show

Checked - sprite is shown in the game (default).

Unchecked - sprite is hidden, not shown in game.

Show or hide the sprite on the game screen.

To start a game with the sprite hidden in the game, uncheck this option.

show()

hide()

Functions

The table below lists all functions that can be used in the code.

The table’s column: Category is the name of the tab where the function’s button appears. The tabs can be found in the game builder, under the code editor.

The column titled Physics states whether the function is available in the arcade option, P2 option or both.

The events’ functions (event handlers) are called when a specific event happens (for example when a key is pressed on the keyboard or when two sprites collide). Events are predefined. Event handlers (functions) may be defined in the code. Event handlers are called at the occurrence of the corresponding event. When an event handler is not specified in the code, the corresponding event goes unhandled.

Using all other functions is by calling the function in the code.

List of Functions

Function Name

Category

Description

Physics

onKey

Events

Called when a key is pressed on the keyboard.

Both

onSwipe

Events

Called when the screen is swiped.

Both

OnCollide

Events

Called when two sprites collide (bump) with each other.

Both

onCollideWithWorldBounds

Events

Called when a sprite collides with one of the world bounds.

Both

onCollideWithTilemap

Events

Called when the sprite collides with a tile in the tilemap.

P2

onClick

Events

Called when the sprite is clicked on (using the mouse).

Both

onAnimationEnd

Events

Called when an animation, that does not run in a loop, ends.

Both

onAnimationLoop

Events

Called each time an animation that runs in a loop ends.

Both

onUpdate

Events

Called on each frame change.

P2

step

Movements

Makes the sprite move.

Arcade

jump

Movements

Makes the sprite jump.

Arcade

setX

Movements

Sets the sprite’s x position.

Both

setY

Movements

Sets the sprite’s y position.

Both

getX

Movements

Returns the sprite’s x position.

Both

getY

Movements

Returns the sprite’s y position.

Both

setRotation

Movements

Rotates the sprite.

Arcade

getRotation

Movements

Returns the sprite’s rotation.

Both

setSpeed

Movements

Sets the sprite’s speed.

Arcade

thrust

Movements

Applies a thrust force on the sprite.

P2

rotateLeft

Movements

Rotates the sprite to the left.

P2

rotateRight

Movements

Rotates the sprite to the right.

P2

getVelocityX

Movements

Returns the sprite’s velocity in the x axis.

P2

getVelocityY

Movements

Returns the sprite’s velocity in the y axis.

P2

show

Display

Shows the sprite.

Both

hide

Display

Hides the sprite.

Both

destroy

Display

Destroys the sprite.

Both

disable

Display

Disables the spite from the game.

Both

enable

Display

Brings back a disables sprite.

Both

setScale

Display

Sets the sprite’s scale.

Both

addAnimation

Display

Adds (defines) an animation to a sprite.

Both

startAnimation

Display

Starts running the animation.

Both

stopAnimation

Display

Stops the animation.

Both

@ vs. sprite name

Referring to a property or function of a sprite/widget, within the sprite/widget’s code, is done by writing: @ before the property’s or function’s name. Referring, within a sprite/widget code, to another sprite/widget’s property or function, use the other sprite/widget name.

In following example - we write the code only in the monkey's sprite.

  • To move the monkey, we use @step

  • To move the hippo, we use: hippo.step

More Examples

Below are some examples of using @ and using the sprite’s or widget’s name:

Function/Property

Sprite/ Widget’s Name

Code

Explanation

step

monkey

@step 1

Monkey steps.

step

monkey

tiger.step 100

Tiger steps.

step

tiger

@step 100

Tiger steps.

setSpeed

monkey

@setSpeed 3

Monkey’s speed is set to be 3 faster than the default.

setSpeed

monkey

tiger.setSpeed 4

Tiger’s speed is set to be 4 times as fast.

destroy

banana

heart.destroy()

Destroys the heart.

destroy

banana

@destroy()

Destroys the banana.

value

monkey

counter.value += 100

Adds 100 to the counter.

start

monkey

timer.start 5

Starts the timer for 5 seconds.

start

timer

@start 20

Starts the timer for 20 seconds.


onKey key

The onKey function (event handler) is called each time a key is pressed on the keyboard. This function can be used to control elements of the game using the keyboard. For example: moving a sprite by pressing keys on the keyboard.

The function is defined in a sprite’s code. The same event can have more than one event handler if written in different sprites.

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

Arguments

Name

Type

Description

key

string

The key that was pressed on the keyboard.

Constants

The following constants can be used to refer to the arrow keys:

  • keyboard.left

  • keyboard.right

  • Keyboard.up

  • keyboard.down

Syntax

@onKey = (key) =>

Example

In the example below, when the right arrow key on the keyboard is pressed, the sprite moves.

@onKey = (key) =>
if key == keyboard.right
@step 1


onSwipe direction

The onSwipe function is called each time a touch-screen is swiped. Define this function to allow controlling behavior of the sprites or the game by swiping the screen.

For example, to move the sprites in the direction of the swipe. Pressing an arrow key on the keyboard throws swipe event with the correct direction (for example, pressing on the right arrow key throws a swipe event with right as the direction).

The function should be defined in a sprite’s code.

This function is triggered by an event (the swiping of the screen event). It does not need to be called explicitly.

Arguments

Name

Type

Description

direction

string

The direction of the swipe.

Constants

These constants should be used for the direction of the swipe:

  • swipe.left

  • swipe.right

  • swipe.up

  • swipe.down

Syntax

@onSwipe = (direction) =>

Example

In this example, when the screen is swiped to the right, the sprite rotates to the right and moves.

@onSwipe = (direction) =>
if direction == swipe.right
@setRotation 0
@step 100

Tip

When no touchpad is available, use the arrow keys on the keyboard to simulate a swipe event (and trigger the onSwipe function).


onCollide sprite, handler

The onCollide function (event handler) is called each time two sprites collide.

The onCollide function is written in one of the colliding sprite’s code. The second sprite is specified as the first argument of the function.

The function should be defined in a sprite’s code.

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

Arguments

Name

Type

Description

sprite

Sprite

The sprite that this sprite collided with.

handler

function

The name of a function to call when the two sprites collide.

Empty () means calling this function.

Syntax

@onCollide sprite, () =>

Example

How the monkey eats the banana: The onCollide function is defined in the banana’s sprite and the monkey is the sprite it collides with. In this example, when the banana collides with the monkey, the banana is destroyed.

@onCollide monkey, () =>
@destroy()

Tip

The onCollide function can be written in either one of the sprite’s code. It should be written in the code of the sprite whose code is easier to maintain or in the sprite that might be duplicated.

For example: if the game includes a monkey and two bananas.

Option 1: The onCollide handler is written in the monkey sprite’s code. In this case, two onCollide functions need to be defined (one with banana1 and the other with banana2).

Option 2: onCollide is written in the banana sprite’s code. The banana sprite is then duplicated. This way, the onCollide function, is duplicated as well.


onCollideWithWorldBounds directions

The function is called when a sprite collides with one of the world’s boundaries. When using arcade physics, the argument directions holds the name of the boundary into which the sprite collided.

The function should be defined in a sprite’s code.

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

The directions argument is used only in the arcade physics. In P2 physics there is no way to distinguish which of the world’s boundaries the sprite collided with.

Arguments

Note - this is applicable only for arcade physics.

Name

Type

Description

directions

Object with 4 attributes

The boundary which the sprite collided with.

Values

The argument directions has four Boolean attributes, representing each of the world’s boundaries. When the sprite collides with a boundary, the corresponding attribute’s value is changed to yes/true. The attributes are:

  • directions.left

  • directions.right

  • directions.up

  • directions.down

Syntax

Arcade physics:

@onCollideWithWorldBounds = (directions) =>

P2 physics:

@onCollideWithWorldBounds = () =>

Example

In this example, the game uses arcade physics. When the sprite collides with the boundary at the bottom, the sprite is destroyed. If it collides with any other boundary, nothing will happen.

@onCollideWithWorldBounds = (directions) =>
if directions.down
@destroy()

In this example, the game uses P2 physics. When the sprite collides with any boundary, the sprite is destroyed.

@onCollideWithWorldBounds = () =>
@destroy()


onCollideWithTilemap()

Applicable only in P2 physics.

The function is called when a sprite collides with a tile. The function has no argument. This means that when a sprite collides with any of the tiles in the game, the same set of instructions will run.

The function should be defined in a sprite’s code.

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

Syntax

@onCollideWithTilemap = () =>

Example

In this example, when the sprite collides with any tile in the tilemap, the sprite is destroyed.

@onCollideWithTilemap = () =>
@destroy()


onClick()

The function is called when a sprite is clicked on. A click of the mouse on other areas or sprites will not be handled by the onClick function, written in this sprite’s code.

This function should be defined in a sprite’s code.

This function is triggered by an event (a mouse clicked event). It does not need to be called explicitly.

Syntax

@onClick = () =>

Example

In this example, when the sprite is clicked on, the sprite is placed at the top left corner.

@onClick = () =>
@setX 0
@setY 0

onAnimationEnd key, handler

The function is called when an animation ends. The function is called only if the animation does not run in a loop (runs only once). This function is defined per a specific animation.

The function is defined per a specific animation.

This function should be defined in a sprite’s code.

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

Arguments

Name

Type

Description

key

string

The name of the animation.

handler

function

The function to call when the animation ends.

Empty () means calling this function.

Syntax

@onAnimationEnd "key", () =>

Example

In this example, when the animation named "fly" ends, the sprite is hidden.

@onAnimationEnd "fly", () =>
@hide()


onAnimationLoop key, handler

The function is called each time an animation that runs in a loop ends.

For example, if the sprite’s position is changed in this function, then each time the animation ends, the sprite’s position will change.

The function is defined per a specific animation.

This function should be defined in a sprite’s code.

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

Arguments

Name

Type

Description

key

string

The name of the animation.

handler

function

The function to call when the animation ends.

Empty () means calling this function.

Syntax

@onAnimationLoop "key", () =>

Example

In this example, each time the animation named "eat" ends, the sprite’s position is changed to the upper left corner. This assumes that the animation "eat" was defined to run in a loop.

@onAnimationLoop "eat", () =>
@setX 0
@setY 0


onUpdate()

Applicable only in P2 physics.

The function is called on each frame change. Define this function when you need something to happen each time a frame changes. For example, if you want to display the sprite’s velocity each time a frame changes.

This function should be defined in a sprite’s code.

This function is triggered by an event.

Syntax

@onUpdate = () =>

Example

In this example, on each frame change, the sprite’s velocity in the y axis is updated and displayed in a Text widget.

@onUpdate = () =>
text.text = @getVelocityY()


step numberOfSteps

Applicable only in arcade physics.

Makes the sprite move. The argument of this function defines the number of pixels the sprite will move.

Arguments

Name

Type

Description

numberOfSteps

number

The number of pixels to move.

Example

If the following code is written in the tiger’s sprite, then the tiger will move 100 pixels to the right.

@step 100


jump() / jump howHigh

Applicable only in arcade physics.

Makes the sprite jump. The jump function can be called with or without an argument. When it is called without an argument, using parentheses is mandatory. The sprite will jump to a certain height (based on the gravity of the game). To make the sprite jump higher or lower, call this function with an argument. The argument defines how many times higher (or lower) the sprite will jump (as opposed to the default jump).

Arguments

Name

Type

Description

howHigh

number

Optional

How much higher (or lower) the sprite will jump.

Example

Here are three examples of how to use this function:

@jump() # default height
@jump 2 # jumps twice as high
@jump 0.5 # jumps half as high

Tip

When the game has no gravity (gravity = 0), the sprites will not jump.


setX newX

Sets the sprite’s x position based on the argument of the function. The sprite is placed at the new position.

Arguments

Name

Type

Description

newX

number

The sprite’s new x position.

Example

If the following code is written in the monkey’s sprite, then the monkey is placed on the left boundary of the game (depending on its y position).

@setX 0


setY newY

Sets the sprite’s y position based on the argument of the function. The sprite is placed at the new position.

Arguments

Name

Type

Description

newY

number

The sprite’s new y position.

Example

If the following code is written in the monkey’s sprite, the monkey will be placed at the top boundary of the game (depending on its x position).

@setY 0


getX()

Returns the sprite’s x position.

Returns

Number - the sprite's x position.

Example

If the following code is written in the monkey’s sprite, the monkey will be placed at the same x position as the tiger’s.

@setX tiger.getX()

getY()

Returns the sprite’s y position.

Returns

Number - the sprite's x position.

Example

If the following code is written in the monkey’s sprite, the monkey will be placed at the same y position as the tiger’s.

@setY tiger.getY()


setRotation degrees

Applicable only in arcade physics.

Rotates the sprite based on the argument.

Arguments

Name

Type

Description

degrees

number

The direction in degrees of where the sprite should rotate to.

For example, the following values set the sprite’s rotation to:

  • 0 - right

  • 90 - down

  • 180 - left

  • 270 - up

Example

If the following code is written in the monkey’s sprite then the monkey is rotated to face left. (its current rotation has no effect on the result)

@setRotation 180

Tip

The argument degrees is the absolute value where the sprite should be rotated to and is not affected by the current sprite’s rotation.


getRotation()

Returns the sprite’s rotation.

Returns

Number - the rotation of the sprite in degrees.

Example

If the code below is written in the frog’s sprite, then the frog will rotate 90 degrees away from where it was previously facing.

Specifically, if the frog is facing left or is rotated to 180 degrees, the following code will cause the frog to rotate 270 degrees so that it faces up. Current rotation (180 degrees + 90 degrees = 270 degrees). After the setRotation instruction, the frog will face up.

@setRotation @getRotation() + 90


setSpeed speed

Applicable only in arcade physics.

Sets the speed of the sprite. This function changes the speed of the sprite in multiples of its default speed.

Arguments

Name

Type

Description

speed

number

How many times faster (or slower) the sprite will move compared to the default speed.

  • 1 - default speed

Example

Here are three examples of how to use this function.

@setSpeed 1 # sets the speed to the default speed
@setSpeed 2 # sets the speed to twice as fast as its default speed
@setSpeed 0.5 # sets the speed to half as fast as its default speed


thrust force

Applicable only in P2 physics.

Applies thrust force to the sprite which pushes the sprite. For example, the thrust can push the sprite forward.

Arguments

Name

Type

Description

force

number

How much force to apply to the sprite.

Example

In the following example, if the gravity of the game is set to 100, the sprite will be pushed forward. If the gravity of the game is set to 200, the sprite will not be pushed forward.

@thrust 130

Tip

The force applied should be higher than the gravity of the game, otherwise the force will not be enough to overcome the gravity and the sprite will not be moved.


rotateLeft speed

Applicable only in P2 physics.

Rotates the sprite to the left. Angular damping is applied on the sprite: Every frame, half of the sprite's velocity is lost. This prevents the sprite from rotating forever.

Arguments

Name

Type

Description

speed

number

The speed in which to rotate the sprite to the left.

Example

Rotates the sprite to the left.

@rotateLeft 5

rotateRight speed

Applicable only in P2 physics.

Rotates the sprite to the right. Angular damping is applied on the sprite. Every frame, half of the sprite's velocity is lost. This prevents the sprite from rotating forever.

Arguments

Name

Type

Description

speed

number

The speed in which to rotate the sprite to the right.

Example

Rotates the sprite to the right.

@rotateRight 5


getVelocityX()

Applicable only in P2 physics.

Returns the sprite’s velocity in the x axis.

Returns

Number - the velocity in the x axis of the sprite.

Example

Displays the sprite’s x velocity in the text widget named textX.

textX.text = @getVelocityX()

Tip

When the sprite is not rotated to the right or to the left, its x velocity will be zero.


getVelocityY()

Applicable only in P2 physics.

Returns the sprite’s velocity in the y axis.

Returns

Number - the velocity in the y axis of the sprite.

Example

Displays the sprite’s y velocity in the text widget named textY.

textY.text = @getVelocityY()


show()

Shows the sprite or the widget.

Example

If this is written in the monkey’s sprite, then the monkey is shown. 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 monkey’s sprite, then the monkey is hidden. If this is written in the Timer widget, then the timer is hidden.

@hide()

Tip

When hiding a sprite, it still exists in the same position, but it is not shown. This means, for example, that another sprite can still collide with the hidden sprite. To make the sprite disappear but with the option to bring back, use the enable/disable functions.


destroy()

Deletes the sprite.

Example

If this is written in the monkey’s sprite, then the monkey is destroyed (deleted)

@destroy()

Tip

Pay attention that events like onKey and onCollide will not be triggered once the sprite is destroyed.


disable()

Disables the sprite by removing it from the game. Unlike a hidden sprite (using the hide() function), other sprites will not be able to collide with a disabled sprite. Unlike a destroyed sprite (using the destroy() function), a disabled sprite can be brought back to the game by using the enable() function.

Example

If this is written in the monkey’s sprite, then the monkey is disabled (hidden without other sprites colliding with the monkey).

@disable()


enable()

Brings back a disabled sprite.

Example

If this is written in the monkey’s sprite and the monkey was disabled, then the monkey is brought back to the game.

@enable()


setScale scale

Sets the scale of the sprite. The function changes the scale of the sprite based on its default scale.

Arguments

Name

Type

Description

scale

number

How many times bigger or smaller than the default size, the sprite will be.

  • 1 - default scale

Example

Here are three examples of how to use this function.

@setScale 1 # sets the scale to the default scale
@setScale 2 # sets the scale to twice as big as the default
@setScale 0.5 # sets the scale to half as big as the default


addAnimation key, framesArray, frameRate, loopAnimation

Adds (defines) an animation. The animation is defined per sprite, two different sprites can have an animation with the same name.

The first argument: key, is the animation’s name. It is used throughout the game to refer to the animation, for example, to start it and handle the event of animation end.

The frames of the sprite sheet are referenced using their indexes.

Arguments

Name

Type

Description

key

string

The animation’s name.

  • a unique name per each sprite

framesArray

array

References (indexes) to the sprite sheet frames included in the animation.

The order of the references (indexes) in the array, sets the order of the frames in the animation.

frameRate

number

Optional

The frame rate defines the number of frames displayed in one second.

The default is 3.

For example:

For framesArray that includes 4 frames:

  • if frameRate is 4

    • the animation will run for 1 second

  • if frameRate is 2

    • the animation will run for 2 seconds

loopAnimation

Boolean

Optional

Defines whether the animation will run once or in a loop.

  • no/false - the animation runs only once (default)

  • yes/true - the animation runs in a loop

Example

An animation named "eat" is added to the sprite, the animation will run in a loop and each run will take one second.

@addAnimation "eat", [3, 1, 0, 2], 4, yes

An animation named "undo" is added to the sprite, the animation will run once and it will take two seconds.

@addAnimation "undo", [3, 2, 1, 0], 2

Tip

A sprite can have more than one animation, for example, using different frames of its sprite sheet or defining different paces in which the animation will run.

For each sprite, only one animation can run at a time.


startAnimation key

Starts running the animation that its name is: key.

Arguments

Name

Type

Description

key

string

The animation’s name.

Example

Start running the animation named "eat"

@startAnimation "eat"


stopAnimation reset

Stops the animation that is running. When the animation ends, the last frame of the animation is shown. For example, if the sprite is an apple with four frames of an apple being eaten, with the last frame being an eaten apple, then when the animation ends, the sprite will be an eaten apple. The animation can be reset to its starting state (i.e. a whole apple) by passing yes/true to the argument reset.

Arguments

Name

Type

Description

reset

Boolean

Defines whether the sprite is reset to its first frame or not.

  • Yes - reset the sprite to its first frame

  • No - do not reset the sprite to its first frame

Example

Stops an animation with resetting the sprite to its first frame.

@stopAnimation yes

Stops an animation without resetting the sprite to its first frame.

@stopAnimation no

Tip

An animation can be stopped before it ends by calling the function stopAnimation. Depending on the argument reset, the sprite will either be reset to its first frame or not.


Relevant Articles:

Game Builder Guide

Game Builder - Widgets Tab

Game Builder - Additional Features

Game Builder (Text Based) - Coding Concepts

Did this answer your question?