Display

display.emoji()

Library display.*
Return value Element
See also  

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

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

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

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

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

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

{
  "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

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

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

Inherits all Element functions

display.ellipse()

Library display.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

{
  "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()

Library display.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

{
  "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()

Library display.*
Return value  
See also  

Overview

Loops over all display elements with the given tag

Syntax

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

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

UI

ui.label()

Library ui.*
Return value UIElement
See also  

Overview

Displays a label on the screen.

Syntax

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

// 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()

Library ui.*
Return value UIElement
See also  

Overview

Displays a button on the screen.

Syntax

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

Usage

// 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

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()

Library ui.*
Return value UIElement
See also  

Overview

Displays a progress-bar on the screen.

Syntax

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

Usage

// 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()

Library physics.*
Return value Element
See also  

Overview

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

Syntax

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

// 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

physics.debug()

physics.setGravity()

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

physics.setGravity(0, 9.8)

physics.addBody()

Alias function to physics.add()

physics.destroyBody()

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

physics.destroyBody(element)

physics.setPosition()

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

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

physics.applyTorque()

Apply torque to an element in the physics engine

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
physics.applyTorque(element, -10)

physics.setAngle()

Set a new angle to an element in the physics engine

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
physics.setAngle(element, 10)

physics.applyImpulse(element, xForce, yForce)

Applies physics impulse to an element

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

physics.applyImpulse(element, 0, -50)

physics.applyForce(element, xForce, yForce)

Applies physics force to a given element.

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

physics.applyForce(element, 0, -50)

physics.stop()

Stops all linear and angular velocity for the element

physics.stop(element: Element)
element Element Required
The element which should stop all linear and agular velocity
physics.stop(element)

World

Library world.*
Return value  
See also  

Overview

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

world.set()

Sets the current size of the world

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

world.set(1920, 640)

world.frame()

Sets the world size and creates a physics frame around it

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.

world.ground()

Camera

Library camera.*
Return value  
See also  

Overview

The camera system which moves inside the world size

camera.follow()

Syntax

camera.follow(element: Element)

Parameters

element Element Required
An Element object that should be followed inside the world

Usage

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

Library color.*
Return value  
See also  

Overview

Create a color for an Element

color.hsb()

Create a color with hue, saturation and brightness

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
// 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

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
// Create a red color
color.rgb(255, 0, 0)

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

Random

Library random.*
Return value  
See also  

Overview

Create a random number, position or size

random.number()

Create a random number with a minimum and maximun value

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

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

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

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

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

Return value

A Size between minimum and maximum values

Input

Library input.*
Return value  
See also  

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.

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
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

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.

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
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.

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
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.

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
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.

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
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.

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
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.

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.

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.

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.

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.

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
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

Library timer.*
Return value  
See also  

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

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

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

timeout(time, callback)

Create a timeout that should be triggered after time argument milliseconds

Syntax

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

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

Util

Library util.*
Return value  
See also  

fill(color: Color)

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

Syntax

fill(color: Color)

Arguments

color Color Required
The color to use as fill color for new elements created
// 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

forever(callback: function)

Arguments

callback function Required
The function callback that should be triggered
forever(() => {
  // is repeated forever, with 20 milliseconds delay
})

repeat(times, callback)

Repeats the number of times given with 20 millisecond delay

Syntax

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
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

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
// 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

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
times(10, () => {
  // is repeated 10 times
})

update(callback)

Repeats on every update loop

Syntax

update(callback: function)

Arguments

callback function Required
The function callback that should be triggered
update(() => {
  // is repeated on every update loop
})

Types

UIElement

Library ui.*
See also ui.label(), ui.button()

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

// 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

Rect

Library display.*
See also display.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

rectangle = { x: Number, y: Number, width: Number, height: Number }

Usage

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

// The rect object
{ 
  x: 100, 
  y: 100, 
  width: 75, 
  height, 75 
}

Point

Library display.*
See also display.emoji()

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

position = { x: Number, y: Number }

Usage

position = { x: 100, y: 100 }

// The point object
{
  x: 100,
  y: 100
}

Size

Library display.*
See also display.emoji()

Represents a size in the coordinate system

width Number
The width in the coordinate system

height Number
The height in the coordinate system

Syntax

size = { width: Number, height: Number }

Usage

size = { width: 100, height: 100 }

// The size object
{
  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

// 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")