Entity

API for creating and manipulating entities as well as components.

Functions

Entity.create

Creates a new entity.

Entity.create(shouldReplicate?: boolean): entity

Parameters

Name	Type	Default Value	Description
shouldReplicate	boolean?	"false"	Only on server. True if the entity should replicate to clients.

Returns

Name	Type	Description
entity	entity	The newly created entity.

Entity.fromAsset3d

Creates a new entity hierarchy from an Asset3d.

Entity.fromAsset3d(asset: Asset3d, position: vector, orientation: Quaternion): entity

Parameters

Name	Type	Default Value	Description
asset	Asset3d	Required	An instance of the asset to create from.
position	vector	Required	The position of the root entity.
orientation	Quaternion	Required	The orientation of the root entity.

Returns

Name	Type	Description
entity	entity	The root entity of the new hierarchy.

Entity.fromMap

Creates entities from a Map.

Entity.fromMap(map: Map): entity[]

Parameters

Name	Type	Default Value	Description
map	Map	Required	An instance of the map to create from.

Returns

Name	Type	Description
entities	entity[]	List of the entities created

Entity.destroy

Destroys an entity.

Entity.destroy(entity: entity)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to destroy.

Entity.isValid

Checks if an entity is valid.

Entity.isValid(entity: entity): boolean

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to check.

Returns

Name	Type	Description
valid	boolean	Whether the entity is valid.

Entity.getId

Gets the ID of an entity.

Entity.getId(entity: entity): number

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the ID of.

Returns

Name	Type	Description
id	number	The ID of the entity.

Entity.isReplicated

True if the entity is replicated from the server to clients.

Modifications made to replicated entities on the client will be considered predictions, and will be overridden when the next update for the entity is sent by the server.

Entity.isReplicated(entity: entity): boolean

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to check.

Returns

Name	Type	Description
replica	boolean	Whether the entity is replicated.

Entity.createComponent

Creates a new component.

Performance for Component Types

Primitive component types are the fastest to create and access. Primitive component types include:

• boolean
• integer
• unsigned
• number
• string
• vector
• quaternion

Reference component types are slower to create and access. Reference component types include:

• table
• buffer
• function
• userdata
• thread

Entity.createComponent(type: 'boolean' | 'integer' | 'unsigned' | 'number' | 'string' | 'vector' | 'quaternion' | 'table' | 'buffer' | 'function' | 'userdata' | 'thread'): component

Parameters

Name	Type	Default Value	Description
type	'boolean' | 'integer' | 'unsigned' | 'number' | 'string' | 'vector' | 'quaternion' | 'table' | 'buffer' | 'function' | 'userdata' | 'thread'	Required	The type of component to create.

Returns

Name	Type	Description
component	component	The newly created component.

Entity.findByComponents

Finds entities which contain the given components.

Entity.findByComponents(components: component[]): entity[]

Parameters

Name	Type	Default Value	Description
components	component[]	Required	The components to search for.

Returns

Name	Type	Description
entities	entity[]	The entities which contain the given components.

Entity.getComponent

Gets a component from an entity.

Entity.getComponent(entity: entity, component: component): any

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the component from.
component	component	Required	The component to get.

Returns

Name	Type	Description
data	any	The component data from the entity.

Entity.setComponent

Sets component data on an entity.

Entity.setComponent(entity: entity, component: component, data: any)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the component on.
component	component	Required	The component to set.
data	any	Required	The data to set.

Entity.removeComponent

Removes a component from an entity.

Entity.removeComponent(entity: entity, component: component)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to remove the component from.
component	component	Required	The component to remove.

Entity.hasComponent

Checks if an entity has a component.

Entity.hasComponent(entity: entity, component: component): boolean

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to check.
component	component	Required	The component to check for.

Returns

Name	Type	Description
hasComponent	boolean	Whether the entity has the component.

Entity.getParent

Gets the parent of an entity.

Entity.getParent(entity: entity): entity?

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the parent of.

Returns

Name	Type	Description
parent	entity?	The parent of the entity.

Entity.getChildren

Gets the children of an entity.

Entity.getChildren(entity: entity): entity[]

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the children of.

Returns

Name	Type	Description
children	entity[]	The children of the entity.

Entity.setParent

Sets the parent of an entity.

Entity.setParent(entity: entity, parent?: entity)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the parent of.
parent	entity?	nil	The new parent, or nil to remove the entity's parent.

Entity.getCachedGlobalTransform

Gets the cached global transform of an entity.

Global transforms are recalculated from entity local transforms once per frame, after Lua executes and before rendering. This means transforms returned by this method may be out of sync from the local transform of the entity or its ancestors. You can force an immediate recalculation of an entity's global transform and those of all its ancestors with calculateGlobalTransform, but beware this isn't cheap if the entity is a deeply nested descendant.

Entity.getCachedGlobalTransform(entity: entity): Transform

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the global transform of.

Returns

Name	Type	Description
transform	Transform	The cached global transform of the entity.

Entity.calculateGlobalTransform

Immediately recalculates the global transforms of an entity and all of its ancestors.

Global transforms are recalculated from entity local transforms once per frame, after Lua executes and before rendering. This means transforms returned by getCachedGlobalTransform may be out of sync from the local transform of the entity or its ancestors. You can force an immediate recalculation of an entity's global transform and those of all its ancestors with this method, but beware this isn't cheap if the entity is a deeply nested descendant.

You should use getCachedGlobalTransform where possible.

Entity.calculateGlobalTransform(entity: entity): Transform

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to calculate the global transform of.

Returns

Name	Type	Description
transform	Transform	The up-to-date global transform of the entity.

Entity.getLocalPosition

Gets the local position of an entity.

Entity.getLocalPosition(entity: entity): vector

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the local position of.

Returns

Name	Type	Description
position	vector	The local position of the entity.

Entity.getLocalOrientation

Gets the local orientation of an entity.

Entity.getLocalOrientation(entity: entity): Quaternion

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the local orientation of.

Returns

Name	Type	Description
rotation	Quaternion	The local orientation of the entity.

Entity.getLocalScale

Gets the local scale of an entity.

Entity.getLocalScale(entity: entity): vector

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the local scale of.

Returns

Name	Type	Description
scale	vector	The local scale of the entity.

Entity.setLocalPosition

Sets the local position of an entity.

Entity.setLocalPosition(entity: entity, position: vector)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the local position of.
position	vector	Required	The local position to set.

Entity.setLocalOrientation

Sets the local orientation of an entity.

Entity.setLocalOrientation(entity: entity, orientation: Quaternion)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the local orientation of.
orientation	Quaternion	Required	The local orientation to set.

Entity.setLocalScale

Sets the local scale of an entity.

Entity.setLocalScale(entity: entity, scale: vector)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the local scale of.
scale	vector	Required	The local scale to set.

Entity.getMesh

Gets the mesh of an entity.

Entity.getMesh(entity: entity): Mesh?

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the mesh of.

Returns

Name	Type	Description
mesh	Mesh?	Mesh of the entity, or nil if it has none.

Entity.setMesh

Sets the mesh of an entity.

Entity.setMesh(entity: entity, mesh?: Mesh)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the mesh of.
mesh	Mesh?	nil	Mesh to set, or nil to remove the entity's mesh.

Entity.getSkeleton

Gets the skeleton of an entity.

Entity.getSkeleton(entity: entity): Skeleton?

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the skeleton of.

Returns

Name	Type	Description
skeleton	Skeleton?	Skeleton of the entity, or nil if it has none.

Entity.setSkeleton

Sets the skeleton of an entity.

Entity.setSkeleton(entity: entity, skeleton?: Skeleton)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the skeleton of.
skeleton	Skeleton?	nil	Skeleton to set, or nil to remove the entity's skeleton.

Entity.getMaterialSlotCount

Gets the number of material slots in the entity's mesh. Returns 0 if the entity has no mesh.

Entity.getMaterialSlotCount(entity: entity): number

Parameters

Name	Type	Default Value	Description
entity	entity	Required	Entity to get the slot count of.

Returns

Name	Type	Description
slotCount	number	Number of material slots available.

Entity.getMaterial

Gets the material of an entity. Use getMaterialSlotCount to check how many material slots are available.

Entity.getMaterial(entity: entity, slot: number): Material

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the material of.
slot	number	Required	The 1-indexed material slot to read from.

Returns

Name	Type	Description
material	Material	Material of the entity in the given slot.

Entity.setMaterial

Sets the material of an entity. Use getMaterialSlotCount to check how many material slots are available.

Entity.setMaterial(entity: entity, slot: number, material: Material)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the material of.
slot	number	Required	The 1-indexed material slot to write to.
material	Material	Required	Material to set.

Entity.getName

Gets the name of an entity.

Entity.getName(entity: entity): string?

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to get the name of.

Returns

Name	Type	Description
name	string?	The name of the entity.

Entity.setName

Sets the name of an entity.

Entity.setName(entity: entity, name: string)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity to set the name of.
name	string	Required	The name to set.

Types

Transform

Position, orientation and scale.

type Transform = { position: vector, orientation: Quaternion, scale: vector }

Properties

Field	Type	Description
position	vector	No description
orientation	Quaternion	No description
scale	vector	No description