Skip to content

README.md

Latest commit

 

History

History
112 lines (80 loc) · 2.88 KB

README.md

File metadata and controls

112 lines (80 loc) · 2.88 KB

EasyLibrary Agent Examples

These examples show how a PocketMine-MP plugin should use the optional EasyLibrary Agent Bridge.

The Agent Bridge is API-first:

Plugin code -> imperazim\agent\api\*
Standard strings -> imperazim\agent\constant\*
Runtime reactions -> imperazim\agent\event\*

The /easyagent command is for diagnostics/admin/debug, not normal plugin logic.

Files

File Shows
AgentFallbackExample.php Safe fallback when the Agent is disabled or offline
AgentFlagsExample.php Network flags such as double XP
AgentKVAndLocksExample.php Shared KV state and global locks
AgentPubSubListenerExample.php Custom PubSub channel and listener flow
AgentRpcExample.php Requesting status from another server
AgentComputeExample.php Running allowlisted compute tasks
AgentRegistryAndStateExample.php Server registry and maintenance/draining state

Recommended plugin pattern

Always start by checking runtime availability:

use imperazim\agent\api\AgentRuntimeAPI;

if(!AgentRuntimeAPI::isAvailable()){
    // Keep your plugin running locally.
    return;
}

Use constants for official values:

use imperazim\agent\constant\AgentChannels;
use imperazim\agent\constant\AgentNetworkFlags;
use imperazim\agent\constant\AgentRpcMethods;

AgentChannels::NETWORK_NOTICE;
AgentNetworkFlags::DOUBLE_XP;
AgentRpcMethods::SERVER_STATUS;

Use custom names only when the contract belongs to your plugin:

AgentPubSubAPI::toNetwork('myplugin.cache.invalidate', 'invalidate');
AgentFlagsAPI::set('myplugin.feature.enabled', true, 300, 'Admin toggle');

Example: flag + listener

One plugin can set a flag:

AgentFlagsAPI::set(AgentNetworkFlags::DOUBLE_XP, true, 3600, 'Weekend booster');

Another plugin or server can listen:

public function onFlagChanged(AgentNetworkFlagChangedEvent $event): void{
    if($event->getFlag() !== AgentNetworkFlags::DOUBLE_XP){
        return;
    }

    $this->doubleXp = $event->isActive();
}

Example: compute as coprocessor

Use compute for tasks that are worth leaving the PMMP main thread:

AgentComputeAPI::runAsync(AgentComputeMethods::LEADERBOARD_SORT, [
    'entries' => $entries,
    'score_key' => 'score',
    'limit' => 10,
]);

Do not use compute for tiny local checks or same-tick gameplay logic.

Running these examples

These are source examples, not a standalone plugin. Copy the relevant pattern into your plugin and register listeners normally through PocketMine-MP.

Your plugin.yml should depend on EasyLibrary:

depend:
  - EasyLibrary

If your plugin can run without the Agent Bridge, keep the Agent as optional and use runtime fallbacks.

Related docs

  • ../../docs/agent-api.md
  • ../../docs/agent-api-contracts.md
  • ../../docs/agent-runtime-events.md
  • ../../docs/agent-compute.md
  • ../../docs/agent-security.md