EcoAPI gives PocketMine-MP plugins one callback based interface for several economy providers. It can be shaded as a virion or loaded through the companion EcoAPIPlugin PHAR. The source is licensed under Apache License 2.0.
virion.yml and plugin.yml declare minimum API 5.0.0, and Composer requires PHP ^8.1. The full Axolotl-PM 5.x range has not been verified. The build workflow pins the exact server source used for static analysis. A local isolated server test confirmed that the companion PHAR and example load, and a connected headless client can read its SimpleEconomy balance.
| Provider | Registration names | Runtime requirement |
|---|---|---|
| EconomyAPI | economyapi, economy |
An enabled compatible EconomyAPI plugin |
| BedrockEconomy | bedrockeconomy, bedrock |
An enabled compatible BedrockEconomy plugin |
| SimpleEconomy | simpleeconomy, simple |
An enabled SimpleEconomy plugin |
| Player XP levels | xp, exp, experience |
No economy plugin |
EcoAPI checks availability when a provider is selected. Provider specific money operations have different storage and callback behavior. Test the selected provider with disposable balances before using it on a live server.
An optional provider is available only after its plugin is enabled. A consumer that selects a provider in onEnable() should declare the desired plugin names under softdepend so they enable first. The example does this for EconomyAPI, BedrockEconomy and SimpleEconomy; when none is ready, it uses built-in XP.
The XP provider treats whole levels as currency. Setting, adding or taking levels keeps the player's progress within the current level. Its callback reports whether Axolotl-PM accepted the level change. An isolated server probe verified this behavior with a synthetic Player and the server's ExperienceManager. A connected player has not been tested.
SimpleEconomy stores whole units. Its adapter rejects fractional, non-finite, negative and out-of-range amounts; adding or taking money also requires an amount greater than zero. A successful callback reports that SimpleEconomy accepted the immediate in-memory change, while its SQL save continues asynchronously. Balance reads can return the configured default when a player's session has not loaded; that value is not proof of a persisted balance.
EconomyAPI rounds submitted amounts to two decimal places. Its adapter rejects non-finite, negative and subcent amounts before submission; adding or taking money also requires a positive amount. A successful callback reports the backend return code, while persistence depends on the configured EconomyAPI provider. Connected-player and persistence integration for EconomyAPI remain unverified.
The BedrockEconomy adapter accepts finite, nonnegative balances for setMoney() and positive amounts for addMoney() and takeMoney(). It rejects values that would change when represented to two decimal places, and accepts whole units only when the configured currency disables decimals. BedrockEconomy 4.0.4 stores cent values from 01 through 09 incorrectly, so the adapter rejects amounts with those cent components instead of risking an incorrect persisted balance. Rejected amounts call the supplied callback with false without submitting a transaction. A success callback reports the underlying BedrockEconomy operation. Isolated SQLite update-failure probes of all three methods returned false and kept their prior balances. Connected-player behavior and other failure modes remain unverified.
In the tested BedrockEconomy 4.0.4 PHAR, a listener that cancels TransactionSubmitEvent causes set, add and subtract to return without invoking either backend callback. EcoAPI cannot report a result in that case. Consumers must not interpret a missing callback as success or use this adapter for a transaction that requires a guaranteed completion signal. An isolated server probe confirmed that a cancelled setMoney() call invoked no callback and left the persisted balance unchanged. Cancellation of addMoney() and takeMoney() follows the same path in the packaged backend code but has not been runtime tested.
For a source based plugin, place a pinned EcoAPI source checkout under virions/EcoAPI and declare the virion in your plugin's devtools.yml:
virions:
- name: EcoAPI
version: ^1.0.0The example/ directory contains this declaration. DevTools builds the consumer PHAR and shades the EcoAPI namespace. Pin the source revision and follow the DevTools build guide for reproducible builds. The repository workflow builds and validates the companion EcoAPIPlugin and shaded example PHARs, then uploads them after its checks pass. An artifact is not a stable release.
Call EcoAPI::init() during your plugin's enable phase, then choose an available provider:
use NhanAZ\EcoAPI\EcoAPI;
EcoAPI::init();
$provider = EcoAPI::detectProvider();
if ($provider === null) {
// No supported provider is available.
return;
}
$provider->getMoney($player, static function (float|int $balance): void {
// Use the balance after the provider invokes the callback.
});getProvider(string $name) selects a registered provider by name. It throws UnknownProviderException for an unknown name and MissingProviderDependencyException when that provider is unavailable. The interface also offers setMoney(), addMoney() and takeMoney() with completion callbacks. Check callback results before claiming that an operation succeeded.
EcoAPI does not provide an atomic transfer between two accounts. Do not implement player payments by chaining takeMoney() and addMoney() and claiming that a later refund makes the operation safe. Use a provider with a verified transaction contract for transfers.
Implement EconomyProvider and register explicit factory and availability callbacks:
use NhanAZ\EcoAPI\EcoAPI;
use NhanAZ\EcoAPI\EconomyProvider;
EcoAPI::registerProvider(
static fn(): EconomyProvider => new MyProvider(),
static fn(): bool => MyProvider::isAvailable(),
"myprovider", "myalias"
);This registration signature replaces the older class string argument before the first stable release. The explicit factory keeps custom construction in the consuming plugin and lets DevTools shade built in provider references safely. Aliases share one registration, so automatic detection considers that provider once.
The repository runs PHPStan at maximum level, PHP lint and provider behavior fixtures. Its workflow pins checkout, server setup, DevTools and artifact upload revisions. CI builds and validates the companion PHAR and a shaded consumer example. Isolated server probes exercised SimpleEconomy and BedrockEconomy 4.0.4 transactions with synthetic player objects, then checked persisted SQLite balances. Scoped SQLite triggers rejected setMoney(), addMoney() and takeMoney() updates on test accounts. Each callback reported failure, and the cached and persisted balances stayed unchanged. A separate EconomyAPI 6.0.0-PM5 probe checked callbacks and the YAML balance after shutdown. A connected headless client received the example's join message and /balance result through SimpleEconomy; SQLite contained the expected test account after shutdown. Bedrock game UI, connected mutations, other providers' connected paths, other backend settings and other database failure paths remain unverified.
Keep player data backups and a previously verified build during upgrades. For support, use NhanAZ Discord. See the LICENSE file for the full Apache License 2.0 text.