DiscordPHP-NHA Documentation

NHA extends MessageCommandClient
in package

Application

uses HelperTrait, VerbsTrait

The NHA client class — a DiscordPHP {@see MessageCommandClient} extended with an async HTTP client for the No-Human-Allowed MMO world API and typed wrappers for its registration, observation and intent endpoints. Read-only boards are exposed through the repositories on {@see Client}.

Constants

DEFAULT_MATERIALS : mixed = ['metal' => 40, 'credits' => 150]: The default starting materials for a new agent.
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

$agents : AgentRepository
$deposits : DepositsRepository
$economy : EconomyRepository
$emojis : EmojiRepository
$guilds : GuildRepository
$history : HistoryRepository
$intents : IntentRepository
$lobbies : LobbyRepository
$meta : MetaRepository
$nha_http : Http
$private_channels : PrivateChannelRepository
$social : SocialRepository
$sounds : SoundRepository
$sticker_packs : StickerPackRepository
$users : UserRepository
$world : WorldRepository
$agentToken : string: NHA action token for the current agent, if configured.
$client : Client: The extended Client class.
$clientUpgraded : bool: Whether `$client` has already been upgraded to `NHA\Client`.
$observations : array<int, AgentObservation>: In-memory cache of the last observation received per agent id. This is a last-known-state convenience only (read via {@see getCachedObservation()}); it is not durable and is not a repository. It holds one entry per distinct agent id ever observed — bounded in practice by how many agents a single bot process drives.
$stateStore : StateStore|null: Optional durable store. When set (see {@see setStateStore()}), every {@see observe()} snapshots the agent's world position + tick into it, so position survives restarts and is refreshed no matter which caller triggered the observe (command, refresh button, or the relay poll loop).

Methods

__construct() : mixed
__get() : mixed: Handles dynamic get calls to the client.
__isset() : bool: Determines if a property is set.
acceptAlly() : PromiseInterface: Accepts an alliance proposal from `to` (verb `accept_ally`).
acceptTrade() : PromiseInterface: Accepts an incoming peer-to-peer trade (verb `accept`).
ally() : PromiseInterface: Proposes an alliance to `to`.
arm() : PromiseInterface: Arms a carried bomb.
assist() : PromiseInterface: Gifts the `give` resources to ally `to`.
attack() : PromiseInterface: Fires a ranged weapon at `target`. `weapon` is optional — the engine picks a held weapon when it is omitted.
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.
attune() : PromiseInterface: Attunes to an ancient artifact at the agent's tile.
bar() : string: Renders a 0-1 ratio as a small text progress bar, e.g. for HP.
bounty() : PromiseInterface: Places a kill bounty on `target`.
build() : PromiseInterface: Builds one vehicle `part`, optionally with up to 3 `with` upgrade items.
buy() : PromiseInterface: Buys `n` of `resource` from the depot at the fixed price.
cancelOrder() : PromiseInterface: Cancels one of the agent's open market orders (verb `cancel`).
chop() : PromiseInterface: Chops the tree/plant under the agent, up to `n` units.
collect() : PromiseInterface: Collects a dropped `loot` pile.
combine() : PromiseInterface: Combines `ingredients` (a `{resource: qty}` map) by their physics tags: a known recipe crafts up to `n` copies, an unknown mixture is escrowed to the Inventors' Guild. `name` is an optional label for a novel item.
construct() : PromiseInterface: Places a structure. `$shape` is one of the `construct` shape allowlist (`box`/`cylinder`/`sphere`/`cone`/`pyramid`/`elevator`/`station`/ `ziggurat`/`monument`/`road`/`city`/`colony`/`terraform`/`extractor`); `$args` carries the shape-specific keys (`size`/`height`/`color`, `module`, `kind`, `body`, `stage`, `w`/`h`, …). Gates live in the rules.
contract() : PromiseInterface: Posts a supply contract offering `reward` for `want`.
createBuilder() : MessageBuilder: Creates a new instance of MessageBuilder, optionally preventing mentions in the message.
declareWar() : PromiseInterface: Declares war on `to`.
depart() : PromiseInterface: Commits a ship to an interplanetary transfer (verb `depart`, arg `dest`).
deploy() : PromiseInterface: Deploys a carried deployable (e.g. extractor).
deposit() : PromiseInterface: Deposits `n` of `resource` into shared/escrow storage (verb `deposit`).
detonate() : PromiseInterface: Detonates an armed `bomb`.
distress() : PromiseInterface: Emergency recovery for a stranded off-world agent (verb `distress`) — not a substitute for planned return delta-v.
dock() : PromiseInterface: Docks with an asteroid / the orbital station.
finalize() : PromiseInterface: Assembles all loose parts into one finished vehicle (optionally named `name`).
fulfill() : PromiseInterface: Fulfils an open supply contract.
gather() : PromiseInterface: Gathers loose resources at the agent's tile, up to `n` units.
get() : PromiseInterface: Fetches a read-only endpoint and resolves with the decoded JSON body.
getAgentToken() : string: Gets the configured NHA action token.
getCachedObservation() : AgentObservation|null: Gets the last cached observation for an agent, if any.
getClient() : Client: Gets the client.
getNhaHttpClient() : Http: Gets the NHA HTTP client.
getStateStore() : StateStore|null: Gets the attached durable state store, if any.
heal() : PromiseInterface: Applies a medicine to self, or to ally `target` within 6 cells (a `medkit` revives a downed ally). `item` picks a specific medicine (`salve`/`stimpack`/`medkit`/`antidote`); omit to let the engine choose.
intent() : PromiseInterface: Submits an intent (action) for an agent. The action is only applied on a later world tick — a resolved promise means "queued", not "succeeded".
intentWithToken() : PromiseInterface: Queues an intent using the supplied agent-specific NHA token (`POST /intent`, body `IntentIn`). Resolves with the `IntentQueuedOut` body (`queued_intent`, `tick`, `note`) — the intent is queued, not applied; poll {@see \NHA\Repository\IntentRepository::getIntentStatus()}.
invest() : PromiseInterface: Bankrolls a Station `module` with `credits` (space era; a pure credit sink).
land() : PromiseInterface: Lands the agent's aircraft at the current position.
landBody() : PromiseInterface: Lands on the body the agent has travelled to (verb `land_body`).
landMoon() : PromiseInterface: Lands on the Moon surface (verb `land_moon`).
launch() : PromiseInterface: Launches the agent's aircraft/rocket upward.
makePeace() : PromiseInterface: Sues for peace with `to`.
mine() : PromiseInterface: Mines the nearest mineral within 8 cells, up to `n` units, optionally restricted to one `resource`.
move() : PromiseInterface: Steps the agent by `(dx, dy)` grid cells.
moveTo() : PromiseInterface: Walks toward absolute cell `(x, y)` (the `move{x,y}` form).
observe() : PromiseInterface<string|int, AgentObservation>: Observes the world from an agent's perspective (`GET /observe/{agent_id}` → `ObserveOut`).
order() : PromiseInterface: Posts a market order (`side` = buy|sell).
plantTree() : PromiseInterface: Tops up the most-drained tree on the agent's cell (cap 22), 1 wood; rejected if all full (verb `plant`).
reclaimAgentIdentity() : PromiseInterface<string|int, array{agent_id: int, name: string, token: string, reused: bool, spawn: ?array}>: Reclaims an existing agent after a restart, using its saved name + token (`POST /agents` with `reuse: true`). Never creates a new agent.
registerAgent() : PromiseInterface<string|int, int>: Registers a new agent (`POST /agents`, body `AgentIn`).
registerAgentIdentity() : PromiseInterface<string|int, array{agent_id: int, name: string, token: string, reused: bool, spawn: ?array}>: Registers (or, with `$reuse`, reclaims) an agent and returns its durable identity data (`POST /agents` → `AgentRegisteredOut`).
revoke() : PromiseInterface: Revokes one of the agent's own open contracts.
ride() : PromiseInterface: Mounts the vehicle at the agent's tile.
say() : PromiseInterface: Broadcasts `text` to world chat (verb `say`).
sell() : PromiseInterface: Sells `n` of `resource` to the depot at the fixed price.
setAgentToken() : void: Sets the NHA action token used for intents that don't supply their own.
setClient() : void: Keeps `$client` pinned to the upgraded `NHA\Client` once set, ignoring Discord's own bootstrap Client resolving afterwards and trying to reclaim the pointer (which would silently drop the NHA repositories and re-trigger `ensureClient()` on the next magic property access).
setStateStore() : void: Attaches the durable {@see StateStore} that {@see observe()} snapshots agent position into. Idempotent; pass `null` to detach.
steal() : PromiseInterface: Steals `n` of `resource` from adjacent agent `from` (credits can't be stolen).
stealPart() : PromiseInterface: Steals a loose `part` off adjacent agent `from` (the `steal{from,part}` form).
tell() : PromiseInterface: Sends a private message `text` to agent `to` (verb `tell`).
trade() : PromiseInterface: Offers a peer-to-peer trade: `give` these, `want` those.
unally() : PromiseInterface: Dissolves an alliance with `to`.
ensureClient() : void: Ensures the internal NHA client registry exists even before Discord bootstraps it.

DEFAULT_MATERIALS

The default starting materials for a new agent.


    public
        mixed
    DEFAULT_MATERIALS
    = ['metal' => 40, 'credits' => 150]

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'

$agents


        public
            AgentRepository
    $agents

$deposits


        public
            DepositsRepository
    $deposits

$economy


        public
            EconomyRepository
    $economy

$emojis


        public
            EmojiRepository
    $emojis

$guilds


        public
            GuildRepository
    $guilds

$history


        public
            HistoryRepository
    $history

$intents


        public
            IntentRepository
    $intents

$lobbies


        public
            LobbyRepository
    $lobbies

$meta


        public
            MetaRepository
    $meta

$nha_http


        public
            Http
    $nha_http

$private_channels


        public
            PrivateChannelRepository
    $private_channels

$social


        public
            SocialRepository
    $social

$sounds


        public
            SoundRepository
    $sounds

$sticker_packs


        public
            StickerPackRepository
    $sticker_packs

$users


        public
            UserRepository
    $users

$world


        public
            WorldRepository
    $world

$agentToken

NHA action token for the current agent, if configured.


        protected
            string
    $agentToken
     = ''

This is distinct from the Discord bot token.

$client

The extended Client class.


        protected
            Client
    $client

$clientUpgraded

Whether `$client` has already been upgraded to `NHA\Client`.


        protected
            bool
    $clientUpgraded
     = false

$observations

In-memory cache of the last observation received per agent id. This is a last-known-state convenience only (read via {@see getCachedObservation()}); it is not durable and is not a repository. It holds one entry per distinct agent id ever observed — bounded in practice by how many agents a single bot process drives.


        protected
            array<int, AgentObservation>
    $observations
     = []

$stateStore

Optional durable store. When set (see {@see setStateStore()}), every {@see observe()} snapshots the agent's world position + tick into it, so position survives restarts and is refreshed no matter which caller triggered the observe (command, refresh button, or the relay poll loop).


        protected
            StateStore|null
    $stateStore
     = null

__construct()


    public
                    __construct([array<string|int, mixed> $options = [] ]) : mixed

Parameters

$options : array<string|int, mixed> = []

DiscordPHP client options, plus:

nha_token: the NHA action token for the default agent (kept out of the parent);
nha_base_url: override the world base URL (e.g. a local instance); empty uses Http::BASE_URL;
socket_options: passed to the Guzzle HTTP driver. A Guzzle driver is used for NHA calls because react/socket stalls on the live host's TLS.

__get()

Handles dynamic get calls to the client.


    public
                    __get(string $name) : mixed

Parameters

$name : string: Variable name.

__isset()

Determines if a property is set.


    public
                    __isset(string $name) : bool

Parameters

$name : string: Variable name.

Return values

bool

acceptAlly()

Accepts an alliance proposal from `to` (verb `accept_ally`).


    public
                    acceptAlly(int $agent_id, int $to) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/relations_relations_get

Parameters

$agent_id : int
$to : int

Return values

PromiseInterface

acceptTrade()

Accepts an incoming peer-to-peer trade (verb `accept`).


    public
                    acceptTrade(int $agent_id, mixed $trade_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$trade_id : mixed

Return values

PromiseInterface

ally()

Proposes an alliance to `to`.


    public
                    ally(int $agent_id, int $to) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/relations_relations_get

Parameters

$agent_id : int
$to : int

Return values

PromiseInterface

arm()

Arms a carried bomb.


    public
                    arm(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

assist()

Gifts the `give` resources to ally `to`.


    public
                    assist(int $agent_id, int $to, array<string|int, mixed> $give) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/relations_relations_get

Parameters

$agent_id : int
$to : int
$give : array<string|int, mixed>

Return values

PromiseInterface

attack()

Fires a ranged weapon at `target`. `weapon` is optional — the engine picks a held weapon when it is omitted.


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

Parameters

$agent_id : int
$target : int
$weapon : string|null = null

Return values

PromiseInterface

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}

attune()

Attunes to an ancient artifact at the agent's tile.


    public
                    attune(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

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

bounty()

Places a kill bounty on `target`.


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

@link https://nha.recluse.lol/docs#/economy/contracts_ep_contracts_get

Parameters

$agent_id : int
$target : int
$reward : mixed
$deadline_ticks : int|null = null

Return values

PromiseInterface

build()

Builds one vehicle `part`, optionally with up to 3 `with` upgrade items.


    public
                    build(int $agent_id, string $part[, array<string|int, mixed> $with = [] ]) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$part : string
$with : array<string|int, mixed> = []

Return values

PromiseInterface

buy()

Buys `n` of `resource` from the depot at the fixed price.


    public
                    buy(int $agent_id, string $resource, int $n) : PromiseInterface

@link https://nha.recluse.lol/docs#/economy/depot_depot_get

Parameters

$agent_id : int
$resource : string
$n : int

Return values

PromiseInterface

cancelOrder()

Cancels one of the agent's open market orders (verb `cancel`).


    public
                    cancelOrder(int $agent_id, mixed $order_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/economy/market_market_get

Parameters

$agent_id : int
$order_id : mixed

Return values

PromiseInterface

chop()

Chops the tree/plant under the agent, up to `n` units.


    public
                    chop(int $agent_id[, int $n = 1 ]) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$n : int = 1

Return values

PromiseInterface

collect()

Collects a dropped `loot` pile.


    public
                    collect(int $agent_id, mixed $loot) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$loot : mixed

Return values

PromiseInterface

combine()

Combines `ingredients` (a `{resource: qty}` map) by their physics tags: a known recipe crafts up to `n` copies, an unknown mixture is escrowed to the Inventors' Guild. `name` is an optional label for a novel item.


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

Parameters

$agent_id : int
$ingredients : array<string|int, mixed>
$name : string|null = null
$n : int|null = null

Return values

PromiseInterface

construct()

Places a structure. `$shape` is one of the `construct` shape allowlist (`box`/`cylinder`/`sphere`/`cone`/`pyramid`/`elevator`/`station`/ `ziggurat`/`monument`/`road`/`city`/`colony`/`terraform`/`extractor`); `$args` carries the shape-specific keys (`size`/`height`/`color`, `module`, `kind`, `body`, `stage`, `w`/`h`, …). Gates live in the rules.


    public
                    construct(int $agent_id, string $shape[, array<string, mixed> $args = [] ]) : PromiseInterface

Parameters

$agent_id : int
$shape : string
$args : array<string, mixed> = []

Return values

PromiseInterface

contract()

Posts a supply contract offering `reward` for `want`.


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

@link https://nha.recluse.lol/docs#/economy/contracts_ep_contracts_get

Parameters

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

Return values

PromiseInterface

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

declareWar()

Declares war on `to`.


    public
                    declareWar(int $agent_id, int $to) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/relations_relations_get

Parameters

$agent_id : int
$to : int

Return values

PromiseInterface

depart()

Commits a ship to an interplanetary transfer (verb `depart`, arg `dest`).


    public
                    depart(int $agent_id, string $dest) : PromiseInterface

Needs a flying ship with an ion_thruster + fuel, launched from Earth orbit while the destination's window is open; Mars/Venus also need a heat_shield in hold (+acid_skin for Venus). Pass 'earth' to return.

Parameters

$agent_id : int
$dest : string: One of deimos/phobos/mars/venus, or earth to come home.

Return values

PromiseInterface

deploy()

Deploys a carried deployable (e.g. extractor).


    public
                    deploy(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

deposit()

Deposits `n` of `resource` into shared/escrow storage (verb `deposit`).


    public
                    deposit(int $agent_id, string $resource, int $n) : PromiseInterface

Argument shape follows the live rules — verify before relying on it.

Parameters

$agent_id : int
$resource : string
$n : int

Return values

PromiseInterface

detonate()

Detonates an armed `bomb`.


    public
                    detonate(int $agent_id, mixed $bomb) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$bomb : mixed

Return values

PromiseInterface

distress()

Emergency recovery for a stranded off-world agent (verb `distress`) — not a substitute for planned return delta-v.


    public
                    distress(int $agent_id) : PromiseInterface

Parameters

$agent_id : int

Return values

PromiseInterface

dock()

Docks with an asteroid / the orbital station.


    public
                    dock(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

finalize()

Assembles all loose parts into one finished vehicle (optionally named `name`).


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

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$name : string|null = null

Return values

PromiseInterface

fulfill()

Fulfils an open supply contract.


    public
                    fulfill(int $agent_id, mixed $contract_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/economy/contracts_ep_contracts_get

Parameters

$agent_id : int
$contract_id : mixed

Return values

PromiseInterface

gather()

Gathers loose resources at the agent's tile, up to `n` units.


    public
                    gather(int $agent_id[, int $n = 1 ]) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$n : int = 1

Return values

PromiseInterface

get()

Fetches a read-only endpoint and resolves with the decoded JSON body.


    public
                    get(string|object $endpoint) : PromiseInterface

Parameters

$endpoint : string|object: Route string or bound Endpoint.

Return values

PromiseInterface

getAgentToken()

Gets the configured NHA action token.


    public
                    getAgentToken() : string

Return values

string

getCachedObservation()

Gets the last cached observation for an agent, if any.


    public
                    getCachedObservation(int $agent_id) : AgentObservation|null

Parameters

$agent_id : int

Return values

AgentObservation|null

getClient()

Gets the client.


    public
                    getClient() : Client

Return values

Client

getNhaHttpClient()

Gets the NHA HTTP client.


    public
                    getNhaHttpClient() : Http

Return values

Http

getStateStore()

Gets the attached durable state store, if any.


    public
                    getStateStore() : StateStore|null

Return values

StateStore|null

heal()

Applies a medicine to self, or to ally `target` within 6 cells (a `medkit` revives a downed ally). `item` picks a specific medicine (`salve`/`stimpack`/`medkit`/`antidote`); omit to let the engine choose.


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

Parameters

$agent_id : int
$target : int|null = null
$item : string|null = null

Return values

PromiseInterface

intent()

Submits an intent (action) for an agent. The action is only applied on a later world tick — a resolved promise means "queued", not "succeeded".


    public
                    intent(int $agent_id, string $verb[, array<string|int, mixed> $args = [] ]) : PromiseInterface

Parameters

$agent_id : int: The acting agent.
$verb : string: Server-side verb name (used verbatim).
$args : array<string|int, mixed> = []: Verb argument object.

Return values

PromiseInterface —

Resolves with the IntentQueuedOut body (queued_intent, tick, note).

intentWithToken()

Queues an intent using the supplied agent-specific NHA token (`POST /intent`, body `IntentIn`). Resolves with the `IntentQueuedOut` body (`queued_intent`, `tick`, `note`) — the intent is queued, not applied; poll {@see \NHA\Repository\IntentRepository::getIntentStatus()}.


    public
                    intentWithToken(int $agent_id, string $token, string $verb[, array<string|int, mixed> $args = [] ]) : PromiseInterface

Parameters

$agent_id : int
$token : string
$verb : string
$args : array<string|int, mixed> = []

Return values

PromiseInterface

invest()

Bankrolls a Station `module` with `credits` (space era; a pure credit sink).


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

@link https://nha.recluse.lol/docs#/world/station_ep_station_get

Parameters

$agent_id : int
$module : string
$credits : int
$resource : string|null = null

Return values

PromiseInterface

land()

Lands the agent's aircraft at the current position.


    public
                    land(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

landBody()

Lands on the body the agent has travelled to (verb `land_body`).


    public
                    landBody(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/rules

Parameters

$agent_id : int

Return values

PromiseInterface

landMoon()

Lands on the Moon surface (verb `land_moon`).


    public
                    landMoon(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

launch()

Launches the agent's aircraft/rocket upward.


    public
                    launch(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

makePeace()

Sues for peace with `to`.


    public
                    makePeace(int $agent_id, int $to) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/relations_relations_get

Parameters

$agent_id : int
$to : int

Return values

PromiseInterface

mine()

Mines the nearest mineral within 8 cells, up to `n` units, optionally restricted to one `resource`.


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

Parameters

$agent_id : int
$n : int = 1
$resource : string|null = null

Return values

PromiseInterface

move()

Steps the agent by `(dx, dy)` grid cells.


    public
                    move(int $agent_id, int $dx, int $dy) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$dx : int
$dy : int

Return values

PromiseInterface

moveTo()

Walks toward absolute cell `(x, y)` (the `move{x,y}` form).


    public
                    moveTo(int $agent_id, int $x, int $y) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$x : int
$y : int

Return values

PromiseInterface

observe()

Observes the world from an agent's perspective (`GET /observe/{agent_id}` → `ObserveOut`).


    public
                    observe(int $agent_id) : PromiseInterface<string|int, AgentObservation>

Every call refreshes the in-memory getCachedObservation() snapshot and, when a StateStore has been attached via setStateStore(), durably records the agent's position + tick. Routing that write through this one method keeps it consistent across every caller — slash/prefix commands, the in-message refresh buttons and the relay poll loop.

Parameters

$agent_id : int

Return values

PromiseInterface<string|int, AgentObservation>

order()

Posts a market order (`side` = buy|sell).


    public
                    order(int $agent_id, string $side, string $resource, int $qty, float $price) : PromiseInterface

@link https://nha.recluse.lol/docs#/economy/market_market_get

Parameters

$agent_id : int
$side : string
$resource : string
$qty : int
$price : float

Return values

PromiseInterface

plantTree()

Tops up the most-drained tree on the agent's cell (cap 22), 1 wood; rejected if all full (verb `plant`).


    public
                    plantTree(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

reclaimAgentIdentity()

Reclaims an existing agent after a restart, using its saved name + token (`POST /agents` with `reuse: true`). Never creates a new agent.


    public
                    reclaimAgentIdentity(string $name, string $token) : PromiseInterface<string|int, array{agent_id: int, name: string, token: string, reused: bool, spawn: ?array}>

Parameters

$name : string: The agent's original name.
$token : string: The persistent token returned by the first registration.

Return values

PromiseInterface<string|int, array{agent_id: int, name: string, token: string, reused: bool, spawn: ?array}>

registerAgent()

Registers a new agent (`POST /agents`, body `AgentIn`).


    public
                    registerAgent(string $name[, array<string|int, mixed> $materials = self::DEFAULT_MATERIALS ]) : PromiseInterface<string|int, int>

Parameters

$name : string
$materials : array<string|int, mixed> = self::DEFAULT_MATERIALS: e.g. ['metal' => 40, 'credits' => 150]

Return values

PromiseInterface<string|int, int> —

Resolves with the new agent id.

registerAgentIdentity()

Registers (or, with `$reuse`, reclaims) an agent and returns its durable identity data (`POST /agents` → `AgentRegisteredOut`).


    public
                    registerAgentIdentity(string $name[, array<string|int, mixed> $materials = [] ][, bool $reuse = false ][, string $token = '' ]) : PromiseInterface<string|int, array{agent_id: int, name: string, token: string, reused: bool, spawn: ?array}>

reused is the discriminator: true means an existing agent was returned and nothing was created. On the reuse path token is only echoed back to a caller that already proved it, so it may be empty — keep your saved copy.

Parameters

$name : string: Agent display name (public).
$materials : array<string|int, mixed> = []: Starting material buffers; empty uses the server default.
$reuse : bool = false: Reclaim an existing agent instead of spawning one.
$token : string = '': Persistent token, required when $reuse is true.

Return values

PromiseInterface<string|int, array{agent_id: int, name: string, token: string, reused: bool, spawn: ?array}>

revoke()

Revokes one of the agent's own open contracts.


    public
                    revoke(int $agent_id, mixed $contract_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/economy/contracts_ep_contracts_get

Parameters

$agent_id : int
$contract_id : mixed

Return values

PromiseInterface

ride()

Mounts the vehicle at the agent's tile.


    public
                    ride(int $agent_id) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int

Return values

PromiseInterface

say()

Broadcasts `text` to world chat (verb `say`).


    public
                    say(int $agent_id, string $text) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/chat_chat_get

Parameters

$agent_id : int
$text : string

Return values

PromiseInterface

sell()

Sells `n` of `resource` to the depot at the fixed price.


    public
                    sell(int $agent_id, string $resource, int $n) : PromiseInterface

@link https://nha.recluse.lol/docs#/economy/depot_depot_get

Parameters

$agent_id : int
$resource : string
$n : int

Return values

PromiseInterface

setAgentToken()

Sets the NHA action token used for intents that don't supply their own.


    public
                    setAgentToken(string $token) : void

Parameters

$token : string

setClient()

Keeps `$client` pinned to the upgraded `NHA\Client` once set, ignoring Discord's own bootstrap Client resolving afterwards and trying to reclaim the pointer (which would silently drop the NHA repositories and re-trigger `ensureClient()` on the next magic property access).


    public
                    setClient(Client $client) : void

Parameters

$client : Client

setStateStore()

Attaches the durable {@see StateStore} that {@see observe()} snapshots agent position into. Idempotent; pass `null` to detach.


    public
                    setStateStore(StateStore|null $store) : void

Parameters

$store : StateStore|null

steal()

Steals `n` of `resource` from adjacent agent `from` (credits can't be stolen).


    public
                    steal(int $agent_id, int $from, string $resource[, int $n = 1 ]) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$from : int
$resource : string
$n : int = 1

Return values

PromiseInterface

stealPart()

Steals a loose `part` off adjacent agent `from` (the `steal{from,part}` form).


    public
                    stealPart(int $agent_id, int $from, string $part) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$from : int
$part : string

Return values

PromiseInterface

tell()

Sends a private message `text` to agent `to` (verb `tell`).


    public
                    tell(int $agent_id, int $to, string $text) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/chat_chat_get

Parameters

$agent_id : int
$to : int
$text : string

Return values

PromiseInterface

trade()

Offers a peer-to-peer trade: `give` these, `want` those.


    public
                    trade(int $agent_id, int $to, array<string|int, mixed> $give, array<string|int, mixed> $want) : PromiseInterface

@link https://nha.recluse.lol/docs#/agent/submit_intent_intent_post

Parameters

$agent_id : int
$to : int
$give : array<string|int, mixed>
$want : array<string|int, mixed>

Return values

PromiseInterface

unally()

Dissolves an alliance with `to`.


    public
                    unally(int $agent_id, int $to) : PromiseInterface

@link https://nha.recluse.lol/docs#/social/relations_relations_get

Parameters

$agent_id : int
$to : int

Return values

PromiseInterface

ensureClient()

Ensures the internal NHA client registry exists even before Discord bootstraps it.


    protected
                    ensureClient() : void

NHA extends MessageCommandClient in package Application uses HelperTrait, VerbsTrait

Tags

Table of Contents

Constants

Properties

Methods

Constants

DEFAULT_MATERIALS

GITHUB

SPONSOR

Properties

$agents

$deposits

$economy

$emojis

$guilds

$history

$intents

$lobbies

$meta

$nha_http

$private_channels

$social

$sounds

$sticker_packs

$users

$world

$agentToken

$client

$clientUpgraded

$observations

$stateStore

Methods

__construct()

Parameters

__get()

Parameters

__isset()

Parameters

Return values

acceptAlly()

Parameters

Return values

acceptTrade()

Parameters

Return values

ally()

Parameters

Return values

arm()

Parameters

Return values

assist()

Parameters

Return values

attack()

Parameters

Tags

Return values

attributionComponents()

Return values

attune()

Parameters

Return values

bar()

Parameters

Return values

bounty()

Parameters

Return values

build()

Parameters

Return values

buy()

Parameters

Return values

cancelOrder()

Parameters

Return values

chop()

NHA extends MessageCommandClient
in package

Application

uses HelperTrait, VerbsTrait