气泡聊天

---

BubbleChat

当玩家聊天时，在其上方显示平滑的、带有动画效果的对话气泡。功能包括：逐词显示、自动调整大小、多行文字换行、分页指示器、嘴部动画、自定义颜色、私人角色扮演频道以及完整的玩家个人设置界面。

---

功能特性

对话气泡

• 基于粒子的气泡：通过附着在实体上的粒子，以客户端帧率平滑地跟随玩家。
• 逐词显示动画：具有自然的语速和标点停顿。
• 自动调整大小：跨越15个宽度等级——气泡会根据消息内容自动伸缩。
• 多行换行（1行、2行和3行气泡）：使用加权字符宽度进行适当的视觉适配。
• 长消息分页系统：将长消息最多拆分为3页，并用圆点指示器显示当前位置。
• 平滑淡出动画：气泡消失时的动画效果。

嘴部动画（视位）

当气泡激活时，玩家模型上会播放基于音素的定制口型同步动画。每个单词会根据其起始字母触发一个嘴型，映射到16个不同的口型位置：

嘴部动画系统使用一个包含16个音素位置（休息、A、O、E/I/U/Y、S/T/D、N、L、R、F/V、H、W、J、K/G、B、M、P）的自定义精灵图，并通过 blockyanim 文件驱动动画。每个位置都注册为独立的动画组，以确保口型之间的转换平滑且即时。

动物语语音

一个灵感来源于《动物森友会》的迷人语音合成系统，与对话气泡同步播放：

• 音素映射音频——每个字母会根据其音素组触发一个带有音高的乐器音符，为每条消息创造独特的“声音”。
• 8种语音类型——每个玩家会话随机分配，每种类型具有不同的音高范围。
• 逐玩家音量控制——可从0%调整到200%（默认100%）。
• 基于距离的衰减——音量会随着与说话者的距离自然降低。
• 逐玩家静音——静音特定玩家的动物语音频，而不隐藏他们的气泡。
• 全局开关——在“语音设置”页面中完全开启或关闭动物语。

喊叫效果

当消息中包含全部大写的单词（2个字母以上）或以 ! 结尾的单词时，会触发一个尖叫粒子效果，与气泡一同播放以增强语气。

外观

• 深色和浅色模式：气泡背景支持逐玩家切换。
• 自定义气泡颜色：通过完整的颜色选择器，支持实时的HSV/RGB/十六进制数值显示。
• 对比度保护（浅色模式）：自动限制过亮的颜色，确保白色文字可读，并带有WCAG对比度指示器。
• 深色模式亮度约束：颜色会变暗至最低15%亮度，以便与气泡框轮廓区分。

玩家颜色覆盖

控制你在其他玩家气泡上看到的颜色，不受他们自身设置的影响：

• 全体玩家覆盖：强制将所有玩家的气泡设置为一种颜色。
• 逐玩家覆盖：为个别玩家设置特定颜色。
• 优先级顺序：全体玩家覆盖 > 逐玩家覆盖 > 说话者自身颜色。

角色扮演频道

用于角色扮演聊天的私人频道，只有频道成员能看到：

• 基于PIN码的频道：使用共享的PIN码创建或加入频道。
• 3个频道槽位：最多保存3个频道，并可在其间切换。
• 聊天前缀：在消息前输入 rp1、rp2 或 rp3 以发送到对应频道，或输入 pbc 强制发送到公共频道。
• 双重可见性：可选择向所有人显示你的气泡（公共+频道），同时向频道成员发送带有[RP]标记的文本。
• 切换确认：通过前缀切换频道前的可选确认提示。
• 逐频道气泡颜色：可为每个频道槽位设置不同的色调颜色，每位观看者可自定义。
• RP剔除距离：频道气泡的独立剔除距离（默认10M）。
• 喊叫范围：喊叫气泡可见性（默认50M）和喊叫粒子可见性（默认75M）的独立范围设置。

可见性控制

• 启用/禁用开关：完全开启或关闭对话气泡。
• 自身可见性开关：显示或隐藏你自己的对话气泡。
• 隐藏玩家：永久隐藏特定玩家的气泡。
• 暂时静音玩家：使用预设时长（5分钟到24小时，自动到期）暂时静音。
• 动物语静音：静音特定玩家的语音音频，同时仍能看到他们的气泡。
• 剔除距离：可从10M调整到200M（默认20M）。
• 最大气泡数量：限制同时显示的气泡数量，从1到50个（默认10个）。

---

设置界面

使用 /bchat 打开完整设置页面：

• 启用：对话气泡的开启/关闭开关。
• 模式：浅色/深色模式切换。
• 自身可见：开启/关闭开关。
• 气泡颜色：颜色选择器，带有实时预览色块、HSV/RGB/十六进制数值显示和“默认”按钮。
• 剔除距离：下拉菜单（10-200M）。
• 最大气泡数：下拉菜单（1-50）。
• 表情：嘴部动画的开启/关闭开关。
• 玩家颜色：用于全局和逐玩家颜色覆盖的子页面。
• 频道：用于RP频道管理、双重可见性、剔除距离和喊叫范围的子页面。
• 隐藏与静音：用于管理隐藏、静音和动物语静音玩家的子页面。
• 语音：用于动物语开关、音量和预览的子页面。
• 重置全部：将所有设置恢复为默认值。
• 撤销 / 重做：完整的操作历史记录（最多50步）。

---

命令

命令	描述
/bchat	打开设置界面
/bchat toggle	开启/关闭对话气泡
/bchat self on|off	显示/隐藏你自己的气泡
/bchat clear	关闭你当前的对话气泡
/bchat theme	打开设置界面
/bchat theme light|dark	通过命令设置气泡模式
/bchat theme color #RRGGBB|reset	通过命令设置气泡色调颜色
/bchat pc	打开玩家颜色页面
/bchat ch	打开频道页面
/bchat hm	打开隐藏与静音页面
/bchat vc	打开语音设置页面
/bchat vc on|off	开启/关闭动物语
/bchat status	显示当前设置
/bchat help	显示命令列表

聊天前缀

前缀	描述
rp1 消息	发送到槽位1中的频道
rp2 消息	发送到槽位2中的频道
rp3 消息	发送到槽位3中的频道
pbc 消息	强制发送公共聊天（绕过当前激活频道）

---

兼容性

• BusyBubble —— 完全双向优先级：发送消息时，对话气泡会清除任何活跃的思考气泡；而当对话气泡激活时，思考气泡也不会生成。当UI打开时，任何激活的对话气泡也会被清除。

---

安装

1. 将 BubbleChat-1.6.8.jar 放入你的 Mods 文件夹。
2. 所有玩家设置均可通过游戏内界面逐玩家配置——无需额外设置。

服务器配置（可选）

首次运行时，BubbleChat会在插件数据目录（Saves/<WorldName>/plugindata/BeyondSmash/BubbleChat/）中创建一个 bubblechat-config.json 文件。服务器管理员可以编辑此文件以自定义服务器范围的默认设置：

{
  "defaultBubbleColor": null,
  "rpChannelsEnabled": true,
  "animaleseEnabled": true
}

设置项	描述
defaultBubbleColor	未选择自己颜色的玩家的默认气泡色调（"#RRGGBB" 或 null 表示无色调）
rpChannelsEnabled	在服务器范围内启用或禁用RP/私人频道
animaleseEnabled	在服务器范围内启用或禁用动物语语音音效

---

已知问题

首次聊天时出现 [AssetUpdate] 消息

当玩家在安装了BubbleChat的服务器上首次发送聊天消息时，他们可能会在聊天框中看到1条 [AssetUpdate] 日志消息：

[AssetUpdate] ParticleSpawners: Starting AddOrUpdate

这是Hytale客户端的行为，而非Bug。 每当插件发送自定义粒子定义时，客户端都会记录此消息。BubbleChat会在玩家首次聊天时（而非加入时）惰性发送其自定义气泡粒子配置，因此从不聊天的玩家不会看到任何消息。

随着游戏在抢先体验阶段之后趋于成熟，这可能会在未来的Hytale更新中得到解决。

头部旋转动画

目前，BubbleChat无法在玩家说话时添加微妙的“说话”头部晃动动画。Hytale的动画系统使用了一个“面部”插槽，该插槽会完全覆盖由摄像机驱动的头部旋转——没有额外的混合模式来叠加一个小动画。如果Hytale在未来更新中添加动画混合支持，将重新审视此问题。

语音聊天接近度指示器

目前没有服务器端API来检测玩家是否在Hytale语音聊天中。原生语音系统完全由C#客户端处理。在玩家上方显示“语音活跃”指示器需要目前尚不存在的客户端API支持。

字体自定义

BubbleChat的文本使用原版名称牌元素（即显示玩家用户名在头顶的同一系统）渲染。这意味着字体、文本颜色和文本样式完全由Hytale内置的名称牌渲染器控制——目前没有服务器端API来更改这些属性。

我希望Hypixel在未来更新中增加对名称牌自定义的更多支持（文本颜色、字体更改、样式等）。一旦该API存在，我将更新BubbleChat以支持这些功能。

---

故障排除

玩家无法加入服务器

如果某些玩家无法连接，并且你在服务器日志中看到类似纹理相关的警告：

Texture dimensions are not multiples of 32: SomePlugin/SomeIcon.png (140x140)

这是由服务器上的另一个插件引起的，该插件的纹理尺寸不正确（PNG尺寸不是32的倍数）。BubbleChat在连接时向每个客户端发送自定义粒子定义，这会触发Hytale客户端重新验证服务器范围内所有粒子纹理——从而暴露了其他插件原本不会注意到的错误。

解决方法： 检查警告消息中标记的是哪些纹理——它们属于其他插件。将这些PNG图像调整为32的倍数（最小32x32），加入问题将得到解决。

来自原版资源的纹理警告

你可能还会看到关于Hytale自带的思考气泡纹理（AppleThought.png、PotatoThought.png等，尺寸为140x140）的警告——Hypixel自身的资源未能通过其自身的验证。这些警告是无害的，可以忽略。

发生这种情况是因为，当任何插件发送自定义粒子定义时，Hytale客户端会重新验证服务器范围内所有的粒子纹理，而不是仅验证该特定更新中引用的纹理。理想情况下，Hytale应修复原版纹理尺寸，并将重新验证的范围限定在仅更新的资源上——这也将消除连接时的 [AssetUpdate] 日志消息。

---

API —— 插件集成

其他插件可以使用BubbleChat API以编程方式触发对话气泡。

你的 manifest.json：

"Dependencies": { "BeyondSmash:BubbleChat": "*" }

用法：

import com.bubblechat.BubbleChatAPI;

// 在玩家上方显示一个对话气泡
BubbleChatAPI.showBubble(playerRef, "Hello world!");

// 清除/关闭一个玩家的活跃气泡
BubbleChatAPI.clearBubble(playerRef);

// 检查BubbleChat是否已加载并准备就绪
BubbleChatAPI.isReady();

// 检查一个玩家是否启用了气泡
BubbleChatAPI.isEnabled(playerRef);

// 检查一个玩家当前是否有活跃的气泡
BubbleChatAPI.hasActiveBubble(playerRef);

通过API触发的气泡会使用说话者自身的主题设置（颜色、浅色/深色模式），并尊重所有观看者的偏好设置（颜色覆盖、静音、隐藏、剔除距离）。

---

更新日志

1.7.1

修复

• 修复了多人游戏中其他玩家看不到气泡背景的问题——粒子配置现在作为单个组合数据包发送给每位观看者。
• 修复了嘴部表情（视位）无法播放的问题——切换到了一个兼容的动画插槽，该插槽能正确支持玩家实体上的动态注册动画。
• 修复了加入游戏后首次聊天时嘴部表情不显示的问题——添加了短暂的延迟，以便客户端在处理实体/粒子设置完成后再播放动画。
• 修复了喊叫粒子效果不触发的问题——修复了因从调度线程访问仅限世界线程的数据而导致的静默崩溃。
• 修复了首次聊天时文字偶尔出现在气泡背景上方的问题——自定义颜色生成器注册不再在实体生成期间发送资源更新。
• 修复了说话者之后加入的远程玩家缺少喊叫粒子生成器的问题。

新增

• 即时文本模式 —— /bchat text instant 可在逐词显示与所有文字同时出现之间切换。

改进

• 减少了登录卡顿——粒子配置不再在连接时发送；所有资源更新都延迟到首次聊天时进行。
• 首次聊天时仅发送单个 [AssetUpdate] 消息——所有粒子生成器、系统、喊叫配置、自定义颜色和嘴部动画都合并为一个数据包发送给每位观看者。

1.6.8

修复

• 修复了加入时不再出现 [AssetUpdate] 消息——粒子配置现在在首次聊天时惰性发送，因此从不聊天的玩家看不到任何资源更新消息。
• 修复了实体工具道具在首次聊天消息后无法恢复其缩放比例的问题——缩放比例恢复现在在每次聊天时都会应用，而不仅仅是第一次。
• 修复了通过实体工具放置的物品实体道具（例如剑掉落物）的缩放比例从未被恢复的问题。
• 缩放比例恢复现在实际上瞬间完成。

---

鸣谢

• EQNOX —— 测试与反馈
• BannerWolf —— 测试与反馈
• sai3rina —— 测试与反馈
• zenkuro —— 测试与反馈
• Matt_97 —— 测试与反馈
• WalnutOwl —— 测试与反馈
• Joey475574 —— 测试与反馈
• AZB —— 测试与反馈
• Jalatxe —— 测试与反馈
• DontActLikeMe —— 测试与反馈