README

EasyLibrary

EasyLibrary 2.0 is a PocketMine-MP development toolkit and library distribution for plugin authors. It bundles the ImperaZim Lib* ecosystem under stable public namespaces, provides runtime module support, and includes optional bridges for advanced network-aware plugins.

EasyLibrary is designed to be lightweight by default. Optional systems, such as the EasyLibrary Agent Bridge, are opt-in and should only be enabled when a server or plugin needs them.

What EasyLibrary provides

Bundled library APIs for commands, forms, HUDs, databases, serializers, triggers, windows, packets, custom content, enchantments, placeholders and world tooling.
Standalone-compatible namespaces: the same public imports are used whether a library is installed standalone or embedded through EasyLibrary.
A plugin-owned module system with manifests, dependency checks, lifecycle cleanup, services and capabilities.
Utility components for filesystem, cache, scheduling, configuration, messaging, validation, metrics and text helpers.
Embedded LibPlaceholder and LibWorld host support with route transfer when standalone plugins are enabled or disabled.
Optional Agent Bridge support for network-aware plugins that need PubSub, registry, KV, flags, locks, RPC, runtime events or safe compute services.

Requirements

PocketMine-MP API 5.0.0+
PHP 8.2+
No required external plugin dependencies
Optional: EasyLibraryAgent Go service when using the Agent Bridge

Installation

Download the EasyLibrary PHAR and place it in the PocketMine-MP plugins/ directory.

Plugins that require EasyLibrary should declare:

depend:
  - EasyLibrary

EasyLibrary loads at STARTUP.

Quick plugin example

use imperazim\command\Command;
use imperazim\form\builder\FormBuilder;
use imperazim\placeholder\PlaceholderAPI;
use imperazim\world\WorldAPI;

When using optional Agent features, depend on the split Agent API namespaces instead of the removed pre-1.0 monolithic AgentAPI class:

use imperazim\agent\api\AgentRuntimeAPI;
use imperazim\agent\api\AgentFlagsAPI;
use imperazim\agent\constant\AgentNetworkFlags;

if(!AgentRuntimeAPI::isAvailable()){
    return; // fallback locally when the bridge is disabled or offline
}

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

Bundled libraries

Library	Namespace	Main purpose
LibPlaceholder	`imperazim\placeholder`	Placeholder parsing and expansion registry
LibWorld	`imperazim\world`	World management, instances, regions, selections and block editing
LibPacket	`imperazim\packet`	Packet handlers, monitors, interceptors, recording and profiling
LibCommand	`imperazim\command`	Commands, arguments, constraints, results, macros and dynamic builders
LibForm	`imperazim\form`	Long, modal, custom, paginated, conditional and chained forms
LibHud	`imperazim\hud`	Boss bars, scoreboards, nametags, titles, notifications and tab lists
LibDB	`imperazim\db`	SQLite/MySQL, query builder, models, migrations, seeds, cache and async queries
LibSerializer	`imperazim\serializer`	Items, blocks, entities, inventories, positions, skins and schematics
LibTrigger	`imperazim\trigger`	Scheduled global, per-player and item triggers with modes and priorities
LibWindow	`imperazim\window`	Virtual inventories, layouts, sessions, transactions and window presets
LibEnchantment	`imperazim\enchantment`	Custom reactive, ticking and toggleable enchantments
LibCustom	`imperazim\custom`	Custom blocks, items, entities, components and palette registration

Use each standalone repository for complete API documentation and examples.

Standalone and embedded modes

Each bundled library can also be installed as an individual plugin. Standalone plugins and EasyLibrary intentionally expose the same namespaces.

Standalone installed:
  the standalone plugin is loaded before EasyLibrary and owns its lifecycle

Standalone absent:
  EasyLibrary exposes the embedded implementation and initializes required
  managers for selected libraries

Standalone enabled or disabled at runtime:
  manager ownership moves between standalone and EasyLibrary without clearing
  registered runtime state or public command routes

Plugins that accept either distribution can declare optional dependencies:

softdepend:
  - EasyLibrary
  - LibPlaceholder
  - LibWorld
  - LibCommand

Module system

EasyLibrary 2.0 supports plugin-owned modules discovered through module.yml or module.yaml manifests.

Declare module sources in the consuming plugin's plugin.yml:

depend:
  - EasyLibrary

easylibrary-modules:
  - path: modules
    namespace: vendor\plugin\modules

Create a manifest:

id: vendor:farm
name: Farm System
version: 1.0.0
loader: FarmModule
namespace: vendor\plugin\modules\farm
enabled: true

dependencies:
  vendor:economy: ">=1.0.0"

provides:
  services:
    - vendor:farm-service
  capabilities:
    - vendor.farm

Create the module:

use imperazim\module\BaseModule;
use imperazim\module\ModuleManager;

final class FarmModule extends BaseModule{
    protected function onEnable(ModuleManager $manager): void{
        $this->provideService('vendor:farm-service', new FarmService());
    }
}

BaseModule provides helpers for commands, listeners, events, scheduled tasks, async jobs, services, APIs, configuration, data folders, health checks and cleanup callbacks.

EasyLibrary Agent Bridge

The EasyLibrary Agent Bridge is an optional network bridge between PocketMine-MP plugins and the external EasyLibraryAgent Go service.

It is disabled by default:

agent:
  enabled: false

When disabled, EasyLibrary does not instantiate the Agent manager, does not register /easyagent, does not start heartbeat or PubSub polling, and does not register Agent placeholders. This keeps EasyLibrary lightweight for projects that only need the base libraries.

When enabled, plugins use imperazim\agent\api\*, imperazim\agent\constant\* and imperazim\agent\event\*:

use imperazim\agent\api\AgentRuntimeAPI;
use imperazim\agent\api\AgentPubSubAPI;
use imperazim\agent\api\AgentRpcAPI;
use imperazim\agent\constant\AgentChannels;
use imperazim\agent\constant\AgentRpcMethods;

if(!AgentRuntimeAPI::isAvailable()){
    return;
}

AgentPubSubAPI::toGroup('default', AgentChannels::NETWORK_NOTICE, 'Network restart in 5 minutes');
AgentRpcAPI::toServer('lumen-vps', AgentRpcMethods::SERVER_STATUS);

The /easyagent command is diagnostic/admin/debug tooling. Real network data should be transferred by plugin code through the API and listeners, not by gameplay command flows.

Agent 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

Agent constants and events

Use constants instead of raw strings for standard channels, targets, RPC methods, flags, states and compute methods:

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

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

Listen to runtime events when plugins need to react to Agent activity:

use imperazim\agent\constant\AgentNetworkFlags;
use imperazim\agent\event\AgentNetworkFlagChangedEvent;
use pocketmine\event\Listener;

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

        // Update local plugin state.
    }
}

Agent compute services

EasyLibraryAgent can act as a safe external coprocessor for heavy, global, batch or asynchronous work. Compute methods are allowlisted by the Go service and validated through AgentComputeMethods in PHP:

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],
]);

Use compute for expensive/global tasks. Keep small local or same-tick logic inside PMMP/PHP.

Documentation

General EasyLibrary docs

Agent Bridge docs

Development

Install dependencies:

composer install

Validate Composer metadata:

composer validate --strict

Lint PHP source:

find src -name '*.php' -print0 | xargs -0 -n1 php -l

Run the quality target when development dependencies are installed:

composer run quality

Changelog

EasyLibrary 2.0.0
EasyLibrary 1.3.x
Development Agent Bridge changes are tracked in CHANGELOG.md.

License

EasyLibrary is licensed under the MIT License.

imperazim / easy-library

Maintainers

Package info

Statistics

Security