PrismaticAPI

插件

· 作者 CroaBeast

适用于 Bukkit/Spigot/Paper 插件的高级颜色操作与文本格式化的多功能库。

0 本站下载 0 关注 更新于 3 个月前

最新 2.0.1 · 26.2 · Bukkit / Folia

一键开服(送7天)
文本描述

? 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.Component
  • net.kyori.adventure.text.minimessage.MiniMessage
  • net.kyori.adventure.text.minimessage.tag.resolver.TagResolver
  • net.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 用 ? 制作

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源