Entity handles

Look up Entity calls and properties. Here entity stands for a live Entity handle, such as enemy.

`entity.get(id)`

Find a live Entity by ID.

Arguments: id: numeric runtime Entity ID.
Returns: Entity handle, or nil if missing.
Works with: Live runtime Entities.
Missing values and errors: Wrong argument counts or types report an error. Actor IDs are not Entity IDs.

const object = entity.get(12345)
if object != nil {
    debug.log(object.id)
}

`entity.exists(id)`

Check whether a runtime Entity exists.

Arguments: id: numeric object ID.
Returns: true if it exists; otherwise false.
Works with: Live runtime Entities.
Missing values and errors: Wrong argument counts or types report an error.

debug.log(entity.exists(12345))

`entity.is_valid()`

Check whether the object still exists.

Arguments: No arguments.
Returns: bool. False if removed.
Works with: Entity handles.
Missing values and errors: A removed object returns false. Wrong argument counts or types report an error.

const object = get_entity("Goblin")
if object != nil {
    debug.log(object.is_valid())
}

`entity.name()`

Read the object name.

Arguments: No arguments.
Returns: string.
Works with: Entity handles.
Missing values and errors: Use a valid handle. Wrong argument counts or types report an error.

const object = get_entity("Goblin")
if object != nil {
    debug.log(object.name())
}

`entity.set_position(x, y, z)`

Set the object position.

Arguments: Three numbers: x, y, z.
Returns: nil.
Works with: Entity handles.
Missing values and errors: Use a valid handle. Wrong argument counts or types report an error.

const object = get_entity("Goblin")
if object != nil {
    object.set_position(0, 2, 0)
}

`entity.translate(x, y, z)`

Move the object by an offset.

Arguments: Three numbers: x, y, z.
Returns: nil.
Works with: Entity handles.
Missing values and errors: Use a valid handle. Wrong argument counts or types report an error.

const object = get_entity("Goblin")
if object != nil {
    object.translate(1, 0, 0)
}

`entity.destroy()`

Destroy the live object.

Arguments: No arguments.
Returns: true.
Works with: Entity handles.
Missing values and errors: Use a valid handle. Wrong argument counts or types report an error.

const object = get_entity("Goblin")
if object != nil {
    object.destroy()
}

`entity.id`

Read the runtime Entity ID.

Arguments: No call arguments. Read this property.
Returns: number. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.id)
}

`entity.name`

Read the Entity name.

Arguments: No call arguments. Read this property.
Returns: string. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.name)
}

`entity.position`

Read or change Entity position.

Arguments: No call arguments. Assign [x, y, z] numbers to change it.
Returns: [x, y, z] numbers. Readable and writable.
Works with: entity handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.position)
}

`entity.velocity`

Read or change Entity velocity.

Arguments: No call arguments. Assign [x, y, z] numbers to change it.
Returns: [x, y, z] numbers. Readable and writable.
Works with: entity handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.velocity)
}

`entity.facing`

Read or change Entity facing.

Arguments: No call arguments. Assign [x, z] numbers to change it.
Returns: [x, z] numbers. Readable and writable.
Works with: entity handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.facing)
}

`entity.grounded`

Read whether the Entity is on the ground.

Arguments: No call arguments. Read this property.
Returns: bool. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.grounded)
}

`entity.animation_name`

Read or select the base animation name.

Arguments: No call arguments. Assign string to change it.
Returns: string. Readable and writable.
Works with: entity handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.animation_name)
}

`entity.health`

Read or set current health.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: entity handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.health)
}

`entity.max_health`

Read or set maximum health.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: entity handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.max_health)
}

`entity.alive`

Read whether the Character is alive.

Arguments: No call arguments. Read this property.
Returns: bool. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.alive)
}

`entity.is_actor`

Read whether this Entity backs an Actor.

Arguments: No call arguments. Read this property.
Returns: bool. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.is_actor)
}

`entity.actor_id`

Read the authored Actor ID, if present.

Arguments: No call arguments. Read this property.
Returns: number or nil. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.actor_id)
}

`entity.package`

Read the Character package, if present.

Arguments: No call arguments. Read this property.
Returns: string or nil. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.package)
}

`entity.attributes`

Read the Entity attribute view.

Arguments: No call arguments. Read this property.
Returns: map. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.attributes)
}

`entity.sound`

Get the Entity sound capability where supported.

Arguments: No call arguments. Read this property.
Returns: Sound handle. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.sound)
}

`entity.physics`

Get the Entity physics controls.

Arguments: No call arguments. Read this property.
Returns: EntityPhysics handle. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.physics)
}

`entity.animation`

Get the Entity animation controls.

Arguments: No call arguments. Read this property.
Returns: EntityAnimation handle. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.animation)
}

`entity.appearance`

Get the Entity appearance capability.

Arguments: No call arguments. Read this property.
Returns: EntityAppearance handle. Read-only.
Works with: entity handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

Appearance-specific controls are not implemented. This handle supports entity, kind, and is_valid().

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.appearance)
}

`entity.jump([impulse])`

Make a Character jump.

Arguments: Optional numeric impulse, default 5.0.
Returns: nil.
Works with: Live Character Entities.
Missing values and errors: Requires an available Character system and a runtime Character. Use a valid handle. Wrong argument counts or types report an error.

const enemy = get_entity("Goblin")
if enemy != nil {
    enemy.jump()
}

`entity.damage(amount)`

Reduce Character health.

Arguments: amount: number.
Returns: The resulting health number.
Works with: Live Character Entities.
Missing values and errors: Requires a runtime Character. Use a valid handle. Wrong argument counts or types report an error.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.damage(10))
}

`entity.heal(amount)`

Restore Character health.

Arguments: amount: number.
Returns: The resulting health number.
Works with: Live Character Entities.
Missing values and errors: Requires a runtime Character. Use a valid handle. Wrong argument counts or types report an error.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.heal(5))
}

`entity.find_path(position)`

Request a path through the World.

Arguments: position: [x, y, z] numbers.
Returns: A basket of three-number waypoints, or nil when no path is found.
Works with: Live Character Entities.
Missing values and errors: Requires a runtime Character. This call does not make it follow the returned route. Use a valid handle. Wrong argument counts or types report an error.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.find_path([20, 1, 20]))
}

`entity.animation.play_layer(slot, clip, joint_root)`

Play an animation over part of a rig.

Arguments: Three strings: layer slot, clip name, and root joint.
Returns: true on success.
Works with: EntityAnimation handles on runtime Characters.
Missing values and errors: Missing Character support, clips, or joints report an error.

const hero = get_entity("Player")
if hero != nil {
    hero.animation.play_layer("Action", "Slash", "Spine")
}

`entity.animation.entity`

Read the owning Entity.

Arguments: No call arguments. Read this property.
Returns: Entity handle. Read-only.
Works with: entity.animation handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const object = get_entity("Player")
if object != nil {
    debug.log(object.animation.entity)
}

`entity.animation.kind`

Read the capability kind.

Arguments: No call arguments. Read this property.
Returns: string. Read-only.
Works with: entity.animation handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const object = get_entity("Player")
if object != nil {
    debug.log(object.animation.kind)
}

`entity.appearance.entity`

Read the owning Entity.

Arguments: No call arguments. Read this property.
Returns: Entity handle. Read-only.
Works with: entity.appearance handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const object = get_entity("Player")
if object != nil {
    debug.log(object.appearance.entity)
}

`entity.appearance.kind`

Read the capability kind.

Arguments: No call arguments. Read this property.
Returns: string. Read-only.
Works with: entity.appearance handles.
Missing values and errors: Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const object = get_entity("Player")
if object != nil {
    debug.log(object.appearance.kind)
}

`entity.animation.is_valid()`

Check whether the owning Entity still exists.

Arguments: No arguments.
Returns: bool.
Works with: The corresponding Entity capability handle.
Missing values and errors: Wrong argument counts or types report an error.

const object = get_entity("Player")
if object != nil {
    debug.log(object.animation.is_valid())
}

`entity.appearance.is_valid()`

Check whether the owning Entity still exists.

Arguments: No arguments.
Returns: bool.
Works with: The corresponding Entity capability handle.
Missing values and errors: Wrong argument counts or types report an error.

const object = get_entity("Player")
if object != nil {
    debug.log(object.appearance.is_valid())
}

[BETA] marks features newer than the current public release. Current release: 0.8.0.