Skip to content

agent-compute.md

Latest commit

 

History

History
204 lines (157 loc) · 4.91 KB

agent-compute.md

File metadata and controls

204 lines (157 loc) · 4.91 KB

Agent Compute Services

Compute Services allow EasyLibraryAgent to act as a safe external coprocessor for PMMP plugins.

Use compute for work that is:

  • expensive enough to avoid doing on the main server tick
  • global or cross-server
  • batch-oriented
  • asynchronous
  • easier to process in the Go Agent than inside a PMMP plugin

Do not use compute for tiny local logic, permission checks, same-tick player interactions or arbitrary code execution.

Safety model

Compute is intentionally stricter than PubSub.

PubSub can use custom channels because plugin-defined events are normal:

AgentPubSubAPI::toNetwork('myplugin.event', 'payload');

Compute cannot use arbitrary method strings. PHP plugins must use official constants, and the Go Agent validates its configured allowlist.

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

AgentComputeAPI::runAsync(AgentComputeMethods::REGION_INTERSECTS, $payload);

The Agent refuses methods that are not listed in [compute].allowed_methods.

Agent config

[compute]
enabled = true
default_timeout_seconds = 5
max_payload_bytes = 65536
max_concurrent_tasks = 4
retain_seconds = 600
allowed_methods = [
  "compute.ping",
  "compute.echo",
  "compute.math.basic",
  "compute.json.diff",
  "compute.region.intersects",
  "compute.leaderboard.sort"
]

Method list

Constant Method Purpose
AgentComputeMethods::PING compute.ping Validate that compute is reachable
AgentComputeMethods::ECHO compute.echo Return payload for diagnostics/examples
AgentComputeMethods::MATH_BASIC compute.math.basic Basic allowlisted math batch operations
AgentComputeMethods::JSON_DIFF compute.json.diff Compare two JSON-like structures
AgentComputeMethods::REGION_INTERSECTS compute.region.intersects Check whether two 3D boxes intersect
AgentComputeMethods::LEADERBOARD_SORT compute.leaderboard.sort Sort entries and return a limited leaderboard

Run async

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

$response = AgentComputeAPI::runAsync(AgentComputeMethods::PING, [
    'source' => 'rankup-main',
]);

$requestId = $response['request_id'] ?? null;

Check status later:

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

Read recent records:

$recent = AgentComputeAPI::recent(10);

List supported methods:

$methods = AgentComputeAPI::methods();

Listen for results

use imperazim\agent\event\AgentComputeResultEvent;
use imperazim\agent\event\AgentComputeFailedEvent;
use pocketmine\event\Listener;

final class ComputeListener implements Listener{
    public function onComputeResult(AgentComputeResultEvent $event): void{
        $method = $event->getMethod();
        $result = $event->getResult();
    }

    public function onComputeFailed(AgentComputeFailedEvent $event): void{
        $reason = $event->getReason();
    }
}

Region intersection example

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

AgentComputeAPI::runAsync(AgentComputeMethods::REGION_INTERSECTS, [
    'a' => [
        'min_x' => 0,
        'min_y' => 0,
        'min_z' => 0,
        'max_x' => 10,
        'max_y' => 10,
        'max_z' => 10,
    ],
    'b' => [
        'min_x' => 5,
        'min_y' => 0,
        'min_z' => 5,
        'max_x' => 15,
        'max_y' => 10,
        'max_z' => 15,
    ],
]);

Expected result data includes whether the boxes intersect and the intersection bounds when available.

Leaderboard sort example

AgentComputeAPI::runAsync(AgentComputeMethods::LEADERBOARD_SORT, [
    'entries' => [
        ['name' => 'Alice', 'score' => 120],
        ['name' => 'Bob', 'score' => 300],
        ['name' => 'Carol', 'score' => 250],
    ],
    'score_key' => 'score',
    'limit' => 2,
    'descending' => true,
]);

Expected result order:

Bob   300
Carol 250

JSON diff example

AgentComputeAPI::runAsync(AgentComputeMethods::JSON_DIFF, [
    'before' => [
        'maintenance' => false,
        'double_xp' => false,
    ],
    'after' => [
        'maintenance' => false,
        'double_xp' => true,
    ],
]);

Use this for configuration previews, layout diffs or admin review screens.

Failure behavior

A compute request may fail when:

  • the Agent is offline
  • compute is disabled
  • the method is not in the allowlist
  • payload exceeds max_payload_bytes
  • concurrency limit is reached
  • timeout expires
  • payload shape is invalid

Plugins should not block the PMMP main tick waiting indefinitely. Use async status/listeners and provide a local fallback.

Related docs