Skip to content

agent-api.md

Latest commit

 

History

History
256 lines (186 loc) · 6.99 KB

agent-api.md

File metadata and controls

256 lines (186 loc) · 6.99 KB

EasyLibrary Agent API

This document describes the public PHP API surface for plugins that use the optional EasyLibrary Agent Bridge.

The bridge is opt-in. In new configs it is disabled by default:

agent:
  enabled: false

When disabled, no Agent runtime is loaded and AgentRuntimeAPI::isAvailable() returns false.

Public namespace layout

The old pre-1.0 monolithic AgentAPI class was removed. Plugin code should use the split API namespaces:

imperazim\agent\api\AgentRuntimeAPI
imperazim\agent\api\AgentPubSubAPI
imperazim\agent\api\AgentRegistryAPI
imperazim\agent\api\AgentDeliveryAPI
imperazim\agent\api\AgentRpcAPI
imperazim\agent\api\AgentKVAPI
imperazim\agent\api\AgentFlagsAPI
imperazim\agent\api\AgentLocksAPI
imperazim\agent\api\AgentServerStateAPI
imperazim\agent\api\AgentCommandDispatchAPI
imperazim\agent\api\AgentPlaceholderAPI
imperazim\agent\api\AgentComputeAPI

Supporting namespaces:

imperazim\agent\constant\*
imperazim\agent\event\*

Always start with runtime checks

Plugins must treat the Agent as optional. Do not assume the bridge is enabled or connected.

use imperazim\agent\api\AgentRuntimeAPI;

if(!AgentRuntimeAPI::isAvailable()){
    // Fallback locally, skip the network feature, or queue local work.
    return;
}

Useful runtime calls:

AgentRuntimeAPI::isEnabled();
AgentRuntimeAPI::isAvailable();
AgentRuntimeAPI::serverId();
AgentRuntimeAPI::metadata();
AgentRuntimeAPI::bridgeVersion();
AgentRuntimeAPI::lastPingOk();

PubSub

PubSub is for event-style messages between servers. Use official channels for EasyLibrary Agent events and custom channels for plugin-owned events.

use imperazim\agent\api\AgentPubSubAPI;
use imperazim\agent\constant\AgentChannels;

AgentPubSubAPI::toNetwork(AgentChannels::NETWORK_NOTICE, 'Network restart in 5 minutes');
AgentPubSubAPI::toGroup('default', AgentChannels::NETWORK_ACTIONBAR, 'Double XP is active');
AgentPubSubAPI::toServer('lobby-1', AgentChannels::NETWORK_TITLE, 'Welcome');

// Custom plugin channel.
AgentPubSubAPI::toNetwork('lumen.booster.changed', 'Double XP changed', [
    'flag' => 'double_xp',
    'active' => true,
]);

Listen for incoming messages:

use imperazim\agent\api\AgentPubSubAPI;
use imperazim\agent\event\AgentMessageEvent;
use pocketmine\event\Listener;

final class NetworkListener implements Listener{
    public function onAgentMessage(AgentMessageEvent $event): void{
        if(!AgentPubSubAPI::eventTargetsThisServer($event)){
            return;
        }

        if($event->getChannel() !== 'lumen.booster.changed'){
            return;
        }

        $data = $event->getDataArray();
        // Update local plugin state.
    }
}

Registry

The registry tracks server heartbeats, players, TPS, metadata and admin state.

use imperazim\agent\api\AgentRegistryAPI;

$registry = AgentRegistryAPI::servers();
$rankup = AgentRegistryAPI::serverInfo('lumen-vps');
$groups = AgentRegistryAPI::groups();
$types = AgentRegistryAPI::types();
$tags = AgentRegistryAPI::tags();

Typical uses:

  • lobby server selector
  • maintenance display
  • routing decisions
  • network player count
  • stale/offline diagnostics

KV, flags and locks

Use KV for shared state, flags for named boolean/network state, and locks for coordination.

use imperazim\agent\api\AgentKVAPI;
use imperazim\agent\api\AgentFlagsAPI;
use imperazim\agent\api\AgentLocksAPI;
use imperazim\agent\constant\AgentNetworkFlags;

AgentKVAPI::set('lumen', 'current_event', 'mining_frenzy', 3600);
$current = AgentKVAPI::get('lumen', 'current_event');

AgentFlagsAPI::set(AgentNetworkFlags::DOUBLE_XP, true, 3600, 'Weekend booster');
$flag = AgentFlagsAPI::get(AgentNetworkFlags::DOUBLE_XP);

$lock = AgentLocksAPI::lock('lumen.locks', 'mine_reset', 60, 'rankup-main');
if(($lock['ok'] ?? false) === true){
    // Run the critical section.
    AgentLocksAPI::unlock('lumen.locks', 'mine_reset', 'rankup-main');
}

Use locks to prevent two servers from performing the same global action at the same time.

RPC

RPC is for request/response operations between servers. It is also used internally by several diagnostics.

use imperazim\agent\api\AgentRpcAPI;
use imperazim\agent\constant\AgentRpcMethods;

$request = AgentRpcAPI::toServer('lumen-vps', AgentRpcMethods::SERVER_STATUS, [], 10);
$requestId = $request['request_id'] ?? null;

if($requestId !== null){
    $status = AgentRpcAPI::status($requestId);
}

Use RPC when a plugin needs an answer from a target server. Use PubSub when it only needs to notify or broadcast an event.

Delivery tracking

Reliable delivery records track ACK/result state for targeted PubSub operations.

use imperazim\agent\api\AgentDeliveryAPI;

$recent = AgentDeliveryAPI::recent(10);
$event = AgentDeliveryAPI::event(123);

Delivery is useful for diagnostics and admin workflows. Normal gameplay logic should not block the main tick waiting for delivery to complete.

Server admin state

use imperazim\agent\api\AgentServerStateAPI;

AgentServerStateAPI::setMaintenance('lumen-vps', true, 'Updating worlds');
AgentServerStateAPI::setDraining('lobby-1', true, 'Restart soon');
AgentServerStateAPI::clear('lumen-vps');

Plugins such as lobby selectors can use registry/admin state to hide or mark servers.

Command dispatch

Command dispatch is an admin automation tool, not the preferred gameplay integration model.

use imperazim\agent\api\AgentCommandDispatchAPI;

AgentCommandDispatchAPI::toServerReliable('lumen-vps', 'say Restart in 5 minutes');

Keep command dispatch protected with allowlist/blocklist settings and avoid using it for normal plugin-to-plugin communication.

Compute services

Use compute for allowlisted external tasks that benefit from being processed outside PMMP.

use imperazim\agent\api\AgentComputeAPI;
use imperazim\agent\constant\AgentComputeMethods;

$result = AgentComputeAPI::runAsync(AgentComputeMethods::LEADERBOARD_SORT, [
    'entries' => [
        ['name' => 'Alice', 'score' => 120],
        ['name' => 'Bob', 'score' => 300],
    ],
    'score_key' => 'score',
    'limit' => 10,
]);

Compute methods are intentionally limited. Use AgentComputeMethods constants; do not build method names dynamically.

Failure behavior

Agent APIs should be used defensively:

$response = AgentFlagsAPI::get('double_xp');
if(($response['ok'] ?? false) !== true){
    // Agent offline, disabled, request failed or flag not found.
    return;
}

Common safe fallback patterns:

  • skip optional network-only feature
  • use local cached state
  • show “unknown/offline” in UI
  • queue work locally and retry later
  • keep gameplay running without Agent-dependent bonuses

Related docs