entity¶

class entity

A scene entity, created using scene.entity() that exists as part of the scene hierarchy. Entity behaviour and visuals are customised by addings various types of components or assets, such as sprite.slice, camera and mesh

There are shortcut properties to attach some common components, while others are built-in (such as transforms, names and relationships)

General

active: boolean¶

The active state of this entity, when inactive an entity will not be rendered, simulate physics or respond to automatic callbacks

Example

function setup()
    scene.main = scene.default3d()
    
    red = material.lit()
    red.baseColor = color.red
    red.roughness = 1

    green = material.lit()
    green.baseColor = color.green
    green.roughness = 1

    blue = material.lit()
    blue.baseColor = color.blue
    blue.roughness = 1
    
    -- Create some sphere that orbit each other with parenting
    e1 = scene.main:entity()
    e1.mesh = mesh.sphere(1.0)
    e1.mesh.material = red
    
    e1.update = function(entity, dt)
        entity.rotation = quat.eulerAngles(0, 0, time.elapsed * 90)
    end
    
    e2 = e1:child()
    e2.y = -2.5
    e2.mesh = mesh.sphere(0.5)
    e2.mesh.material = green
    e2.update = e1.update
    
    e3 = e2:child()
    e3.y = -1
    e3.mesh = mesh.sphere(0.25)
    e3.mesh.material = blue
    
    -- Test switching entity active states on and off for bits of the hierarchy
    parameter.boolean("E1_Active", true, function(b)
        e1.active = b
    end)
    
    parameter.watch("e1.activeInHierarchy")
    
    parameter.boolean("E2_Active", true, function(b)
        e2.active = b
    end)
    
    parameter.watch("e2.activeInHierarchy")
    
    parameter.boolean("E3_Active", true, function(b)
        e3.active = b
    end)
    
    parameter.watch("e3.activeInHierarchy")
end

activeInHierarchy: boolean [readonly]¶: The computed active in hierarchy state of this entity. Only true when all parents up to the root are active as well

valid: boolean¶: Checks the validity of this entity. When an entity is destroyed it is invalid and can no longer be used. non-valid entities will raise errors when calling functions or accessing properties

id: integer¶: A read-only identifier unique to the entity

name: string¶

The name of the entity, useful when referring to the entity later using the scene and entity indexers

scene.main = scene()
scene.main:entity("ball") -- create a new entity named 'ball'
print(scene.main.ball) -- retrieve the entity named 'ball'

Lifecycle

destroy([delay])¶

Marks this entity for destruction in the next scene.update(), or after a delay (in seconds), further access to this entity after destruction will result in errors

Example

function setup()
    scene.main = scene.default3d()
    e = scene.main:entity()
    e.rotation = quat.eulerAngles(45, 45, 45)
    e.mesh = mesh.box(1,1,1)
    e.mesh.material = material.lit()

    -- Destroy after 1 second when touched
    e.touched = function(entity, touch)
        if touch.began then entity:destroy(1) end
    end

    -- Play hurt sound when destroyed
    e.destroyed = function()
        sound.play(SOUND_HURT)
    end

end

Components

add(component, ...)¶

Adds a component to this entity, there are several types of objects that can act as entities

Lua classes/components
- Anything you can dream of…
built-in classes
- camera.rigs.orbit
- camera.rigs.canvas
- physics3d.grabber
assets
- mesh
- image / image.slice

scene.main = scene()
local sphere = scene.main:entity()
sphere:add(mesh.sphere(1)) -- Add a sphere mesh to the entity

-- Add an orbit rig to the camera (supersedes OrbitViewer from Craft)
scene.camera:add(camera.rigs.orbit)

-- Hypothetical day-night cycle Lua component for making the same orbit the planet
scene.sun:add(DayNightCycle, 60)

Note on Lua classes/components

When calling entity:add(component, ...) with a Lua class, all parameters will be forwarded to the created(...) event after the component’s construction, allowing for customised initialisation

remove(component)¶

Removes a given component type from this entity

scene.main = scene()
local sphere = scene.main:entity()
sphere:add(mesh.sphere(1)) -- add a sphere mesh to the entity
sphere:remove(mesh) -- remove the sphere mesh

has(component)¶

Checks if a component type is attached to this entity

scene.main = scene()
local sphere = scene.main:entity()
sphere:add(mesh.sphere(1)) -- add a sphere mesh to the entity
print(sphere:has(mesh)) -- prints 'true'

get(component)¶

Retrieves a component type attached to this entity

scene.main = scene()
local sphere = scene.main:entity()
sphere:add(mesh.sphere(1)) -- add a sphere mesh to the entity
print(sphere:get(mesh)) -- prints the mesh description

components: table<component>¶: Retrieves a list of all components attached to this entity

dispatch(name, ...)¶

Calls the method name on this entity (including any custom methods) and any attached custom lua components. Additional arguments will be passed to the method as well

Parameters:: name – The name of the method to call
Type:: string

Relationships

parent: entity¶: The parent of this entity or nil if it is a root entity

root: entity¶: The root parent entity in the scene heirarchy (or self if this entity has no parent)

children: table<entity>¶: A list of all immediate children of this entity

childCount: integer¶: The number of children that this entity possesses

depth: integer¶: The depth of this entity in the hierarchy (roots have a depth of 0)

index(name) [metamethod]

Retrieves children with the supplied name using the property syntax (i.e. myEntity.theChildName)

Note that this will not work if the child name is an existing property or method name in the entity class

child(name)¶: Creates a new child entity of this entity

findChild(name)¶

Returns:: Finds the child named name or nil if it does not exist

childAt(index)¶

Returns:: The child entity at a given index (between 1..childCount) or nil if an invalid index is supplied

moveBefore(entity)¶

Rearranges this entity to appear before the supplied entity in the transform hierarchy

Note this may result in an entity’s parent changing to make it the sibling or another entity

moveAfter(entity)¶

Rearranges this entity to appear after the supplied entity in the transform hierarchy

Note this may result in an entity’s parent changing to make it the sibling or another entity

Transform

position: vec3¶: The position of the entity in local 3D space

worldPosition: vec3¶: The position of the entity in global 3D space

scale: vec3¶: The scale of the entity in local 3D space

uniformScale: number¶: The uniform scale of the entity in local 3D space

rotation: quat¶: The rotation of the entity in local 3D space

worldRotation: quat¶: The rotation of the entity in world 3D space

eulerRotation: vec3¶: The euler rotation of the entity in local 3D space (in degrees)

x: number¶: The x position of the entity in local 3D space

y: number¶: The y position of the entity in local 3D space

z: number¶: The z position of the entity in local 3D space

sx: number¶: The x scale of the entity in local 3D space

sy: number¶: The y scale of the entity in local 3D space

sz: number¶: The z scale of the entity in local 3D space

rx: number¶: The euler rotation around the local x axis of the entity in degrees

ry: number¶: The euler rotation around the local y axis of the entity in degrees

rz: number¶: The euler rotation around the local z axis of the entity in degrees

forward: number¶: The positive z axis of this entity’s coordinate space transformed into world space

right: number¶: The positive x axis of this entity’s coordinate space transformed into world space

up: number¶: The positive y axis of this entity’s coordinate space transformed into world space

transformPoint(localPoint)¶

Transform a point from local to world space

Parameters:: localPoint (vec3) – The point to transform

inverseTransformPoint(worldPoint)¶

Transform a point from world to local space

Parameters:: worldPoint (vec3) – The point to transform

transformDirection(localDir)¶

Transform a vector from local to world space

Parameters:: localDir (vec3) – The vector to transform

inverseTransformDirection(worldDir)¶

Transform a vector from world to local space

Parameters:: worldDir (vec3) – The vector to transform

translate(x, y[, z])¶

Moves the entity by the provided translation vector in local space

Also supports vec2 and vec3 parameters

Sprite Properties

sprite: image.slice¶: The sprite (image.slice) attached to this entity. This will be drawn at the entities’ transform within the scene

color: color¶: The tint color to use

flipX: boolean¶: Flips the sprite on the x-axis

flipY: boolean¶: Flips the sprite on the y-axis

Mesh Properties

mesh: mesh¶: The mesh attached to this entity. This will be drawn the entities’ transform within the scene

material: material¶: The material attached to this entity (used in conjunction with meshes/sprites)

UI Properties / Methods

size: vec2¶: The size of the UI element

anchorX: enum¶

The horizontal anchoring of this UI element within its parent coordinate system

Values:

LEFT
CENTER
RIGHT
STRETCH

anchorY: enum¶

The vertical anchoring of this UI element within its parent coordinate system

Values:

TOP
MIDDLE
BOTTOM
STRETCH

pivot: vec2¶: The pivot point, representing the center of the UI element (in normalized coordinates)

clip: boolean¶: When enabled, clips drawing to within the bounds of the UI element

Physics2D Properties

body2d: physics2d.body¶: The attached 2D physics body (if there is one)

collider2d: physics2d.collider¶: The first attached 2D physics collider (if there is one)

colliders2d: table<physics2d.collider>¶: All attached 2D physics colliders

joints2d: table<physics2d.joint>¶: All attached 2D physics joints

Physics3D Properties

body3d: physics3d.body¶: The attached 3D physics body (if there is one)

collider3d: physics3d.collider¶: The first attached 3D physics collider (if there is one)

colliders3d: table<physics3d.collider>¶: All attached 3D physics colliders

joints3d: table<physics3d.joint>¶: All attached 3D physics joints

Lifecycle Callbacks

A series of handy callbacks that can be set which will be invoked automatically by scene systems

created: function¶

Callback for the created(…) event, which is called right after a Lua component is created, and forwards all parameters passed from the entity:add(component, ...) function

SelfDestructor = class('SelfDestructor')

-- Called when created but no parameters are forwarded here
function SelfDestructor:init()
end

-- Use for custom component initialization, all parameters forwarded to here
function SelfDestructor:created(delay)
   print("I will self destruct in ", delay, " seconds")
   self.entity:destroy(delay)
end

...

local ent = main.scene:entity()
ent:add(SelfDestructor, 3) -- prints "I will self destruct in 3 seconds"

destroyed: function¶: Callback for the destroyed() event, which is called right before the entity is destroyed

Physics Callbacks

collisionBegan2d: function¶: Callback for the collisionBegan2d(contact) event, which is called when a collision occurs with a physics2d.body attached to this entity

collisionBegan3d: function¶: Callback for the collisionBegan3d(contact) event, which is called when a collision occurs with a physics3d.body attached to this entity

Simulation Callbacks

update: function¶: Callback for the update(dt) event, which is called on all active entities once per frame. The dt parameter passes the delta time of the enclosing scene for this frame

fixedUpdate: function¶: Callback for the fixedUpdate(dt) event, which is called on all active entities once per fixed update (called a fixed number of times per second). The dt parameter passes the fixed delta time of the enclosing scene

Interaction Callbacks

touched: function¶

Callback for the touched(touch) event, which is called whenever a touch occurs (in response to user interaction)

During the BEGAN phase of an incomming touch, returning true from this function will capture the touch for all subsequent events, otherwise the touch will be lost

hitTest: boolean [default = false]¶: Enables hit testing for the touched(touch) event, which will filter touches based on collision checks using attached physics components on the main camera