Wheel

Null otherwise. Also reached as ctx.body.wheels and ctx.vehicle.wheels from the body's own behaviour. Who drives. A wheel no vehicle composes is driven by behaviours: {@link Wheel.setMotorTorque}, {@link Wheel.setBrakeTorque} and {@link Wheel.setSteer} hold until the next call, and each tick the wheel's spring and tyre push its body — a cart, a trailer, a robot on wheels. A wheel a vehicle composes is driven by the vehicle. On an input: "script" vehicle, each field a behaviour writes takes that wheel over from the vehicle's command until the vehicle's next {@link Vehicle.drive} (torque vectoring, a spun-up wheel); on an auto vehicle a write changes nothing and is counted on GET /perf → unwired.vehicle_ignored. Signs. Positive motor torque rolls it along its forward (its composed -Z). Steer is positive right, like the steer action and {@link Vehicle.steerAngle}. ts // A cart: drive every wheel, steer the ones named "front-…", and brake when nothing is held. update(ctx) { const go = ctx.input?.action("throttle").held ?? false for (const w of ctx.body!.wheels) { w.setMotorTorque(go ? 40 : 0) w.setBrakeTorque(go ? 0 : 200) if (w.entity.id.startsWith("front-")) w.setSteer(0.3 * (ctx.input?.axis("steer")[0] ?? 0)) } }

Signature

export interface Wheel {
  /** Drive torque at the axle, N·m, from the next tick until the next call. Positive rolls it forward. */
  setMotorTorque(nm: number): void
  /** Brake torque, N·m, 0 or more, from the next tick until the next call. */
  setBrakeTorque(nm: number): void
  /** Steer angle about the body's up, radians, **positive right**, from the next tick until the next call. */
  setSteer(radians: number): void
  /** The wheel's own entity. */
  readonly entity: EntityHandle
  /** `"script"`: behaviours drive it. `"vehicle"`: its vehicle does. */
  readonly drivenBy: "script" | "vehicle"
  readonly grounded: boolean
  /** Where it touches the ground; null in the air. */
  readonly contact: WheelContact | null
  /** Slip ratio (`long`; 0 on a `clamp` tyre, which rolls at road speed) and slip angle (`lat`), radians. */
  readonly slip: { long: number; lat: number }
  readonly rpm: number
  /** N the spring carries. */
  readonly load: number
  /** 0 at the spring's rest length or longer, 1 against the bump stop. */
  readonly compression: number
  /** Radians, **positive right**. */
  readonly steerAngle: number
  /** N·m: the torques in force — a behaviour's, or what its vehicle asked of it. */
  readonly motorTorque: number
  readonly brakeTorque: number
  /** Metres. */
  readonly radius: number
  /** True when it was locked on the last step: on the ground, turning at under half the road speed under braking, above 3 m/s (a `curve` tyre; the arcade model's `clamp` tyre cannot lock). */
  readonly locked: boolean
  /** What the ground did to its grip on the last step, as a multiplier on the tyre's own: 1 on dry asphalt, about 0.7 soaked, 0.12 on ice; 0 in the air. */
  readonly grip: number
  /** Its tyre's condition (see {@link Wheel.setTyre}): multipliers on its grip and rolling resistance, 1 and 1 new. */
  readonly tyre: { grip: number; rolling: number }
  /**
   * Puts the tyre in a condition until set again, from the next tick: multipliers on its grip and its rolling
   * resistance, 0 or more; a field left out keeps its value. Works on any wheel, an `input: "auto"` vehicle's
   * too: a blowout is something that happens to a tyre, not a control. Returns false when the wheel has gone; a
   * NaN throws `wheel.not-finite`, a negative value `wheel.tyre-invalid`. It is simulation state: a replay or a
   * rollback replays it.
   *
   * ```ts
   * // An instructor's "tyre blowout" inject on the front left.
   * ctx.events.on("blowout", () => ctx.vehicle!.wheels[0].setTyre({ grip: 0.3, rolling: 10 }))
   * ```
   */
  setTyre(tyre: { grip?: number; rolling?: number }): boolean
}

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

Members

Example

The tested fixture fixtures/recipes/drone-search/scenes/behaviors/carrier.ts.

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

/** Moves a kinematic body round `props.path` (world [x, z] points) at `props.speed` m/s, facing where it goes: the
 * stand-in for a boat or a truck the drone launches from, and for the contact it looks for. */
interface Props {
  path: [number, number][]
  speed: number
}

interface State {
  next: number
}

export default {
  init(ctx) {
    ctx.state.next ??= 0
  },
  update(ctx, dt) {
    const path = ctx.props.path
    const goal = path[ctx.state.next % path.length]
    if (goal === undefined) return
    const p = ctx.entity.position
    const to: [number, number, number] = [goal[0], p[1], goal[1]]
    ctx.entity.lookAt(to)
    if (ctx.entity.moveToward(to, ctx.props.speed * dt)) ctx.state.next = (ctx.state.next + 1) % path.length
  },
} satisfies Behavior<State, Props>