NTCEmojiChatFolia

NTCEmojiChatFolia 是为 NeoTcc 服务器定制的聊天表情插件，支持玩家上传自定义表情、聊天点击保存、手动同步资源包、管理员表情管理 GUI、QQ 群机器人上传接口预留，以及面向中型服务器的资源包下载队列和带宽保护。

--

1. HELLO

• 支持平台：Paper / Folia，api-version: 1.21
• 资源包同步方式：玩家手动执行 /emoji sync
• 上传网页端口：默认 8123
• 玩家保存表情上限：默认 18 个

---

2. 主要功能

2.1 聊天表情

玩家可以在聊天中使用已保存的自定义表情。插件会将对应表情 token 替换为资源包字体字符，并附带 hover 提示。

表情 hover 中会提示：

这是一个自定义表情，如果未能正常显示请尝试使用 /emoji sync 同步资源。

如果接收者尚未保存该表情，hover 会提供点击保存交互，执行：

/emoji save <emojiId>

2.2 玩家表情 GUI

玩家执行：

/emoji

会打开 27 格 GUI：

• 上方最多显示 18 个玩家已保存表情。
• 左键点击表情：根据玩家发送模式执行操作。
• 右键点击表情：从玩家自己的表情列表中移除。
• 第 22 格：切换发送方式。
  • 文本互动组件提示
  • 直接发送该表情
• 第 24 格：上传表情按钮。
  • 点击后提示并补全 /emoji upload 。
  • Lore 会说明需要在补全命令后输入表情名称。

2.3 上传自定义表情

玩家使用：

/emoji upload <name>

插件会生成一个临时上传网页链接，玩家打开网页上传图片。

当前上传限制：

upload-server:
  max-file-size-kb: 1024
  max-image-width: 2048
  max-image-height: 2048

说明：

• 单张上传图片最大 1024 KB。
• 解码后的宽高最大 2048x2048。
• 图片最终会被缩放为 64x64 后写入动态资源包。
• /emoji upload 与 /emoji sync 共用 10 分钟冷却。
• OP / ntc.admin / emojichat.admin 不受冷却限制。

2.4 手动同步资源包

玩家执行：

/emoji sync

插件才会尝试向该玩家发送当前服务器表情资源包。

设计原则：

• 不在玩家加入服务器时主动发送资源包。
• 不在上传完成后主动发送资源包。
• 不在保存别人表情后主动发送资源包。
• 只在玩家手动 /emoji sync 时发送资源包。

这样可以避免玩家集中上线时直接触发资源包下载风暴。

2.5 首次提示

如果玩家从未成功加载过资源包，加入服务器后会收到一次小型多行聊天公告，建议玩家执行 /emoji sync，并建议安装 ResourcePackCached。

安装链接：

https://modrinth.com/mod/resourcepackcached

该提示只会对每名玩家显示一次。

2.6 管理 GUI

管理员执行：

/emoji set

可以打开管理 GUI。

管理 GUI 功能：

• 显示当前所有已注册的动态表情。
• 显示表情基础信息。
• 显示保存人数。
• 右键可全局删除表情。
• 删除后会从所有玩家保存列表中移除。

2.7 QQ 机器人上传接口预留

配置项：

qq-bot-api:
  enabled: false
  path: "/api/qq/emoji/upload"
  auth-token: "change-me"
  default-owner-name: "KiKi-FusionBot"

默认关闭。启用前必须修改 auth-token，否则接口会拒绝工作。

推荐仅在可信网络或反向代理鉴权后开放该接口。

---

3. 当前命令列表

当前保留的命令：

/emoji
/emoji list
/emoji upload <name>
/emoji save <emojiId>
/emoji sync
/emoji set
/emoji reload
/emoji help

当前未保留的旧命令：

/emoji info
/emoji mine
/emoji remove
/emoji saved

/emoji save 已恢复，因为聊天点击保存依赖此命令。

---

4. 权限节点

普通权限

emojichat.command.emoji: true
emojichat.chat: true
emojichat.upload: true
emojichat.save: true

管理权限

ntc.admin:
  default: op

拥有 ntc.admin 的玩家拥有完整插件管理员权限，并且不受 /emoji sync 与 /emoji upload 冷却限制。

旧权限仍保留兼容：

emojichat.admin:
  default: op

OP 默认拥有完整管理员权限。

---

5. 数据与资源包机制

5.1 表情数据

每个动态表情会包含：

image.png
meta.yml

玩家保存表情会写入玩家数据文件。

默认限制：

personal-emojis:
  max-saved-per-player: 18

这样可以控制聊天替换遍历量，也避免玩家个人 GUI 过大。

5.2 无人保存自动清理

当一个动态表情没有任何玩家保存时，插件会删除其相关数据，用于减少长期无用数据堆积。

注意：QQ 机器人上传的表情如果不加入玩家库，可能需要额外管理或定期清理，否则可能长期留在全局表情库中。

5.3 资源包缓存

当前版本已做资源包缓存优化：

• /emoji sync 优先使用已生成的资源包。
• 表情上传、删除、重载或数据变更后才需要重新生成资源包。
• 资源包 SHA-1 使用流式读取计算，避免一次性将完整 zip 读入内存。

这能明显降低 /emoji sync 对 CPU 和磁盘 IO 的压力。

---

6. 服务器性能压力说明

6.1 常驻压力

插件常驻压力较低，主要常驻行为包括：

• 监听聊天事件。
• 监听资源包加载状态。
• 保持上传 / 下载 HTTP 服务。
• 管理玩家表情数据缓存。

常态 70 人在线时，插件本身不应成为主要 TPS 压力来源。

6.2 聊天替换压力

聊天替换主要受以下因素影响：

可见玩家数量 × 消息长度 × 发送者已保存表情数量

由于每名玩家最多保存 18 个表情，聊天替换复杂度受到限制。

在 70 人在线情况下，正常聊天频率下压力通常较低。

压力等级：低

6.3 玩家 GUI 压力

普通玩家 GUI 固定为 27 格，最多显示 18 个保存表情。

打开 GUI 时只需要读取玩家自己的保存列表和少量按钮物品。

压力等级：低

6.4 管理 GUI 压力

管理 GUI 会展示全局注册表情和保存人数。

当前版本已将保存人数统计缓存化，避免每次打开管理 GUI 都遍历所有玩家数据。

压力等级：

• 表情数量 300 以内：低
• 表情数量 300 - 800：中低
• 表情数量 1000+：中

6.5 上传表情压力

上传流程包括：

1. 接收 HTTP 上传。
2. 校验文件大小。
3. 解码图片。
4. 校验分辨率。
5. 缩放到 64x64。
6. 写入 PNG。
7. 写入表情 meta 数据。
8. 标记或生成资源包缓存。

压力主要来自图片解码和资源包生成。

由于已限制：

max-file-size-kb: 1024
max-image-width: 2048
max-image-height: 2048

普通上传不会造成明显压力。

压力等级：中低

6.6 资源包生成压力

资源包生成会将所有动态表情图片和字体 JSON 打包成完整 zip。

表情数量越多，生成压力越高。

动态表情数量	资源包生成压力
100 以内	很低
100 - 300	低
300 - 500	中低
500 - 1000	中
1000+	中高，建议定期清理

当前已经避免 /emoji sync 每次都重建资源包，因此压力主要集中在上传、删除和重载时。

---

7. 带宽压力说明

7.1 服务器带宽基准

当前适配目标：

上传带宽上限约 70 Mib/s

换算：

70 Mib/s ÷ 8 ≈ 8.75 MiB/s

当前资源包下载保护配置：

resource-pack:
  download-queue:
    enabled: true
    max-concurrent-downloads: 2
    max-bytes-per-second: 2097152

含义：

• 同时最多 2 个玩家下载资源包。
• 每个下载连接最多约 2 MiB/s。
• 总资源包下载峰值约 4 MiB/s。
• 约等于 32 Mib/s。

因此在 70 Mib/s 上行下，理论上仍保留约：

70 Mib/s - 32 Mib/s = 38 Mib/s

给玩家日常游玩、语音/代理转发、地图数据和其他服务使用。

实际网络存在 TCP、代理、系统调度和丢包等开销，所以这是理论估算，不是绝对值。

7.2 资源包大小估算

资源包大小主要取决于动态表情数量和 PNG 压缩率。

由于表情会缩放为 64x64，单个表情通常不会很大。

动态表情数量	典型资源包大小	偏大情况
50	150 KB - 600 KB	约 1 MB
100	300 KB - 1.2 MB	约 2 MB
300	900 KB - 3.6 MB	约 6 MB
500	1.5 MB - 6 MB	约 10 MB
1000	3 MB - 12 MB	约 20 MB

复杂图片、噪点图片、透明边缘较多的 PNG 会使资源包偏大。

7.3 70 人集中同步时的等待估算

当前默认：

并发下载数 = 2
单连接速度 = 2 MiB/s

如果 70 名玩家同时执行 /emoji sync：

资源包大小	每批 2 人耗时	70 人总批次数	估算总耗时
5 MiB	2.5 秒	35 批	约 88 秒
10 MiB	5 秒	35 批	约 175 秒
20 MiB	10 秒	35 批	约 350 秒
50 MiB	25 秒	35 批	约 875 秒

当前等待超时：

wait-timeout-seconds: 900

因此在资源包不超过约 50 MiB 的情况下，70 人集中同步基本能排队完成。

建议将资源包长期控制在 20 MiB 以下，这样即使 70 人同时同步，也能在约 6 分钟内完成。

---