主题
BetterSidebar Python 接入指南
v1.0.0本指南介绍如何在 Python 插件中对接 BetterSidebar，在侧边栏显示自定义变量。
无需下载
BetterSidebar 启动时自动生成 Python API 模块，直接 import 使用！
快速开始
1. 声明依赖
python
class MyPlugin(Plugin):
api_version = "0.10"
depend = ["better_sidebar"]2. 在 on_enable 中导入并使用 API
python
class MyPlugin(Plugin):
api_version = "0.10"
depend = ["better_sidebar"]
def on_enable(self):
from sidebar_api import get_sidebar_api
self.sidebar = get_sidebar_api()
def on_some_event(self, event):
self.sidebar.set_value("my", "score", player.name, "100")
def on_disable(self):
self.sidebar.delete_variable("my", "score")
self.sidebar.close()重要
必须在 on_enable() 内 import，不能在文件顶部 import！因为 API 模块在 BetterSidebar 启动后才会生成。
3. 配置 BetterSidebar
在 plugins/better_sidebar/config.json 中添加变量：
json
{
"lines": [
"§e分数: §a{my.score}"
]
}完整示例：跳跃计数器
python
from endstone.plugin import Plugin
from endstone.event import event_handler, PlayerJumpEvent
class JumpCounter(Plugin):
api_version = "0.10"
depend = ["better_sidebar"]
def __init__(self):
super().__init__()
self.sidebar = None
self.jump_counts = {}
def on_enable(self):
from sidebar_api import get_sidebar_api
self.sidebar = get_sidebar_api()
self.register_events(self)
self.logger.info("JumpCounter 已启动")
@event_handler
def on_player_jump(self, event: PlayerJumpEvent):
player = event.player
name = player.name
self.jump_counts[name] = self.jump_counts.get(name, 0) + 1
self.sidebar.set_value("stats", "jumps", name, str(self.jump_counts[name]))
def on_disable(self):
if self.sidebar:
self.sidebar.delete_variable("stats", "jumps")
self.sidebar.close()配置文件：
json
{
"lines": [
"§e跳跃次数: §a{stats.jumps}"
]
}API 方法一览
| 方法 | 参数 | 说明 |
|---|---|---|
set_value | category, key, player, value | 设置变量值 |
get_value | category, key, player | 获取变量值 |
delete_value | category, key, player | 删除单个玩家的值 |
delete_variable | category, key | 删除整个变量 |
close | 无 | 关闭连接 |
注意事项
必须声明依赖
你的插件必须添加 depend = ["better_sidebar"]，确保 BetterSidebar 先加载并生成 API 模块。
import 位置
必须在 on_enable() 内 import，不能在文件顶部！
python
# ❌ 错误
from sidebar_api import get_sidebar_api
# ✅ 正确
def on_enable(self):
from sidebar_api import get_sidebar_api插件卸载时清理数据
在 on_disable() 中调用 delete_variable() 清理注册的变量，避免残留数据：
python
def on_disable(self):
if self.sidebar:
self.sidebar.delete_variable("你的category", "你的key")
self.sidebar.close()数据持久化
侧边栏数据库只用于显示，如需持久化统计数据，请在你的插件中自行保存。
事件处理器装饰器
所有事件处理方法必须添加 @event_handler 装饰器。