Handle

A generic handle that represents any special kind of entity, such as a component or a resource.

Although the type means Typescript doesn’t know the exact kind of entity, it is known at runtime. Because of this, if you already know the kind, you can simply type cast it:

const Person = component()
const bob = entity().set(Person)

query(Person).forEach((handle) => {
    // We know for sure that we won't be giving the `Person` component to anything
    // other than simple entities, so we can safely type cast it as one.
    const entity = handle as EntityHandle
})

Extended by

Properties

id

readonly id: RawId

Defined in: handle.ts:175

A numerical entity identifier used internally.

Useful when you cannot pass the entire handle to something, but can pass its numerical ID instead. For example, storing an entity’s ID in an instance’s attribute, which cannot hold complex data structures.

In order to get back the appropriate handle from an ID, use the resolveId function.

Methods

children()

children(): Handle[]

Defined in: handle.ts:422

Gets all children (the sources of ChildOf relationships) for this entity.

Returns

Handle[]

Example

const alice = entity()
const charlie = entity().set(pair(ChildOf, alice))
const bob = entity().set(pair(ChildOf,  alice))

const children = alice.children() // [charlie, bob]

clear()

clear(): this

Defined in: handle.ts:330

Clears all components and relationship pairs from this entity, but does not despawn the entity.

Components and relationship pairs with the Persistent component (i.e. most built-in components) will not be removed.

Returns

this

components()

components(): ComponentHandle<unknown>[]

Defined in: handle.ts:346

Returns all components associated with this entity.

Returns

ComponentHandle<unknown>[]

despawn()

despawn(): void

Defined in: handle.ts:526

Completely deletes this entity from the world.

Throws an error if the entity is marked as persistent.

Returns

void

exists()

exists(): boolean

Defined in: handle.ts:433

Returns true if this entity exists in the world.

Returns

boolean

get()

get<Args>(…componentsOrPairs): WrapLuaTuple<Flatten<Nullable<InferValues<Args>>>>

Defined in: handle.ts:263

Retrieves the values of up to 4 components or relationship pairs on this entity.

Missing components or pairs will return undefined.

Type Parameters

Args

Args extends OneUpToFour<ComponentHandle<unknown> | Pair<unknown>>

Parameters

componentsOrPairs

…Args

Returns

WrapLuaTuple<Flatten<Nullable<InferValues<Args>>>>

Example

const name = myEntity.get(Name)

const [position, velocity] = myEntity.get(Position, Velocity)

const carCount = myEntity.get(pair(Owns, car))

has()

has(…componentsOrPairs): boolean

Defined in: handle.ts:293

Returns true if this entity has all of the specified components or relationship pairs.

A maximum of 4 components or pairs can be checked at once.

Parameters

componentsOrPairs

…OneUpToFour<ComponentHandle<unknown> | Pair<unknown>>

Returns

boolean

Example

const IsDead = component()
const Owns = component()

const house = entity()
const bob = entity()
    .set(IsDead)
    .set(pair(Owns, house))

if (bob.has(IsDead, pair(Owns, house))) {
    // Why don't we rob Bob's house?
}

parent()

parent(): Handle

Defined in: handle.ts:405

Gets the parent (the target of a ChildOf relationship) for this entity, if such a relationship exists.

Returns

Handle

Example

const alice = entity()
const charlie = entity().set(pair(ChildOf, alice))

const parent = charlie.parent() // alice

relationships()

relationships(): Pair<unknown>[]

Defined in: handle.ts:364

Returns all relationship pairs associated with this entity.

Returns

Pair<unknown>[]

remove()

remove(componentOrPair): this

Defined in: handle.ts:306

Removes a component or relationship pair from this entity.

Throws an error if trying to remove a component or relationship pair with the Persistent component (i.e. most built-in components).

Parameters

componentOrPair

ComponentHandle<unknown> | Pair<unknown>

Returns

this

set()

Call Signature

set(tagComponent): this

Defined in: handle.ts:192

Assigns a tag component to this entity.

Parameters

tagComponent

ComponentHandle<undefined>

Returns

this

Example

const IsAlive = component()
myEntity.set(IsAlive)

Call Signature

set<V>(component, value): this

Defined in: handle.ts:206

Assigns a component and its value to this entity.

Type Parameters

V

V

Parameters

component

ComponentHandle<V>

value

NoInfer<V>

Returns

this

Example

const Health = component<number>()
const Stamina = component<number>()

entity()
    .set(Health, 100)
    .set(Stamina, 50)

Call Signature

set(tagPair): this

Defined in: handle.ts:219

Assigns a relationship pair to this entity.

Parameters

tagPair

Pair<undefined>

Returns

this

Example

const Likes = component()

const bob = entity()
const alice = entity()
    .set(pair(Likes, bob))

Call Signature

set<P>(pair, value): this

Defined in: handle.ts:235

Assigns a relationship pair and its value to this entity.

Type Parameters

P

P extends Pair<unknown>

Parameters

pair

P

value

InferValue<P>

Returns

this

Example

const Owns = component<number>()

const car = entity()
const perfume = entity()

const alice = entity()
    .set(pair(Owns, car), 2)
    .set(pair(Owns, perfume), 5)

targetOf()

targetOf(relation, nth?): Handle

Defined in: handle.ts:458

Returns the target entity of a relationship pair from this entity.

If there are multiple targets for the given relationship, the nth index can be specified (starting at 0).

Parameters

relation

ComponentHandle

nth?

number = 0

Returns

Handle

Example

const Likes = component()

const bob = entity()
const charlie = entity()
const alice = entity()
    .set(pair(Likes, bob))
    .set(pair(Likes, charlie))

// The order of targets is not guaranteed.
const maybeBob = alice.targetOf(Likes, 0)
const maybeCharlie = alice.targetOf(Likes, 1)

targetsOf()

targetsOf(relation): Handle[]

Defined in: handle.ts:479

Returns all target entities of a relationship pair from this entity.

Parameters

relation

ComponentHandle

Returns

Handle[]

Example

const Likes = component()

const bob = entity()
const charlie = entity()
const alice = entity()
    .set(pair(Likes, bob))
    .set(pair(Likes, charlie))

const likedEntities = alice.targetsOf(Likes)

toString()

toString(): string

Defined in: handle.ts:390

Gets the label assigned to this entity.

Returns

string