Caffeine

World

Reference Core Last updated: Lua 17 · Dryad 13

Create and destroy entities, move them, and read or write transforms, 2D physics, sprites and particle emitters. Dryad adds position and scale natives.

All namespaces

Namespace: caffeine.world · Dryad prefix: caffeine_world_

create#

Lua: caffeine.world.create · Dryad: caffeine_world_create

text
create() -> integer

Creates an entity named "LuaEntity".

Returns: integer. The new entity id, or 0 when there is no world.

Example

lua
local e = caffeine.world.create()

destroy#

Lua: caffeine.world.destroy · Dryad: caffeine_world_destroy

text
destroy(entity)

Destroys an entity. Does nothing when there is no world.

ParametersTypeDescription
entityintegerEntity id.

Returns: none

Example

lua
caffeine.world.destroy(e)

hasComponent#

Lua: caffeine.world.hasComponent

text
hasComponent(entity, type) -> boolean

Checks one of four built-in component types. "Transform" is also true for a Position3D. For other components use caffeine.component.has.

ParametersTypeDescription
entityintegerEntity id.
typestringOne of "Transform", "Sprite", "RigidBody2D", "Collider2D".

Returns: boolean. True when the entity has it; false for any other type name.

Example

lua
if caffeine.world.hasComponent(e, 'Sprite') then end

getTransform#

Lua: caffeine.world.getTransform

text
getTransform(entity) -> table

Reads the position of the entity (from Position3D or Transform); rotation and scale come from Transform.

ParametersTypeDescription
entityintegerEntity id.

Returns: table. {x, y, z, rotation, scaleX, scaleY}; defaults 0 and scale 1.

Example

lua
local t = caffeine.world.getTransform(e)
caffeine.debug.log(t.x .. ', ' .. t.y)

setTransform#

Lua: caffeine.world.setTransform

text
setTransform(entity, t)

Writes position (and rotation/scale on a Transform). Creates a Transform when the entity has neither Transform nor Position3D.

ParametersTypeDescription
entityintegerEntity id.
ttableFields x, y, z, rotation, scaleX, scaleY; missing fields keep the current value.

Returns: none

Example

lua
caffeine.world.setTransform(e, { x = 1, y = 2 })

addTransform#

Lua: caffeine.world.addTransform

text
addTransform(entity, t)

Alias of caffeine.world.setTransform.

ParametersTypeDescription
entityintegerEntity id.
ttableSame fields as setTransform.

Returns: none

Example

lua
caffeine.world.addTransform(e, { x = 0, y = 0 })

distanceTo#

Lua: caffeine.world.distanceTo · Dryad: caffeine_world_distance

text
distanceTo(a, b) -> number

Straight-line distance between two entities.

ParametersTypeDescription
aintegerFirst entity id.
bintegerSecond entity id.

Returns: number. Distance in world units; 1e9 when either entity has no position or there is no world.

Example

lua
local d = caffeine.world.distanceTo(e, target)

findNearest#

Lua: caffeine.world.findNearest

text
findNearest(from, maxDist) -> integer

Finds the closest other entity that has a Position3D or Transform within maxDist.

ParametersTypeDescription
fromintegerEntity to search around.
maxDistnumberSearch radius; must be greater than 0.

Returns: integer. Id of the nearest other entity with a position, or 0.

Example

lua
local near = caffeine.world.findNearest(e, 10)

setYawPitch#

Lua: caffeine.world.setYawPitch

text
setYawPitch(entity, yaw, pitch)

Sets a 3D rotation (Rotation3D quaternion, roll 0). When the entity has a Transform its rotation x/y are also written in degrees.

ParametersTypeDescription
entityintegerEntity id.
yawnumberYaw in radians.
pitchnumberPitch in radians.

Returns: none

Example

lua
caffeine.world.setYawPitch(e, caffeine.math.radians(90), 0)

getRigidBody2D#

Lua: caffeine.world.getRigidBody2D

text
getRigidBody2D(entity) -> table

Reads the 2D rigid body of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: table. {mass, restitution, friction, linearDamping, isKinematic, lockRotation, velocityX, velocityY}; empty when there is no RigidBody2D.

Example

lua
local rb = caffeine.world.getRigidBody2D(e)

setRigidBody2D#

Lua: caffeine.world.setRigidBody2D

text
setRigidBody2D(entity, t)

Adds a RigidBody2D when missing and writes it. Fields you omit are reset to the defaults listed, except velocityX/velocityY, which keep their value.

ParametersTypeDescription
entityintegerEntity id.
ttableFields mass (1), restitution (0.3), friction (0.5), linearDamping (0), isKinematic (false), lockRotation (true), velocityX, velocityY.

Returns: none

Example

lua
caffeine.world.setRigidBody2D(e, { mass = 2, friction = 0.8 })

getVelocity#

Lua: caffeine.world.getVelocity

text
getVelocity(entity) -> table

Reads the 2D velocity of the rigid body.

ParametersTypeDescription
entityintegerEntity id.

Returns: table. {x, y}; 0 when there is no RigidBody2D.

Example

lua
local v = caffeine.world.getVelocity(e)

setVelocity#

Lua: caffeine.world.setVelocity

text
setVelocity(entity, v)

Sets the 2D velocity (adds a RigidBody2D when missing) and wakes the body.

ParametersTypeDescription
entityintegerEntity id.
vtable{x, y}; missing fields keep the current value.

Returns: none

Example

lua
caffeine.world.setVelocity(e, { x = 5, y = 0 })

getSprite#

Lua: caffeine.world.getSprite

text
getSprite(entity) -> table

Reads the sprite name and frame index.

ParametersTypeDescription
entityintegerEntity id.

Returns: table. {name, frameIndex}; empty when there is no Sprite.

Example

lua
local s = caffeine.world.getSprite(e)

setSprite#

Lua: caffeine.world.setSprite

text
setSprite(entity, t)

Adds a Sprite when missing and writes name and frame index.

ParametersTypeDescription
entityintegerEntity id.
ttableFields name (string, default "") and frameIndex (default 0).

Returns: none

Example

lua
caffeine.world.setSprite(e, { name = 'hero', frameIndex = 2 })

addSprite#

Lua: caffeine.world.addSprite

text
addSprite(entity, t)

Alias of caffeine.world.setSprite.

ParametersTypeDescription
entityintegerEntity id.
ttableSame fields as setSprite.

Returns: none

Example

lua
caffeine.world.addSprite(e, { name = 'hero' })

addParticleEmitter#

Lua: caffeine.world.addParticleEmitter

text
addParticleEmitter(entity, t)

Adds a particle emitter component to the entity (and a Transform when missing).

ParametersTypeDescription
entityintegerEntity id.
ttableFields maxParticles (100), emissionRate (10), lifetime (2), startSize (1), endSize (0), startColor and endColor ({r,g,b,a} in 0..1).

Returns: none

Example

lua
caffeine.world.addParticleEmitter(e, { emissionRate = 30, lifetime = 1.5 })

caffeine_world_is_alive#

Lua: not available · Dryad: caffeine_world_is_alive

text
caffeine_world_is_alive(entity) -> boolean

Dryad only: checks that an entity id still refers to a live entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: boolean. True when the entity exists.

Example

dryad
function onUpdate(entity, dt) {
  if (caffeine_world_is_alive(entity)) { caffeine_translate(entity, 0, dt, 0); }
}

caffeine_set_position#

Lua: not available · Dryad: caffeine_set_position

text
caffeine_set_position(entity, x, y, z)

Dryad only: sets the position of an entity (Position3D and/or Transform; a Transform is created when it has neither).

ParametersTypeDescription
entityintegerEntity id.
xnumberX.
ynumberY.
znumberZ.

Returns: none

Example

dryad
caffeine_set_position(entity, 0, 1, 0);

caffeine_translate#

Lua: not available · Dryad: caffeine_translate

text
caffeine_translate(entity, dx, dy, dz)

Dryad only: moves an entity by an offset.

ParametersTypeDescription
entityintegerEntity id.
dxnumberOffset on X.
dynumberOffset on Y.
dznumberOffset on Z.

Returns: none

Example

dryad
caffeine_translate(entity, 1 * dt, 0, 0);

caffeine_get_position_x#

Lua: not available · Dryad: caffeine_get_position_x

text
caffeine_get_position_x(entity) -> number

Dryad only: reads the X position of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: number. Position on X; 0 when the entity has none.

Example

dryad
let p = caffeine_get_position_x(entity);

caffeine_get_position_y#

Lua: not available · Dryad: caffeine_get_position_y

text
caffeine_get_position_y(entity) -> number

Dryad only: reads the Y position of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: number. Position on Y; 0 when the entity has none.

Example

dryad
let p = caffeine_get_position_y(entity);

caffeine_get_position_z#

Lua: not available · Dryad: caffeine_get_position_z

text
caffeine_get_position_z(entity) -> number

Dryad only: reads the Z position of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: number. Position on Z; 0 when the entity has none.

Example

dryad
let p = caffeine_get_position_z(entity);

caffeine_set_scale#

Lua: not available · Dryad: caffeine_set_scale

text
caffeine_set_scale(entity, x, y, z)

Dryad only: sets the scale of an entity (Scale3D or Transform).

ParametersTypeDescription
entityintegerEntity id.
xnumberScale on X.
ynumberScale on Y.
znumberScale on Z.

Returns: none

Example

dryad
caffeine_set_scale(entity, 2, 2, 2);

caffeine_get_scale_x#

Lua: not available · Dryad: caffeine_get_scale_x

text
caffeine_get_scale_x(entity) -> number

Dryad only: reads the X scale of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: number. Scale on X; 1 when the entity has none.

Example

dryad
let s = caffeine_get_scale_x(entity);

caffeine_get_scale_y#

Lua: not available · Dryad: caffeine_get_scale_y

text
caffeine_get_scale_y(entity) -> number

Dryad only: reads the Y scale of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: number. Scale on Y; 1 when the entity has none.

Example

dryad
let s = caffeine_get_scale_y(entity);

caffeine_get_scale_z#

Lua: not available · Dryad: caffeine_get_scale_z

text
caffeine_get_scale_z(entity) -> number

Dryad only: reads the Z scale of an entity.

ParametersTypeDescription
entityintegerEntity id.

Returns: number. Scale on Z; 1 when the entity has none.

Example

dryad
let s = caffeine_get_scale_z(entity);