Display

display.emoji()

Overview

Displays an emoji on the screen which can be created with a string (e.g. "🤩"),
emoji tag (e.g. “starstruck”) or the emoji number (e.g. 17).

Syntax

1
2
display.emoji(path: (String | Number) [, position: Point])
display.emoji(path: (String | Number) [, x: Number, y: Number])

Parameters

path String Required

Can be either string of emoji (“🤩”), emoji tag (“starstruck”) or the emoji number (17)

position Point Optional

A Point object of a position to place the emoji

x Number Optional

The x position in the coordinate system to place the emoji. Must be used with y argument

y Number Optional

The y position in the coordinate system to place the emoji. Must be used with x argument

Usage

1
2
3
4
5
6
7
8
9
// Starstruck
display.emoji("🤩")
display.emoji("starstruck")
display.emoji(17)

// With position
display.emoji("🤩", 100, 100)
display.emoji("🤩", { x: 100, y: 100 })
display.emoji("🤩", random.pos())

Return value

An Element object of the type emoji

The Emoji object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "type": "emoji",
  "tag": "starstruck",
  "emoji": {
    "id": 16,
    "no": "17",
    "code": "U+1F929",
    "icon": "🤩",
    "tag": "starstruck"
  }
}

Attributes

type String

The type of an emoji element is emoji

tag String

The tag of an emoji element is set to Emoji type tag.

emoji Emoji

The emoji attribute is an Emoji object that is used

Inherits all Element attributes

Functions

Inherits all Element functions

display.rect()

Overview

Displays a rectangle on the screen. Can be created by providing a Rect OR Point AND Size OR x, y, width and height.

Syntax

1
2
3
display.rect(frame: Rect)
display.rect(position: Point, size: Size)
display.rect(x: Number, y: Number, width: Number, height: Number)

Parameters

frame Rect Required

The frame rectangle of the type Rect of this rectangle

OR

position Point Required

A Point object of a position to place the rectangle

size Size Required

A Size object of the size of the rectangle

OR

x Number Required

The x position in the coordinate system to place the rect

y Number Required

The y position in the coordinate system to place the rect

width Number Required

The width of the rectangle

height Number Required

The height of the rectangle

Usage

1
2
3
4
5
6
7
8
9
10
// With x, y, width, height
display.rect(100, 100, 100, 100)

// With postition and size
display.rect({ x: 100, y: 100 }, { width: 100, height: 100 })
display.rect(random.pos(), { width: 100, height: 100 })
display.rect(random.pos(), random.size(10, 100))

// With rectangle
display.rect({ x: 100, y: 100, width: 100, height: 100 })

Return value

An Element object of the type rect

The Rect object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "cornerRadius": 0,
  "type": "rect",
  "tag": "rect"
}

Attributes

type String

The type of an rectangle element is rect

tag String

The tag of an rectangle element is set to rect type tag.

cornerRadius Number

The corner radius of the corners of the rect

Inherits all Element attributes

Functions

Inherits all Element functions

display.circle()

Overview

Displays a circle on the screen. Can be created by providing a position and radius OR x, y coordinates and radius.

Syntax

1
2
display.circle(position: Point, radius: Number)
display.circle(x: Number, y: Number, radius: Number)

Parameters

position Point Required

A Point object of a position to place the circle

radius Number Required

A Number of the radius of the circle

OR

x Number Required

The x position in the coordinate system to place the circle

y Number Required

The y position in the coordinate system to place the circle

radius Number Required

A Number of the radius of the circle

Usage

1
2
3
4
5
6
7
// With postition and radius
display.circle({ x: 100, y: 100 }, 50)
display.circle(random.pos(), 50)
display.circle(random.pos(), random.num(10, 50))

// With x, y and radius
display.circle(100, 100, 50)

Return value

An Element object of the type circle

The Circle object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "radius": 50,
  "type": "circle",
  "tag": "circle"
}

Attributes

type String

The type of a circle element is circle

tag String

The tag of a circle element is set to circle type tag.

radius Number

The radius of the circle

Inherits all Element attributes

Functions

Inherits all Element functions

display.polygon()

Overview

Displays a polygon on the screen.
Can be created by providing a position, radius and vertices OR x, y coordinates, radius and vertices.

Syntax

1
2
3
display.polygon(position: Point, radius: Number, vertices: Number)

display.polygon(x: Number, y: Number, radius: Number, vertices: Number)

Parameters

position Point Required

A Point object of a position to place the polygon

radius Number Required

A Number of the radius of the polygon

vertices Number Required

A Number of vertices for this polygon. Default value is 3, e.g. triangle.

OR

x Number Required

The x position in the coordinate system to place the polygon

y Number Required

The y position in the coordinate system to place the polygon

radius Number Required

A Number of the radius of the polygon

vertices Number Required

A Number of vertices for this polygon. Default value is 3, e.g. triangle.

Usage

1
2
3
4
5
6
7
// With postition, radius and vertices
display.polygon({ x: 100, y: 100 }, 50, 3)
display.polygon(random.pos(), 50, 5)
display.polygon(random.pos(), random.num(10, 50), random.num(3, 9))

// With x, y, radius and vertices
display.polygon(100, 100, 50, 5)

Return value

An Element object of the type polygon

The Polygon object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "radius": 50,
  "vertices": 3,
  "type": "polygon",
  "tag": "polygon"
}

Attributes

type String

The type of a polygon element is polygon

tag String

The tag of a polygon element is set to polygon type tag.

radius Number

The radius of the polygon

vertices Number

The number of vertices the polygon should have

Inherits all Element attributes

Functions

Inherits all Element functions

display.line()

Overview

Displays a line on the screen from one coordinate point to another

Syntax

1
2
display.line(fromPosition: Point, toPosition: Point)
display.line(x1: Number, y1: Number, x2: Number, y2: Number)

Parameters

fromPosition Point Required

A Point object from which the line should start

toPosition Point Required

A Point object from which the line should end

OR

x1 Number Required

The x start position in the coordinate system

y1 Number Required

The y start position in the coordinate system

x2 Number Required

The x end position in the coordinate system

y2 Number Required

The y end position in the coordinate system

Usage

1
2
3
4
5
6
7
8
9
// With points
display.line({ x: 100, y: 100 }, { x: 200, y: 200 })
display.line({ x: 480, y: 320 }, random.pos())

// With coordinates
display.line(100, 100, 200, 200)

point = { x: 200, y: 200 }
display.line(100, 100, point.x, point.y)

Return value

An Element object of the type line

The Line object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 200,
    "height": 1
  },
  "scale": 1.0,
  "angle": 45,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "type": "line",
  "tag": "line"
}

Attributes

type String

The type of an line element is line

tag String

The tag of an line element is set to line type tag.

style String

The style of the line. Available styles:

• "solid" - solid line, the default
• "dots" - line with cicles
• "blocks" - line with rectangles
• "polygons" - line with polygons
• "clouds" - line with cloud shapes
• "stars" - line with star shapes
• "hearts" - line with heart shapes

lineCap String

If the line style is solid this property sets
the current line cap. Default is "round". Available line caps:

• "butt" - Stops at from and to positions
• "round" - Rounded ends
• "square" - Square ends

width Number

The width of the line

elements Number

If the current style is one of "dots" ,"blocks" ,"polygons" ,"clouds" ,"stars" or "hearts".
This property sets the number of elements in the line. Default is 6.

vertices Number

If the current style is "polygons".
This property sets the number of vertices the polygons should have. Default is 5.

position2 Point

The end position point for the line.
The line goes from position Point to position2 Point

angle Number

The current angle of the line from position Point to position2 Point

Inherits all Element attributes

Functions

from(position)

position Point required

Set the start position of the line

Setting the start position of the line

1
line.from({ x: 100, y: 100 })

to(position)

position Point required

Set the end position of the line

Setting the end position of the line

1
line.to({ x: 100, y: 100 })

Inherits all Element functions

display.ellipse()

Overview

Displays an ellipse on the screen with given x and y radius

Syntax

1
2
display.ellipse(position: Point, radiusX: Number, radiusY: Number)
display.ellipse(x: Number, y: Number, radiusX: Number, radiusY: Number)

Parameters

position Point Required

A Point object from which the line should start

radiusX Number Required

The x radius to use for the ellipse

radiusY Number Required

The y radius to use for the ellipse

OR

x Number Required

The x position in the coordinate system

y Number Required

The y position in the coordinate system

radiusX Number Required

The x radius to use for the ellipse

radiusY Number Required

The y radius to use for the ellipse

Usage

1
2
3
4
5
6
7
// With points
display.ellipse({ x: 100, y: 100}, 20, 40)
display.ellipse(random.pos(), 20, 40)
display.ellipse(random.pos(), random.num(10, 25), random.num(10, 25))

// With coordinates
display.ellipse(100, 100, 20, 40)

Return value

An Element object of the type ellipse

The Ellipse object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 200,
    "height": 1
  },
  "scale": 1.0,
  "angle": 45,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "type": "ellipse",
  "tag": "ellipse",
  "radiusX": 20,
  "radiusY": 40
}

Attributes

type String

The type of an ellipse element is ellipse

tag String

The tag of an ellipse element is set to ellipse type tag.

radiusX Number

The radius to use for the x axis of this ellipse element

radiusY Number

The radius to use for the y axis of this ellipse element

Inherits all Element attributes

Functions

Inherits all Element functions

display.star()

Overview

Displays a star on the screen. Can be created by providing a position and radius OR x, y coordinates and radius.

Syntax

1
2
display.star(position: Point, radius: Number)
display.star(x: Number, y: Number, radius: Number)

Parameters

position Point Required

A Point object of a position to place the star

radius Number Required

A Number of the radius of the star

OR

x Number Required

The x position in the coordinate system to place the star

y Number Required

The y position in the coordinate system to place the star

radius Number Required

A Number of the radius of the star

Usage

1
2
3
4
5
6
7
// With postition and radius
display.star({ x: 100, y: 100 }, 50)
display.star(random.pos(), 50)
display.star(random.pos(), random.num(10, 50))

// With x, y and radius
display.star(100, 100, 50)

Return value

An Element object of the type star

The Star object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "radius": 50,
  "type": "star",
  "tag": "star"
}

Attributes

type String

The type of a star element is star

tag String

The tag of a star element is set to star type tag.

radius Number

The radius of the star

Inherits all Element attributes

Functions

Inherits all Element functions

display.heart()

Overview

Displays a heart on the screen. Can be created by providing a position and radius OR x, y coordinates and radius.

Syntax

1
2
display.heart(position: Point, radius: Number)
display.heart(x: Number, y: Number, radius: Number)

Parameters

position Point Required

A Point object of a position to place the heart

radius Number Required

A Number of the radius of the heart

OR

x Number Required

The x position in the coordinate system to place the heart

y Number Required

The y position in the coordinate system to place the heart

radius Number Required

A Number of the radius of the heart

Usage

1
2
3
4
5
6
7
// With postition and radius
display.heart({ x: 100, y: 100 }, 50)
display.heart(random.pos(), 50)
display.heart(random.pos(), random.num(10, 50))

// With x, y and radius
display.heart(100, 100, 50)

Return value

An Element object of the type heart

The heart object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "radius": 50,
  "type": "heart",
  "tag": "heart"
}

Attributes

type String

The type of a heart element is heart

tag String

The tag of a heart element is set to heart type tag.

radius Number

The radius of the heart

Inherits all Element attributes

Functions

Inherits all Element functions

display.cloud()

Overview

Displays a cloud on the screen. Can be created by providing a position and radius OR x, y coordinates and radius.

Syntax

1
2
display.cloud(position: Point, radius: Number)
display.cloud(x: Number, y: Number, radius: Number)

Parameters

position Point Required

A Point object of a position to place the cloud

radius Number Required

A Number of the radius of the cloud

OR

x Number Required

The x position in the coordinate system to place the cloud

y Number Required

The y position in the coordinate system to place the cloud

radius Number Required

A Number of the radius of the cloud

Usage

1
2
3
4
5
6
7
// With postition and radius
display.cloud({ x: 100, y: 100 }, 50)
display.cloud(random.pos(), 50)
display.cloud(random.pos(), random.num(10, 50))

// With x, y and radius
display.cloud(100, 100, 50)

Return value

An Element object of the type cloud

The Cloud object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "position": {
    "x": 100,
    "y": 100
  },
  "size": {
    "width": 75,
    "height": 75
  },
  "scale": 1.0,
  "angle": 0,
  "angleOffset": 0,
  "active": true,
  "color": color.hsb(0, 0, 100),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "radius": 50,
  "type": "cloud",
  "tag": "cloud"
}

Attributes

type String

The type of a cloud element is cloud

tag String

The tag of a cloud element is set to cloud type tag.

radius Number

The radius of the cloud

Inherits all Element attributes

Functions

Inherits all Element functions

display.each()

Overview

Loops over all display elements with the given tag

Syntax

1
display.each(tag: String, callback: function(element: Element))

Parameters

tag String Required

The tag string value to loop through

callback function Required

Required parameter for this function

callback parameters

• element Element

  An element tagged with given tag

Usage

1
2
3
4
// Move all elements tagged with `cat`
display.each("cat", (element) => {
  element.move(2)
})

UI

ui.label()

Overview

Displays a label on the screen.

Syntax

1
2
3
ui.label(text: String)
ui.label(text: String, position: Point)
ui.label(text: String, x: Number, y: Number)

Parameters

text String Required

The text to display

position Point Optional

A Point object of a position to place the label

OR

text String Required

The text to display

x Number Optional

The x position in the coordinate system to place the label

y Number Optional

The y position in the coordinate system to place the label

Usage

1
2
3
4
5
6
7
8
9
10
// Label without position
ui.label("Score")

// Label with value at position
positionLbl = ui.label("Score", { x: 100, y: 100 })
positionLbl.value = 100

// Label with value at x, y coordinates
positionLbl2 = ui.label("Score", 860, 100)
positionLbl2.value = 100

Return value

An UIElement object of the type label

Attributes

text String

The text to display in the label

value Number|String

The value to display in the label, with formatting: {text}: {value}

ui.button()

Overview

Displays a button on the screen.

Syntax

1
2
3
ui.button(text: String)
ui.button(text: String, position: Point)
ui.button(text: String, x: Number, y: Number)

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Button without position
startBtn = ui.button("Start!")
startBtn.action(() => {
  // Action called when clicked
})

// Button with position
postionBtn = ui.button("Start!", { x: 100, y: 100 })
postionBtn.action(() => {
  // Action called when clicked
})

// Button with x, y coordinates
postionBtn = ui.button("Start!", 100, 100)
postionBtn.action(() => {
  // Action called when clicked
})

Parameters

text String Required

The text to display

position Point Optional

A Point object of a position to place the label

OR

text String Required

The text to display

x Number Optional

The x position in the coordinate system to place the label

y Number Optional

The y position in the coordinate system to place the label

Return value

An UIElement object of the type button

Attributes

Functions

button.action(callback)

Callback is called when this element is clicked by any input type.

callback function

Required parameter for this function

Action with callback

1
2
3
btn.action(() => {
  // element is clicked / tapped
})

button.click(callback)

Alias function to element.action(callback)

button.clicked(callback)

Alias function to element.action(callback)

ui.progress()

Overview

Displays a progress-bar on the screen.

Syntax

1
ui.progress(x: Number, y: Number, width: Number, height: Number)

Usage

1
2
3
// Progress-bar with 50% progress
progressBar = ui.progress(150, 50, 200, 25)
progressBar.value = 0.5

Parameters

x Number Required

The x position in the coordinate system to place the progress bar

y Number Required

The y position in the coordinate system to place the progress bar

width Number Required

The width of the progress bar

height Number Required

The height of the progress bar

Return value

An UIElement object of the type progress

Attributes

progressColor Color

The foreground color of

trackColor Color

The track color which is behind the progress

value Number

The percentage progress to show. Range from 0 to 1 where 0.5 is 50%.
Can be used to get and set the current value of the progress.

Functions

Physics

physics.add()

Overview

Add an element to the physics engine. Can be used with an element OR an array of elements.

Syntax

1
2
physics.add(element: Element [, options: Object])
physics.add(elements: [Element] [, options: Object])

Parameters

element Element Required

An Element object that should become a physics object

options Object Optional

An object of optional arguments.

• type String - dynamic, static or kinematic. Default is dynamic
• density Number - multiplied with the area of the shape to calculate mass. Lighter is lower than 1.0, water is 1.0, heavier is bigger than 1.0. Default is 1.0
• friction Number - 0.0 is no friction, 1.0 is alot of friction. Default is 0.2
• restitution Number - how much velocity is returned after collision. Default is 0.2
• bounce Number - alias to restitution
• sensor Boolean - Default is false
• static Boolean - Default is false, sets the type to static
• kinematic Boolean - Default is false
• radius Number - Default is 0
• angularDamping Number - Sets the angular damping of the physics body. Default is 0
• linearDamping Number - Sets the linear damping of the physics body. Default is 0

OR

elements [Element] Required

An Array of Element object that should becom physics objects

options Object Optional

An object of optional arguments.

• type String - dynamic, static or kinematic. Default is dynamic
• density Number - lighter is lower than 1.0, water is 1.0, heavier is bigger than 1.0. Default is 1.0
• friction Number - 0.0 is no friction, 1.0 is alot of friction. Default is 0.2
• restitution Number - how much velocity is returned after collision. Default is 0.2
• bounce Number - alias to restitution
• sensor Boolean - Default is false
• static Boolean - Default is false, sets the type to static
• kinematic Boolean - Default is false
• radius Number - Default is 0
• angularDamping Number - Sets the angular damping of the physics body. Default is 0
• linearDamping Number - Sets the linear damping of the physics body. Default is 0

Usage

1
2
3
4
5
6
7
8
9
10
11
12
// Add physics to circle
physics.add(
  display.circle(random.pos(), 50)
)

// Add physics to multiple elements
physics.add([
  display.emoji("🤩"),
  display.emoji("🦄"),
  display.emoji("🔥")
])

Return value

An Element object of the type of the element provided.

OR

An [Element] of the elements provided as argument.

physics.debug()

Enables debug drawing of the physics bodies

1
physics.debug()

physics.setGravity()

1
physics.setGravity(x: Number, y: Number)

Sets the gravity of the physics engine. The default values are (0, 9.8) to simulate earth gravity.

Set gravity to “earth” values

1
physics.setGravity(0, 9.8)

physics.addBody()

Alias function to physics.add()

physics.destroyBody()

1
physics.destroyBody(element: Element)

element Element Required

The element which should be destroyed

Destroy an elements physics properties which was previously added the physics engine

1
physics.destroyBody(element)

physics.setPosition()

1
physics.setPosition(element: Element, position: Point)

element Element Required

The element which should get new position

position Point Required

The position where the element should be placed

Setting position of a physics element

1
physics.setPosition(element, { x: 100, y: 100 })

physics.applyTorque()

Apply torque to an element in the physics engine

1
physics.applyTorque(element: Element, force: Number)

element Element Required

The element which should receive torque force

force Number Required

The amount of force to apply for the torque

1
physics.applyTorque(element, -10)

physics.setAngle()

Set a new angle to an element in the physics engine

1
physics.setAngle(element: Element, radians: Number)

element Element Required

The element which should get a new angle

radians Number Required

A number value of radians to apply to the element

1
physics.setAngle(element, 10)

physics.applyImpulse(element, xForce, yForce)

Applies physics impulse to an element

1
physics.applyImpulse(element: Element, xForce: Number, yForce: Number)

element Element Required

The element which should be applied

xForce Number Required

The xForce to apply to the element

yForce Number Required

The yForce to apply to the element

Applying physics impulse to an element

1
physics.applyImpulse(element, 0, -50)

physics.applyForce(element, xForce, yForce)

Applies physics force to a given element.

1
physics.applyForce(element: Element, xForce: Number, yForce: Number)

element Element Required

The element which should be be affected by the force

xForce Number Required

The amount of force to apply in the x direction

yForce Number Required

The amount of force to apply in the y direction

Applying physics force to an element

1
physics.applyForce(element, 0, -50)

physics.stop()

Stops all linear and angular velocity for the element

1
physics.stop(element: Element)

element Element Required

The element which should stop all linear and agular velocity

1
physics.stop(element)

World

Overview

Defines the size of the world which the Camera can navigate inside

world.set()

Sets the current size of the world

1
2
3
world.set()
world.set(size: Size)
world.set(width: Number, height: Number)

With no arguments the default size of 960x640 is used.

OR

size Size Required

The size of the world

OR

width Number Required

The width size the world should have. Default is 960

height Number Required

The height size the world should have. Default is 640

Setting the size of the world

1
world.set(1920, 640)

world.frame()

Sets the world size and creates a physics frame around it

1
2
3
world.frame()
world.frame(size: Size)
world.frame(width: Number, height: Number)

With no arguments the default size of 960x640 is used.

OR

size Size Required

The size of the world

OR

width Number Required

The width size the world should have. Default is 960

height Number Required

The height size the world should have. Default is 640

world.ground()

Creates physics ground in the current world width. The default width of 640
points is used.

1
world.ground()

Camera

Overview

The camera system which moves inside the world size

camera.follow()

Syntax

1
camera.follow(element: Element)

Parameters

element Element Required

An Element object that should be followed inside the world

Usage

1
2
3
4
5
6
7
8
9
10
world.set(1280, 1280)

player = display.emoji("🤩")

camera.follow(player)

player.update(() => {
  player.pointTo(input)
  player.move(5)
})

Return value

An Element object of the type of the element provided.

Color

Overview

Create a color for an Element

color.hsb()

Create a color with hue, saturation and brightness

1
color.hsb(hue: Number, saturation: Number, brightness: Number [, alpha: Number = 100])

hue Number Required

A number between 0 and 360

saturation Number Required

A number between 0 and 100

brightness Number Required

A number between 0 and 100

alpha Number Optional

A number between 0 and 100, default value is 100

1
2
3
4
5
// Set the background to sky blue
display.color = color.hsb(197, 42, 92)

// A HSB color with alpha 50%
color.hsb(197, 42, 92, 50)

color.rgb()

Create a color with red, green and blue

1
color.rgb(red: Number, green: Number, blue: Number [, alpha: Number = 100])

red Number Required

A number between 0 and 255

green Number Required

A number between 0 and 255

blue Number Required

A number between 0 and 255

alpha Number Optional

A number between 0 and 100, default value is 100

1
2
3
4
5
// Create a red color
color.rgb(255, 0, 0)

// Red color with alpha 50%
color.rgb(255, 0, 0, 50)

Random

Overview

Create a random number, position or size

random.number()

Create a random number with a minimum and maximun value

1
random.number(minimum: Number = 10, maximum: Number = 100)

minimum Number Required

The minimum value that should be generated. Default is 10

maximum Number Required

The maximum value that should be generated. Default is 100

Generate a random number between 1 and 6

1
random.number(1, 6)

Return value

A random Number between minimum and maximum values

random.num()

Alias function for random.number()

random.position()

Generate a random position Point within the bounds of the world size

1
2
3
4
5
6
7
8
world.set(1920, 1280)

// Generate a point with
//  x value between 0 and 1920
//  y value between 0 and 1280
pos = random.position()
print(pos)
// => { "x": 306, "y": 226 }

Return value

A Point withing the world size

random.pos()

Alias function for random.position()

random.size()

Generate a random Size within given minimum and maximum values

1
random.size(minimum: Number = 10, maximum: Number = 100)

minimum Number Required

The minimum value that should be generated. Default is 10

maximum Number Required

The maximum value that should be generated. Default is 100

Usage

Generate a rectangle with random position and size

1
display.rect(random.pos(), random.size(10, 50))

Return value

A Size between minimum and maximum values

Input

Overview

Handling of user input through keyboard, mouse and touches

input.key()

Handle an input key event.
Callback is called when an input event is triggered.

1
input.key(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • keyCode Number

    The key code of the current key pressed

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

1
2
3
4
5
6
7
8
9
10
11
input.key(function(event) {
  if (event.began) {
    // The first event on key down
  }
  if (event.updated) {
    // The update event, repeats while holding
  }
  if (event.ended) {
    // The last event on key up
  }
})

Using input.key() to handle arrow keys and space

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
input.key(function(event) {
  if (event.keyCode == 38) {
    // handle up arrow button
  }
  if (event.keyCode == 39) {
    // handle right arrow button
  }
  if (event.keyCode == 40) {
    // handle down arrow button
  }
  if (event.keyCode == 37) {
    // handle left arrow button
  }
  if (event.keyCode == 32) {
    // handle space button
  }
})

input.up()

Handle an input event from the up arrow key with keyCode 38.
Callback is called when an input event is triggered.

1
input.up(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

1
2
3
input.up((event) => {
  // handle up arrow key
})

input.right()

Handle an input event from the right arrow key with keyCode 39.
Callback is called when an input event is triggered.

1
input.right(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

1
2
3
4
5
6
7
8
9
10
11
12
13
input.right((event) => {
  // handle right arrow key
  
  if (event.phase == "began") {
    // handle right began / key down
  }
  if (event.phase == "updated") {
    // handle right update / key is down
  }
  if (event.phase == "ended") {
    // handle right ended / key right
  }
})

input.down()

Handle an input event from the down arrow key with keyCode 40.
Callback is called when an input event is triggered.

1
input.down(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

1
2
3
input.down((event) => {
  // handle down arrow key
})

input.left()

Handle an input event from the left arrow key with keyCode 37.
Callback is called when an input event is triggered.

1
input.left(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

1
2
3
input.left((event) => {
  // handle left arrow key
})

input.space()

Handle an input event from the space key with keyCode 32.
Callback is called when an input event is triggered.

1
input.space(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

1
2
3
input.space((event) => {
  // handle space arrow key
})

input.w()

Handle an input event from the “w” key with keyCode 87.
Callback is called when an input event is triggered.

1
input.w(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

input.a()

Handle an input event from the “a” key with keyCode 65.
Callback is called when an input event is triggered.

1
input.a(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

input.s()

Handle an input event from the “s” key with keyCode 83.
Callback is called when an input event is triggered.

1
input.s(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

input.d()

Handle an input event from the “d” key with keyCode 68.
Callback is called when an input event is triggered.

1
input.d(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object

  An event object with data containing information about the current input event.

  • phase String

    A string value of the current event phase which is "began", "updated" or "ended"

  • began Boolean

    A boolean value indicating if the event began

  • updated Boolean

    A boolean value indicating if the event is between began and ended

  • ended Boolean

    A boolean value indicating if the event ended

input.point()

Handle input events from mouse / touch.
Callback is called when an input event is triggered.

1
input.point(callback: function)

callback function Required

Required parameter for this function

callback parameters

• event Object
  An event object with data containing information about the current input event.

  • phase String
    A string value of the current event phase which is "began", "updated" or "ended"
  • began Boolean
    A boolean value indicating if the event began
  • updated Boolean
    A boolean value indicating if the event is between began and ended
  • ended Boolean
    A boolean value indicating if the event ended
  • position Point
    A point object indicating where the event occurred in the display coordinate system

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
input.point((event) => {
  if (event.began) {
    // handle mouse / touch input began
  }
  if (event.updated) {
    // handle mouse / touch input update
  }
  if (event.ended) {
    // handle mouse / touch input ended
    element.applyImpulse(
      element.position.x - event.position.x,
      element.position.y - event.position.y
    )
  }
})

Timer

Overview

Create a timer for repeating or delayed events

timer.every(time, callback)

Create a timer which fires every time provided as an argument

Syntax

1
timer.every(time: Number, callback: function)

Arguments

time Number Required

The time in milliseconds the callback should be called

callback function Required

The function callback that should be triggered on every time interval

Create a timer that is triggered every 500 millisecond

1
2
3
timer.every(500, () => {
  // called every 500 millisecond
})

timeout(time, callback)

Create a timeout that should be triggered after time argument milliseconds

Syntax

1
timeout(time: Number, callback: function)

Arguments

time Number Required

The time in milliseconds the callback should be called

callback function Required

The function callback that should be triggered on after time delay

Create a timeout that should be triggerd after delay

1
2
3
timeout(500, () => {
  // called after 500 millisecond delay
})

Util

fill(color: Color)

Set the fill color to be used for the new elements created

Syntax

1
fill(color: Color)

Arguments

color Color Required

The color to use as fill color for new elements created

1
2
// Sets the background of new elements to sky blue color
fill(color.hsb(197, 42, 92))

forever(callback)

Repeats forever with 20 millisecond delay

Syntax

1
forever(callback: function)

Arguments

callback function Required

The function callback that should be triggered

1
2
3
forever(() => {
  // is repeated forever, with 20 milliseconds delay
})

repeat(times, callback)

Repeats the number of times given with 20 millisecond delay

Syntax

1
repeat(times: Number, callback: function)

Arguments

times Number Required

The times the callback should be repeated

callback function Required

The function callback that should be triggered

1
2
3
repeat(10, () => {
  // is repeated 10 times, with 20 milliseconds delay
})

stroke(color: Color, width: Number = 1)

Set the border color to be used for the new elements created.
Border width defaults to 1.

Syntax

1
stroke(color: Color, width: Number = 1)

Arguments

color Color Required

The color to use as border color for new elements created

width Number Optional

The width of the border for new elements created

1
2
// Sets the border of new elements to sky blue color with width of 2
stroke(color.hsb(197, 42, 92), 2)

times(times, callback)

Calls the callback the number of times given immediately with no delay

Syntax

1
times(times: Number, callback: function)

Arguments

times Number Required

The times the callback should be repeated

callback function Required

The function callback that should be triggered

1
2
3
times(10, () => {
  // is repeated 10 times
})

update(callback)

Repeats on every update loop

Syntax

1
update(callback: function)

Arguments

callback function Required

The function callback that should be triggered

1
2
3
update(() => {
  // is repeated on every update loop
})

Types

UIElement

UIElement differs from Element by staying inside the display when using the camera system.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// The ui element object
{
  "text": "This is the text",
  "position": {
    "x": 320,
    "y": 100
  },
  "inset": { 
    "top": 10,
    "left": 14,
    "bottom": 10,
    "right": 14
  },
  "fontSize": 30,
  "font": "Arial",
  "color": color.hsb(0, 0, 10),
  "backgroundColor": color.hsb(0, 0, 90),
  "borderColor": color.hsb(0, 0, 0),
  "borderWidth": 0,
  "cornerRadius": 0
}

Attributes

text String

The text to display for this ui element

position Point

The position in the display coordinate system.
Changing the position of the element will move it.

inset Object

The inset defines the padding to use inside the ui element.

top Number

The top padding to use for this ui element.

left Number

The left padding to use for this ui element.

bottom Number

The bottom padding to use for this ui element.

right Number

The right padding to use for this ui element.

fontSize Number

The font size of this ui element

font String

The font to use for the text in this ui element

color Color

The color of the text in this ui element

backgroundColor Color

The color of the background for this ui element

borderColor Color

The color of the border for this ui element

borderWidth Number

The width of the border for this ui element

cornerRadius Number

The corner radius to use for this ui element

Functions

Point

Represents a point in the coordinate system

x Number
The x position in the coordinate system

y Number
The y position in the coordinate system

Syntax

1
position = Point(x: Number, y: Number)

Usage

1
position = Point(100, 100)

1
2
3
4
5
// The point object
{
  "x": 100,
  "y": 100
}

Vec2

Represents a point in the coordinate system

x Number
The x position in the coordinate system

y Number
The y position in the coordinate system

Syntax

1
position = Vec2(x: Number, y: Number)

Usage

1
position = Vec2(100, 100)

1
2
3
4
5
// The Vec2 object
{
  "x": 100,
  "y": 100
}

Size

Represents a size in the coordinate system

width Number
The width in the coordinate system

height Number
The height in the coordinate system

Syntax

1
size = Size(width: Number, height: Number)

Usage

1
size = Size(100, 100)

1
2
3
4
5
// The size object
{
  "width": 75,
  "height": 75
}

Rect

Represents a rectangle in the coordinate system

x Number
The x position in the coordinate system

y Number
The y position in the coordinate system

width Number
The width of the rectangle

height Number
The height of the rectangle

Syntax

1
2
3
Rect(x: Number, y: Number, width: Number, height: Number)
Rect(origin: Point, size: Size)
Rect(rect: Object)

Usage

1
2
3
4
5
rectangle = Rect(100, 100, 75, 75)

rectangle = Rect(Point(100, 100), Size(75, 75))

rectangle = Rect({ x: 100, y: 100, width: 75, height: 75 })

1
2
3
4
5
6
7
// The rect object
{ 
  "x": 100,
  "y": 100,
  "width": 75,
  "height": 75
}

Base Types

1. String
2. Number
3. Bigint
4. Boolean
5. Undefined
6. Null
7. Symbol
8. Object

The object types

1. Object
2. Array
3. Date

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Numbers
width = 15
scale = 1.5

// Strings
color = "Blue"
name = "John Doe"

// Boolean
first = true
last = false

// Object
position = { x: 321, y: 345 }

// Array
basket = ["Apples", "Bananas", "Blueberries"]

// Date
date = new Date("2024-04-25")