Element

Library display.*
See also display.emoji(), display.rect(), display.circle(), display.polygon(), display.cloud(), display.line(), display.ellipse(), display.star() 
// The element 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,
  alpha: 1
}

Attributes

position Point

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

x Number

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

y Number

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

size Size

The size of this element

width Number

The width of the element. Changing the width will change the width size of the element.

height Number

The height of the element. Changing the height will change the height size of the element.

scale Number

The scale of this element

angle Number

The angle of this element

angleOffset Number

The angle offset of the drawing of this element

active Boolean

Indicates if this element is active or not

color Color

The color of this element

borderColor Color

The border color of this element

borderWidth Number

The border width of this element

alpha Number

The alpha value of this element. 0 is invisible, 1 is visible

flip Boolean

Flip the drawing of this element

Methods

applyForce(xForce, yForce)

Applies physics force to this element.

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 element

element.applyForce(0, -50)

applyImpulse(xForce, yForce)

Applies physics impulse to this element.

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 element

element.applyImpulse(0, -50)

applyTorque(force)

Applies physics torque to this element. Negative value applies counter-clockwise torque.

force Number required
The amount of force to apply in the clockwise or counter-clockwise direction

Applying physics force to element

// apply clockwise torque
element.applyTorque(10)

// apply counter-clockwise torque
element.applyTorque(-10)

bounceX()

Rotates this element in a direction that mirrors the x direction and keeps the current y direction.

element.update(() => {
  element.move(2)

  if (element.x > 100) {
    element.bounceX()
  }
})

bounceY()

Rotates this element in a direction that mirrors the y direction and keeps the current x direction.

element.update(() => {
  element.move(2)

  if (element.y > 100) {
    element.bounceY()
  }
})

changeX(value)

Changes the current x coordinate position by the specified value

Syntax

element.changeX(value: Number)
value Number required
The value amount to change x coordinate by

changeY(value)

Changes the current y coordinate position by the specified value

Syntax

element.changeY(value: Number)
value Number required
The value amount to change y coordinate by

click(callback)

Alias function to element.clicked(callback)

clicked(callback)

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

Syntax

clicked((event: Object) => {})
callback function required
Required parameter for this function

callback parameters

  • event Object
    An event object with data containing information about the current clicked event.
    • self Element
      A reference to the element triggered by the click action

Clicked with callback

element.clicked((e) => {
  // element is clicked / tapped
})

collide(other)

Check to test if this element collides with another element.

Returns true if the elements collide.

Syntax

collide(element: Element)
other Element required
Required parameter for this function

Check if elements are colliding

if (element.collide(other)) {
  // the elements collide
} else {
  // the elements does not collide
}

collision(callback)

Callback is called when this element collides with another element.

Syntax

collision((event: Object) => {})
callback function required
Required parameter for this function

callback parameters

  • event Object
    A collision event containing data about the collision event
    • tag String
      A string value containing the tag value of the other element in the collision
    • other Element
      The other element in the collision
    • self Element
      The element receiving the current collision event

Collision with callback

element.collision((event) => {
  if (event.tag == "cloud") {
    // element is colliding with something tagged with cloud
  }
})

destroy()

Removes element from display and destroys this element from processing. If the element has physics attached the physics body is also removed.

Destroy an element

element.destroy()

distanceTo(other)

The distanceTo returns a Number which is the distance to another Element.

Syntax

distanceTo(other: Element) -> Number
function arguments
other Element required
Required parameter. Another Element that this function calculates the distance to.

Get the distance to another element

distance = element.distanceTo(another)
if (distance > 10) {
  // the distance is greater than 10
}

follow()

The follow method updates the current elements angle to point to another given element and moves it a given number of points. This happens on the update loop. Default move distance is 1

Syntax

follow(other: Element, distance: Number = 1)

function arguments

other Element required
Required parameter. Another Element that this element should point towards. Can also be any object with a position point { position: Point } like Input

distance Number optional

  • Optionale parameter. Default value is 1

Follow another object

element.follow(other, 2)

glideTo()

Alias function to element.moveTo(point)

goTo(point)

Send this element to another point

Syntax

element.goTo(point: Point)
element.goTo(x: Number, y: Number)
point Point required
Required parameter for this function

OR

x Number required
The x coordinate the element should go to
y Number required
The y coordiante the element should go to

Setting the position point for element

element.goTo(100, 100)
element.goTo({ x: 100, y: 100 })
element.goTo(random.pos())

hide()

Hides this element from display but is not removed / destroyed.

hidden()

Returns true if the element is hidden.

ifOnEdgeBounce()

Rotates this element in a direction that mirrors the direction it was coming from if touching the edge of the display.

element.update(() => {
  element.move(2)

  element.ifOnEdgeBounce()
})

ifOnEdgeContinue()

Moves the element to the opposite side of the world if on the edge of the world.

element.update(() => {
  element.move(2)

  element.ifOnEdgeContinue()
})

inView()

Returns true if the element is visible in current camera view.

Returns

  • Boolean
    true, if the element is visible in the camera view.
if (element.inView()) {
  // element is in camera view
} else {
  // element is not in camera view
}

inWorld()

Returns true if the element is inside the world size

Returns

  • Boolean
    true, if the element is inside the world size
if (element.inWorld()) {
  // element is in the world
} else {
  // element is outside to world
}

move(distance)

Moves the current element the given distance in the direction of the elements current angle

function arguments
distance Number required
Required parameter. The distance to move

Moving an element

element.move(10)

moveForce(value)

Applies physics force in the direction of the elements current angle

function arguments
value Number required
The force value to apply this element

If the element does not have a physics body the elements move() function is called

Moving an element with physics force

element.moveForce(10)

moveImpulse(value)

Applies physics impulse in the direction of the elements current angle

function arguments
value Number required
The impulse value to apply this element

If the element does not have a physics body the elements move() function is called

Moving an element with physics impulse

element.moveImpulse(10)

moveTo(point)

Move this element to another point with an animation

Syntax

element.moveTo(point: Point)
element.moveTo(x: Number, y: Number)
point Point required
Required parameter for this function

OR

x Number required
The x coordinate the element should go to
y Number required
The y coordiante the element should go to

Animate an element to another position

element.moveTo(100, 100)
element.moveTo({ x: 100, y: 100 })
element.moveTo(random.pos())

moveToBack()

Moves the element to the back of the draw order. The element will be drawn behind the other elements.

Move an element to the back of the draw order

element.moveToBack()

moveToFront()

Moves the element to the front of the draw order. The element will be drawn in front of the other elements.

Move an element to the front of the draw order

element.moveToFront()

notInView()

Returns true if the element is not visible in current camera view.

Returns

  • Boolean
    true, if the element is not visible in the camera view.
if (element.notInView()) {
  // element is in camera view
} else {
  // element is not in camera view
}

onEdge()

Returns true if the element is on the edge of the world

Returns

  • Boolean
    true if the element is on the edge to the world
if (element.onEdge()) {
  // the element is on the edge of the world
}

onEdgeX()

Returns true if the element is on the edge of the x axis in the coordinate space of the world

Returns

  • Boolean
    true if the element is on the edge of the x axis to the world
if (element.onEdgeX()) {
  // the element is on the edge of the x axis
}

onEdgeY()

Returns true if the element is on the edge of the y axis in the coordinate space of the world

Returns

  • Boolean
    true if the element is on the edge of the y axis to the world
if (element.onEdgeY()) {
  // the element is on the edge of the y axis
}

point(callback)

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

Syntax

element.point((event: Object) => {})
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
    • self Element
      A reference to the element triggered by the point action
element.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
    )
  }
})

pointInDirection(degree)

The pointInDirection sets the angle of the element

function arguments
degree Number required
The degree that the element should point to.

Point to 90 degrees

element.pointInDirection(90)

pointTo(other)

The pointTo updates the current elements angle to point to another firebox element

function arguments
other Element required
Required parameter. Another Element that this element should point towards. Can also be any object with a position point { position: Point } like Input

Point to another object with { position: Point }

element.update(() => {
  element.pointTo(another)
})

remove()

Alias function to element.destroy()

rotate(value)

Rotates this element by a given value.

functions arguments
value Number required
The amount to rotate the element

Rotate an element

element.update(() => {
  element.rotate(2)
})

say()

Display a speech bubble by the side of the element

  • text String required
    The text to display inside the speach bubble
  • duration Number optional
    The duration to show the speech bubble

Show speech bubble beside an element

element.say("Hello World!")

// Show speech bubble for 2 seconds
element.say("Hello World!", 2000)

setX(value)

Sets the current x position coordinate for this element

Syntax

element.setX(value: Number)
value Number required
The x coordinate the element should go to

setY(value)

Sets the current y position coordinate for this element

Syntax

element.setY(value: Number)
value Number required
The y coordinate the element should go to

shift()

Shifts the element a given size on the x and y axis

Syntax

element.shift(x: Number, y: Number)
x Number required
The number of sizes to shift on the x axis
y Number required
The number of sizes to shift on the y axis

Jump one size to the right

element.shift(1, 0)

show()

Shows this element if it was hidden. Opposite of element.hide().

Show a hidden element

if (element.hidden()) {
  element.show() // shows an element if hidden
}

tap(callback)

Alias function to element.clicked(callback)

turnLeft(value)

Rotates this element by a given value in degrees counterclockwise.

functions arguments
value Number required
The amount to rotate the element counterclockwise

Rotate an element in the counterclockwise direction

element.update(() => {
  element.turnLeft(2)
})

turnRight(value)

Rotates this element by a given value in degrees clockwise.

functions arguments
value Number required
The amount to rotate the element clockwise

Rotate an element in the clockwise direction

element.update(() => {
  element.turnRight(2)
})

update(callback)

Callback is called when this element is updated in the update loop.

Syntax

update((event: Object) => {})
  • callback function required
    Required parameter for this function

callback parameters

  • event Object
    An event object with data containing information about the current element update event.
    • self Element
      A reference to the current element being updated.

Update with callback

element.update((event) => {
  // this is called every update loop
})

wait(value)

Halt all movement and wait for a given value in milliseconds.

functions arguments
value Number required
The amount of time to wait in milliseconds

Wait for 1 second

element.wait(1000)