# Instances

> Talos next · Since 0.7

The instances of an `instancedMesh` entity: what `ctx.world.instances(entity)` returns.

Every instance has a stable id that hits and picks report too; every list is ascending by id.

## Signature

```ts
export interface Instances {
  /** The instanced mesh's entity. */
  readonly entity: EntityHandle
  /** How many instances there are now. */
  readonly count: number
  /** Every instance id, ascending. */
  ids(): number[]
  /** The instance with this id, or null. */
  get(id: number): InstanceRecord | null
  /** Adds an instance (`position` required; no rotation and scale 1 by default); returns its new id, or null when the value is not a transform. */
  add(value: InstanceInput & { position: Vec3 }): number | null
  /** Changes the given fields of instance `id`; false when there is no such instance. */
  update(id: number, value: InstanceInput): boolean
  /** Removes instance `id`; false when there is none. Its id is never given again. */
  remove(id: number): boolean
  /**
   * Ids of the instances within `radius` of `center` (the mesh's frame), ascending. Inclusive: an instance
   * at exactly `radius` is in. Unlike `query({ near })` it compares squared distances (f32).
   */
  inSphere(center: Vec3, radius: number): number[]
}
```

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

## Members

| Member | Signature | Description |
|---|---|---|
| `entity` | `readonly entity: EntityHandle` | The instanced mesh's entity. |
| `count` | `readonly count: number` | How many instances there are now. |
| `ids` | `ids(): number[]` | Every instance id, ascending. |
| `get` | `get(id: number): InstanceRecord \| null` | The instance with this id, or null. |
| `add` | `add(value: InstanceInput & { position: Vec3 }): number \| null` | Adds an instance (`position` required; no rotation and scale 1 by default); returns its new id, or null when the value is not a transform. |
| `update` | `update(id: number, value: InstanceInput): boolean` | Changes the given fields of instance `id`; false when there is no such instance. |
| `remove` | `remove(id: number): boolean` | Removes instance `id`; false when there is none. Its id is never given again. |
| `inSphere` | `inSphere(center: Vec3, radius: number): number[]` | Ids of the instances within `radius` of `center` (the mesh's frame), ascending. Inclusive: an instance at exactly `radius` is in. Unlike `query({ near })` it compares squared distances (f32). |

## Example

The tested fixture `fixtures/app/agent.ts`.

```ts
import type { Behavior } from "@argus/api"

// Sends a nav agent to `props.target` once, then reports arrival through ctx.state so the
// test can read it without polling the crowd directly.
export default {
  init(ctx) {
    ctx.state.arrived = false
    ctx.nav?.goTo(ctx.props.target as [number, number, number])
  },
  update(ctx) {
    if (ctx.nav?.arrived) ctx.state.arrived = true
  },
} satisfies Behavior
```