# Scenes & Entities
Scenes, entities, cameras, effects and lights
[Reference](index.md)
## Guides
### Scenes in Codea
A `scene` holds the objects in a 2D or 3D world. Each object is an `entity`; add components such as a mesh, camera, light, or physics body to give it an appearance or behavior.
Codea draws and updates the scene for you, including its physics simulation.
```lua
function setup()
scn = scene()
-- Camera entity
local cam = scn:entity("camera")
cam:add(camera.perspective(60))
cam:add(camera.rigs.orbit)
cam.z = -10
-- A sphere
local sphere = scn:entity("sphere")
sphere:add(mesh.sphere(1))
-- Make this the active scene
scene.main = scn
end
```
## Creating Scenes
Create a scene with `scene()` and assign it to `scene.main` to draw and update it each frame.
```lua
scn = scene()
scene.main = scn
```
You can have multiple scenes and switch between them by reassigning `scene.main`.
## Entities
Entities are the basic building blocks of a scene. They have a transform (position, rotation, scale) and can hold any number of components.
Create entities with `scene:entity()`:
```lua
-- Named entity (accessible by name later)
local ball = scn:entity("ball")
-- Access by name
print(scn.ball)
```
Child entities are created under an existing entity and inherit its transform:
```lua
local arm = scn:entity("arm")
local hand = arm:child("hand")
hand.z = 2 -- 2 units ahead of the arm's local origin
```
## Components
Components add behaviour to entities. Attach them with [`entity.add()`](#entity:add):
```lua
local sphere = scn:entity("sphere")
-- Add a mesh
sphere:add(mesh.sphere(1))
-- Add a lit material
sphere.material = material.lit()
-- Add a 3D physics body
sphere:add(physics3d.body(physics3d.DYNAMIC))
sphere:add(physics3d.sphere(1))
```
Custom Lua classes are also valid components:
```lua
Rotator = class("Rotator")
function Rotator:update(dt)
self.entity.ry = self.entity.ry + dt * 90
end
local cube = scn:entity()
cube:add(mesh.box())
cube:add(Rotator)
```
## Drawing in an Entity
An entity or script component can implement `draw()` to draw sprites, text, and shapes in the entity’s local coordinates. Each callback starts with the entity’s world transform and inherits the current drawing style. Codea restores the style and model, view, and projection matrices afterward, including after an error or unmatched stack operations. There is no implicit style reset. Use explicit pushes and pops when you need separate styles or transforms *within* a callback.
Sprites and text normally draw over scene geometry. Enable [`style.depth()`](Graphics.md#style.depth) to let opaque objects hide them:
```lua
function ball:draw()
style.depth(true).textRenderer(style.atlas)
fill(255)
fontSize(1)
shapeMode(CENTER)
textAlign(CENTER | MIDDLE)
matrix.translate(0, 1.5, 0)
text(self.name)
end
```
The atlas text renderer keeps small world-space text sharp. Depth-tested sprites and text do not write depth, and retain their drawing order after scene geometry. This requires a depth buffer and a scene using `drawOrder.distance`; ordered 2D scenes do not depth-test.
## The Scene Camera
Every scene needs at least one camera entity with a `camera` component attached:
```lua
local cam = scn:entity("camera")
cam:add(camera.perspective(60)) -- 60° field of view
cam.z = -5 -- Pull back 5 units
```
Use `camera.rigs.orbit` to add an interactive orbit controller that works with mouse and touch:
```lua
cam:add(camera.rigs.orbit)
```
## Lifecycle Callbacks
Give an entity an `update()` function to move it each frame, or a `touched()` function to respond to touches. You can also define these functions in a Lua component:
```lua
local ent = scn:entity()
function ent:update(dt)
self.ry = self.ry + dt * 45
end
function ent:touched(touch)
if touch.began then
self:destroy()
end
return true -- capture the touch
end
```
### Camera Effects
Camera effects change the finished picture of a scene. Add bloom to make bright
areas glow, adjust the colors, darken the edges with a vignette, or blur part of
the picture with tilt shift.
## Getting started
Attach a camera to a scene entity and set its effect properties. Effects run
when the camera draws the scene. `camera:apply()` sets the drawing matrices
only; it does not apply effects to shapes or meshes you draw yourself.
```lua
function setup()
local world = scene()
local eye = world:entity("Camera")
eye.z = -8
local cam = eye:add(camera.perspective(60))
cam.bloom.strength = 0.6
cam.bloom.threshold = 0.9
cam.saturation = 1.1
cam.vignette = 0.2
cam.grain = 0.02
local ball = world:entity("Ball")
ball:add(mesh.sphere(1))
scene.main = world
end
```
## Tilt shift and custom effects
`cam.tiltShift.blur = 6` adds up to six points of blur outside the sharp band.
The defaults keep the middle of the image sharp. Adjust `focus`, `range` and
`falloff` together to place the band and soften its edges.
Add your own shader with `cam:addEffect(source)`. Custom effects run in the
order you add them, after the built-in effects. Each receives the picture so far
as `source`; declare a `scene` sampler to also read the original picture.
Use the returned shader to change its uniforms. See [Camera](#camera) for details.
## Layering cameras and controlling effects
With `camera.none` or `camera.depth` as the clear mode, the finished picture
is drawn over what is already on screen. Keep alpha in custom shaders so
transparent areas stay transparent. A camera that clears color first clears
its whole image. Effects follow the camera’s viewport and resize with it.
Bloom uses smaller images, while tilt shift and custom shaders work on full-size
images and can cost more to draw. Set bloom strength or tilt-shift blur to zero
to skip that effect. Set `cam.effectsEnabled = false` to turn off all effects.
`cam:clearEffects()` removes custom effects without resetting the built-in settings.
## Scene
### scene
```lua
scene
```
Holds the entities in a 2D or 3D world and handles their drawing, input, and physics. Set `scene.main` to draw and update a scene automatically.
create a default 3D scene
### scene.main
```lua
scene.main
```
Sets the main Codea scene, which will be automatically drawn, updated and handle touch events
#### Example
```lua
function setup()
scene.main = scene.default3d()
end
```
### scene.default3d(name)
```lua
scene.default3d(name)
```
Creates the default 3D scene containing a perspective camera, directional light and HDR environment, with an optional name
create a default 3D scene
#### Parameters
- **name** (string, optional): Name assigned to the scene or entity, or the entity name to search for.
#### Returns
- **scene**:
### scene.default2d(name)
```lua
scene.default2d(name)
```
Creates the default 2D scene containing an orthographic camera, with an optional name
create a default 2D scene
#### Parameters
- **name** (string, optional): Name assigned to the scene or entity, or the entity name to search for.
#### Returns
- **scene**:
### scene.read(key)
```lua
scene.read(key)
```
Loads and returns a scene with the supplied asset key
load a scene from an asset
#### Parameters
- **key** (asset.key): Asset key identifying the scene file.
#### Returns
- **scene**:
### scene.save(key, scene)
```lua
scene.save(key, scene)
```
Saves the supplied scene at the given asset key location
save a scene to an asset
#### Parameters
- **key** (asset.key): Asset key identifying the scene file.
- **scene** (scene): Scene to save.
### scene.name
```lua
scene.name
```
Gets or sets a name for this scene
name of the scene
### scene.world2d
```lua
scene.world2d
```
Gets the scene’s 2D physics world, providing access to various physics functions and properties such as `physics2d.world.applyForce()`
2D physics world of the scene
### scene.world3d
```lua
scene.world3d
```
Gets the scene’s 3D physics world, providing access to various physics functions and properties such as `physics3d.world.applyForce()`
3D physics world of the scene
### scene.sky
```lua
scene.sky
```
Sets the sky visuals, which will depend on the type used:
- `asset.key` - Use an image pointed to by a given asset key
- `image` - Use an image directly (assumed to be a cube image)
- `color` - Use a solid color
sky background of the scene
### scene.skyBlur
```lua
scene.skyBlur
```
The blur strength of the skybox
blur strength of the skybox
### scene.skyExposure
```lua
scene.skyExposure
```
The brightness of the skybox
brightness of the skybox
### scene.camera
```lua
scene.camera
```
camera entity of the scene
### scene.sun
```lua
scene.sun
```
sun entity of the scene
### scene.canvas
```lua
scene.canvas
```
main UI canvas of the scene
### scene.pixelsPerUnit
```lua
scene.pixelsPerUnit
```
The amount of pixels that are in a grid unit
pixels per world unit
### scene.drawOrder
```lua
scene.drawOrder
```
How the scene orders its draws, which can be one of the following values:
- `drawOrder.distance` - draw opaque objects first, then transparent objects sorted back to front by distance from the camera (default)
- `drawOrder.ordered` - draw objects in the order they are submitted, without sorting by distance
how the scene orders its draws
### scene:entity(name)
```lua
scene:entity(name)
```
Creates a new blank `entity` with an optional name
create a new entity
#### Parameters
- **name** (string, optional): Name assigned to the scene or entity, or the entity name to search for.
#### Returns
- **entity**:
### scene:findEntity(name)
```lua
scene:findEntity(name)
```
find an entity by name
#### Parameters
- **name** (string): Name assigned to the scene or entity, or the entity name to search for.
#### Returns
- **entity**:
### scene:entities(activeOnly)
```lua
scene:entities(activeOnly)
```
Returns a table containing all root entities
get the root entities in the scene
#### Parameters
- **activeOnly** (boolean, optional, default: true): When set, returns only active root entities
#### Returns
- **table**:
### scene:index(name) [metamethod]()
```lua
scene:index(name) [metamethod]()
```
Returns the root entity with the given name (if it exists)
get a root entity by name
#### Returns
- **entity**:
### scene:draw()
```lua
scene:draw()
```
Immediately draws the scene to the current context. When autoUpdate is enabled, `update(dt)` will be called as well
If set as `scene.main` this will be called automatically right before the global `draw()` function
draw the scene
### scene:update(deltaTime)
```lua
scene:update(deltaTime)
```
Updates the scene, called automatically when `draw()` is called but can also be called manutally if needed
update the scene
#### Parameters
- **deltaTime** (number): Elapsed simulation time in seconds.
## Entity
### entity
```lua
entity
```
A scene entity, created using [`scene.entity()`](#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)
get or set the active state of this entity
### entity.active
```lua
entity.active
```
The active state of this entity, when inactive an entity will not be rendered, simulate physics or respond to automatic callbacks
get or set the active state of this entity
#### Example
```lua
function setup()
scene.main = scene.default3d()
red = material.lit()
red.color = color.red
red.roughness = 1
green = material.lit()
green.color = color.green
green.roughness = 1
blue = material.lit()
blue.color = 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
```
### entity.activeInHierarchy
```lua
entity.activeInHierarchy
```
The computed active in hierarchy state of this entity. Only `true` when all parents up to the root are active as well
get the computed active state in the hierarchy
### entity.valid
```lua
entity.valid
```
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
get whether this entity is valid
### entity.id
```lua
entity.id
```
A read-only identifier unique to the entity
get the unique identifier of this entity
### entity.name
```lua
entity.name
```
The name of the entity, useful when referring to the entity later using the `scene` and `entity` indexers
get or set the name of this entity
#### Example
```lua
scene.main = scene()
scene.main:entity("ball") -- create a new entity named 'ball'
print(scene.main.ball) -- retrieve the entity named 'ball'
```
### entity:destroy(delay)
```lua
entity:destroy(delay)
```
Marks this entity for destruction in the next [`scene.update()`](#scene:update), or after a `delay` (in seconds), further access to this entity after destruction will result in errors
mark this entity for destruction
#### Parameters
- **delay** (number, optional): Delay before destruction, in seconds; omit to destroy on the next scene update.
#### Example
```lua
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
```
### entity:add(component, ...)
```lua
entity: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`
- `voxel.world`
- assets
- `mesh`
- `image` / `image.slice`
*Note on Lua classes/components*
add a component to this entity
#### Parameters
- **component** (table or userdata): Component class or supported asset type; add() also accepts assets such as a mesh or image.
- **...** (any): Additional arguments forwarded to the component constructor or dispatched method.
#### Example
```lua
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)
```
### entity:remove(component)
```lua
entity:remove(component)
```
Removes a given component type from this entity
remove a component from this entity
#### Parameters
- **component** (table or userdata): Component class or supported asset type; add() also accepts assets such as a mesh or image.
#### Example
```lua
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
```
### entity:has(component)
```lua
entity:has(component)
```
Checks if a component type is attached to this entity
check if a component is attached to this entity
#### Parameters
- **component** (table or userdata): Component class or supported asset type; add() also accepts assets such as a mesh or image.
#### Example
```lua
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'
```
### entity:get(component)
```lua
entity:get(component)
```
Retrieves a component type attached to this entity
get a component attached to this entity
#### Parameters
- **component** (table or userdata): Component class or supported asset type; add() also accepts assets such as a mesh or image.
#### Example
```lua
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
```
### entity.components
```lua
entity.components
```
Retrieves a list of all components attached to this entity
get all components attached to this entity
### entity:dispatch(name, ...)
```lua
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
dispatch a method call to this entity and its components
#### Parameters
- **name** (string): The name of the method to call
- **...** (any): Additional arguments forwarded to the component constructor or dispatched method.
### entity.parent
```lua
entity.parent
```
The parent of this entity or `nil` if it is a root entity
get or set the parent of this entity
### entity.root
```lua
entity.root
```
The root parent entity in the scene heirarchy (or self if this entity has no parent)
get the root entity in the hierarchy
### entity.children
```lua
entity.children
```
A list of all immediate children of this entity
get all immediate children of this entity
### entity.childCount
```lua
entity.childCount
```
The number of children that this entity possesses
get the number of children of this entity
### entity.depth
```lua
entity.depth
```
The depth of this entity in the hierarchy (roots have a depth of 0)
get the depth of this entity in the hierarchy
### entity:index(name) [metamethod]()
```lua
entity: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*
retrieve a child by name using property syntax
### entity:child(name)
```lua
entity:child(name)
```
Creates a new child entity of this entity
create a new child entity
#### Parameters
- **name** (string): Name of the child entity or component method to find or invoke.
### entity:findChild(name)
```lua
entity:findChild(name)
```
find a child entity by name
#### Parameters
- **name** (string): Name of the child entity or component method to find or invoke.
#### Returns
- **value**: Finds the child named name or nil if it does not exist
### entity:childAt(index)
```lua
entity:childAt(index)
```
get the child entity at a given index
#### Parameters
- **index** (integer): Child index, starting at 1.
#### Returns
- **value**: The child entity at a given index (between 1..childCount) or nil if an invalid index is supplied
### entity:moveBefore(entity)
```lua
entity: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*
move this entity before another in the hierarchy
#### Parameters
- **entity** (entity): Sibling to place this entity before or after.
### entity:moveAfter(entity)
```lua
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*
move this entity after another in the hierarchy
#### Parameters
- **entity** (entity): Sibling to place this entity before or after.
### entity.position
```lua
entity.position
```
The position of the entity in local 3D space
get or set the local position of this entity
### entity.worldPosition
```lua
entity.worldPosition
```
The position of the entity in global 3D space
get or set the world position of this entity
### entity.scale
```lua
entity.scale
```
The scale of the entity in local 3D space
get or set the scale of this entity
### entity.uniformScale
```lua
entity.uniformScale
```
The uniform scale of the entity in local 3D space
get or set the uniform local scale of this entity
### entity.rotation
```lua
entity.rotation
```
The rotation of the entity in local 3D space
get or set the local rotation of this entity
### entity.worldRotation
```lua
entity.worldRotation
```
The rotation of the entity in world 3D space
get or set the world rotation of this entity
### entity.eulerRotation
```lua
entity.eulerRotation
```
The euler rotation of the entity in local 3D space (in degrees)
get or set the local euler rotation in degrees
### entity.x
```lua
entity.x
```
The x position of the entity in local 3D space
get or set the local x position
### entity.y
```lua
entity.y
```
The y position of the entity in local 3D space
get or set the local y position
### entity.z
```lua
entity.z
```
The z position of the entity in local 3D space
get or set the local z position
### entity.sx
```lua
entity.sx
```
The x scale of the entity in local 3D space
get or set the local x scale
### entity.sy
```lua
entity.sy
```
The y scale of the entity in local 3D space
get or set the local y scale
### entity.sz
```lua
entity.sz
```
The z scale of the entity in local 3D space
get or set the local z scale
### entity.rx
```lua
entity.rx
```
The euler rotation around the local x axis of the entity in degrees
get or set the local x euler rotation in degrees
### entity.ry
```lua
entity.ry
```
The euler rotation around the local y axis of the entity in degrees
get or set the local y euler rotation in degrees
### entity.rz
```lua
entity.rz
```
The euler rotation around the local z axis of the entity in degrees
get or set the local z euler rotation in degrees
### entity.forward
```lua
entity.forward
```
The positive z axis of this entity’s coordinate space transformed into world space
get the forward direction in world space
### entity.right
```lua
entity.right
```
The positive x axis of this entity’s coordinate space transformed into world space
get the right direction in world space
### entity.up
```lua
entity.up
```
The positive y axis of this entity’s coordinate space transformed into world space
get the up direction in world space
### entity:transformPoint(localPoint)
```lua
entity:transformPoint(localPoint)
```
Transform a point from local to world space
transform a point from local to world space
#### Parameters
- **localPoint** (vec3): The point to transform
### entity:inverseTransformPoint(worldPoint)
```lua
entity:inverseTransformPoint(worldPoint)
```
Transform a point from world to local space
transform a point from world to local space
#### Parameters
- **worldPoint** (vec3): The point to transform
### entity:transformDirection(localDir)
```lua
entity:transformDirection(localDir)
```
Transform a vector from local to world space
transform a direction from local to world space
#### Parameters
- **localDir** (vec3): The vector to transform
### entity:inverseTransformDirection(worldDir)
```lua
entity:inverseTransformDirection(worldDir)
```
Transform a vector from world to local space
transform a direction from world to local space
#### Parameters
- **worldDir** (vec3): The vector to transform
### entity:translate(x, y, z)
```lua
entity:translate(x, y, z)
```
Moves the entity by the provided translation vector in local space
Also supports `vec2` and `vec3` parameters
translate this entity in local space
#### Parameters
- **x** (number): Translation along the x axis.
- **y** (number): Translation along the y axis.
- **z** (number, optional): Translation along the z axis.
### entity.sprite
```lua
entity.sprite
```
The sprite (`image.slice`) attached to this entity. This will be drawn at the entities’ transform within the scene
get or set the sprite attached to this entity
### entity.color
```lua
entity.color
```
The tint color to use
get or set the tint color of this entity
### entity.visible
```lua
entity.visible
```
Sets/gets whether the entity should be drawn or not
get or set whether this entity is visible
### entity.flipX
```lua
entity.flipX
```
Flips the sprite on the x-axis
get or set whether the sprite is flipped on x
### entity.flipY
```lua
entity.flipY
```
Flips the sprite on the y-axis
get or set whether the sprite is flipped on y
### entity.mesh
```lua
entity.mesh
```
The mesh attached to this entity. This will be drawn the entities’ transform within the scene
get or set the mesh attached to this entity
### entity.material
```lua
entity.material
```
The material attached to this entity (used in conjunction with meshes/sprites)
get or set the material attached to this entity
### entity.size
```lua
entity.size
```
The size of the UI element
get or set the size of the UI element
### entity.anchorX
```lua
entity.anchorX
```
The horizontal anchoring of this UI element within its parent coordinate system
Values:
- `LEFT`
- `CENTER`
- `RIGHT`
- `STRETCH`
get or set the horizontal anchor of this UI element
### entity.anchorY
```lua
entity.anchorY
```
The vertical anchoring of this UI element within its parent coordinate system
Values:
- `TOP`
- `MIDDLE`
- `BOTTOM`
- `STRETCH`
get or set the vertical anchor of this UI element
### entity.pivot
```lua
entity.pivot
```
The pivot point, representing the center of the UI element (in normalized coordinates)
get or set the pivot point of this UI element
### entity.clip
```lua
entity.clip
```
When enabled, clips drawing to within the bounds of the UI element
get or set whether clipping is enabled
### entity.body2d
```lua
entity.body2d
```
The attached 2D physics body (if there is one)
get the attached 2D physics body
### entity.collider2d
```lua
entity.collider2d
```
The first attached 2D physics collider (if there is one)
get the first attached 2D physics collider
### entity.colliders2d
```lua
entity.colliders2d
```
All attached 2D physics colliders
get all attached 2D physics colliders
### entity.joints2d
```lua
entity.joints2d
```
All attached 2D physics joints
get all attached 2D physics joints
### entity.body3d
```lua
entity.body3d
```
The attached 3D physics body (if there is one)
get the attached 3D physics body
### entity.collider3d
```lua
entity.collider3d
```
The first attached 3D physics collider (if there is one)
get the first attached 3D physics collider
### entity.colliders3d
```lua
entity.colliders3d
```
All attached 3D physics colliders
get all attached 3D physics colliders
### entity.joints3d
```lua
entity.joints3d
```
All attached 3D physics joints
get all attached 3D physics joints
### entity.created
```lua
entity.created
```
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
callback invoked when this entity is created
#### Example
```lua
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"
```
### entity.destroyed
```lua
entity.destroyed
```
Callback for the destroyed() event, which is called right before the entity is destroyed
callback invoked before this entity is destroyed
### entity.collisionBegan2d
```lua
entity.collisionBegan2d
```
Callback for the `collisionBegan2d(contact)` event, which is called when a collision occurs with a physics2d.body attached to this entity
callback invoked when a 2D collision begins
### entity.collisionBegan3d
```lua
entity.collisionBegan3d
```
Callback for the `collisionBegan3d(contact)` event, which is called when a collision occurs with a physics3d.body attached to this entity
callback invoked when a 3D collision begins
### entity.update
```lua
entity.update
```
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
callback invoked once per frame
### entity.fixedUpdate
```lua
entity.fixedUpdate
```
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
callback invoked once per fixed update
### entity.touched
```lua
entity.touched
```
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
callback invoked when a touch event occurs
### entity.hitTest
```lua
entity.hitTest
```
Enables hit testing for the `touched(touch)` event, which will filter touches based on collision checks using attached physics components on the main camera
enable hit testing for touch events
## Camera
### camera
```lua
camera
```
A camera object used for rendering. Can also be used as a component in scenes
create an orthographic camera
#### Example
```lua
scn = scene()
-- Create an entity and attach a perspective camera to it
cam = scn:entity():add(camera.perspective(45, 0.1, 100))
```
#### Example
```lua
-- Use a camera directly with drawing calls
cam = camera.perspective(45, 0.1, 100)
cam:apply()
```
### camera.ortho(size, near, far)
```lua
camera.ortho(size, near, far)
```
create an orthographic camera
#### Parameters
- **size** (number): Vertical span of the orthographic view, in world units.
- **near** (number, optional): Distance to the near clipping plane, in world units.
- **far** (number, optional): Distance to the far clipping plane, in world units.
#### Returns
- **camera**: A new orthographic camera
### camera.perspective(fov, near, far)
```lua
camera.perspective(fov, near, far)
```
create a perspective camera
#### Parameters
- **fov** (number): Vertical field of view, in degrees.
- **near** (number, optional): Distance to the near clipping plane, in world units.
- **far** (number, optional): Distance to the far clipping plane, in world units.
#### Returns
- **camera**: A new perspective camera
### camera.isOrtho
```lua
camera.isOrtho
```
Determines if the camera is orthographic or perspective
whether the camera is orthographic
### camera.orthoSize
```lua
camera.orthoSize
```
The ortho graphic size (height) of this camera when in orthographic mode
orthographic height of the camera
### camera.clearMode
```lua
camera.clearMode
```
The clear mode, which can be one of the following values:
- `camera.none` - do not clear the background
- `camera.color` - clear the color only
- `camera.depth` - clear the depth only
- `camera.depthAndColor` - clear both the depth and color
- `camera.sky` - clear depth and draw the scene sky (the default for a 3D scene)
how the camera clears the view
### camera.clearColor
```lua
camera.clearColor
```
The color to use when clearing the screen with this camera
clear color of the camera
### camera.fieldOfView
```lua
camera.fieldOfView
```
The field of view for this camera when in perspective mode
field of view of the camera
### camera.nearPlane
```lua
camera.nearPlane
```
The distance of near view plane from the view origin
distance to the near plane
### camera.farPlane
```lua
camera.farPlane
```
The distance of far view plane from the view origin
distance to the far plane
### camera.priority
```lua
camera.priority
```
The priority of the camera when used within a scene (cameras with lower values are drawn first)
draw order priority of the camera
### camera.projection
```lua
camera.projection
```
Sets/gets a custom projection matrix
custom projection matrix
### camera.view
```lua
camera.view
```
Sets/gets a custom view matrix
custom view matrix
### camera.viewport
```lua
camera.viewport
```
Sets/gets the current viewport using normalized coordinates. Can be used for adjusting the rendered area of the camera relative to the screen. For instance, writing `camera.viewport = vec4(0.0, 0.0, 0.5, 1.0)` will render the camera to only the left half of the screen.
- `x`: The x position of the viewport
- `y`: The y position of the viewport
- `z`: The width of the viewport
- `w`: The height of the viewport
normalized viewport of the camera
### camera.aspect
```lua
camera.aspect
```
Sets/gets the aspect ratio of the viewport
aspect ratio of the viewport
### camera:apply()
```lua
camera:apply()
```
Apply this cameras settings to the matrix stack
apply the camera to the matrix stack
### camera:screenToWorld(x, y, z)
```lua
camera:screenToWorld(x, y, z)
```
Takes a 2D point on the screen (in points) and a depth value and unprojects this point into 3D space. Useful for things like raycasting from touches
convert screen coordinates to world space
#### Parameters
- **x** (number): x coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
- **y** (number): y coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
- **z** (number): z coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
#### Returns
- **number**: The point at screen position x, y projected z units into the screen in world space
- **number**:
- **number**:
### camera:screenToRay(x, y)
```lua
camera:screenToRay(x, y)
```
Takes a 2D point on the screen (in points) and returns a ray that starts at the camera and points through that point into the scene. Use it with raycasts to find what is under a touch
convert a screen point to a ray
#### Parameters
- **x** (number): x coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
- **y** (number): y coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
#### Returns
- **vec3**: The origin of the ray and its direction (normalized)
- **vec3**:
#### Example
```lua
function touched(touch)
local origin, dir = scene.main.camera:get(camera):screenToRay(touch.x, touch.y)
local hit = scene.main.world3d:raycast(origin, dir, 100)
end
```
### camera:worldToScreen(x, y, z)
```lua
camera:worldToScreen(x, y, z)
```
Takes a 3D point in world space and projects it onto screen coordinates (in points)
convert world coordinates to screen space
#### Parameters
- **x** (number): x coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
- **y** (number): y coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
- **z** (number): z coordinate of the point being converted; screen x/y are in points and world coordinates are in scene units.
#### Returns
- **number**: The point in world space (x, y, z) projected onto the screen
- **number**:
### camera.effectsEnabled
```lua
camera.effectsEnabled
```
Enable post-processing for this camera. Defaults to `true`. Set to
`false` for a reflection or other secondary draw, then restore it.
Settings and custom effects are retained while disabled. Effects are only
used when the camera renders a scene; `cam:apply()` alone applies matrices.
enable or bypass camera post-processing
### camera.bloom
```lua
camera.bloom
```
Read-only settings object; change its fields rather than replacing it.
Bloom spreads bright parts of the camera image into a glow. A strength of
zero skips the bloom passes. The camera renders into a floating-point image
before finishing, preserving brightness above white.
configure glow around bright parts of the image
### camera.tiltShift
```lua
camera.tiltShift
```
Read-only settings object; change its fields rather than replacing it.
Blur increases away from a sharp horizontal band. Coordinates for the band
are fractions of the camera image height, measured from the bottom.
A blur of zero skips tilt shift. This is an image-space effect, not a
depth-of-field simulation.
configure a sharp band with blur above and below it
### camera.saturation
```lua
camera.saturation
```
Color saturation, default 1. Use 0 for grayscale, values between 0 and 1
for muted color, and values above 1 for stronger color.
adjust camera color saturation
### camera.vignette
```lua
camera.vignette
```
Darkening toward the image edges, default 0 (off). Start with a small
positive value such as 0.2 and adjust for the image. Values are not clamped
by the setter.
darken the edges of the camera image
### camera.grain
```lua
camera.grain
```
Animated film-grain strength, default 0 (off). Small positive values such
as 0.02 add subtle noise. Values are not clamped by the setter.
add animated grain to the camera image
### camera:addEffect(source)
```lua
camera:addEffect(source)
```
Compile a fragment-shader body and append it to this camera’s custom
effect chain. Returns the shader, which can be used to set uniforms or
remove the effect later. Effects run in insertion order, after tilt shift,
bloom and color grading. Intermediate custom-effect images are RGBA8;
`scene` still provides the original floating-point camera image.
The supplied body has `uv` (texture coordinates), `FragColor` (output),
`source` (sampler2D containing the previous stage), `resolution`
(vec4: pixel width, pixel height, inverse width, inverse height), and
`time` (seconds) declared for it. Declare `uniform sampler2D scene;`
to sample the camera image before any effects. Write all four components
of `FragColor`, preserving alpha when compositing cameras.
If the source contains `#version`, it is treated as a complete fragment
shader: provide the declarations yourself. Effect passes disable depth
testing and depth writes and manage their own blend state.
append a custom full-screen fragment effect
#### Parameters
- **source** (string): GLSL fragment body, or a complete fragment shader with a version declaration.
#### Returns
- **shader**: The appended effect shader.
#### Example
```lua
local effect = cam:addEffect([[
uniform sampler2D scene;
void main() {
vec4 processed = texture(source, uv);
vec4 original = texture(scene, uv);
// Keep the center sharp while retaining effects at the edges.
float edge = smoothstep(0.15, 0.5, length(uv - vec2(0.5)));
FragColor = mix(original, processed, edge);
}
]])
```
### camera:addEffect(effect)
```lua
camera:addEffect(effect)
```
Append an existing shader and return it. It must render a full-screen
image using the effect vertex layout and declare a `source` sampler.
`resolution` and `scene` are supplied when declared. The shader
returned by the source-string overload can be reused with another camera.
Uniforms are shared when the same shader instance is reused.
append an existing camera effect shader
#### Parameters
- **effect** (shader): Full-screen effect shader.
#### Returns
- **shader**: The same shader instance.
### camera:removeEffect(effect)
```lua
camera:removeEffect(effect)
```
Remove every occurrence of this shader from this camera’s custom chain.
Does nothing if it is absent. Built-in effect settings are unchanged.
remove a custom camera effect
#### Parameters
- **effect** (shader): Shader previously returned by addEffect.
### camera:clearEffects()
```lua
camera:clearEffects()
```
Remove all custom shaders from this camera. Bloom, tilt shift, saturation,
vignette and grain settings are unchanged. Use `effectsEnabled = false`
to bypass both built-in and custom effects without discarding settings.
remove all custom camera effects
### camera.bloom.strength
```lua
camera.bloom.strength
```
Glow amount, default 0 (off). Positive values add bloom.
glow amount
### camera.bloom.threshold
```lua
camera.bloom.threshold
```
Brightness cutoff for bloom, default 0.9. Lower values include more of the image.
brightness cutoff for bloom
### camera.tiltShift.blur
```lua
camera.tiltShift.blur
```
Maximum blur radius in points, default 0 (off).
maximum blur radius in points
### camera.tiltShift.focus
```lua
camera.tiltShift.focus
```
Center of the sharp band as a fraction of image height from the bottom, default 0.5.
center of the sharp band as a fraction of image height from the bottom
### camera.tiltShift.range
```lua
camera.tiltShift.range
```
Half-height of the sharp band as a fraction of image height, default 0.12.
half-height of the sharp band as a fraction of image height
### camera.tiltShift.falloff
```lua
camera.tiltShift.falloff
```
Distance outside the sharp band over which blur reaches its maximum, default 0.4.
distance outside the sharp band over which blur reaches its maximum
## Lights
### Lighting a Scene
Add lights to show the shape and surface of 3D objects. Attach a light to an entity in a scene, or use `light.push()` and `light.pop()` when drawing meshes yourself.
**Using a light as a component in a scene**
```lua
function setup()
-- Create a basic scene with a single directional light source
scn = scene()
sun = scn:entity("sun")
sun.eulerRotation = vec3(45, 45, 0)
sunLight = sun:add(light.directional(vec3(0,-1,0)))
sunLight.castShadows = true
-- Add a model to represent the sun
sun:add(mesh.cone())
sun.material = material.unlit()
sun.material.color = color.yellow
sun.position = vec3(0,3,0)
inspector.add(sun)
cam = scn:entity("camera")
cam:add(camera.perspective(60))
cam:add(camera.rigs.orbit)
cam.z = -10
-- Some stuff to light
sphere = scn:entity("sphere")
sphere:add(mesh.sphere())
ground = scn:entity("ground")
ground:add(mesh.plane())
ground.y = -1
ground.uniformScale = 10
scene.main = scn
end
```
### light
```lua
light
```
create a new directional light
### light.directional(direction)
```lua
light.directional(direction)
```
Create a new directional light. Directional lights simulate a distant light source (like the sun) that casts parallel rays in a given direction and supports shadow mapping.
create a new directional light
#### Parameters
- **direction** (vec3, optional): The direction vector the light casts in world space, defaults to vec3(0, -1, 0)
#### Returns
- **light**: A new directional light
#### Example
```lua
sun = scn:entity("sun")
sunLight = sun:add(light.directional(vec3(0, -1, 0)))
sunLight.castShadows = true
```
### light.point(position)
```lua
light.point(position)
```
Create a new positional point light that radiates in all directions from a given position.
*Note: point lights are not currently supported by the renderer*
create a new point light
#### Parameters
- **position** (vec3, optional): The world-space position of the light source, defaults to the origin
#### Returns
- **light**: A new point light
### light.spot(position, direction)
```lua
light.spot(position, direction)
```
Create a new spot light that emits a cone of light from a position toward a direction.
*Note: spot lights are not currently supported by the renderer*
create a new spot light
#### Parameters
- **position** (vec3, optional): The world-space position of the light source, defaults to the origin
- **direction** (vec3, optional): The direction the cone points in world space, defaults to vec3(0, -1, 0)
#### Returns
- **light**: A new spot light
### light.push(light)
```lua
light.push(light)
```
Adds a light for meshes drawn after this call. Pair it with `light.pop()` when finished.
This applies basic lighting to 3D objects with lit materials for all subsequent draw calls until `light.pop()` is called. Immediate mode lighting does not support advanced features such as shadows — use scene-based lights for those.
push a light source onto the rendering stack
#### Parameters
- **light** (light): The light to push onto the rendering stack
#### Returns
- **light**: The same light for chaining
### light.pop()
```lua
light.pop()
```
Pops a light source from the rendering stack
pop a light source from the rendering stack
### light.clear()
```lua
light.clear()
```
Clears all lights from the rendering stack
clear all lights from the rendering stack
### light.type
```lua
light.type
```
Get/set the type of light. Possible values are:
- DIRECTIONAL
- POINT
- SPOT
- ENVIRONMENT
get or set the type of light
### light.intensity
```lua
light.intensity
```
The intensity of the light source
get or set the intensity of the light
### light.color
```lua
light.color
```
The color of the light source
get or set the light color
### light.castShadows
```lua
light.castShadows
```
Enables/disables shadow casting. Cascaded shadow mapping works for a single directional light source
*note: shadows currently only work with directional lights*
get or set whether the light casts shadows
### light.shadowOptions
```lua
light.shadowOptions
```
Get the shadow options for this light
*note: shadows currently only work with directional lights*
get the shadow options for this light
### light.shadowOptions
```lua
light.shadowOptions
```
get or set the number of shadow cascades
### light.shadowOptions.cascades
```lua
light.shadowOptions.cascades
```
The number of shadow cascades to used in rendering. The maximum number of cascades is 5
get or set the number of shadow cascades
### light.shadowOptions.size
```lua
light.shadowOptions.size
```
The size of the cascade textures to use when rendering. High values result in more detailed shadows at the cost of memory and rendering performance
get or set the shadow map size
### light.shadowOptions.constantBias
```lua
light.shadowOptions.constantBias
```
This attribute represents the constant bias applied to the depth values during shadow map comparisons. It helps in reducing self-shadowing artifacts by offsetting the comparison depth slightly. The default value is set to 0.001
get or set the constant shadow bias
### light.shadowOptions.normalBias
```lua
light.shadowOptions.normalBias
```
This attribute denotes the normal bias applied during shadow map comparisons. Normal bias helps in mitigating surface acne by adjusting the depth comparison based on surface normals. The default value is set to 0.1
get or set the normal shadow bias
### light.shadowOptions.far
```lua
light.shadowOptions.far
```
The far clipping plane distance for the shadow map rendering. It defines the maximum distance up to which shadows will be calculated. The default value is set to 0.0, implying no limit by default
get or set the far shadow distance
### light.shadowOptions.nearHint
```lua
light.shadowOptions.nearHint
```
A hint for the near clipping plane distance for shadow map rendering. It suggests the minimum distance from the camera to start shadow map calculations efficiently. The default value is set to 1
get or set the near shadow distance hint
### light.shadowOptions.farHint
```lua
light.shadowOptions.farHint
```
Similar to ‘nearHint’, this provides a hint for the far clipping plane distance for shadow map rendering. It suggests the maximum distance from the camera for efficient shadow map calculations. The default value is set to 100
get or set the far shadow distance hint
### light.shadowOptions.polygonOffsetConstant
```lua
light.shadowOptions.polygonOffsetConstant
```
This represents the constant factor used in polygon offset calculations. It adjusts the depth values of rendered polygons to resolve depth fighting issues. The default value is set to 0.5
get or set the polygon offset constant
### light.shadowOptions.polygonOffsetSlope
```lua
light.shadowOptions.polygonOffsetSlope
```
Denotes the slope factor used in polygon offset calculations. It works in conjunction with the constant factor to provide precise depth adjustments for polygons. The default value is set to 2.0
get or set the polygon offset slope