ResourceHandle

Defined in: src/handle.ts:563

A handle for resources spawned with resource().

Extends

Handle

Type Parameters

Value

Value = unknown

Properties

[VALUE_SYMBOL]

[VALUE_SYMBOL]: Value

Defined in: src/handle.ts:564

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

changed()

changed(listener): () => void

Defined in: src/handle.ts:592

Registers a listener that is called whenever the value of this resource changes.

The returned function can be called to unregister the listener.

Parameters

listener

(newValue) => void

Returns

(): void

Returns

void

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

read()

read(): Value

Defined in: src/handle.ts:572

Returns the current value of this resource.

Not to be confused with get, which can be used to retrieve the value of components attached to resources, just like with entities.

Returns

Value

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)