QueryFilter

Signature

export interface QueryFilter {
  tag?: string
  component?: string
  /**
   * Within `radius` metres (default 1) of this point or entity (an entity counts at its world position).
   * Inclusive: an entity at exactly `radius` is kept (`distance <= radius`).
   * The distance is f32 Euclidean distance, the length of the difference vector with every step rounded to
   * 32-bit float, so it can differ in the last bits from the same sum in JavaScript's doubles. An entity a
   * hair either side of `radius` can therefore land on the other side of the test from a double-precision
   * check of your own.
   */
  near?: Target
  /** Metres, default 1. Only read together with `near`. Inclusive, as `near` says. */
  radius?: number
  /** Inside the bounds of this trigger volume or entity (by id or handle). */
  inside?: string | EntityHandle
  /**
   * `"distance"`: nearest `near` first. Needs `near`. The sort is stable: entities at equal distance keep
   * the order they have without `sort`, which is slot order. Distance is the f32 measure `near` describes,
   * so two candidates whose true distances differ by less than a float's last bit can tie and then go by
   * slot order. To pick "the nearest" the way the engine does, ask the engine
   * (`{ near, sort: "distance", limit: 1 }`) rather than ranking by a distance you compute in JavaScript
   * doubles, which can order near-ties differently.
   *
   * Without `sort`, matches come in **slot order**: the order entities occupy the engine's entity table.
   * That is the same on every machine for the same scene and the same spawns, but it is **not** sorted by
   * id (`"crawler#10"` can come before or after `"crawler#2"`), and a small change to the scene changes it. Sort
   * by `entity.id` yourself where a result must not depend on it.
   */
  sort?: "distance"
  /** At most this many matches (a whole number, 0 or more), after `sort`: `{ near, sort: "distance", limit: 1 }` is the nearest. */
  limit?: number
}

Import: import type { QueryFilter } from "@argus/api"

Members

Example

The tested fixture fixtures/host/door.ts.

import type { Behavior } from "@argus/api"
// docs/API.md, "Joints": a door on a hinge that swings open while the player is near and closes
// behind them. Typechecked by packages/api's tests.
export default {
  update(ctx) {
    const player = ctx.world.find("player")
    const near = player !== null && ctx.entity.distanceTo(player) < 2
    ctx.joint?.setMotor(near ? Math.PI / 2 : 0, { mode: "position", maxForce: 200 })
  },
} satisfies Behavior