Fiasco SDK

Appearance

@vaguevoid/fiasco / ecs/queries / Query

Type Alias: Query<T> ​

Query<T> = object & QueryKind & Omit<Generator<T>, "flatMap" | "return" | "throw">

Defined in: src/ecs/queries.ts:46

The life-blood of every ECS system. Define queries for requesting access to engine component and entity data.

Query data are dynamically Dependency Injected into system functions automatically.

Queries are implemented as https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator|Iterators and have common iterator helpers attached.

ts
import { Query, Transform, Component } from '@vaguevoid/fiasco'

type Car = Component<{ speed: number }>

function system(cars: Query<[Car, Transform]>) {
  for (const [car, transform] of cars) {
    car.speed++
    transform.position.x += 0.5
  }
}
ts
import { Query, Transform, Component } from '@vaguevoid/fiasco'

type Car = Component<{ speed: number }>

function system(cars: Query<[Car, Transform]>) {
  // take only the first 2 cars
  for (const [car, transform] of cars.take(2)) {
    car.speed++
    transform.position.x += 0.5
  }
}

Type declaration ​

first() ​

first(): undefined | T

Get the first entity in the query results. Order is not guarenteed.

Returns ​

undefined | T

the entity object or undefined if the results are empty.

Example ​

ts
function system(query: Query<[Transform]>) {
   const entity = query.first()
   if (entity) {
     // ...
   }
}

get() ​

get(entityId): undefined | T

Get an entity in the query results with the given entity ID.

Parameters ​

entityId ​

bigint

The ID of the entity.

Returns ​

undefined | T

the entity object or undefined if that entity does not exist.

Example ​

ts
function system(query: Query<[Transform]>) {
  const id = engine.spawn([...])
  // ... next frame
  const entity = query.get(id)
  if (entity) {
    // ...
  }
}

getByLabel() ​

getByLabel(label): undefined | T

Get an entity by it's given label.

Parameters ​

label ​

string

The string label that was previously attached to the entity.

Returns ​

undefined | T

the entity object or undefined if no entity is found with that label.

Example ​

ts
function system(query: Query<[Transform]>) {
  const entity = query.getByLabel("car")
  if (entity) {
    // ...
  }
}

length() ​

length(): number

Get the count of entities in the query results.

Returns ​

number

Example ​

ts
function system(query: Query<[Transform]>) {
  const count = query.length()
  console.log(count) // -> number
}

Type Parameters ​

T ​

T extends ComponentKind[]