DiscordPHP-NHA Documentation

AgentObservation
in package
implements JsonSerializable uses HelperTrait

A lightweight, read-only wrapper around a single `GET /observe/:id` response (the `ObserveOut` schema). This is intentionally a plain data holder (not a Discord `Part`) since observations describe world state, not Discord entities. Exact keys vary by era and agent state, so every accessor normalises the shapes the world is known to emit.

Tags
link

Endpoint reference

#/components/schemas/ObserveOut
since
3.0.0

Table of Contents

Interfaces

JsonSerializable

Constants

GITHUB  : mixed = 'https://github.com/discord-php/DiscordPHP-NHA'
The project source repository.
SPONSOR  : mixed = 'https://github.com/sponsors/valzargaming'
GitHub Sponsors page for the maintainer.

Properties

$agentId  : int
$raw  : array<string|int, mixed>
Raw, decoded JSON body as returned by the world.

Methods

__construct()  : mixed
attributionComponents()  : TextDisplay}
A {@see Separator} plus a subtle one-line footer crediting the project and pointing at the repo and GitHub Sponsors. Appended to the rich panels (observation, help, control panel) — not the one-line replies.
bar()  : string
Renders a 0-1 ratio as a small text progress bar, e.g. for HP.
createBuilder()  : MessageBuilder
Creates a new instance of MessageBuilder, optionally preventing mentions in the message.
get()  : mixed
Reads a (possibly nested, dot-separated) key from the raw payload.
getBounties()  : array<string|int, mixed>
Bounty offers visible to the agent (empty when absent).
getContracts()  : array<string|int, mixed>
Supply contracts visible to the agent (empty when absent).
getHp()  : float|null
Current HP (`hp`, falling back to `health`), or null when absent.
getInventory()  : array<string|int, mixed>
The agent's inventory as a `{resource: qty}` map (empty when absent).
getMaxHp()  : float
Maximum HP (`max_hp`/`hp_max`), defaulting to 100.
getMessages()  : array<string|int, mixed>
Recent world/chat messages visible to the agent (empty when absent).
getNearbyAgents()  : array<string|int, mixed>
Other agents near this one (`nearby_agents`, falling back to `nearby.agents`/`agents`).
getPosition()  : array<string|int, mixed>|null
The agent's world position, always normalised to `['x' => int, 'y' => int]` (or `null` when the payload carries none).
getThreats()  : array<string|int, mixed>
Recent alerts/threats against the agent (`alerts`/`threats`/`threat_alerts`).
getVision()  : mixed
The agent's vision radius (`vision`/`sight_radius`), or null when absent.
isDowned()  : bool
True when the agent is downed (0 HP) at the tick this observation reflects.
jsonSerialize()  : array<string|int, mixed>
toContainer()  : Container
Builds a Components V2 container summarising this observation, with context-aware quick-action buttons wired via `Button::setListener()` so they work from any entry point (chat command, slash command, button).
contextRow()  : ActionRow|null
The third button row — only built when the world offers something to interact with right here.
contextSuffix()  : string
One short line of world context appended to the position line.
count()  : int
Count of a nearby-list key (`nearby_deposits`, `loot`, `artifacts`, …).

Constants

GITHUB

The project source repository.

public mixed GITHUB = 'https://github.com/discord-php/DiscordPHP-NHA'

SPONSOR

GitHub Sponsors page for the maintainer.

public mixed SPONSOR = 'https://github.com/sponsors/valzargaming'

Properties

$raw read-only

Raw, decoded JSON body as returned by the world.

public array<string|int, mixed> $raw

Methods

__construct()

public __construct(int $agentId, array<string|int, mixed> $raw) : mixed
Parameters
$agentId : int

The agent this observation belongs to.

$raw : array<string|int, mixed>

The decoded GET /observe/:id body, kept verbatim.

attributionComponents()

A {@see Separator} plus a subtle one-line footer crediting the project and pointing at the repo and GitHub Sponsors. Appended to the rich panels (observation, help, control panel) — not the one-line replies.

public static attributionComponents() : TextDisplay}
Return values
TextDisplay}

bar()

Renders a 0-1 ratio as a small text progress bar, e.g. for HP.

public static bar(float $current, float $max[, int $length = 10 ]) : string
Parameters
$current : float
$max : float
$length : int = 10
Return values
string

createBuilder()

Creates a new instance of MessageBuilder, optionally preventing mentions in the message.

public static createBuilder([bool $prevent_mentions = true ]) : MessageBuilder
Parameters
$prevent_mentions : bool = true
Return values
MessageBuilder

get()

Reads a (possibly nested, dot-separated) key from the raw payload.

public get(string $path[, mixed $default = null ]) : mixed
Parameters
$path : string
$default : mixed = null

getBounties()

Bounty offers visible to the agent (empty when absent).

public getBounties() : array<string|int, mixed>
Return values
array<string|int, mixed>

getContracts()

Supply contracts visible to the agent (empty when absent).

public getContracts() : array<string|int, mixed>
Return values
array<string|int, mixed>

getHp()

Current HP (`hp`, falling back to `health`), or null when absent.

public getHp() : float|null
Return values
float|null

getInventory()

The agent's inventory as a `{resource: qty}` map (empty when absent).

public getInventory() : array<string|int, mixed>
Return values
array<string|int, mixed>

getMaxHp()

Maximum HP (`max_hp`/`hp_max`), defaulting to 100.

public getMaxHp() : float
Return values
float

getMessages()

Recent world/chat messages visible to the agent (empty when absent).

public getMessages() : array<string|int, mixed>
Return values
array<string|int, mixed>

getNearbyAgents()

Other agents near this one (`nearby_agents`, falling back to `nearby.agents`/`agents`).

public getNearbyAgents() : array<string|int, mixed>
Return values
array<string|int, mixed>

getPosition()

The agent's world position, always normalised to `['x' => int, 'y' => int]` (or `null` when the payload carries none).

public getPosition() : array<string|int, mixed>|null

GET /observe/:id returns position as a positional [x, y] pair; older shapes used a {x, y} object under position/pos, and some payloads put flat x/y scalars at the top level. All three are accepted here so callers never have to care which one the world sent.

Return values
array<string|int, mixed>|null

getThreats()

Recent alerts/threats against the agent (`alerts`/`threats`/`threat_alerts`).

public getThreats() : array<string|int, mixed>
Return values
array<string|int, mixed>

getVision()

The agent's vision radius (`vision`/`sight_radius`), or null when absent.

public getVision() : mixed

isDowned()

True when the agent is downed (0 HP) at the tick this observation reflects.

public isDowned() : bool
Return values
bool

jsonSerialize()

public jsonSerialize() : array<string|int, mixed>
Tags
inheritDoc

Returns the raw observation payload unchanged.

Return values
array<string|int, mixed>

toContainer()

Builds a Components V2 container summarising this observation, with context-aware quick-action buttons wired via `Button::setListener()` so they work from any entry point (chat command, slash command, button).

public toContainer(NHA $nha[, string|null $token = null ]) : Container

Row 1 is always movement + refresh. Row 2 is the harvest/interact loop (mine/chop/gather/plant/heal). Row 3 appears only when the world offers something to interact with (loot / artifact / elevator / asteroid / sky). While downed, only chat is allowed, so the action rows are hidden.

$token is the acting agent's own NHA token. Pass it for a per-user agent (the /start / /observe flow) so the buttons submit intents with that token instead of the bot's ambient default-agent token; leave it null for the default agent, whose token is already configured on $nha.

Respects Discord's limits: ≤5 buttons per row, ≤5 rows per message.

Parameters
$nha : NHA
$token : string|null = null
Return values
Container

contextRow()

The third button row — only built when the world offers something to interact with right here.

private contextRow(NHA $nha, callable(callable): callable $act, callable(string, array<string|int, mixed>=): mixed $submit) : ActionRow|null
Parameters
$nha : NHA
$act : callable(callable): callable

Wraps a listener so it refreshes the message after acting.

$submit : callable(string, array<string|int, mixed>=): mixed

Submits a verb for this agent (token-aware).

Return values
ActionRow|null

contextSuffix()

One short line of world context appended to the position line.

private contextSuffix() : string
Return values
string

count()

Count of a nearby-list key (`nearby_deposits`, `loot`, `artifacts`, …).

private count(string $key) : int
Parameters
$key : string
Return values
int
On this page

Search results