# RoadProgress

> Talos next · Since 0.7

One entity's progress along a road, from {@link RoadLine.progress}.

## Signature

```ts
export interface RoadProgress {
  /** Distance along the road where the entity is now, as `closest` gives it (0 to `length` on a closed road). */
  readonly s: number
  /** Metres right of the centre line, negative left. */
  readonly offset: number
  /** Laps completed: every checkpoint crossed in order, then the start line. Always 0 on an open road. */
  readonly lap: number
  /**
   * Metres past the start line, laps included, and never past the next checkpoint still owed: what
   * the race order sorts by. Negative behind the line on the grid; `s` on an open road.
   */
  readonly distance: number
  /** The gate to cross next, an index into `gates`; null on a road with no gates. */
  readonly nextGate: number | null
  /** True after going backward along the road for more than 10 m (net of going forward again). */
  readonly wrongWay: boolean
  /** Race position among the entities tracked on this road, 1 for the leader. */
  readonly place: number
}
```

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

## Members

| Member | Signature | Description |
|---|---|---|
| `s` | `readonly s: number` | Distance along the road where the entity is now, as `closest` gives it (0 to `length` on a closed road). |
| `offset` | `readonly offset: number` | Metres right of the centre line, negative left. |
| `lap` | `readonly lap: number` | Laps completed: every checkpoint crossed in order, then the start line. Always 0 on an open road. |
| `distance` | `readonly distance: number` | Metres past the start line, laps included, and never past the next checkpoint still owed: what the race order sorts by. Negative behind the line on the grid; `s` on an open road. |
| `nextGate` | `readonly nextGate: number \| null` | The gate to cross next, an index into `gates`; null on a road with no gates. |
| `wrongWay` | `readonly wrongWay: boolean` | True after going backward along the road for more than 10 m (net of going forward again). |
| `place` | `readonly place: number` | Race position among the entities tracked on this road, 1 for the leader. |

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