RGB 渐变文本

模块简介

RGB 是 Suite 的渐变文本渲染模块，提供 逐字渐变 与 动态扫光 两种文本效果，通过 PlaceholderAPI 对外暴露。模块将 entries 目录下定义的渐变色条目渲染为带 ArcartX 颜色码的彩色文本，可直接用于聊天、TAB 列表、称号、UI 文本等任何支持 PlaceholderAPI 的场景。

模块为纯计算型服务，无数据库、无跨服同步、无 UI 交互，启动时加载条目配置后即可通过占位符输出渲染结果。

属性	值
模块 ID	`rgb`
版本	1.4.4
配置文件	`config.yml`
条目目录	`entries/`（相对模块数据目录）
外部依赖	PlaceholderAPI（必需）
模块依赖	无
数据库	无（纯计算型，不持久化）
跨服同步	无
命令入口	无模块命令（宿主 `/axs reload rgb` 重载配置）
对外能力	`RgbRenderable`（渐变文本渲染）
PAPI 前缀	`%axsrgb_*%`

功能特性

特性	说明
逐字渐变	文本按字符（codePoint）分配颜色梯度，支持两色到任意多色渐变（如红 → 黄 → 蓝）
动态扫光	在渐变基础上叠加移动的高亮光带，可配置扫光颜色、宽度和强度
动画帧切换	每隔 `switch-interval-ticks` tick 切换到下一帧，形成动态流光效果；设为 `0` 则显示静态渐变
PAPI 嵌套	`text` 字段先按目标玩家解析 PlaceholderAPI（如 `%player_name%`），再叠加 RGB 渐变
多条目管理	`entries/` 目录下每个 YAML 文件可包含多个条目，根键即为条目 ID，按文件名排序加载
递归引用检测	自动检测条目间的递归 PAPI 引用并中止渲染，防止死循环
文本长度截断	渲染文本最大 1024 字符，超长自动截断，防止恶意超长输入拖慢渲染
颜色格式兼容	支持 `#RRGGBB`、`§#RRGGBB`、`RRGGBB` 三种颜色输入格式
条目热重载	通过 `/axs reload rgb` 可热重载条目配置，无需重启服务器

依赖

依赖类型	名称	必需	说明
外部依赖	PlaceholderAPI	是	RGB 模块通过 PAPI 占位符 `%axsrgb_<entryId>%` 输出渲染结果，是硬依赖
模块依赖	无	-	RGB 不依赖其他 Suite 模块即可运行

PlaceholderAPI 是 RGB 模块的硬依赖。若未安装 PlaceholderAPI，模块仍可加载，但无法通过占位符输出任何渲染结果，模块失去实际意义。

RGB 文本说明

渐变与扫光

逐字渐变：文本按字符在 gradient-colors 调色板中逐字插值，支持两色到任意多色，形成平滑渐变。
动态扫光：在渐变上叠加移动的高亮光带，由 shine-color、shine-width、shine-strength 控制。
动画帧：switch-interval-ticks 控制帧切换速度。0 为静态渐变；2 约每 100ms 一帧（较快）；3 约每 150ms 一帧（适中）。

条目引用

条目的 text 字段先按目标玩家解析 PAPI 占位符，再叠加渐变，因此可嵌套 %axsrgb_<otherId>% 引用其他条目。

条目可以互相引用，但不能形成环（如 a 引用 b、b 又引用 a）。检测到环时渲染结果为空串，调试模式下会输出警告日志。渲染文本最大 1024 字符，超长自动截断。

RGB 颜色需要玩家安装 ArcartX 客户端才能显示。未安装客户端的玩家会看到原始颜色码文本。

快速上手

安装 PlaceholderAPI 和 ArcartX 客户端模组
启动服务器，模块自动生成 config.yml 和 entries/default.yml
编辑 entries/default.yml 添加自定义渐变色条目
执行 /axs reload rgb 热重载
在聊天/TAB/称号/UI 中使用 %axsrgb_<entryId>% 输出渲染文本

概览