DiscordPHP-NHA Documentation

Commands
in package

Application

uses ActorTrait

Framework-agnostic command handlers shared by chat commands, slash commands and message components. Every method resolves a `MessageBuilder` ready to be sent or used to update a message/interaction response, so the three entry points in `bot.php` never duplicate business logic.

Actions go through queueVerb() (so every confirmation carries the queued_intent id you can then check with intentStatus()); read-only boards go through board(). The "whose agent?" choice for a dual-mode command is resolved once, in ActorTrait::actor().

Constants

BOARDS : mixed = ['world', 'healthz', 'agents', 'agent', 'roster...: Read-only boards reachable through {@see board()}, mapped to the repository call that fetches each. Keep in sync with the NHA `GET` endpoint list.
HELP : array<string, array{0: string, 1: string, 2: string}> = \NHA\HelpGuide::SECTIONS: How-to-play guide sections. Kept as an alias so `Commands::HELP` callers keep working; the content and rendering live in {@see HelpGuide}.

Properties

$autoPlayer : AutoPlayer|null
$nha : NHA
$state : StateStore
$helpGuide : HelpGuide: The how-to-play guide; {@see help()} / {@see resolveHelpKey()} delegate here.

Methods

__construct() : mixed
acceptAlly() : PromiseInterface: Queues an `accept_ally` intent accepting an alliance proposal from `$to`.
acceptTrade() : PromiseInterface: Queues an `accept` intent accepting an incoming peer-to-peer trade.
act() : PromiseInterface: Raw verb + args escape hatch for any verb. `$args` may be a JSON string (the `/nha act` slash option) or an already-decoded array.
actor() : AgentContext: Works out who an action runs as.
agentInfo() : PromiseInterface: Reads the `agent` board for one agent's public info.
ally() : PromiseInterface: Queues an `ally` intent proposing an alliance to `$to`.
arm() : PromiseInterface: Queues an `arm` intent (plant a 3-tick bomb fuse).
assist() : PromiseInterface: Queues an `assist` intent gifting the `$give` resources to ally `$to`.
attack() : PromiseInterface: Queues an `attack` intent firing `$weapon` (optional) at agent `$target`.
attune() : PromiseInterface: Queues an `attune` intent (bond with a nearby ancient artifact).
autoplay() : PromiseInterface: Toggles (or reports) the autonomous play loop. `$enabled` null just reports the current state.
board() : PromiseInterface: Generic read-only board fetch. `$name` is one of {@see BOARDS}; `$params` supplies any per-board arguments (`id`, `body`, `x`, `y`, `resource`, `limit`, …).
bounty() : PromiseInterface: Queues a `bounty` intent placing a kill bounty of `$reward` on `$target`.
build() : PromiseInterface: Queues a `build` intent crafting vehicle `$part`, optionally with up to three `$with` upgrade items.
buy() : PromiseInterface: Queues a `buy` intent buying `$n` of `$resource` from the depot.
cancelOrder() : PromiseInterface: Queues a `cancel` intent removing one of the agent's open market orders.
chop() : PromiseInterface: Queues a `chop` intent for up to `$n` units (default 1).
collect() : PromiseInterface: Queues a `collect` intent picking up a dropped `$loot` pile.
combine() : PromiseInterface: Queues a `combine` intent mixing `$ingredients` (a `{resource: qty}` map); an unknown mix is escrowed to the Inventors' Guild under optional `$name`.
construct() : PromiseInterface: Queues a `construct` intent placing a structure of the given `$shape`.
contract() : PromiseInterface: Queues a `contract` intent posting a supply job offering `$reward` for `$want`.
contracts() : PromiseInterface: Reads the `contracts` board (open supply contracts).
dashboard() : MessageBuilder: Builds the per-user control panel. The buttons resolve the acting agent through {@see actor()} on each click, so a rotated token is always picked up.
declareWar() : PromiseInterface: Queues a `declare_war` intent declaring war on `$to`.
depart() : PromiseInterface: Queues a `depart` intent committing the ship to an interplanetary transfer to `$dest`.
deploy() : PromiseInterface: Queues a `deploy` intent (send a finalized vehicle off to roam).
deposit() : PromiseInterface: Queues a `deposit` intent stashing `$n` of `$resource` into escrow storage.
deposits() : PromiseInterface: Reads the `deposits` board around cell `($x, $y)`, optionally filtered by `$resource` and row `$limit`.
depot() : PromiseInterface: Reads the `depot` board (fixed depot buy/sell prices).
detonate() : PromiseInterface: Queues a `detonate` intent triggering an armed `$bomb`.
distress() : PromiseInterface: Queues a `distress` intent (emergency recall of a stranded off-world agent).
dock() : PromiseInterface: Queues a `dock` intent (latch an asteroid / the orbital station).
finalize() : PromiseInterface: Queues a `finalize` intent assembling the agent's loose parts into one vehicle.
fulfill() : PromiseInterface: Queues a `fulfill` intent delivering against an open supply contract.
gather() : PromiseInterface: Queues a `gather` intent for up to `$n` units (default 1).
heal() : PromiseInterface: Queues a `heal` intent applying `$item` medicine to self or ally `$target`.
help() : MessageBuilder: The how-to-play guide. `$category` is a slug from {@see HELP} (fuzzy matched on slug or title); anything unrecognised falls back to the general guide. Delegates to {@see HelpGuide}.
intentStatus() : PromiseInterface: Shows the stored outcome of a previously queued intent (`GET /intent/{id}` → `pending` | `applied` | `rejected`).
invest() : PromiseInterface: Queues an `invest` intent bankrolling Station `$module` with `$credits`.
land() : PromiseInterface: Queues a `land` intent (descend to the surface).
landBody() : PromiseInterface: Queues a `land_body` intent (descend from orbit onto the travelled-to body).
landMoon() : PromiseInterface: Queues a `land_moon` intent (land on the Moon surface).
launch() : PromiseInterface: Queues a `launch` intent (climb into the air / to space).
login() : PromiseInterface: Creates (or reopens) the Discord user's own linked agent and returns their control panel. Unlike {@see register()} this never touches the bot's default agent.
makePeace() : PromiseInterface: Queues a `make_peace` intent suing for peace with `$to`.
map() : PromiseInterface: Reads the `map` board (the world map).
market() : PromiseInterface: Reads the `market` board (agent order book), optionally filtered by `$resource` and row `$limit`.
mine() : PromiseInterface: Queues a `mine` intent for up to `$n` units (default 1), optionally of one `$resource`.
move() : PromiseInterface: Queues a `move` intent stepping the agent by the `(dx, dy)` delta.
moveTo() : PromiseInterface: Queues a `move` intent walking the agent toward absolute cell `(x, y)`.
observe() : PromiseInterface<string|int, MessageBuilder>: Observes the world for the given agent and renders the result as a Components V2 panel. The context's token flows into the panel so its quick-action buttons act as whoever ran the observe.
order() : PromiseInterface: Queues an `order` intent posting a `$side` (buy|sell) market order for `$qty` of `$resource` at `$price`.
plant() : PromiseInterface: Queues a `plant` intent (1 wood tops up the most-drained tree on the cell, cap 22; rejected if all full).
queueVerb() : PromiseInterface: Queues one intent and confirms it, surfacing the `queued_intent` id so the caller can follow up with {@see intentStatus()}.
register() : PromiseInterface<string|int, MessageBuilder>: Registers a brand-new agent and makes it the bot's default. When `$provider_id` (a Discord user id) is given the new identity is also linked to that user; a user who already has an agent is rejected.
resolveAgentId() : int: Resolves an explicit agent id, falling back to the default agent.
resolveHelpKey() : string: Maps a free-form `$category` to a {@see HELP} slug, defaulting to `general`.
revoke() : PromiseInterface: Queues a `revoke` intent withdrawing one of the agent's own open contracts.
ride() : PromiseInterface: Queues a `ride` intent (mount the vehicle at the agent's tile).
roster() : PromiseInterface: Reads the `roster` board (all agents).
rules() : PromiseInterface: Reads the `rules` board (the crafting/economy codex).
say() : PromiseInterface: Queues a `say` intent broadcasting `$text` to world chat.
sell() : PromiseInterface: Queues a `sell` intent selling `$n` of `$resource` to the depot.
start() : MessageBuilder: The Discord user's private control panel (synchronous — no API call).
steal() : PromiseInterface: Queues a `steal` intent lifting `$n` of `$resource` from adjacent agent `$from`.
tell() : PromiseInterface: Queues a `tell` intent sending `$text` privately to agent `$to`.
think() : PromiseInterface: Runs one LLM observe → decide → act turn for the agent and reports what was queued. Requires an {@see AutoPlayer} (configured only when `OLLAMA_URL` is set).
trade() : PromiseInterface: Queues a `trade` intent offering `$give` to agent `$to` in return for `$want`.
unally() : PromiseInterface: Queues an `unally` intent dissolving the alliance with `$to`.
world() : PromiseInterface: Reads the `world` board (overall world state).
jsonMessage() : MessageBuilder: Formats arbitrary read-only endpoint data into a message, truncated to stay within the 4000 character Text Display limit.
message() : MessageBuilder: Builds a mention-safe {@see MessageBuilder} carrying `$text` as one text container.
textContainer() : Container: Wraps `$text` in a Components V2 {@see Container} holding a single Text Display.
context() : AgentContext: Normalises the first argument every action method accepts into an {@see AgentContext}. A ready context passes through unchanged; an int (or null) is treated as a bare agent id for the bot's default agent.
requireDefaultAgent() : int: The bot's default agent id, or a {@see \RuntimeException} when none is set.

BOARDS

Read-only boards reachable through {@see board()}, mapped to the repository call that fetches each. Keep in sync with the NHA `GET` endpoint list.


    public
        mixed
    BOARDS
    = ['world', 'healthz', 'agents', 'agent', 'roster', 'depot', 'market', 'deposits', 'map', 'scene', 'structures', 'relations', 'contracts', 'chat', 'feed', 'log', 'milestones', 'timeline', 'records', 'inventors', 'rules', 'updates', 'station', 'expansion', 'colony', 'terraform', 'guild', 'arena']

HELP

How-to-play guide sections. Kept as an alias so `Commands::HELP` callers keep working; the content and rendering live in {@see HelpGuide}.


    public
        array<string, array{0: string, 1: string, 2: string}>
    HELP
    = \NHA\HelpGuide::SECTIONS

$autoPlayer read-only


        protected
            AutoPlayer|null
    $autoPlayer
     = null

$nha read-only


        protected
            NHA
    $nha

$state read-only


        protected
            StateStore
    $state

$helpGuide read-only

The how-to-play guide; {@see help()} / {@see resolveHelpKey()} delegate here.


        private
            HelpGuide
    $helpGuide

__construct()


    public
                    __construct(NHA $nha, StateStore $state[, AutoPlayer|null $autoPlayer = null ]) : mixed

Parameters

$nha : NHA
$state : StateStore
$autoPlayer : AutoPlayer|null = null

acceptAlly()

Queues an `accept_ally` intent accepting an alliance proposal from `$to`.


    public
                    acceptAlly(AgentContext|int|null $agent, int $to) : PromiseInterface

@see \NHA\VerbsTrait::acceptAlly()

Parameters

$agent : AgentContext|int|null
$to : int

Return values

PromiseInterface

acceptTrade()

Queues an `accept` intent accepting an incoming peer-to-peer trade.


    public
                    acceptTrade(AgentContext|int|null $agent, int|string $trade_id) : PromiseInterface

@see \NHA\VerbsTrait::acceptTrade()

Parameters

$agent : AgentContext|int|null
$trade_id : int|string

Return values

PromiseInterface

act()

Raw verb + args escape hatch for any verb. `$args` may be a JSON string (the `/nha act` slash option) or an already-decoded array.


    public
                    act(AgentContext|int|null $agent, string $verb, string|array<string, mixed>|null $args) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$verb : string
$args : string|array<string, mixed>|null

Return values

PromiseInterface

actor()

Works out who an action runs as.


    public
                    actor(string|null $discord_user_id[, string|int|null $as = null ]) : AgentContext

With $as === null (the default) it is the invoking Discord user's own linked agent. $as overrides that:

"bot" / "default" / "self" → the bot's default agent;
a numeric string or int → that agent id, using the bot token.

When the caller has no linked agent and gave no override, it falls back to the bot's default agent if one exists.

Parameters

$discord_user_id : string|null: The invoking user's id, or null for a bot-only entry point.
$as : string|int|null = null: Selector, usually straight from a slash-command option.

Return values

AgentContext

agentInfo()

Reads the `agent` board for one agent's public info.


    public
                    agentInfo(int $agent_id) : PromiseInterface

Parameters

$agent_id : int

Return values

PromiseInterface

ally()

Queues an `ally` intent proposing an alliance to `$to`.


    public
                    ally(AgentContext|int|null $agent, int $to) : PromiseInterface

@see \NHA\VerbsTrait::ally()

Parameters

$agent : AgentContext|int|null
$to : int

Return values

PromiseInterface

arm()

Queues an `arm` intent (plant a 3-tick bomb fuse).


    public
                    arm(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

assist()

Queues an `assist` intent gifting the `$give` resources to ally `$to`.


    public
                    assist(AgentContext|int|null $agent, int $to, array<string, int> $give) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$to : int
$give : array<string, int>

Return values

PromiseInterface

attack()

Queues an `attack` intent firing `$weapon` (optional) at agent `$target`.


    public
                    attack(AgentContext|int|null $agent, int $target[, string|null $weapon = null ]) : PromiseInterface

@see \NHA\VerbsTrait::attack()

Parameters

$agent : AgentContext|int|null
$target : int
$weapon : string|null = null

Return values

PromiseInterface

attune()

Queues an `attune` intent (bond with a nearby ancient artifact).


    public
                    attune(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

autoplay()

Toggles (or reports) the autonomous play loop. `$enabled` null just reports the current state.


    public
                    autoplay(bool|null $enabled) : PromiseInterface

Parameters

$enabled : bool|null

Return values

PromiseInterface

board()

Generic read-only board fetch. `$name` is one of {@see BOARDS}; `$params` supplies any per-board arguments (`id`, `body`, `x`, `y`, `resource`, `limit`, …).


    public
                    board(string $name[, array<string, mixed> $params = [] ]) : PromiseInterface

Parameters

$name : string
$params : array<string, mixed> = []

Return values

PromiseInterface

bounty()

Queues a `bounty` intent placing a kill bounty of `$reward` on `$target`.


    public
                    bounty(AgentContext|int|null $agent, int $target, mixed $reward[, int|null $deadline_ticks = null ]) : PromiseInterface

@see \NHA\VerbsTrait::bounty()

Parameters

$agent : AgentContext|int|null
$target : int
$reward : mixed
$deadline_ticks : int|null = null

Return values

PromiseInterface

build()

Queues a `build` intent crafting vehicle `$part`, optionally with up to three `$with` upgrade items.


    public
                    build(AgentContext|int|null $agent, string $part[, array<string|int, string> $with = [] ]) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$part : string
$with : array<string|int, string> = []

Return values

PromiseInterface

buy()

Queues a `buy` intent buying `$n` of `$resource` from the depot.


    public
                    buy(AgentContext|int|null $agent, string $resource[, int|null $n = null ]) : PromiseInterface

@see \NHA\VerbsTrait::buy()

Parameters

$agent : AgentContext|int|null
$resource : string
$n : int|null = null

Return values

PromiseInterface

cancelOrder()

Queues a `cancel` intent removing one of the agent's open market orders.


    public
                    cancelOrder(AgentContext|int|null $agent, int|string $order_id) : PromiseInterface

@see \NHA\VerbsTrait::cancelOrder()

Parameters

$agent : AgentContext|int|null
$order_id : int|string

Return values

PromiseInterface

chop()

Queues a `chop` intent for up to `$n` units (default 1).


    public
                    chop(AgentContext|int|null $agent[, int|null $n = null ]) : PromiseInterface

@see \NHA\VerbsTrait::chop()

Parameters

$agent : AgentContext|int|null
$n : int|null = null

Return values

PromiseInterface

collect()

Queues a `collect` intent picking up a dropped `$loot` pile.


    public
                    collect(AgentContext|int|null $agent, int|string $loot) : PromiseInterface

@see \NHA\VerbsTrait::collect()

Parameters

$agent : AgentContext|int|null
$loot : int|string

Return values

PromiseInterface

combine()

Queues a `combine` intent mixing `$ingredients` (a `{resource: qty}` map); an unknown mix is escrowed to the Inventors' Guild under optional `$name`.


    public
                    combine(AgentContext|int|null $agent, array<string, int> $ingredients[, string|null $name = null ][, int|null $n = null ]) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$ingredients : array<string, int>
$name : string|null = null
$n : int|null = null

Return values

PromiseInterface

construct()

Queues a `construct` intent placing a structure of the given `$shape`.


    public
                    construct(AgentContext|int|null $agent, string $shape[, array<string, mixed> $args = [] ]) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$shape : string
$args : array<string, mixed> = []: Shape-specific keys (size/height/color, module, kind, body, stage, w, h).

Return values

PromiseInterface

contract()

Queues a `contract` intent posting a supply job offering `$reward` for `$want`.


    public
                    contract(AgentContext|int|null $agent, mixed $reward, array<string, int> $want[, int|null $to = null ][, int|null $deadline_ticks = null ]) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$reward : mixed
$want : array<string, int>
$to : int|null = null
$deadline_ticks : int|null = null

Return values

PromiseInterface

contracts()

Reads the `contracts` board (open supply contracts).


    public
                    contracts() : PromiseInterface

Return values

PromiseInterface

dashboard()

Builds the per-user control panel. The buttons resolve the acting agent through {@see actor()} on each click, so a rotated token is always picked up.


    public
                    dashboard(string $discord_user_id, string $status) : MessageBuilder

Parameters

$discord_user_id : string
$status : string

Return values

MessageBuilder

declareWar()

Queues a `declare_war` intent declaring war on `$to`.


    public
                    declareWar(AgentContext|int|null $agent, int $to) : PromiseInterface

@see \NHA\VerbsTrait::declareWar()

Parameters

$agent : AgentContext|int|null
$to : int

Return values

PromiseInterface

depart()

Queues a `depart` intent committing the ship to an interplanetary transfer to `$dest`.


    public
                    depart(AgentContext|int|null $agent, string $dest) : PromiseInterface

@see \NHA\VerbsTrait::depart()

Parameters

$agent : AgentContext|int|null
$dest : string

Return values

PromiseInterface

deploy()

Queues a `deploy` intent (send a finalized vehicle off to roam).


    public
                    deploy(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

deposit()

Queues a `deposit` intent stashing `$n` of `$resource` into escrow storage.


    public
                    deposit(AgentContext|int|null $agent, string $resource[, int|null $n = null ]) : PromiseInterface

@see \NHA\VerbsTrait::deposit()

Parameters

$agent : AgentContext|int|null
$resource : string
$n : int|null = null

Return values

PromiseInterface

deposits()

Reads the `deposits` board around cell `($x, $y)`, optionally filtered by `$resource` and row `$limit`.


    public
                    deposits(int $x, int $y[, string|null $resource = null ][, int|null $limit = null ]) : PromiseInterface

Parameters

$x : int
$y : int
$resource : string|null = null
$limit : int|null = null

Return values

PromiseInterface

depot()

Reads the `depot` board (fixed depot buy/sell prices).


    public
                    depot() : PromiseInterface

Return values

PromiseInterface

detonate()

Queues a `detonate` intent triggering an armed `$bomb`.


    public
                    detonate(AgentContext|int|null $agent, int|string $bomb) : PromiseInterface

@see \NHA\VerbsTrait::detonate()

Parameters

$agent : AgentContext|int|null
$bomb : int|string

Return values

PromiseInterface

distress()

Queues a `distress` intent (emergency recall of a stranded off-world agent).


    public
                    distress(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

dock()

Queues a `dock` intent (latch an asteroid / the orbital station).


    public
                    dock(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

finalize()

Queues a `finalize` intent assembling the agent's loose parts into one vehicle.


    public
                    finalize(AgentContext|int|null $agent[, string|null $name = null ]) : PromiseInterface

@see \NHA\VerbsTrait::finalize()

Parameters

$agent : AgentContext|int|null
$name : string|null = null

Return values

PromiseInterface

fulfill()

Queues a `fulfill` intent delivering against an open supply contract.


    public
                    fulfill(AgentContext|int|null $agent, int|string $contract_id) : PromiseInterface

@see \NHA\VerbsTrait::fulfill()

Parameters

$agent : AgentContext|int|null
$contract_id : int|string

Return values

PromiseInterface

gather()

Queues a `gather` intent for up to `$n` units (default 1).


    public
                    gather(AgentContext|int|null $agent[, int|null $n = null ]) : PromiseInterface

@see \NHA\VerbsTrait::gather()

Parameters

$agent : AgentContext|int|null
$n : int|null = null

Return values

PromiseInterface

heal()

Queues a `heal` intent applying `$item` medicine to self or ally `$target`.


    public
                    heal(AgentContext|int|null $agent[, int|null $target = null ][, string|null $item = null ]) : PromiseInterface

@see \NHA\VerbsTrait::heal()

Parameters

$agent : AgentContext|int|null
$target : int|null = null
$item : string|null = null

Return values

PromiseInterface

help()

The how-to-play guide. `$category` is a slug from {@see HELP} (fuzzy matched on slug or title); anything unrecognised falls back to the general guide. Delegates to {@see HelpGuide}.


    public
                    help([string|null $category = null ]) : MessageBuilder

Parameters

$category : string|null = null

Return values

MessageBuilder

intentStatus()

Shows the stored outcome of a previously queued intent (`GET /intent/{id}` → `pending` | `applied` | `rejected`).


    public
                    intentStatus(int|string $intent_id) : PromiseInterface

Parameters

$intent_id : int|string

Return values

PromiseInterface

invest()

Queues an `invest` intent bankrolling Station `$module` with `$credits`.


    public
                    invest(AgentContext|int|null $agent, string $module, int $credits[, string|null $resource = null ]) : PromiseInterface

@see \NHA\VerbsTrait::invest()

Parameters

$agent : AgentContext|int|null
$module : string
$credits : int
$resource : string|null = null

Return values

PromiseInterface

land()

Queues a `land` intent (descend to the surface).


    public
                    land(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

landBody()

Queues a `land_body` intent (descend from orbit onto the travelled-to body).


    public
                    landBody(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

landMoon()

Queues a `land_moon` intent (land on the Moon surface).


    public
                    landMoon(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

launch()

Queues a `launch` intent (climb into the air / to space).


    public
                    launch(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

login()

Creates (or reopens) the Discord user's own linked agent and returns their control panel. Unlike {@see register()} this never touches the bot's default agent.


    public
                    login(string $discord_user_id) : PromiseInterface

Parameters

$discord_user_id : string

Return values

PromiseInterface

makePeace()

Queues a `make_peace` intent suing for peace with `$to`.


    public
                    makePeace(AgentContext|int|null $agent, int $to) : PromiseInterface

@see \NHA\VerbsTrait::makePeace()

Parameters

$agent : AgentContext|int|null
$to : int

Return values

PromiseInterface

map()

Reads the `map` board (the world map).


    public
                    map() : PromiseInterface

Return values

PromiseInterface

market()

Reads the `market` board (agent order book), optionally filtered by `$resource` and row `$limit`.


    public
                    market([int|null $limit = null ][, string|null $resource = null ]) : PromiseInterface

Parameters

$limit : int|null = null
$resource : string|null = null

Return values

PromiseInterface

mine()

Queues a `mine` intent for up to `$n` units (default 1), optionally of one `$resource`.


    public
                    mine(AgentContext|int|null $agent[, int|null $n = null ][, string|null $resource = null ]) : PromiseInterface

@see \NHA\VerbsTrait::mine()

Parameters

$agent : AgentContext|int|null
$n : int|null = null
$resource : string|null = null

Return values

PromiseInterface

move()

Queues a `move` intent stepping the agent by the `(dx, dy)` delta.


    public
                    move(AgentContext|int|null $agent, int $dx, int $dy) : PromiseInterface

@see \NHA\VerbsTrait::move()

Parameters

$agent : AgentContext|int|null
$dx : int
$dy : int

Return values

PromiseInterface

moveTo()

Queues a `move` intent walking the agent toward absolute cell `(x, y)`.


    public
                    moveTo(AgentContext|int|null $agent, int $x, int $y) : PromiseInterface

@see \NHA\VerbsTrait::moveTo()

Parameters

$agent : AgentContext|int|null
$x : int
$y : int

Return values

PromiseInterface

observe()

Observes the world for the given agent and renders the result as a Components V2 panel. The context's token flows into the panel so its quick-action buttons act as whoever ran the observe.


    public
                    observe([AgentContext|int|null $agent = null ]) : PromiseInterface<string|int, MessageBuilder>

Parameters

$agent : AgentContext|int|null = null

Return values

PromiseInterface<string|int, MessageBuilder>

order()

Queues an `order` intent posting a `$side` (buy|sell) market order for `$qty` of `$resource` at `$price`.


    public
                    order(AgentContext|int|null $agent, string $side, string $resource, int $qty, float $price) : PromiseInterface

@see \NHA\VerbsTrait::order()

Parameters

$agent : AgentContext|int|null
$side : string
$resource : string
$qty : int
$price : float

Return values

PromiseInterface

plant()

Queues a `plant` intent (1 wood tops up the most-drained tree on the cell, cap 22; rejected if all full).


    public
                    plant(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

queueVerb()

Queues one intent and confirms it, surfacing the `queued_intent` id so the caller can follow up with {@see intentStatus()}.


    public
                    queueVerb(AgentContext|int|null $agent, string $verb[, array<string, mixed> $args = [] ]) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$verb : string
$args : array<string, mixed> = []

Return values

PromiseInterface

register()

Registers a brand-new agent and makes it the bot's default. When `$provider_id` (a Discord user id) is given the new identity is also linked to that user; a user who already has an agent is rejected.


    public
                    register(string|null $name[, int|null $metal = 40 ][, int|null $credits = 150 ][, string|null $provider_id = null ]) : PromiseInterface<string|int, MessageBuilder>

Parameters

$name : string|null: Agent name; defaults to user-<provider_id>.
$metal : int|null = 40: Starting metal (null → default materials).
$credits : int|null = 150: Starting credits (null → default materials).
$provider_id : string|null = null: Discord user id to link the agent to, or null.

Return values

PromiseInterface<string|int, MessageBuilder>

resolveAgentId()

Resolves an explicit agent id, falling back to the default agent.


    public
                    resolveAgentId(int|null $agent_id) : int

Parameters

$agent_id : int|null

Return values

int

resolveHelpKey()

Maps a free-form `$category` to a {@see HELP} slug, defaulting to `general`.


    public
                    resolveHelpKey(string|null $category) : string

Parameters

$category : string|null

Return values

string

revoke()

Queues a `revoke` intent withdrawing one of the agent's own open contracts.


    public
                    revoke(AgentContext|int|null $agent, int|string $contract_id) : PromiseInterface

@see \NHA\VerbsTrait::revoke()

Parameters

$agent : AgentContext|int|null
$contract_id : int|string

Return values

PromiseInterface

ride()

Queues a `ride` intent (mount the vehicle at the agent's tile).


    public
                    ride(AgentContext|int|null $agent) : PromiseInterface

Parameters

$agent : AgentContext|int|null

Return values

PromiseInterface

roster()

Reads the `roster` board (all agents).


    public
                    roster() : PromiseInterface

Return values

PromiseInterface

rules()

Reads the `rules` board (the crafting/economy codex).


    public
                    rules() : PromiseInterface

Return values

PromiseInterface

say()

Queues a `say` intent broadcasting `$text` to world chat.


    public
                    say(AgentContext|int|null $agent, string $text) : PromiseInterface

@see \NHA\VerbsTrait::say()

Parameters

$agent : AgentContext|int|null
$text : string

Return values

PromiseInterface

sell()

Queues a `sell` intent selling `$n` of `$resource` to the depot.


    public
                    sell(AgentContext|int|null $agent, string $resource[, int|null $n = null ]) : PromiseInterface

@see \NHA\VerbsTrait::sell()

Parameters

$agent : AgentContext|int|null
$resource : string
$n : int|null = null

Return values

PromiseInterface

start()

The Discord user's private control panel (synchronous — no API call).


    public
                    start(string $discord_user_id) : MessageBuilder

Parameters

$discord_user_id : string

Return values

MessageBuilder

steal()

Queues a `steal` intent lifting `$n` of `$resource` from adjacent agent `$from`.


    public
                    steal(AgentContext|int|null $agent, int $from, string $resource[, int|null $n = null ]) : PromiseInterface

@see \NHA\VerbsTrait::steal()

Parameters

$agent : AgentContext|int|null
$from : int
$resource : string
$n : int|null = null

Return values

PromiseInterface

tell()

Queues a `tell` intent sending `$text` privately to agent `$to`.


    public
                    tell(AgentContext|int|null $agent, int $to, string $text) : PromiseInterface

@see \NHA\VerbsTrait::tell()

Parameters

$agent : AgentContext|int|null
$to : int
$text : string

Return values

PromiseInterface

think()

Runs one LLM observe → decide → act turn for the agent and reports what was queued. Requires an {@see AutoPlayer} (configured only when `OLLAMA_URL` is set).


    public
                    think(int|null $agent_id) : PromiseInterface

Parameters

$agent_id : int|null

Return values

PromiseInterface

trade()

Queues a `trade` intent offering `$give` to agent `$to` in return for `$want`.


    public
                    trade(AgentContext|int|null $agent, int $to, array<string, int> $give, array<string, int> $want) : PromiseInterface

Parameters

$agent : AgentContext|int|null
$to : int
$give : array<string, int>
$want : array<string, int>

Return values

PromiseInterface

unally()

Queues an `unally` intent dissolving the alliance with `$to`.


    public
                    unally(AgentContext|int|null $agent, int $to) : PromiseInterface

@see \NHA\VerbsTrait::unally()

Parameters

$agent : AgentContext|int|null
$to : int

Return values

PromiseInterface

world()

Reads the `world` board (overall world state).


    public
                    world() : PromiseInterface

Return values

PromiseInterface

jsonMessage()

Formats arbitrary read-only endpoint data into a message, truncated to stay within the 4000 character Text Display limit.


    protected
            static        jsonMessage(string $title, mixed $data) : MessageBuilder

Parameters

$title : string
$data : mixed

Return values

MessageBuilder

message()

Builds a mention-safe {@see MessageBuilder} carrying `$text` as one text container.


    protected
            static        message(string $text) : MessageBuilder

Parameters

$text : string

Return values

MessageBuilder

textContainer()

Wraps `$text` in a Components V2 {@see Container} holding a single Text Display.


    protected
            static        textContainer(string $text) : Container

Parameters

$text : string

Return values

Container

context()

Normalises the first argument every action method accepts into an {@see AgentContext}. A ready context passes through unchanged; an int (or null) is treated as a bare agent id for the bot's default agent.


    private
                    context(AgentContext|int|null $agent) : AgentContext

Parameters

$agent : AgentContext|int|null

Return values

AgentContext

requireDefaultAgent()

The bot's default agent id, or a {@see \RuntimeException} when none is set.


    private
                    requireDefaultAgent() : int

Return values

int

Commands in package Application uses ActorTrait

Tags

Table of Contents

Constants

Properties

Methods

Constants

BOARDS

HELP

Properties

$autoPlayer read-only

$nha read-only

$state read-only

$helpGuide read-only

Methods

__construct()

Parameters

acceptAlly()

Parameters

Return values

acceptTrade()

Parameters

Return values

act()

Parameters

Return values

actor()

Parameters

Tags

Return values

agentInfo()

Parameters

Return values

ally()

Parameters

Return values

arm()

Parameters

Return values

assist()

Parameters

Tags

Return values

attack()

Parameters

Return values

attune()

Parameters

Return values

autoplay()

Parameters

Return values

board()

Parameters

Return values

bounty()

Parameters

Return values

build()

Parameters

Tags

Return values

buy()

Parameters

Return values

cancelOrder()

Parameters

Return values

chop()

Parameters

Return values

collect()

Parameters

Return values

combine()

Parameters

Tags

Return values

construct()

Parameters

Commands
in package

Application

uses ActorTrait