Entity functions

add_entity_to_liquid_collision

function add_entity_to_liquid_collision(uid: integer, add: boolean)

uid: integer
add: boolean

Attach liquid collision to entity by uid (this is what the push blocks use) Collision is based on the entity's hitbox, collision is removed when the entity is destroyed (bodies of killed entities will still have the collision) Use only for entities that can move around, (for static prefer update_liquid_collision_at ) If entity is in back layer and liquid in the front, there will be no collision created, also collision is not destroyed when entity changes layers, so you have to handle that yourself

apply_entity_db

function apply_entity_db(uid: integer)

uid: integer

Apply changes made in get_type() to entity instance by uid.

attach_ball_and_chain

function attach_ball_and_chain(uid: integer, off_x: number, off_y: number): integer

uid: integer
off_x: number
off_y: number

Returns integer

Spawns and attaches ball and chain to uid, the initial position of the ball is at the entity position plus off_x, off_y

attach_entity

function attach_entity(overlay_uid: integer, attachee_uid: integer)

overlay_uid: integer
attachee_uid: integer

Attaches attachee to overlay, similar to setting get_entity(attachee).overlay = get_entity(overlay). However this function offsets attachee (so you don't have to) and inserts it into overlay's inventory.

carry

function carry(mount_uid: integer, rider_uid: integer)

mount_uid: integer
rider_uid: integer

Make mount_uid carry rider_uid on their back. Only use this with actual mounts and living things.

drop

function drop(who_uid: integer, what_uid?: integer)

who_uid: integer
what_uid?: integeroptional

Drop held entity, what_uid optional, if set, it will check if entity is holding that entity first before dropping it

enter_door

function enter_door(player_uid: integer, door_uid: integer)

player_uid: integer
door_uid: integer

Calls the enter door function, position doesn't matter, can also enter closed doors (like COG, EW) without unlocking them

entity_get_items_by

function entity_get_items_by(uid: integer, entity_type: ENT_TYPE, mask: MASK): integer[]

uid: integer
entity_type: ENT_TYPE
mask: MASK

Returns integer[]

function entity_get_items_by(uid: integer, entity_types: ENT_TYPE[], mask: MASK): integer[]

uid: integer
entity_types: ENT_TYPE[]
mask: MASK

Returns integer[]

Gets uids of entities attached to given entity uid. Use entity_type and mask (MASK) to filter, set them to 0 to return all attached entities.

entity_has_item_type

function entity_has_item_type(uid: integer, entity_type: ENT_TYPE): boolean

uid: integer
entity_type: ENT_TYPE

Returns boolean

function entity_has_item_type(uid: integer, entity_types: ENT_TYPE[]): boolean

uid: integer
entity_types: ENT_TYPE[]

Returns boolean

Check if the entity uid has some ENT_TYPE entity_type in their inventory, can also use table of entity_types

entity_has_item_uid

function entity_has_item_uid(uid: integer, item_uid: integer): boolean

uid: integer
item_uid: integer

Returns boolean

Check if the entity uid has some specific item_uid by uid in their inventory

entity_remove_item

function entity_remove_item(uid: integer, item_uid: integer, check_autokill?: boolean)

uid: integer
item_uid: integer
check_autokill?: booleanoptional

Remove item by uid from entity. check_autokill defaults to true, checks if entity should be killed when missing overlay and kills it if so (can help with avoiding crashes)

filter_entities

function filter_entities(entities: integer[], predicate: fun(p1: any): boolean): integer[]

entities: integer[]
predicate: fun(p1: any): boolean: Returning nil (or nothing): treated as false.

Returns integer[]

Returns a list of all uids in entities for which predicate(get_entity(uid)) returns true

get_door_target

function get_door_target(uid: integer): integer, integer, integer

uid: integer

Returns integer, integer, integer

Get door target world, level, theme

get_entities_at

function get_entities_at(entity_type: ENT_TYPE, mask: MASK, x: number, y: number, layer: LAYER, radius: number): integer[]

entity_type: ENT_TYPE
mask: MASK
x: number
y: number
layer: LAYER
radius: number

Returns integer[]

function get_entities_at(entity_types: ENT_TYPE[], mask: MASK, x: number, y: number, layer: LAYER, radius: number): integer[]

entity_types: ENT_TYPE[]
mask: MASK
x: number
y: number
layer: LAYER
radius: number

Returns integer[]

Get uids of matching entities inside some radius (ENT_TYPE, MASK). Set entity_type or mask to 0 to ignore that, can also use table of entity_types Recommended to always set the mask, even if you look for one entity type

get_entities_by

-- find all cavemen and give them bombs
-- using a type and mask in get_entities_by speeds up the search, cause the api knows which bucket to search in
for i,uid in ipairs(get_entities_by(ENT_TYPE.MONS_CAVEMAN, MASK.MONSTER, LAYER.BOTH)) do
    local x, y, l = get_position(uid)
    spawn_entity_snapped_to_floor(ENT_TYPE.ITEM_BOMB, x, y, l)
end

function get_entities_by(entity_type: ENT_TYPE, mask: MASK, layer: LAYER): integer[]

entity_type: ENT_TYPE
mask: MASK
layer: LAYER

Returns integer[]

function get_entities_by(entity_types: ENT_TYPE[], mask: MASK, layer: LAYER): integer[]

entity_types: ENT_TYPE[]
mask: MASK
layer: LAYER

Returns integer[]

Get uids of entities by some conditions (ENT_TYPE, MASK). Set entity_type or mask to 0 to ignore that, can also use table of entity_types. Recommended to always set the mask, even if you look for one entity type

get_entities_by_draw_depth

function get_entities_by_draw_depth(draw_depth: integer, l: LAYER): integer[]

draw_depth: integer
l: LAYER

Returns integer[]

function get_entities_by_draw_depth(draw_depths: integer[], l: LAYER): integer[]

draw_depths: integer[]
l: LAYER

Returns integer[]

Get uids of entities by draw_depth. Can also use table of draw_depths. You can later use filter_entities if you want specific entity

get_entities_by_type

local types = {ENT_TYPE.MONS_SNAKE, ENT_TYPE.MONS_BAT}
set_callback(function()
    local uids = get_entities_by_type(ENT_TYPE.MONS_SNAKE, ENT_TYPE.MONS_BAT)
    -- is not the same thing as this, but also works
    local uids2 = get_entities_by_type(types)
    print(tostring(#uids).." == "..tostring(#uids2))
end, ON.LEVEL)

function get_entities_by_type(...: any): integer[]

...: any

Returns integer[]

Get uids of entities matching id. This function is variadic, meaning it accepts any number of id's. You can even pass a table! This function can be slower than the get_entities_by with the mask parameter filled

get_entities_overlapping_grid

function get_entities_overlapping_grid(x: number, y: number, layer: LAYER): integer[]

x: number
y: number
layer: LAYER

Returns integer[]

Get uids of static entities overlapping this grid position (decorations, backgrounds etc.)

get_entities_overlapping_hitbox

function get_entities_overlapping_hitbox(entity_type: ENT_TYPE, mask: MASK, hitbox: AABB, layer: LAYER): integer[]

entity_type: ENT_TYPE
mask: MASK
hitbox: AABB
layer: LAYER

Returns integer[]

function get_entities_overlapping_hitbox(entity_types: ENT_TYPE[], mask: MASK, hitbox: AABB, layer: LAYER): integer[]

entity_types: ENT_TYPE[]
mask: MASK
hitbox: AABB
layer: LAYER

Returns integer[]

Get uids of matching entities overlapping with the given hitbox. Set entity_type or mask to 0 to ignore that, can also use table of entity_types

get_entity

documented onlysource

function get_entity(uid: integer): Entity

uid: integer

Returns Entity

Get the Entity behind an uid, converted to the correct type. To see what type you will get, consult the entity hierarchy list

get_entity_name

function get_entity_name(type: ENT_TYPE, fallback_strategy?: boolean): string

type: ENT_TYPE
fallback_strategy?: booleanoptional

Returns string

Get localized name of an entity from the journal, pass fallback_strategy as true to fall back to the ENT_TYPE.* enum name if the entity has no localized name

get_entity_type

function get_entity_type(uid: integer): ENT_TYPE

uid: integer

Returns ENT_TYPE

Get the ENT_TYPE... of the entity by uid

get_grid_entity_at

function get_grid_entity_at(x: number, y: number, layer: LAYER): integer

x: number
y: number
layer: LAYER

Returns integer

Gets a grid entity, such as floor or spikes, at the given position and layer.

get_local_players

function get_local_players(): Player[]

Returns Player[]

Get the thread-local version of players

get_player

documented onlysource

function get_player(slot: integer, or_ghost: boolean?): Player|PlayerGhost

slot: integer
or_ghost: boolean?

Returns Player|PlayerGhost

Returns Player (or PlayerGhost if get_player(1, true)) with this player slot

get_playerghost

function get_playerghost(slot: integer): PlayerGhost?

slot: integer

Returns PlayerGhost? (may be nil)

Returns PlayerGhost with this player slot 1..4

get_type

function get_type(id: ENT_TYPE): EntityDB?

id: ENT_TYPE

Returns EntityDB? (may be nil)

Get the EntityDB behind an ENT_TYPE...

kill_entity

function kill_entity(uid: integer, destroy_corpse?: boolean)

uid: integer
destroy_corpse?: booleanoptional

Kills an entity by uid. destroy_corpse defaults to true, if you are killing for example a caveman and want the corpse to stay make sure to pass false.

move_entity

function move_entity(uid: integer, x: number, y: number, vx: number, vy: number)

uid: integer
x: number
y: number
vx: number
vy: number

function move_entity(uid: integer, x: number, y: number, vx: number, vy: number, layer: LAYER)

uid: integer
x: number
y: number
vx: number
vy: number
layer: LAYER

Teleport entity to coordinates with optional velocity

move_grid_entity

function move_grid_entity(uid: integer, x: number, y: number, layer: LAYER)

uid: integer
x: number
y: number
layer: LAYER

Teleport grid entity, the destination should be whole number, this ensures that the collisions will work properly

pick_up

-- spawn and equip a jetpack on the player
pick_up(players[1].uid, spawn(ENT_TYPE.ITEM_JETPACK, 0, 0, LAYER.PLAYER, 0, 0))

function pick_up(who_uid: integer, what_uid: integer)

who_uid: integer
what_uid: integer

Pick up another entity by uid. Make sure you're not already holding something, or weird stuff will happen.

poison_entity

function poison_entity(entity_uid: integer)

entity_uid: integer

Poisons entity, to cure poison set Movable.poison_tick_timer to -1

set_contents

function set_contents(uid: integer, item_entity_type: ENT_TYPE)

uid: integer
item_entity_type: ENT_TYPE

Set the contents of Coffin, Present, Pot, Container Check the entity hierarchy list for what the exact ENT_TYPE's can this function affect

set_door

function set_door(uid: integer, w: integer, l: integer, t: integer)

uid: integer
w: integer
l: integer
t: integer

Short for set_door_target.

set_door_target

function set_door_target(uid: integer, w: integer, l: integer, t: integer)

uid: integer
w: integer
l: integer
t: integer

Make an ENT_TYPE.FLOOR_DOOR_EXIT go to world w, level l, theme t

unequip_backitem

function unequip_backitem(who_uid: integer)

who_uid: integer

Unequips the currently worn backitem

waddler_count_entity

function waddler_count_entity(entity_type: ENT_TYPE): integer

entity_type: ENT_TYPE

Returns integer

Returns how many of a specific entity type Waddler has stored

waddler_entity_type_in_slot

function waddler_entity_type_in_slot(slot: integer): integer

slot: integer

Returns integer

Gets the entity type of the item in the provided slot

waddler_get_entity_meta

function waddler_get_entity_meta(slot: integer): integer

slot: integer

Returns integer

Gets the 16-bit meta-value associated with the entity type in the associated slot

waddler_remove_entity

function waddler_remove_entity(entity_type: ENT_TYPE, amount_to_remove: integer)

entity_type: ENT_TYPE
amount_to_remove: integer

Removes an entity type from Waddler's storage. Second param determines how many of the item to remove (default = remove all)

waddler_set_entity_meta

function waddler_set_entity_meta(slot: integer, meta: integer)

slot: integer
meta: integer

Sets the 16-bit meta-value associated with the entity type in the associated slot

waddler_store_entity

function waddler_store_entity(entity_type: ENT_TYPE): integer

entity_type: ENT_TYPE

Returns integer

Store an entity type in Waddler's storage. Returns the slot number the item was stored in or -1 when storage is full and the item couldn't be stored.

worn_backitem

function worn_backitem(who_uid: integer): integer

who_uid: integer

Returns integer

Returns the uid of the currently worn backitem, or -1 if wearing nothing