Scoreboard Sidebar API - 玩家独立计分板

简介

Sidebar API 是一款用于为每位玩家轻松创建个性化侧边栏（计分板）的插件。这是它的第二个版本，提供了丰富的动画效果、PlaceholderAPI 集成以及防闪烁等特性，让侧边栏的创建与管理变得简单高效。

✨特性与更新

• 防闪烁：优化显示，减少侧边栏更新时的视觉闪烁。
• 步骤功能：允许为不同的文本行设置独立的动画更新频率。
• 自动更新器：插件支持自动检查并更新。
• PlaceholderAPI 支持：可集成 PlaceholderAPI 以使用丰富的变量占位符。

依赖说明

• PlaceholderAPI：这是一个软依赖。强烈推荐安装以使用变量功能，但非必需。
• 下载链接：https://www.spigotmc.org/resources/placeholderapi.6245/

🔧安装指南

• 下载本资源。
• 将下载的 SidebarAPI.jar 文件放入服务器的 /plugins/ 目录。
• （可选）下载 PlaceholderAPI。
• （可选）将 PlaceholderAPI 的 jar 文件也放入服务器的 /plugins/ 目录。
• 重启服务器即可完成安装。如果安装了 PlaceholderAPI，控制台会显示类似 [SidebarAPI] Hooked PlaceholderAPI vx.x.x 的消息。

🎮API 使用教程

创建侧边栏文本行

首先，需要创建要在侧边栏中显示的文本行。

创建静态文本行

SidebarString line1 = new SidebarString(ChatColor.RED + "Line 1!");

创建带多个变体的动画文本行

SidebarString line2 = new SidebarString(
    ChatColor.RED + "Line 2 Variation 1",
    ChatColor.BLUE + "Line 2 Variation 2",
    ChatColor.GREEN + "Line 2 Variation 3"
);

生成滚动动画

从 2.3 版本开始，可以自动生成滚动动画文本

SidebarString mySidebarString = SidebarString.generateScrollingAnimation("You are awesome", 6);

• "You are awesome" 是要进行动画的文本。
• 6 是显示宽度。此代码将生成一系列长度为 6 个字符的变体，例如："You ar"， "ou are"， "u are " 等。

创建侧边栏实例

使用文本行创建侧边栏对象

Sidebar mySidebar = new Sidebar("My Title", plugin, 60, line1, line2);

• "My Title"：侧边栏的标题。
• plugin：你的主类（继承 JavaPlugin）的实例。
• 60：动画切换的间隔时间（单位：游戏刻）。动画通过循环每个 SidebarString 对象中的不同变体来实现。

动态管理条目

可以随时向侧边栏添加或移除文本行

SidebarString line3 = new SidebarString("Hello", "World");
// 添加条目
mySidebar.addEntry(line3);
// 移除条目
mySidebar.removeEntry(line3);

向玩家显示/隐藏

向特定玩家显示或隐藏侧边栏

mySidebar.showTo(player);
mySidebar.hideFrom(player);

❓PlaceholderAPI 集成

注意：以下所有方法在 PlaceholderAPI 未加载时都会抛出 SidebarOptionalException。

为特定玩家设置 SidebarString 中的占位符：

mySidebarString.setPlaceholders(player);

直接添加包含占位符的变体

mySidebarString.addVariation(player, "What is uuup!");

在构造时即设置占位符玩家

SidebarString mySidebarString = new SidebarString(player, "Variation 1", "Variation 2", "etc.");

为侧边栏中所有文本行设置占位符

mySidebar.setAllPlaceholders(player);

获取已挂钩的 PlaceholderAPI 实例：

// 如果未挂钩 PlaceholderAPI，则返回 null
PlaceholderAPIPlugin instance = SidebarAPI.getPlaceholderAPI();

提示：API 包含更多获取器、设置器以及管理条目的方法，详细内容请查阅下载包中包含的 Javadoc 文档。

⭐步骤功能详解

从 2.8 版本开始，SidebarString 类新增了 step 属性。它定义了需要调用 SidebarString#getNext() 方法多少次才会实际返回下一个变体。默认 step 为 1，即每次调用都切换变体。

此系统允许不同的文本行拥有独立的“动画速率”。例如，一个文本行每秒切换一次，而另一个每两秒切换一次。

相关方法和构造函数

// 创建一个 step 为 2 的新 SidebarString
SidebarString line1 = new SidebarString(2, "variation 1", "variation 2", "etc.");

// 创建一个 step 为 2 且预设了占位符玩家的新 SidebarString
SidebarString line2 = new SidebarString(player1, 2, "var 1", "var 2");

// 获取 line1 的 step 值
int step = line1.getStep();

// 将 line2 的 step 值设置为 4 (此方法可链式调用)
line2.setStep(4);

注意：step 数据可通过配置文件进行管理。

✨侧边栏占位符

从 2.5 版本起，SidebarAPI 定义了以下 3 个可用于 PlaceholderAPI 的占位符。

%sidebar_title%

返回指定玩家当前显示的侧边栏标题。如果未找到侧边栏，则返回空字符串 ""。

%sidebar_linenextvar_n%

将 n 替换为任意大于等于 0 的整数。

返回指定玩家侧边栏中第 n 行文本的下一个变体。如果发生错误（如语法无效），则返回空字符串 ""。

%sidebar_line_n_var_n%

将第一个 n 和第二个 n 分别替换为任意大于等于 0 的整数。

返回指定玩家侧边栏中第 1st n 行文本的第 2nd n 个变体。如果发生错误，则返回空字符串 ""。

💡更新与占位符玩家

从 2.6 版本开始，Sidebar#update() 方法会在 Sidebar#getPlaceholderPlayerForUpdate() 不为 null 时，自动调用 Sidebar#setAllPlaceholders(player)。

设置用于更新的占位符玩家

mySidebar.setPlaceholderPlayerForUpdate(player);

移除占位符玩家（停止自动设置占位符）

mySidebar.setPlaceholderPlayerForUpdate(null);

🔧支持与链接

• 报告漏洞：请在讨论区或 GitHub 上提交。
• 源代码：https://github.com/ColoredCarrot/scoreboard-sidebar-api
• Javadocs：http://coloredcarrot.com/code/api/sidebar/javadocs/index.html
• 原版发布页：https://www.spigotmc.org/threads/api-scoreboard-sidebar-api.136026/