DataHandle

A value belongs to the tick it is recorded on. A recording writes it as the column <entity>:data.<name> (named in --data-fields) and, in the JSONL form, in every row's data; a tick on which a behaviour records nothing for a name leaves that cell empty (null in JSONL), rather than repeating an old value. Recording is cheap and needs no recorder running. ts update(ctx) { const y = ctx.entity.worldPosition[1] ctx.data.record("altitude", y) ctx.data.record("climbing", (ctx.body?.velocity[1] ?? 0) > 0) ctx.data.record("phase", y < 1 ? "takeoff" : "cruise") }

Signature

export interface DataHandle {
  /**
   * Publish this entity's `value` for `name` on this tick: a finite number, a boolean or a string of at
   * most 256 characters. `name` is 1 to 64 of `A-Z a-z 0-9 _ - .`. A second record of one name in a tick
   * replaces the first. Anything else throws a `RangeError`.
   */
  record(name: string, value: number | boolean | string): void
}

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

Members

Example

The tested fixture fixtures/host/telemetry.ts.

import type { Behavior } from "@argus/api"
// docs/API.md, "Recording data": a flight controller's telemetry for `argus run --record-data`,
// beside the transforms the recorder reads itself. Typechecked by packages/api's tests.
export default {
  update(ctx) {
    const target = (ctx.props as { altitude: number }).altitude
    const y = ctx.entity.worldPosition[1]
    ctx.data.record("altitudeError", target - y)
    ctx.data.record("climbing", (ctx.body?.velocity[1] ?? 0) > 0)
    ctx.data.record("phase", Math.abs(target - y) < 0.1 ? "hold" : "seek")
  },
} satisfies Behavior