$entity

Find, create and destroy entities; walk the hierarchy; read names and transforms.

47 natives. Read-only natives only look things up; the rest change something. Parameter types use the language's names (Types).

are_children_pending

read-only

$entity.are_children_pending(entity: Entity) -> bool

Get whether any entity ancestor is not ready (either pending created or destroyed).

Parameter	Type	Meaning
entity	Entity	The entity whose children will be checked.

Returns bool: True if any children are not yet ready.

calculate_local_transform

read-only

$entity.calculate_local_transform(parent_scale: vec3, parent_rotation: vec4, parent_position: vec3, world_scale: vec3, world_rotation: vec4, world_position: vec3, mask: int) -> list

Calculate a local transform given a parent and child's world transform.

Parameter	Type	Meaning
parent_scale	vec3	Parent scale.
parent_rotation	vec4	Parent rotation.
parent_position	vec3	Parent position.
world_scale	vec3	World scale.
world_rotation	vec4	World rotation.
world_position	vec3	World position.
mask	int	Mask of ventity_transform_mask_t describing components of transform to not inherit.

Returns list: Resulting scale, rotation, and transform.

compare_entity_guid

read-only

$entity.compare_entity_guid(entity_l: Entity, entity_r: Entity) -> int

Return whether the first or second given entity is "less than" the other

Parameter	Type	Meaning
entity_l	Entity	The first entity.
entity_r	Entity	The second entity.

Returns int: -1 if first entity is less than, 1 if the second entity is less than, 0 only if they are the same entity or both null.

destroy

$entity.destroy(entity: Entity, spare_children: bool, immediate: bool)

Destroy an entity, and optionally destroy its descendants.

Parameter	Type	Meaning
entity	Entity	The entity.
spare_children	bool	Skip recursive destroy and only destroy this ent?
immediate	bool	If true, the entity is destroyed at the end of the event. Otherwise destroy waits to the next frame.

destroy_level

$entity.destroy_level(level: Reference, spare_children: bool, immediate: bool, only_ready: bool)

Destroy all entities from the given level, and optionally destroy those entities' descendants. Note that this function is forceful; all of these entities are destroyed regardless of owning package.

Parameter	Type	Meaning
level	Reference	Reference to level file.
spare_children	bool	Suppress recursive destroy of entities parented to this level
immediate	bool	If true, the level is destroyed at the end of the event. Otherwise destroy waits to the next frame.
only_ready	bool	If true, only spawned and ready entities will be considered.

get

read-only

$entity.get() -> Entity

Get the owning entity for the current component script.

Returns Entity: The owning entity.

get_all_children_named

read-only

$entity.get_all_children_named(name: string, parent: Entity, should_recurse: bool, prefix: bool) -> list

Get a list of child entities of a specified name from an entity.

Parameter	Type	Meaning
name	string	The entity's name to look for.
parent	Entity	(Optional) Parent entity. Omit to use the calling entity.
should_recurse	bool	Indicates to search children recursively or not.
prefix	bool	True to match any name starting with the provided value, False to match the exact name only.

Returns list: The list of children with the specified name.

get_all_components

read-only

$entity.get_all_components(entity: Entity, script_name: string, name: string, var_name: string, var_value: var) -> list

Get all components of a specified type on a specified entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
script_name	string	The script name.
name	string	(Optional) When specified, only objects with this name will be returned. Omit to return all results. Warns on NULL.
var_name	string	(Optional) Filters results to only values with the specified field. Omit to return all results. Warns on NULL.
var_value	var	(Optional, required if 'var' specified) Filters results to only values where the 'var' field has the specified value. Omit to return all results.

Returns list: List of components.

get_all_components_in_children

read-only

$entity.get_all_components_in_children(entity: Entity, script_name: string, name: string, var_name: string, var_value: var) -> list

Retrieves a list of all components of a given type in a hierarchy, excluding parent entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
script_name	string	The script name.
name	string	(Optional) When specified, only objects with this name will be returned. Omit to return all results. Warns on NULL.
var_name	string	(Optional) Filters results to only values with the specified field. Omit to return all results. Warns on NULL.
var_value	var	(Optional, required if 'var' specified) Filters results to only values where the 'var' field has the specified value. Omit to return all results.

Returns list: The components found in children.

get_all_components_in_children_and_parent

read-only

$entity.get_all_components_in_children_and_parent(entity: Entity, script_name: string, name: string) -> list

Retrieves a list of all components of a given type in a hierarchy, including parent entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
script_name	string	The script name.
name	string	(Optional) When specified, only objects with this name will be returned. Omit to return all results. Warns on NULL.

Returns list: The components found in children.

get_all_components_untyped

read-only

$entity.get_all_components_untyped(entity: Entity, should_recurse: bool) -> list

Get all components on a specified entity without regard to type. Prefer entity.get_all_components<...> if possible.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
should_recurse	bool	Indicates to search children recursively or not.

Returns list: List of components.

get_child_named

read-only

$entity.get_child_named(name: string, should_recurse: bool, parent: Entity) -> Entity

Get a child entity by its name from an entity.

Parameter	Type	Meaning
name	string	The entity's name to look for.
should_recurse	bool	Indicates to search children recursively or not.
parent	Entity	Parent entity. If null, calling entity is used.

Returns Entity: The named child entity.

get_children

read-only

$entity.get_children(entity: Entity) -> list

Get the children of an entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.

Returns list: List of child entities.

get_first_component

read-only

$entity.get_first_component(entity: Entity, script_name: string, name: string, var_name: string, var_value: var) -> Component

Get the first component of a specified type.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
script_name	string	The script name.
name	string	(Optional) When specified, only objects with this name will be returned. Omit to return all results. Warns on NULL.
var_name	string	(Optional) Filters results to only values with the specified field. Omit to return all results. Warns on NULL.
var_value	var	(Optional, required if 'var' specified) Filters results to only values where the 'var' field has the specified value. Omit to return all results.

Returns Component: The found component, or null.

get_first_component_in_children

read-only

$entity.get_first_component_in_children(entity: Entity, script_name: string, name: string, var_name: string, var_value: var, no_recurse: bool) -> Component

Retrieve the first component of a given type in a hierarchy, excluding parent entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
script_name	string	The script name.
name	string	(Optional) When specified, only objects with this name will be returned. Omit to return all results. Warns on NULL.
var_name	string	(Optional) Filters results to only values with the specified field. Omit to return all results. Warns on NULL.
var_value	var	(Optional, required if 'var' specified) Filters results to only values where the 'var' field has the specified value. Omit to return all results.
no_recurse	bool	Set true to prevent searching granchildren etc.

Returns Component: The component or null if not found.

get_first_component_in_children_and_parent

read-only

$entity.get_first_component_in_children_and_parent(entity: Entity, script_name: string, name: string) -> Component

Retrieve the first component of a given type in a hierarchy, including parent entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
script_name	string	The script name.
name	string	(Optional) When specified, only objects with this name will be returned. Omit to return all results. Warns on NULL.

Returns Component: The component or null if not found.

get_flag_status

read-only

$entity.get_flag_status(flag: int, entity: Entity) -> bool

Get whether a flag is set on an entity.

Parameter	Type	Meaning
flag	int	The entity flag to check the status of e.g. k_game_entity_flag_net_priority_high
entity	Entity	The entity to read flags from. If null, we'll read the flags from the caller's entity.

Returns bool: True if the flag passed in is set

get_forward

read-only

$entity.get_forward(transform: Component) -> vec3

Get the world-space forward vector from the given transform component, or, if not provided, the calling entity's transform component.

Parameter	Type	Meaning
transform	Component	Optional transform component

Returns vec3: World-space forward

get_hierarchy_components_of_type

read-only

$entity.get_hierarchy_components_of_type(script_name: string, ent_to_check: Entity, search_parent_count: int) -> list

Retrieve a list of all component of the specified type from the specified entity's tree, starting from a child and progressing up through the specified number of parents.

Parameter	Type	Meaning
script_name	string	The script name.
ent_to_check	Entity	The child entity to check.
search_parent_count	int	The number of the child's parents to check. If negative search the entire hierarchy tree.

Returns list: The list of found components. If none are found, and empty list is returned.

get_hierarchy_entity_named

read-only

$entity.get_hierarchy_entity_named(name: string, entity: Entity) -> Entity

Retrieve an entity of the specified name within the specified entity's hierarchy

Parameter	Type	Meaning
name	string	The name of the entity to look for.
entity	Entity	(Optional) The entity whose hierarchy should be searched. If this field isn't specified, the entity is derived from the calling component.

Returns Entity: The found entity; otherwise null.

get_hierarchy_singleton

read-only

$entity.get_hierarchy_singleton(script_name: string, ent_to_check: Entity) -> Component

Retrieve a component of which there is assumed to be only one instance from an entity tree, starting from a child and progressing up through its parents.

Parameter	Type	Meaning
script_name	string	The script name.
ent_to_check	Entity	The child entity to check. If null, the caller's entity will be used.

Returns Component: The component or null if not found.

get_name

read-only

$entity.get_name(entity: Entity) -> string

Get the name of an entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.

Returns string: Name of the entity, or NULL if it's not named.

get_owning_package

read-only

$entity.get_owning_package(entity: Entity) -> Reference

Return the owning package of a given entity. An entity is destroyed when its owning package is unloaded or despawned. The owning package is the package whose net channel the entity is associated with.

Parameter	Type	Meaning
entity	Entity	The entity.

Returns Reference: The package.

get_owning_user

read-only

$entity.get_owning_user() -> User

Get the owning user of the calling component.

Returns User: The owning user or zero.

get_owning_user_from_component

read-only

$entity.get_owning_user_from_component(component: Component) -> User

Get the owning user of the specified component.

Parameter	Type	Meaning
component	Component	The component.

Returns User: The owning user or zero.

get_owning_user_from_entity

read-only

$entity.get_owning_user_from_entity(entity: Entity) -> User

Get the owning user of the specified entity.

Parameter	Type	Meaning
entity	Entity	The entity.

Returns User: The owning user or zero.

get_parent

read-only

$entity.get_parent(entity: Entity) -> Entity

Get the parent of an entity.

Parameter	Type	Meaning
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.

Returns Entity: The parent entity.

get_right

read-only

$entity.get_right(transform: Component) -> vec3

Get the world-space right vector from the given transform component, or, if not provided, the calling entity's transform component.

Parameter	Type	Meaning
transform	Component	Optional transform component

Returns vec3: World-space right

get_up

read-only

$entity.get_up(transform: Component) -> vec3

Get the world-space up vector from the given transform component, or, if not provided, the calling entity's transform component.

Parameter	Type	Meaning
transform	Component	Optional transform component

Returns vec3: World-space up

get_world_position

read-only

$entity.get_world_position(transform: Component) -> vec3

Get the world-space position from the given transform component, or, if not provided, the calling entity's transform component.

Parameter	Type	Meaning
transform	Component	Optional transform component

Returns vec3: World-space position

get_world_rotation

read-only

$entity.get_world_rotation(transform: Component) -> vec4

Get the world-space rotation from the given transform component, or, if not provided, the calling entity's transform component.

Parameter	Type	Meaning
transform	Component	Optional transform component

Returns vec4: World-space rotation

get_world_scale

read-only

$entity.get_world_scale(transform: Component) -> vec3

Get the world-space scale from the given transform component, or, if not provided, the calling entity's transform component.

Parameter	Type	Meaning
transform	Component	Optional transform component

Returns vec3: World-space scale

inherit_transform

$entity.inherit_transform(parent_scale: vec3, parent_rotation: vec4, parent_position: vec3, local_scale: vec3, local_rotation: vec4, local_position: vec3, mask: int) -> list

Combine a parent and child entity's transform.

Parameter	Type	Meaning
parent_scale	vec3	Parent scale.
parent_rotation	vec4	Parent rotation.
parent_position	vec3	Parent position.
local_scale	vec3	Local scale.
local_rotation	vec4	Local rotation.
local_position	vec3	Local position.
mask	int	Mask of ventity_transform_mask_t describing components of transform to not inherit.

Returns list: Resulting scale, rotation, and transform.

invalidate_world_transform_cache

read-only

$entity.invalidate_world_transform_cache()

Invalidate the world transform cache. Use after writing to the transform, but before reading it again in the same component.

is_ancestor

read-only

$entity.is_ancestor(ancestor: Entity, child: Entity) -> bool

Get whether an entity is an ancestor of another entity (upper in hierarchy).

Parameter	Type	Meaning
ancestor	Entity	The ancestor entity.
child	Entity	The child entity.

Returns bool: True if entity is an ancestor of child, or two entities are the same.

is_draw_only

read-only

$entity.is_draw_only(entity: Entity) -> bool

Return true if the entity is draw only

Parameter	Type	Meaning
entity	Entity	The entity to check. Will use calling entity if NULL.

Returns bool: Whether the entity is draw only.

is_in_draw_phase

$entity.is_in_draw_phase() -> bool

Returns true is the script is being run as part of a draw or early_draw event

Returns bool: True if running in a draw or early draw event, false otherwise.

is_level_spawned

$entity.is_level_spawned(level: Reference) -> bool

Return whether there exist in the world any entities from the given level.

Parameter	Type	Meaning
level	Reference	Reference to level file.

Returns bool: True if spawned, otherwise false.

is_rollback

read-only

$entity.is_rollback() -> bool

Return true if the world is currently rolled back

Returns bool: True if the world is rolled back, false otherwise.

level_contains_entity

read-only

$entity.level_contains_entity(level: Reference, entity: Entity) -> bool

Return whether the given entity was spawned from the given level.

Parameter	Type	Meaning
level	Reference	Reference to a level file.
entity	Entity	The entity to check.

Returns bool: True if the entity came from the level, false otherwise.

print

read-only

$entity.print(entity: Entity)

Print entity information to the console.

Parameter	Type	Meaning
entity	Entity	The entity.

schedule_event_on_component

read-only

$entity.schedule_event_on_component(name: string, target: Component, args: list, seconds: float, use_game_time: bool, ignore_rollback: bool)

Queues an event on a specific component for some user specified time in the future.

Parameter	Type	Meaning
name	string	Name of the event.
target	Component	The recipient of the event.
args	list	Event arguments.
seconds	float	Number of seconds in the future when the event should trigger.
use_game_time	bool	If true, game time is used. Otherwise system time is used.
ignore_rollback	bool	If true, rolling back past the time when the event was scheduled, will not unschedule it.

set_flag

$entity.set_flag(flag: int, entity: Entity)

Set a flag on an entity.

Parameter	Type	Meaning
flag	int	The entity flag to set e.g. k_game_entity_flag_net_priority_high
entity	Entity	The entity or null if the calling entity should be used.

set_parent

$entity.set_parent(parent: Entity, entity: Entity, end_of_frame: bool)

Set the parent of an entity. Will not take effect until the end of the current event.

Parameter	Type	Meaning
parent	Entity	The entity to set as the parent.
entity	Entity	(Optional) The entity to operate on. Omit to use the entity of the calling script. Warns on NULL.
end_of_frame	bool	If true, this action will take effect at the end of frame, otherwise, it will take effect at the end of current event.

spawn

$entity.spawn(entity: Entity, parent: Entity, net_name: var, local_only: bool, mode: int, owner: User, immediate: bool) -> Entity

Create an entity by cloning another entity.

Parameter	Type	Meaning
entity	Entity	The template entity from which to spawn a new entity.
parent	Entity	Optional entity used as reference for inherited functionality
net_name	var	Generally don't use. If specified, allows the engine to make certain network optimizations. Must be unique.
local_only	bool	If true, the new entity will not be registered for network replication.
mode	int	Use k_entity_spawn_draw to force draw-only spawn, or use k_entity_spawn_logic to force logic spawn, otherwise use k_entity_spawn_default.
owner	User	Owning user, or nulluser if none.
immediate	bool	If true, the entity is spawned at the end of the event. Otherwise spawn waits to the next frame.

Returns Entity: New entity.

spawn_level

$entity.spawn_level(level: Reference, parent: Entity, net_name: var, local_only: bool, mode: int, owner: User, immediate: bool, package: Reference) -> Entity

Create all entities in the given level and return the root entity. If the parent entity is marked local only, this level will be spawned local only. The level must be in the calling entity's owning package unless package is specified.

Parameter	Type	Meaning
level	Reference	Reference to level file.
parent	Entity	Optional entity used as reference for inherited functionality
net_name	var	Generally don't use. If specified, allows the engine to make certain network optimizations. Must be unique.
local_only	bool	If true, the new entities in the level will not be registered for network replication.
mode	int	Use k_entity_spawn_draw to force draw-only spawn, or use k_entity_spawn_logic to force logic spawn, otherwise use k_entity_spawn_default.
owner	User	Owning user, or null_user if none.
immediate	bool	If true, the level is spawned at the end of the event. Otherwise spawn waits to the next frame.
package	Reference	Optionally, the owning package to assign the new entities. If not specified, the owning package will be inherited from the calling entity (see entity.get_owning_package). The owning package must contain the level.

Returns Entity: Root of entity tree copied from level data.

try_queue_event

read-only

$entity.try_queue_event(name: string, entity: Entity, args: list, end_of_frame: bool)

Try to enqueue an event on a specific entity. Does not assume the event exists on all of the entity's components.

Parameter	Type	Meaning
name	string	Name of the event.
entity	Entity	The recipient of the event.
args	list	Event arguments.
end_of_frame	bool	If true, the event is queued to run at the end of the frame, otherwise it runs at the end of the active event.