# HoldOptions

> Talos 0.7 · Since 0.6

Options for {@link WorldQuery.hold}.

## Signature

```ts
export interface HoldOptions {
  /**
   * Where the body is carried, in the holder's own frame (forward is -Z, as `entity.rotation` has it).
   * Omitted, the body is held wherever it is relative to the holder at the moment of the grab.
   */
  offset?: Vec3
  /** How far behind its hold point the body may be, and still falling behind, before the hold breaks. Default 1 m. */
  breakDistance?: number
  /** Fastest the hold moves the body, m/s. Default 20; lower for something heavy that swings in slowly. */
  maxSpeed?: number
  /** Refuse a body heavier than this, kg. Default: no limit. */
  maxMass?: number
}
```

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

## Members

| Member | Signature | Description |
|---|---|---|
| `offset` | `offset?: Vec3` | Where the body is carried, in the holder's own frame (forward is -Z, as `entity.rotation` has it). Omitted, the body is held wherever it is relative to the holder at the moment of the grab. |
| `breakDistance` | `breakDistance?: number` | How far behind its hold point the body may be, and still falling behind, before the hold breaks. Default 1 m. |
| `maxSpeed` | `maxSpeed?: number` | Fastest the hold moves the body, m/s. Default 20; lower for something heavy that swings in slowly. |
| `maxMass` | `maxMass?: number` | Refuse a body heavier than this, kg. Default: no limit. |

## Example

The tested fixture `fixtures/host/road-edges.ts`.

```ts
// A behavior that keeps a car inside the road's wall: what `ctx.world.road(id).edge(s)` is for.
import type { Behavior } from "@argus/api"

export default {
  update(ctx) {
    const road = ctx.world.road("track")
    if (road === null) return
    const here = road.closest(ctx.entity.position)
    const edge = road.edge(here.s)
    // Keep the car's centre a radius inside the wall's inner face, or the kerb's edge when there is no wall.
    const limit = (edge.barrier?.inner ?? edge.kerbOuter) - 0.8
    const over: number = Math.abs(here.offset) - limit
    const wallHeight: number | undefined = road.barrier?.heightM
    const sides: "left" | "right" | "both" | undefined = road.barrier?.sides
    const kerb: number = road.kerbWidth + road.kerbHeight
    ctx.state.over = [over, wallHeight, sides, kerb, edge.halfWidth, edge.barrier?.left, edge.barrier?.right, edge.barrier?.outer, edge.barrier?.height]
  },
} satisfies Behavior
```