泡泡无论如何

Bubble Anyway

Bubble Anyway 是一个以 API 为先的 Minecraft 信息通知浮层模组。 其他模组可以直接调用提供的 API，从任务完成、机器状态变化、成就达成、登录事件或任何其他游戏事件中触发通知，并在大多数原版及模组 GUI 屏幕上方显示清晰、可自定义的消息气泡。 对于不需要直接 Java 依赖的集成，也提供命令和 KubeJS 支持。

功能特性

• 同时显示多个气泡，支持优先级、替换、ID 和按玩家清除。
• 为其他模组提供直接的 Java API，用于发送针对特定玩家、多人及服务器范围的通知，而无需执行命令。
• 通过服务器事件、命令、服务端 API、KubeJS 或客户端 KubeJS 脚本触发气泡。
• 通过高优先级浮层层在大多数 HUD 和 GUI 屏幕之上渲染。
• 根据气泡文本自动调整大小，支持换行、自动换行和物品图标。也支持固定的最小宽度和高度。
• 支持九个锚点位置：TOP_LEFT、CENTER_TOP、TOP_RIGHT、CENTER_LEFT、CENTER、CENTER_RIGHT、BOTTOM_LEFT、CENTER_BOTTOM 和 BOTTOM_RIGHT。
• 支持从屏幕左、右、上或下边缘使用 FADE 淡入淡出或滑入动画。
• 自定义文本颜色、大小、对齐方式、粗体、斜体、下划线、删除线、混淆文本、阴影、自动换行和换行。
• 添加 Minecraft 物品图标，可配置大小、间距，并为图标和文本提供独立的 X/Y 偏移量。
• 使用自定义背景颜色或支持九宫格缩放的 PNG 纹理。
• 气泡出现时可播放可配置的音效。默认为原版按钮点击音效。
• 定义可复用的主题，使服务器只需发送主题 ID 和文本，而无需在每条消息中重复所有视觉设置。
• 内置两个九宫格背景：bubble_anyway:textures/gui/background.png 和 bubble_anyway:textures/gui/background_modern.png。

面向其他模组的 API

Bubble Anyway 设计为可被其他模组嵌入。模组可以直接从其自身的 Java 事件处理器中触发气泡，而无需构造命令或要求玩家与聊天框交互。

常见的服务器端入口点是：

import com.bubbleanyway.api.BubbleServerApi;
// 从服务器端事件（例如任务完成）中调用此方法。
BubbleServerApi.showJson(player,
    "{"id":"quest_complete","text":"Quest complete!","priority":100}");
// 使用本地主题，当样式已预定义时仅发送文本。
BubbleServerApi.showTheme(player, "my_mod:quest_notice", "Quest complete!");

可用的服务端集成方法包括：

• show(player, spec) 和 show(players, spec)
• showJson(player, json) 和 showJson(players, json)
• showAll(server, spec) 和 showAllJson(server, json)
• showTheme(player, themeId, text) 和 showThemeJson(player, themeId, overridesJson)
• showAllTheme(server, themeId, text) 和 showAllThemeJson(server, themeId, overridesJson)
• clear(player)、clear(players) 和 clearAll(server)

这些 API 允许附加模组决定通知何时出现，而 Bubble Anyway 则负责布局、动画、文本格式化、图标、音效、主题以及向客户端的传递。基于主题的调用还避免了为每个事件重复发送庞大的样式 JSON 对象。

对于 KubeJS 集成，请在服务器端使用 BubbleKubeJSServerApi，或在客户端使用 BubbleKubeJSBindings。这使得 Bubble Anyway 可以作为任务、进度、经济、机器和内容模组的共享通知服务。

支持的版本

加载器	Minecraft
Forge	1.19.2
Forge	1.20.1
NeoForge	1.21.1
NeoForge	1.26.1.2
Fabric	1.20.1
Fabric	1.21.1

所有包含的目标版本均为 1.0.0。请安装与您的 Minecraft 版本和模组加载器相匹配的文件。

命令示例

/bubble show @a {"theme":"bubble_anyway:defualt","text":"Welcome to the server\nHave fun!"}

同时支持传统的 JSON 格式：

/bubble show @a {"text":"Server restart in 5 minutes","anchor":"CENTER_TOP","y":18,"animation":"SLIDE_FROM_TOP","duration":100,"priority":200}

清除气泡使用：

/bubble clear

客户端 KubeJS

const BubbleAnyway = Java.loadClass('com.bubbleanyway.kubejs.BubbleKubeJSBindings');
BubbleAnyway.showJson(JSON.stringify({
  id: 'local_notice',
  theme: 'bubble_anyway:defualt',
  text: 'Client KubeJS is ready\nThis bubble is local only.'
}));

客户端 KubeJS 气泡不需要服务器命令或服务器事件。

服务器端 KubeJS

const BubbleServer = Java.loadClass('com.bubbleanyway.kubejs.BubbleKubeJSServerApi');
PlayerEvents.loggedIn(event => {
  BubbleServer.showJson(event.player, JSON.stringify({
    id: 'welcome',
    theme: 'bubble_anyway:defualt',
    text: 'Welcome back!'
  }));
});

服务端调用会将通知发送给选定的玩家、一组玩家或服务器上的所有玩家。

JSON 示例

{
  "id": "quest_complete",
  "theme": "bubble_anyway:morden",
  "text": "Quest complete!\nYou received a diamond.",
  "icon": "minecraft:diamond",
  "iconSize": 16,
  "iconGap": 6,
  "anchor": "CENTER_TOP",
  "y": 18,
  "animation": "SLIDE_FROM_TOP",
  "fadeIn": 8,
  "fadeOut": 12,
  "duration": 100,
  "priority": 100,
  "replace": true
}

当存在 theme 时，未指定的字段将从本地主题中加载。显式的 JSON 字段将覆盖该气泡的主题设置。

主题

默认主题会在首次启动时复制到 config/bubble_anyway/themes.json。现有的用户配置会被保留。一个主题可以包含任何受支持的气泡字段，因此一个完整的主题在调用时只需提供主题 ID 和文本。

Forge 目标还支持服务器数据包主题和服务端主题同步。其他加载器目标使用打包/客户端配置的主题系统。

配置示例：

{
  "themes": {
    "my_mod:warning": {
      "textColor": "#FFFFFFFF",
      "backgroundColor": "#D9A83232",
      "padding": 10,
      "anchor": "CENTER_TOP",
      "y": 18,
      "animation": "SLIDE_FROM_TOP",
      "fadeIn": 8,
      "fadeOut": 12,
      "duration": 100,
      "priority": 200,
      "shadow": false
    }
  }
}

在支持的服务器配置上使用 /reload 可重新加载主题数据。客户端也会读取本地主题配置，无需在每条气泡数据包中包含完整的主题定义。

九宫格背景

将 background 设置为纹理资源路径，并将 backgroundBorder 设置为边缘大小（以像素为单位）：

{
  "background": "bubble_anyway:textures/gui/background.png",
  "backgroundBorder": 8,
  "backgroundGuide": 1,
  "padding": 10
}

backgroundBorder 会保持四个角和四条边缘带保持原始大小，只拉伸中心区域。backgroundGuide 会从每个切片和最终渲染中排除参考线像素。这对于包含 1 像素参考线、将 66x66 源图像分隔为可用的九宫格区域的情况非常有用。

自定义纹理可以由资源包或其他模组提供。PNG 资源必须在客户端上可用。

重要兼容性说明

Bubble Anyway 设计为在正常 HUD 和 GUI 内容之上渲染。如果某个模组在浮层渲染之后直接绘制、替换屏幕帧缓冲或使用自定义渲染管线，仍然可以绘制在其之上。此类屏幕可能需要特定于加载器或模组的集成。

许可协议

保留所有权利。有关使用许可，请参阅仓库中的许可证。