文本描述
? PrismaticAPI
Bukkit/Paper 插件的终极文本格式化引擎。
RGB 颜色 · 渐变 · 彩虹色 · MiniMessage · 交互式消息
✨ PrismaticAPI 是什么?
PrismaticAPI 是一个 Bukkit/Paper 文本格式化库,让你的插件拥有精美、现代的文本而无需头疼。一个共享引擎同时支持传统的 Bukkit 字符串和 Adventure 组件——渐变、彩虹色、按玩家适配的十六进制回退、MiniMessage 兼容性以及点击/悬停交互事件全部包含在内。
? 功能特性
- ? 多种 RGB 语法 —
{#ff8800},%#ff8800%,[#ff8800],<#ff8800>,&#ff8800,#ff8800,&xff8800 - ? 渐变与彩虹标签 — 每个字符的颜色过渡,支持任意数量的色阶停止点
- ? MiniMessage 集成 — 在同一字符串中混合使用 Prismatic 标签和 MiniMessage 标签(运行时可选)
- ? Adventure 支持 — 从同一管道生成
net.kyori.adventure.text.Component输出,完全可选 - ?️ 交互式消息 —
Element: 仅解析一次,支持点击事件、悬停文本、悬停物品、占位符、URL 自动检测 - ? 感知玩家的格式化 — VNC + ViaVersion 集成,根据玩家的 Minecraft 版本提供十六进制或传统输出
- ?️ 设计安全 — 不强制依赖 Adventure;即使缺少该库也能正常启动
- ⚡ 向后兼容 — 经典的
PrismaticAPI.colorize(...)方法仍可照常使用
? 导入方法
Gradle (Kotlin DSL)
repositories {
maven("https://croabeast.github.io/repo/")
}
dependencies {
implementation("me.croabeast:PrismaticAPI:1.5.0")
}
Gradle (Groovy DSL)
repositories {
maven { url 'https://croabeast.github.io/repo/' }
}
dependencies {
implementation 'me.croabeast:PrismaticAPI:1.5.0'
}
Maven
<repository>
<id>croabeast-repo</id>
<url>https://croabeast.github.io/repo/</url>
</repository>
<dependency>
<groupId>me.croabeast</groupId>
<artifactId>PrismaticAPI</artifactId>
<version>1.5.0</version>
</dependency>
提示: 如果你的插件使用了
PrismaticAPI.adventure(),请确保在编译类路径中包含 Adventure API,并在启动时保证所需的 Adventure 运行时类存在。
? 支持的语法
? 单色 RGB 颜色
| 语法 | 示例 |
|---|---|
| 花括号 | {#ff8800} |
| 百分号 | %#ff8800% |
| 方括号 | [#ff8800] |
| 尖括号 | <#ff8800> |
| BungeeCord 十六进制 | &xff8800 |
| 纯十六进制 | #ff8800 |
| 带 & 的十六进制 | &#ff8800 |
? 渐变
<g:ff0000>Hello world</g:0000ff>
<gradient:ff0000>Hello world</gradient:0000ff>
<#ff0000>Hello world</#0000ff>
<#ff0000:#00ff00:#0000ff>Hello world</gradient> ← 多色阶!
? 彩虹色
<rainbow:1>Hello world</rainbow>
<r:1>Hello world</r>
? 传统格式化
&a 绿色 &l 粗体
&c 红色 &n 下划线
&6 金色 &o 斜体
&r 重置 &k 乱码
? MiniMessage(当存在 Adventure 时)
标准的 MiniMessage 标签(如 <bold>、<red>、<gradient:...> 等)可以与 Prismatic 标签在同一字符串中自由混合使用。
? 快速开始
? 传统字符串(始终安全)
// 基本 colorize
String colored = PrismaticAPI.colorize(player, "<g:ff0000>Hello</g:0000ff> &lworld!");
player.sendMessage(colored);
// 直接使用外观接口
Formatter<String> legacy = PrismaticAPI.legacy();
String gradient = legacy.applyGradient("Sunset", new Color(255, 100, 0), new Color(255, 0, 100), false);
String rainbow = legacy.applyRainbow("Colorful!", 1.0f, false);
String solid = legacy.applyColor(new Color(0, 200, 255), "Aqua text", false);
? Adventure 组件(可选)
if (PrismaticAPI.isAdventureAvailable()) {
Formatter<Component> adv = PrismaticAPI.adventure();
Component component = adv.colorize(player, "<rainbow:1>PrismaticAPI</rainbow>");
player.sendMessage(component); // Paper 原生 API
}
?️ 交互式消息
Element 是唯一的消息类型。解析一次,按玩家渲染:
// 标记格式:<action:"argument">text</text>
Element menu = Element.parse(
"<run:\"/spawn\">&aGo to Spawn</text>" +
" &7| " +
"<suggest:\"/msg \">&bSend a Message</text>"
);
player.spigot().sendMessage(menu.bungee(player));
player.sendMessage(menu.legacy(player));
手动构建:
Element button = Element.text("Click me!")
.toBuilder()
.color("#ff8800")
.click("run", "/help")
.hover("&eOpen help menu", "&7Uses Prismatic colors")
.build();
player.spigot().sendMessage(button.bungee(player));
标记中支持的点击操作: execute / click / run / suggest / url / file / page / copy
?️ Element 深入解析
Element 是唯一的消息类型。它是不可变且仅解析一次的:交互标记、裸 URL 和占位符令牌在解析时确定,后续每次渲染都会复用这些结果。为每个配置项保留一个实例,并将其分发给所有玩家。
Element line = Element.parse("<g:ff8800>Welcome</g:00ffaa> &7{player}");
player.sendMessage(line.legacy(player)); // legacy String
player.spigot().sendMessage(line.bungee(player)); // BaseComponent[]
Adventure 输出故意放在单独的类中,这样即使服务器没有 Adventure 运行时,接触元素也不会加载任何 Kyori 类:
if (PrismaticAPI.isAdventureAvailable()) {
Component c = AdventureElement.render(line, player);
}
?️ 构建
通过 Element.Builder 进行变更,因此共享实例永远不会在其他消费者不知情的情况下发生变化。样式和事件调用适用于最后追加的分段。
Element button = Element.builder()
.append("Spawn")
.color("#00ffaa")
.bold()
.click(Click.RUN_COMMAND, "/spawn")
.hover("&7Go to spawn", "&8/spawn")
.build();
// 从现有元素派生而不修改它
Element louder = button.toBuilder().append(" &c!").build();
| Builder 方法 | 作用 |
|---|---|
append(String) |
将纯文本作为新分段添加 |
appendMarkup(String) |
解析交互标记并添加分段 |
append(Element) |
添加另一个元素的各个分段 |
raw(String) |
替换最后一个分段的文本,同时保留其事件 |
color / bold / italic / underlined / strikethrough |
设置最后一个分段的样式 |
click / hover / hoverItem |
将事件附加到最后一个分段 |
clickAll / hoverAll |
将事件应用到所有分段 |
clearClick / clearHover |
从最后一个分段移除事件 |
autoLinkUrl() |
使最后一个分段根据文本中的第一个 URL 生成 OPEN_URL 点击事件 |
?️ 点击事件
Click 枚举不携带平台类型:映射到 Bungee 或 Adventure 的操作发生在对应的渲染器内部。
| 常量 | 字符串别名 | 作用 |
|---|---|---|
RUN_COMMAND |
execute, click, run, run_command |
以玩家身份运行命令 |
OPEN_URL |
open_url, url |
在浏览器中打开 URL |
OPEN_FILE |
open_file, file |
在客户端机器上打开文件 |
SUGGEST_COMMAND |
suggest, suggest_command |
将文本插入聊天但不发送 |
CHANGE_PAGE |
change_page, page |
翻页(书) |
COPY_TO_CLIPBOARD |
clipboard, copy, copy_to_clipboard |
复制文本到剪贴板 |
builder.click(Click.OPEN_URL, "https://example.com"); // 枚举常量
builder.click("url", "https://example.com"); // 字符串别名
builder.click("run:/spawn"); // 紧凑格式 "action:payload"
未知或空的别名会解析为 SUGGEST_COMMAND。
? 悬停提示
文本悬停支持可变参数、List<String> 或使用 <n> 分隔符的单字符串:
builder.hover("&eLine one", "&7Line two");
builder.hover(Arrays.asList("&eLine one", "&7Line two"));
builder.hover("&eLine one<n>&7Line two");
物品悬停接受原始 SNBT/NBT JSON,或使用 b64: 前缀的 Base64 负载以避免转义问题:
builder.hoverItem("{id:\"minecraft:diamond_sword\",Count:1b}");
builder.hoverItem("b64:" + Base64.getUrlEncoder().withoutPadding().encodeToString(nbt.getBytes(UTF_8)));
?️ 标记格式
<action:"argument">visible text</text>
<action:"arg1"|action2:"arg2">visible text</text>
- 开始标签包含一个或多个由
|分隔的action:"argument"对。 - 结束标签始终为
</text>。 - 支持的操作:表格中的所有点击别名,以及
hover和hover_item。
<!-- 仅点击 -->
<run:"/spawn">Go to Spawn</text>
<!-- 仅悬停 -->
<hover:"&eThis is hover text<n>&7Second line">Hover over me</text>
<!-- 仅物品悬停 -->
<hover_item:"{id:\"minecraft:diamond\",Count:1b}">A diamond</text>
<!-- 点击 + 悬停(用管道分隔) -->
<run:"/spawn"|hover:"&eTeleport home">Go Home</text>
关于标记的工具方法:
Element.isMarkup(raw); // 文本是否包含交互标签?
Element.stripMarkup(raw); // 移除标签,保留可见文本
element.toMarkup(); // 序列化回标记;重新解析为等效元素
自定义格式
MarkupFormat 是解析策略。注意 accept 不接受玩家参数:解析只发生一次,不能依赖于消息接收者是谁。
Element parsed = Element.parse(raw, myFormat);
? 占位符
形状为 {name} 和 %name% 的令牌在解析后作为数据保留,并在渲染时解析。这使得渐变可以跨越解析后的值,而不是令牌本身的长度:
Element line = Element.parse("<g:ff0000>Hello {player}</g:00ff00>");
RenderContext ctx = RenderContext.of(player, name ->
"player".equals(name) ? player.getName() : null);
player.sendMessage(line.legacy(ctx));
返回 null 的解析器会将原始令牌保留在原处。以 # 开头的令牌是 Prismatic 颜色语法,而非占位符,因此 {#ff8800} 和 %#ff8800% 不会被处理。
⚡ 渲染缓存
只有两种颜色配置文件:Target.HEX 和 Target.LEGACY,因此每个片段会在两个槽位中缓存其着色文本。一个渲染给一百名玩家的元素需要支付两次颜色管线费用。
当渲染实际解析占位符,或通过 RenderContext.withFormatter(...) 提供自定义格式化器时,会跳过缓存。
toString() 返回原始文本且从不进行渲染——它由字符串拼接、日志记录和调试器调用,这些都不应触发渲染或需要玩家。
? URL 自动检测
Element.parse 会将非标记跨度中的任何裸 URL(http://、https:// 或 www.)转换为其自身的段,并带有 OPEN_URL 点击事件。在构建器上,请显式调用 autoLinkUrl()。显式点击始终优先。
? 颜色连续性
当片段不以显式颜色代码开头时,前一片段的最后一种颜色会自动前置。这可以防止片段之间出现意外的白色重置:
"&aGreen text</text> and more text</text>"
↑ 自动添加 &a 前缀
⚙️ 格式化管线
PrismaticAPI 按以下确切顺序处理文本:
输入字符串
│
├─ 1. MiniMessage ──────────── (仅在存在 Adventure 时)
├─ 2. Prismatic 多色 ───────── 渐变与彩虹
├─ 3. 单 RGB 代码 ───────────── {#ff8800}, <#ff8800>, &xff8800 …
└─ 4. 传统 Bukkit 代码 ──────── &a, &l, &r …
│
▼
格式化输出
此顺序允许 MiniMessage 和 Prismatic 标签共存,而无需在每个运行时都依赖 Adventure。
? 实用方法
legacy() 和 adventure() 外观均暴露相同的辅助方法:
| 方法 | 描述 |
|---|---|
fromString(hex) |
将颜色令牌或十六进制字符串解析为 ChatColor |
stripBukkit(string) |
移除 &a、§a 样式的代码 |
stripSpecial(string) |
移除粗体、斜体、下划线等 |
stripRGB(string) |
移除渐变 / 彩虹 / 单 RGB 语法 |
stripMiniMessage(string) |
移除 MiniMessage 标签 |
stripAll(string) |
移除所有内容 —— 返回纯文本 |
startsWithColor(string) |
如果格式化字符串以颜色代码开头则返回 true |
getStartColor(string) |
格式化字符串中的第一个颜色代码 |
getEndColor(string) |
格式化字符串中的最后一个颜色代码 |
⚠️ 重要行为说明
colorize(String) 是保守的
当不带 Player 调用时,PrismaticAPI 无法检测接收者是否支持十六进制颜色,因此它会降级为最近的传统颜色。对于感知玩家输出的场景:
// ✅ 感知玩家:当玩家版本支持时保留 RGB
String formatted = PrismaticAPI.legacy().colorize(player, raw);
// ⚠️ 无玩家上下文:始终回退到传统模式
String formatted = PrismaticAPI.colorize(raw);
Adventure 始终是可选的
PrismaticAPI 在没有 Adventure 的情况下也能完美运行。只有 PrismaticAPI.adventure() 需要它。对调用进行保护:
if (PrismaticAPI.isAdventureAvailable()) {
// 安全调用 PrismaticAPI.adventure()
}
运行时所需的 Adventure 类:
net.kyori.adventure.text.Componentnet.kyori.adventure.text.minimessage.MiniMessagenet.kyori.adventure.text.minimessage.tag.resolver.TagResolvernet.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer
? 从 1.3.x 迁移
| 旧 API | 新 API |
|---|---|
PrismaticAPI.colorize(player, raw) |
未更改 ✅ |
PrismaticAPI.applyGradient(...) |
未更改 ✅ |
RichText text = PrismaticAPI.colorizeText(player, raw) |
PrismaticAPI.adventure().colorize(player, raw) |
text.component() |
adventure().colorize(...) 的结果已经是 Component |
applyColorText(...) |
PrismaticAPI.adventure().applyColor(...) |
applyGradientText(...) |
PrismaticAPI.adventure().applyGradient(...) |
applyRainbowText(...) |
PrismaticAPI.adventure().applyRainbow(...) |
? 从 1.5.x 迁移
me.croabeast.prismatic.chat 包已消失。Element 替代了其中的所有内容。
| 旧 API | 新 API |
|---|---|
PrismaticAPI.chatComponent(raw) |
Element.text(raw).toBuilder() |
PrismaticAPI.multiComponent(raw) |
Element.parse(raw) |
ChatComponent / MultiComponent |
Element(单一类型;单个片段不是特殊情况) |
component.compile(player) |
element.bungee(player) |
component.setMessage(raw) |
builder.raw(raw) |
component.setClick(Click.EXECUTE, v) |
builder.click(Click.RUN_COMMAND, v) |
component.setHover(...) |
builder.hover(...) |
component.setHoverItem(json) |
builder.hoverItem(json) |
multi.setClickToAll(...) |
builder.clickAll(...) |
multi.setHoverToAll(...) |
builder.hoverAll(...) |
multi.append(raw) |
builder.appendMarkup(raw) |
multi.copy() |
不需要;Element 是不可变的 |
multi.toFormattedString() |
element.toMarkup() |
ChatFormat |
MarkupFormat(无 Player 参数) |
DEFAULT_FORMAT.removeFormat(raw) |
Element.stripMarkup(raw) |
DEFAULT_FORMAT.isFormatted(raw) |
Element.isMarkup(raw) |
ChatComponent.URL_PATTERN |
Element.URL_PATTERN |
ChatProcessor.colorize |
RenderContext.withFormatter(...) |
ChatProcessor.prepare |
MarkupFormat.prepare(...) |
ChatComponent.Click.EXECUTE |
Click.RUN_COMMAND(字符串别名未变) |
ChatComponent.Click.SUGGEST |
Click.SUGGEST_COMMAND |
ChatComponent.Click.CLIPBOARD |
Click.COPY_TO_CLIPBOARD |
有两个值得注意的行为变更:
- 可变性。 旧组件就地修改;
Element是不可变的。element.toBuilder()...build()返回一个新实例,而原始实例保持不变。 - 空消息。
compile()文档化了一个非空数组,并用空白组件填充空消息。Element.text("").bungee()返回一个空数组。
?️ 构建
./gradlew jar
本项目依赖于来自 CroaBeast Maven 仓库的 VNC(me.croabeast.vnc:VNC:1.2.1),该依赖会在构建过程中自动解析。
? 许可证
详细信息请参阅 LICENSE。
由 CroaBeast 用 ? 制作
你是这个资源的作者?登录后可认领此资源。
相似资源
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
ExyliaPlugins 的库。
通过对话框或铁砧界面帮助你的 Anthme
自定义你的Minecraft头像!
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
评论 0
登录后参与评分
还没有评论,来抢沙发吧