BetterSidebar C++ 接入指南

v1.0.0

本指南介绍如何在 C++ 插件中对接 BetterSidebar，在侧边栏显示自定义变量。

快速开始

1. 下载 API 文件

⬇️ 下载 sidebar_api.h

将 sidebar_api.h 放入你的插件项目 include/ 目录。

2. 包含头文件

#include "sidebar_api.h"

3. 获取服务并注册变量

class MyPlugin : public endstone::Plugin {
    std::shared_ptr<ISidebarService> sidebar_;

public:
    void onEnable() override {
        sidebar_ = getServer().getServiceManager().load<ISidebarService>("SidebarService");
        
        if (sidebar_) {
            sidebar_->registerVariable("my", "score", [this](const std::string& playerName) {
                return std::to_string(getPlayerScore(playerName));
            });
            getLogger().info("已注册侧边栏变量: {my.score}");
        } else {
            getLogger().warning("BetterSidebar 未安装");
        }
    }
    
    void onDisable() override {
        if (sidebar_) {
            sidebar_->unregisterVariable("my", "score");
        }
    }
    
    int getPlayerScore(const std::string& playerName) {
        return scores_[playerName];
    }

private:
    std::unordered_map<std::string, int> scores_;
};

4. 配置 BetterSidebar

在 plugins/better_sidebar/config.json 中添加变量：

{
    "lines": [
        "§e我的分数: §a{my.score}"
    ]
}

完整示例

以下是一个完整的插件示例，统计玩家挖掘方块次数：

include/mining_counter.h

#pragma once

#include <endstone/endstone.hpp>
#include <endstone/plugin/service_manager.h>
#include "sidebar_api.h"
#include <unordered_map>
#include <mutex>

class MiningCounter : public endstone::Plugin {
public:
    void onEnable() override {
        getLogger().info("MiningCounter Enabled!");
        
        sidebar_ = getServer().getServiceManager().load<ISidebarService>("SidebarService");
        if (sidebar_) {
            sidebar_->registerVariable("stats", "mining", [this](const std::string& playerName) {
                std::lock_guard<std::mutex> lock(mutex_);
                return std::to_string(miningCounts_[playerName]);
            });
        }
        
        registerEvent(&MiningCounter::onBlockBreak, *this);
    }

    void onDisable() override {
        if (sidebar_) {
            sidebar_->unregisterVariable("stats", "mining");
        }
    }

    void onBlockBreak(endstone::BlockBreakEvent &event) {
        auto &player = event.getPlayer();
        std::lock_guard<std::mutex> lock(mutex_);
        miningCounts_[player.getName()]++;
    }

private:
    std::shared_ptr<ISidebarService> sidebar_;
    std::unordered_map<std::string, int> miningCounts_;
    std::mutex mutex_;
};

src/main_plugin.cpp

#include "mining_counter.h"

ENDSTONE_PLUGIN("mining_counter", "1.0.0", MiningCounter)
{
    description = "统计玩家挖掘次数";
    authors = {"Your Name"};
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(mining_counter C CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)
FetchContent_Declare(
    endstone
    GIT_REPOSITORY https://github.com/EndstoneMC/endstone.git
    GIT_TAG v0.10
)
FetchContent_MakeAvailable(endstone)

endstone_add_plugin(${PROJECT_NAME} src/main_plugin.cpp)
target_include_directories(${PROJECT_NAME} PRIVATE include)

API 参考

ISidebarService 接口

class ISidebarService : public endstone::Service {
public:
    virtual bool registerVariable(
        const std::string& category,
        const std::string& key,
        SidebarVariableProvider provider
    ) = 0;

    virtual bool unregisterVariable(
        const std::string& category,
        const std::string& key
    ) = 0;

    virtual bool hasVariable(
        const std::string& category,
        const std::string& key
    ) = 0;

    virtual std::string getExternalValue(
        const std::string& category,
        const std::string& key,
        const std::string& playerName
    ) = 0;
};

SidebarVariableProvider

using SidebarVariableProvider = std::function<std::string(const std::string& playerName)>;

回调函数接收玩家名，返回要显示的字符串值。

注意事项

线程安全

如果你的数据可能被多线程访问，请使用 std::mutex 保护数据。

检查服务是否存在

始终检查 load<ISidebarService>() 的返回值是否为空，因为用户可能没有安装 BetterSidebar。

插件卸载时注销变量

在 onDisable() 中调用 unregisterVariable() 清理注册的变量。