CameraArm

Since 0.6

{@link CameraHandle.arm}: what the engine rig's boom is doing this frame.

Signature

export interface CameraArm {
  /** True while a `third-person` or `orbit` rig resolved its arm this frame. Every number is 0 when false. */
  readonly active: boolean
  /** The length the rig asked for, metres: the `distance` of the last `set`. */
  readonly desired: number
  /** The length it has, pivot to eye, after collision and the recovery ease. */
  readonly length: number
  /** Shorter than the arm's minimum (0.5 m): the eye is in or against the character. */
  readonly collapsed: boolean
  /** Geometry is shortening the arm. */
  readonly blocked: boolean
  /** What is shortening it, or null. */
  readonly blocker: EntityHandle | null
  /** 0..1, how far the followed character is faded away (see `fadeStart`). */
  readonly fade: number
  /** Radius of the sphere the boom sweeps: `probeRadius`, widened so the near plane never enters a wall. */
  readonly probeRadius: number
}

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

Members

Member	Signature	Description
`active`	`readonly active: boolean`	True while a `third-person` or `orbit` rig resolved its arm this frame. Every number is 0 when false.
`desired`	`readonly desired: number`	The length the rig asked for, metres: the `distance` of the last `set`.
`length`	`readonly length: number`	The length it has, pivot to eye, after collision and the recovery ease.
`collapsed`	`readonly collapsed: boolean`	Shorter than the arm's minimum (0.5 m): the eye is in or against the character.
`blocked`	`readonly blocked: boolean`	Geometry is shortening the arm.
`blocker`	`readonly blocker: EntityHandle \| null`	What is shortening it, or null.
`fade`	`readonly fade: number`	0..1, how far the followed character is faded away (see `fadeStart`).
`probeRadius`	`readonly probeRadius: number`	Radius of the sphere the boom sweeps: `probeRadius`, widened so the near plane never enters a wall.

Example

The tested fixture fixtures/recipes/collectible-and-goal/scenes/behaviors/goal-exit.ts.

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

/**
 * The exit, which the player wins at once every coin is collected.
 *
 * It counts the `collected` events, and once `required` are in, the player walking into it wins.
 * Entering it early does nothing, so the order the coins are taken in is free.
 *
 * `goal-reached` is the event the built-in `hud` behaviour marks a goal done on. The scene's
 * `goal` components (coin-1, coin-2, exit, in that order) are what `critic.play` walks to.
 */
interface State {
  collected: string[]
  won: boolean
}

interface Props {
  /** Coins needed before the exit counts. Default 1. */
  required?: number
  /** String key shown as the objective on a win. Default `exit.won`. */
  wonKey?: string
  /** Tag the player carries. Default `player`. */
  playerTag?: string
}

export default {
  init(ctx) {
    if (!Array.isArray(ctx.state.collected)) ctx.state.collected = []
    if (typeof ctx.state.won !== "boolean") ctx.state.won = false
  },

  onEvent(ctx, event) {
    if (event.name !== "collected") return
    const goal = (event.data as { goal?: string } | null)?.goal
    if (typeof goal !== "string" || ctx.state.collected.includes(goal)) return
    ctx.state.collected.push(goal)
    ctx.events.emit("goal-reached", { goal })
  },

  onTrigger(ctx, trigger) {
    if (ctx.state.won || !trigger.entering) return
    if (!trigger.other.hasTag(ctx.props.playerTag ?? "player")) return
    if (ctx.state.collected.length < (ctx.props.required ?? 1)) return
    ctx.state.won = true
    ctx.events.emit("goal-reached", { goal: ctx.entity.id })
    // A HUD text value is a key into `meta.strings`, not the text itself.
    ctx.hud.objective(ctx.props.wonKey ?? "exit.won")
  },
} satisfies Behavior<State, Props>