MoneyCore API 接口

v2.0.0

MoneyCore 提供完整的经济系统 API，支持 C++ 和 Python 两种语言接入。

Python 超简单

Python 插件只需 1 个文件 money_api.py 即可调用所有经济 API！

📋 接口列表

基础操作

方法	参数	返回值	说明
`getMoney`	`playerName: string`	`double`	获取玩家余额
`setMoney`	`playerName: string, amount: double`	`void`	设置玩家余额
`addMoney`	`playerName: string, amount: double, reason: string`	`void`	增加玩家余额
`subMoney`	`playerName: string, amount: double, reason: string`	`void`	扣除玩家余额

商店推荐接口

方法	参数	返回值	说明
`hasMoney`	`playerName: string, amount: double`	`bool`	检查余额是否足够
`trySubMoney`	`playerName: string, amount: double, reason: string`	`bool`	尝试扣款（原子操作）✨推荐
`transfer`	`from: string, to: string, amount: double, reason: string`	`bool`	转账（原子操作）

查询接口

方法	参数	返回值	说明
`playerExists`	`playerName: string`	`bool`	玩家是否存在于经济系统
`getEconomyType`	-	`string`	获取经济类型 `plugin`/`scoreboard`
`isSyncEnabled`	-	`bool`	是否启用计分板同步

格式化接口

方法	参数	返回值	说明
`formatMoney`	`amount: double`	`string`	格式化金额显示
`getCurrencySuffix`	-	`string`	获取货币后缀

统计接口

方法	参数	返回值	说明
`getTopPlayers`	`limit: int`	`vector<pair<string, double>>`	获取财富排行榜

返回值	类型	说明
balance	double	玩家余额，不存在返回0

C++Python

cpp

double balance = service->getMoney("Steve");
getLogger().info("玩家余额: {}", balance);

python

balance = money.get_money("Steve")
self.logger.info(f"玩家余额: {balance}")

setMoney - 设置玩家余额

直接设置玩家余额为指定数值。

参数	类型	说明
playerName	string	玩家名称
amount	double	要设置的余额

C++Python

cpp

service->setMoney("Steve", 1000.0);

python

money.set_money("Steve", 1000.0)

addMoney - 增加玩家余额

给玩家增加指定金额。

参数	类型	说明
playerName	string	玩家名称
amount	double	增加的金额
reason	string	原因（可选，默认"plugin"）

C++Python

cpp

service->addMoney("Steve", 100.0, "任务奖励");
service->addMoney("Steve", 50.0);  // 不写原因

python

money.add_money("Steve", 100.0, "任务奖励")
money.add_money("Steve", 50.0)  # 不写原因

subMoney - 扣除玩家余额

从玩家扣除指定金额（不检查余额是否足够）。

参数	类型	说明
playerName	string	玩家名称
amount	double	扣除的金额
reason	string	原因（可选，默认"plugin"）

C++Python

cpp

service->subMoney("Steve", 50.0, "购买物品");

python

money.sub_money("Steve", 50.0, "购买物品")

查询操作接口

playerExists - 检查玩家是否存在

检查玩家是否存在于经济系统中。

参数	类型	说明
playerName	string	玩家名称

返回值	类型	说明
exists	bool	是否存在

C++Python

cpp

if (service->playerExists("Steve")) {
    // 玩家存在
}

python

if money.player_exists("Steve"):
    # 玩家存在

getEconomyType - 获取经济类型

获取当前使用的经济类型。

返回值	类型	说明
type	string	"plugin" 或 "scoreboard"

C++Python

cpp

std::string type = service->getEconomyType();
// type = "plugin" 或 "scoreboard"

python

economy_type = money.get_economy_type()
# economy_type = "plugin" 或 "scoreboard"

isSyncEnabled - 是否启用计分板同步

检查是否启用了计分板同步功能。

返回值	类型	说明
enabled	bool	是否启用

C++Python

cpp

bool sync = service->isSyncEnabled();

python

sync = money.is_sync_enabled()

商店推荐接口

hasMoney - 检查余额是否足够

检查玩家余额是否大于等于指定金额。

参数	类型	说明
playerName	string	玩家名称
amount	double	需要的金额

返回值	类型	说明
enough	bool	余额是否足够

C++Python

cpp

if (service->hasMoney("Steve", 100.0)) {
    // 余额足够
} else {
    // 余额不足
}

python

if money.has_money("Steve", 100.0):
    # 余额足够
else:
    # 余额不足

trySubMoney - 尝试扣款（推荐）

商店插件推荐使用此接口！

先检查余额是否足够，足够则扣除并返回true，不足则返回false。

参数	类型	说明
playerName	string	玩家名称
amount	double	扣除的金额
reason	string	原因（可选）

返回值	类型	说明
success	bool	是否扣款成功

C++Python

cpp

if (service->trySubMoney("Steve", 100.0, "购买钻石剑")) {
    // 扣款成功，给予物品
    player->sendMessage("购买成功！");
} else {
    // 余额不足
    player->sendMessage("余额不足！");
}

python

if money.try_sub_money("Steve", 100.0, "购买钻石剑"):
    # 扣款成功，给予物品
    player.send_message("购买成功！")
else:
    # 余额不足
    player.send_message("余额不足！")

transfer - 转账

玩家间转账，原子操作（要么全部成功，要么全部失败）。

参数	类型	说明
from	string	转出玩家
to	string	转入玩家
amount	double	转账金额
reason	string	原因（可选）

返回值	类型	说明
success	bool	是否转账成功

C++Python

cpp

if (service->transfer("Steve", "Alex", 50.0, "交易")) {
    // 转账成功
} else {
    // 转账失败（余额不足）
}

python

if money.transfer("Steve", "Alex", 50.0, "交易"):
    # 转账成功
else:
    # 转账失败

格式化接口

formatMoney - 格式化金额

将金额格式化为显示字符串。

参数	类型	说明
amount	double	金额

返回值	类型	说明
formatted	string	格式化字符串，如 "1234.56"

C++Python

cpp

std::string str = service->formatMoney(1234.567);
// str = "1234.57"

python

str = money.format_money(1234.567)
# str = "1234.57"

getCurrencySuffix - 获取货币后缀

获取配置的货币后缀。

返回值	类型	说明
suffix	string	货币后缀，如 "金币"

C++Python

cpp

std::string suffix = service->getCurrencySuffix();
player->sendMessage("你有 " + service->formatMoney(balance) + " " + suffix);

python

suffix = money.get_currency_suffix()
player.send_message(f"你有 {money.format_money(balance)} {suffix}")

统计接口

getTopPlayers - 获取排行榜

获取财富排行榜前N名玩家。

参数	类型	说明
limit	int	返回数量（可选，默认10）

返回值	类型	说明
list	vector/list	玩家名和余额的列表

C++Python

cpp

auto top = service->getTopPlayers(5);
for (auto &[name, balance] : top) {
    getLogger().info("{}: {}", name, balance);
}

python

top = money.get_top_players(5)
for name, balance in top:
    self.logger.info(f"{name}: {balance}")

getTotalEconomy - 获取服务器总经济

获取服务器所有玩家余额总和。

返回值	类型	说明
total	double	总经济

C++Python

cpp

double total = service->getTotalEconomy();
getLogger().info("服务器总经济: {}", total);

python

total = money.get_total_economy()
self.logger.info(f"服务器总经济: {total}")

完整示例：商店插件

C++ 商店示例Python 商店示例

cpp

#include "money_api.h"

void buyItem(endstone::Player &player, const std::string &item, double price) {
    auto service = getServer().getServiceManager().load<IMoneyService>("MoneyService");
    if (!service) {
        player.sendMessage("经济系统未加载！");
        return;
    }
    
    if (service->trySubMoney(player.getName(), price, "购买" + item)) {
        // 给予物品
        giveItem(player, item);
        
        std::string suffix = service->getCurrencySuffix();
        player.sendMessage("购买成功！花费 " + service->formatMoney(price) + " " + suffix);
        
        double newBal = service->getMoney(player.getName());
        player.sendMessage("剩余余额: " + service->formatMoney(newBal) + " " + suffix);
    } else {
        player.sendMessage("余额不足！需要 " + service->formatMoney(price) + " " + service->getCurrencySuffix());
    }
}

python

from money_api import MoneyAPI

class MyShopPlugin(Plugin):
    def on_enable(self):
        self.money = MoneyAPI()  # 自动连接数据库
        
    def buy_item(self, player, item, price):
        if self.money.try_sub_money(player.name, price, f"购买{item}"):
            # 给予物品
            self.give_item(player, item)
            
            suffix = self.money.get_currency_suffix()
            player.send_message(f"购买成功！花费 {self.money.format_money(price)} {suffix}")
            
            new_bal = self.money.get_money(player.name)
            player.send_message(f"剩余余额: {self.money.format_money(new_bal)} {suffix}")
        else:
            player.send_message(f"余额不足！需要 {self.money.format_money(price)} {self.money.get_currency_suffix()}")

推荐使用原子操作

使用 trySubMoney 而不是 hasMoney + subMoney 组合：

cpp

// ❌ 不推荐（非原子操作，可能出现竞态条件）
if (service->hasMoney(player, 100)) {
    service->subMoney(player, 100, "reason");
}

// ✅ 推荐（原子操作）
if (service->trySubMoney(player, 100, "reason")) {
    // 扣款成功
}

📥 下载 API 文件

C++ 开发

money_api.h - C++ 接口头文件

Python 开发

money_api.py - Python API 文件（只需这 1 个！）

超级简单

Python 开发者只需下载 money_api.py 一个文件，无需任何额外依赖！

MoneyCore API 接口 ​

📋 接口列表 ​

基础操作 ​

商店推荐接口 ​

查询接口 ​

格式化接口 ​

统计接口 ​

setMoney - 设置玩家余额 ​

addMoney - 增加玩家余额 ​

subMoney - 扣除玩家余额 ​

查询操作接口 ​

playerExists - 检查玩家是否存在 ​

getEconomyType - 获取经济类型 ​

isSyncEnabled - 是否启用计分板同步 ​

商店推荐接口 ​

hasMoney - 检查余额是否足够 ​

trySubMoney - 尝试扣款（推荐） ​

transfer - 转账 ​

格式化接口 ​

formatMoney - 格式化金额 ​

getCurrencySuffix - 获取货币后缀 ​

统计接口 ​

getTopPlayers - 获取排行榜 ​

getTotalEconomy - 获取服务器总经济 ​

完整示例：商店插件 ​

📥 下载 API 文件 ​

C++ 开发 ​

Python 开发 ​

MoneyCore API 接口

📋 接口列表

基础操作

商店推荐接口

查询接口

格式化接口

统计接口

setMoney - 设置玩家余额

addMoney - 增加玩家余额

subMoney - 扣除玩家余额

查询操作接口

playerExists - 检查玩家是否存在

getEconomyType - 获取经济类型

isSyncEnabled - 是否启用计分板同步

商店推荐接口

hasMoney - 检查余额是否足够

trySubMoney - 尝试扣款（推荐）

transfer - 转账

格式化接口

formatMoney - 格式化金额

getCurrencySuffix - 获取货币后缀

统计接口

getTopPlayers - 获取排行榜

getTotalEconomy - 获取服务器总经济

完整示例：商店插件

📥 下载 API 文件

C++ 开发

Python 开发