# QueryFilter

> Talos 0.7 · Since 0.6; changed in 0.7

Filter for {@link WorldQuery.query}; every given field must match.

## Signature

```ts
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

| Member | Signature | Description |
|---|---|---|
| `tag` | `tag?: string` |  |
| `component` | `component?: string` |  |
| `near` | `near?: Target` | 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. |
| `radius` | `radius?: number` | Metres, default 1. Only read together with `near`. Inclusive, as `near` says. |
| `inside` | `inside?: string \| EntityHandle` | Inside the bounds of this trigger volume or entity (by id or handle). |
| `sort` | `sort?: "distance"` | `"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. |
| `limit` | `limit?: number` | At most this many matches (a whole number, 0 or more), after `sort`: `{ near, sort: "distance", limit: 1 }` is the nearest. |

## Example

The tested fixture `fixtures/host/door.ts`.

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