CharsApi - 终极方块消息插件

CharsApi 是一款允许玩家或开发者快速用方块构建彩色消息的插件。它支持使用默认字体（如 Mineplex）、系统字体或插件字体文件夹中的字体来构建字符，并支持动画效果，可在构建大型字符时减少因瞬间放置大量方块造成的卡顿。无论是用于大厅标识、游戏信息提示，还是其他任何你想传达的内容，CharsApi 都能帮你轻松实现。

💡安装字体

你可以从网上下载字体（例如 http://www.dafont.com/）并安装。

• 在服务器上安装：将字体文件放入 plugins/CharsApi/Fonts/ 文件夹。
• 在本地系统安装（Windows）：将字体文件放入控制面板的“字体”文件夹。

安装完成后，重启服务器即可。

🎮命令与权限

权限：chars

命令别名：chars, char, ch

主要命令

• build <格式字符串> - 构建字符
• clear <ID> - 清除指定ID的字符
• clear all - 清除地图上所有字符
• list <页码> - 显示检测到的字体列表
• font default - 将构建字体设置为默认字体
• font <大小> <字体类型> <字体名称> - 设置构建字体

- **字体类型**：0 - 普通，1 - 粗体，2 - 斜体

- **字体名称**：从 `/ch list` 获取，例如 `"Agency FB"`

• animations <in/out> - 显示可用的构建/清除动画列表
• vars - 显示变量列表
• updater <子命令> - 管理自动更新字符

使用示例

• /ch build &2Welcome &fthere's &4Merbio
• /ch clear 1
• /ch font 38 1 Agency FB
• /ch list 1
• /ch updater create chars_spawn 9

🔧格式详解

构建字符时，你可以使用以下格式代码来定制效果。

颜色与方块

默认构建方块是白色羊毛，类似于聊天中的颜色代码。

• 颜色：使用 & 加上颜色代码（0-9, a-f）。

- 例如：`/ch build &a Green` 会用绿色羊毛构建“Green”。

- `&X` 会随机选择颜色。

• 方块类型：使用 # 加上方块代码来改变方块材质。

- 例如：`/ch build #c &1 I am #p &5 player`

- **方块参数**：

- `C` - 粘土

- `W` - 羊毛

- `G` - 玻璃

- `P` - 玻璃板

• 特殊替代方块：使用 & 加上字母（g-m）来使用特殊方块。

- 例如：`/ch build #c clay &g Block` 中，`&g` 代表基岩。

变量

插件内置变量系统，使用 %变量名% 的格式调用（% 可在配置中修改）。

• 例如：/ch build Online: %online% / %maxplayers% 可能生成 “Online: 4 / 20”。

动画效果

• 构建动画（输入）：使用 @ 加上动画ID。

- 例如：`/ch build @4 #g&a Green Dragon`

• 清除动画（输出）：使用 ! 加上动画ID。

- 例如：`/ch build !1 #c&8 Drop Blocks`，然后使用 `/ch clear <ID>` 清除时会播放动画。

多行与上划线

• 多行文本：使用 \n 创建新行。

- 例如：`/ch build @6#g&a First Line \n @5#c&5 Second Line`

• 上划线：使用 $ 加上方块代码在文字上方添加线条。

- 例如：`/ch build $w #c&4 Car` 会构建红色粘土文字“Car”，并在上方加上黑色羊毛线。

- **上划线参数**：`C`（黑色粘土）、`W`（黑色羊毛）、`G`（黑色玻璃）、`P`（黑色玻璃板）、`L`（发光方块/萤石）。

✨更新器 (Updater)

更新器允许你在同一位置创建自动轮换的字符。主命令为 /ch u <子命令>。

子命令列表

• create <更新器名称> <更新时间> - 创建更新器
• remove <更新器名称> - 移除更新器
• tpto <更新器名称> - 传送到更新器位置
• setloc - 设置更新器位置和朝向（到玩家当前位置）
• settime <更新时间> - 设置更新器轮换时间
• add <文本> - 向更新器添加文本
• del <文本ID> - 从更新器移除文本
• info - 查看当前选中的更新器信息（包含文本ID）
• list - 列出所有更新器
• select <更新器名称> - 选择要编辑的更新器
• flush - 清除更新器在空中显示的所有文本
• start - 启动更新器
• stop - 停止更新器
• save - 保存更新器

使用示例

创建更新器：创建一个名为 n_spawn、每12秒轮换一次的更新器，并添加3条不同样式的文本。

/ch u create n_spawn 12
/ch u add @3#c&1Welcome
/ch u add @3#c&2on
/ch font 30 1 Agency FB
/ch u add @3#c&3SPAWN&4!
/ch u save

修改更新器：选择更新器，停止它，修改位置和更新时间，然后保存（保存后会自动启动）。

/ch u select n_spawn
/ch u select n_spawn  # 再次确认选择
/ch u stop
/ch u setloc
/ch u settime 15
/ch u save

⭐API 开发者部分

CharsBuilder 类

这是用于构建字符的核心类，包含字体、间距等设置。

CharsBuilder builder = new CharsBuilder();

创建与移除字符

使用 CharsString 类来操作你的方块消息。

• 创建文本方案：

    CharsString textCS = builder.replace("#cYour Text");

• 构建文本：

    textCS = builder.build(buildLocation, spawnLocation, textCS);

- 第一个位置是构建位置，第二个是文本朝向的旋转中心。

- 也可以基于玩家位置和朝向构建：`textCS = builder.build(player, textCS);`

• 清除文本：

    textCS.clearChars();

修改构建器设置

通过 BlockSettings 类进行配置。

// 获取当前设置或创建新设置
BlockSettings settings = builder.getBlockSettings(); // 或 new BlockSettings();

// 修改设置示例
settings.setWordSpacing(2);
settings.setLetterSpacing(1);
settings.setPlayerSpacing(5);
settings.setColorChar('$');
settings.setFont(new Font("Arial", Font.PLAIN, 20));
settings.addMaterialReplacement('N', Material.SPONGE);

// 将设置应用回构建器
builder.setBlockSettings(settings);

创建自动更新字符

使用 CharsUpdater 类管理自动轮换的字符。

// 创建更新器（时间秒，位置，朝向）
CharsUpdater updater = new CharsUpdater(10, location, BlockFace.NORTH);

// 添加字符（使用当前builder的设置）
int textId = updater.addCharsString(builder, "&aHello World");

// 建议在修改前停止更新器
updater.cancel();
// ... 进行修改，例如 updater.setSeconds(15);
updater.start(); // 重新启动

添加自定义变量

你可以为构建器添加动态变量。

// 静态变量
CharsBuilder.addCharsVariables(
    new CharsVariable("Hello World!", "hi world", "h w", "hw")
);

// 动态变量（例如在线玩家数）
CharsBuilder.addCharsVariables(
    new CharsVariable(new CharsVariable.onVarCheck() {
        @Override
        public String on() {
            return getServer().getOnlinePlayers().size() + " / " + getServer().getMaxPlayers();
        }
    }, "fullOnline", "fon")
);

插件包含更多类和功能，你可以通过 IDE 的“Alt + Space”查看 pl.merbio. 包下的完整内容。