ComponentHandle

Defined in: src/handle.ts:519

A handle for components spawned with component().

Currently, it has no unique methods, so it only serves as a marker.

Extends

• Handle

Type Parameters

Value

Value = unknown

Properties

[VALUE_SYMBOL]

[VALUE_SYMBOL]: Value

Defined in: src/handle.ts:520

---

id

readonly id: RawId

Defined in: src/handle.ts:148

The numeric ID underlying this handle.

Meant to be used when one cannot use the higher-level abstractions provided by Toucan, such as storing an entity’s ID in an instance’s attribute, which cannot hold complex data structures.

In order to get back the high-level handle from an ID, use the resolveId function.

Inherited from

Handle.id

Methods

children()

children(): Handle[]

Defined in: src/handle.ts:372

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: src/handle.ts:286

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

Components with the Persistent component (i.e. built-in components) will not removed.

Returns

this

Inherited from

Handle.clear

---

components()

components(): ComponentHandle<unknown>[]

Defined in: src/handle.ts:298

Returns all components associated with this entity.

Returns

ComponentHandle<unknown>[]

Inherited from

Handle.components

---

despawn()

despawn(): void

Defined in: src/handle.ts:474

Completely deletes this entity from the world.

Returns

void

Inherited from

Handle.despawn

---

exists()

exists(): boolean

Defined in: src/handle.ts:383

Returns true if this entity exists.

Returns

boolean

Inherited from

Handle.exists

---

get()

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

Defined in: src/handle.ts:234

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<Pair<unknown> | ComponentHandle<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: src/handle.ts:259

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<Pair<unknown> | ComponentHandle<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 | undefined

Defined in: src/handle.ts:355

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

Returns

Handle | undefined

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: src/handle.ts:316

Returns all relationship pairs associated with this entity.

Returns

Pair<unknown>[]

Inherited from

Handle.relationships

---

remove()

remove(componentOrPair): this

Defined in: src/handle.ts:268

Removes a component or relationship pair from this entity.

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

Parameters

componentOrPair

Pair<unknown> | ComponentHandle<unknown>

Returns

this

Inherited from

Handle.remove

---

set()

Call Signature

set(tagComponent): this

Defined in: src/handle.ts:163

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: src/handle.ts:177

Assigns a component and its value to this entity.

Type Parameters

V

V

Parameters

component

ComponentHandle<V>

value

NoInfer

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: src/handle.ts:190

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: src/handle.ts:206

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

Defined in: src/handle.ts:408

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

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: src/handle.ts:429

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: src/handle.ts:340

Gets the label assigned to this entity.

Returns

string

Inherited from

Handle.toString