Economy provider interface and DevTools virion for PocketMine-MP plugins
The repository contains the EconomyProviderAPI virion, a companion plugin for server installation, and a small example.
virion.yml and plugin.yml declare minimum API 5.0.0, and Composer requires PHP ^8.1. The build workflow checks a pinned Axolotl-PM revision and the 5.0.0 API floor. The full Axolotl-PM 5.x range has not been verified.
| Provider | Registration names | Runtime requirement |
|---|---|---|
| SimpleEconomy (recommended) | simpleeconomy, simple |
An enabled SimpleEconomy plugin |
| EconomyAPI | economyapi, economy |
An enabled compatible EconomyAPI plugin |
| BedrockEconomy | bedrockeconomy, bedrock |
An enabled compatible BedrockEconomy plugin |
| Player XP levels | xp, exp, experience |
No economy plugin |
EconomyProviderAPI can select an external provider only after its plugin is enabled. Declare optional providers in softdepend when selecting one during onEnable(). The example falls back to built-in XP.
XPuses whole levels as currency and preserves the player's progress within the current level.SimpleEconomyaccepts whole units. Its callback reports the in-memory result while database saving continues asynchronously. Reads may return the configured default before a player's session loads.EconomyAPIaccepts amounts with up to two decimal places. Its callback reports the backend result.BedrockEconomyuses asynchronous updates. Version4.0.4requires Xbox authentication and mishandles amounts with cents from.01to.09, which EconomyProviderAPI rejects. If a matchingTransactionSubmitEventis canceled, the supplied callback receivesfalseonce.
For a source based plugin, place a pinned EconomyProviderAPI source checkout under virions/EconomyProviderAPI and declare the virion in your plugin's devtools.yml:
virions:
- name: EconomyProviderAPI
version: ^3.0.0The example/ directory contains this declaration. DevTools builds the consumer PHAR and shades the EconomyProviderAPI namespace. Pin the source revision and follow the DevTools build guide for reproducible builds. The repository workflow builds and validates the companion EconomyProviderAPIPlugin and shaded example PHARs, then uploads them after its checks pass. An artifact is not a stable release.
Call EconomyProviderAPI::init() during your plugin's enable phase, then choose an available provider:
use AxolotlBucketLabs\EconomyProviderAPI\EconomyProviderAPI;
EconomyProviderAPI::init();
$provider = EconomyProviderAPI::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.
EconomyProviderAPI 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 AxolotlBucketLabs\EconomyProviderAPI\EconomyProviderAPI;
use AxolotlBucketLabs\EconomyProviderAPI\EconomyProvider;
EconomyProviderAPI::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.
CI runs PHPStan at maximum level, PHP lint, provider fixtures, PHAR validation and an Axolotl-PM 5.0.0 startup smoke test. The full server version range, connected BedrockEconomy transactions and Bedrock game UI remain unverified.
Keep player data backups and a previously verified build during upgrades. For support, use AxolotlBucketLabs Discord. See the LICENSE file for the full Apache License 2.0 text.