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 |
Events | Called when a key is pressed on the keyboard. | Both | |
Events | Called when the screen is swiped. | Both | |
Events | Called when two sprites collide (bump) with each other. | Both | |
Events | Called when a sprite collides with one of the world bounds. | Both | |
Events | Called when the sprite collides with a tile in the tilemap. | P2 | |
Events | Called when the sprite is clicked on (using the mouse). | Both | |
Events | Called when an animation, that does not run in a loop, ends. | Both | |
Events | Called each time an animation that runs in a loop ends. | Both | |
Events | Called on each frame change. | P2 | |
Movements | Makes the sprite move. | Arcade | |
Movements | Makes the sprite jump. | Arcade | |
Movements | Sets the sprite’s x position. | Both | |
Movements | Sets the sprite’s y position. | Both | |
Movements | Returns the sprite’s x position. | Both | |
Movements | Returns the sprite’s y position. | Both | |
Movements | Rotates the sprite. | Arcade | |
Movements | Returns the sprite’s rotation. | Both | |
Movements | Sets the sprite’s speed. | Arcade | |
Movements | Applies a thrust force on the sprite. | P2 | |
Movements | Rotates the sprite to the left. | P2 | |
Movements | Rotates the sprite to the right. | P2 | |
Movements | Returns the sprite’s velocity in the x axis. | P2 | |
Movements | Returns the sprite’s velocity in the y axis. | P2 | |
Display | Shows the sprite. | Both | |
Display | Hides the sprite. | Both | |
Display | Destroys the sprite. | Both | |
Display | Disables the spite from the game. | Both | |
Display | Brings back a disables sprite. | Both | |
Display | Sets the sprite’s scale. | Both | |
Display | Adds (defines) an animation to a sprite. | Both | |
Display | Starts running the animation. | Both | |
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
@stepTo 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:
|
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.
|
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.
|
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.
|
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:
|
loopAnimation | Boolean | Optional Defines whether the animation will run once or 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.
|
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: