ComponentHandle

Defined in: handle.ts:584

A handle for components spawned with component().

Extends

• Handle

Type Parameters

Value

Value = unknown

Properties

[VALUE_SYMBOL]

[VALUE_SYMBOL]: Value

Defined in: handle.ts:585

---

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.

Inherited from

Handle.id

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]

Inherited from

Handle.children

---

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

Inherited from

Handle.clear

---

components()

components(): ComponentHandle<unknown>[]

Defined in: handle.ts:346

Returns all components associated with this entity.

Returns

ComponentHandle<unknown>[]

Inherited from

Handle.components

---

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

Inherited from

Handle.despawn

---

exists()

exists(): boolean

Defined in: handle.ts:433

Returns true if this entity exists in the world.

Returns

boolean

Inherited from

Handle.exists

---

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))

Inherited from

Handle.get

---

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?
}

Inherited from

Handle.has

---

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

Inherited from

Handle.parent

---

relationships()

relationships(): Pair<unknown>[]

Defined in: handle.ts:364

Returns all relationship pairs associated with this entity.

Returns

Pair<unknown>[]

Inherited from

Handle.relationships

---

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

Inherited from

Handle.remove

---

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)

Inherited from

Handle.set

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)

Inherited from

Handle.set

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))

Inherited from

Handle.set

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)

Inherited from

Handle.set

---

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)

Inherited from

Handle.targetOf

---

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)

Inherited from

Handle.targetsOf

---

toString()

toString(): string

Defined in: handle.ts:390

Gets the label assigned to this entity.

Returns

string

Inherited from

Handle.toString