MoonBridge/docs/player-operations.md

玩家操作与部署完善设计

状态：本文保留首批玩家操作的设计基线。当前消息模型见富文本与命令补全。2026-09-26 Prism 记录是历史提交下的真实在线认证和客户端结果，不代表当前初次路由分支的完整模组包验收；当前路由证据见专项验收。

目标与边界

补齐插件管理玩家连接的最小操作，以及可配置的服务器列表展示。核心负责协议、连接身份、线程切换和资源释放；插件负责 Ban 数据、权限、玩法与业务准备。普通 PLAY 转发保持现有路径。每项完成以自动化协议/会话测试和发行包检查为准，不以设计文档代替运行证据。

1. 玩家操作

在 Players 增加：

CompletionStage<MessageResult> sendMessage(PlayerIdentity player, String message);
CompletionStage<DisconnectResult> disconnect(PlayerIdentity player, String reason);

身份与调用

• 两项操作均核对 UUID 和连接代次。旧连接请求不能作用于重连后的玩家。
• 调用方可在任意线程调用；会话状态与网络写入由玩家 EventLoop 串行执行。通过插件上下文取得的返回 stage 在 I/O 线程外完成。
• sendMessage 面向已进入可发消息状态的玩家；disconnect 也可作用于已经建立身份、尚在准入或初始选服中的玩家。
• 参数错误在调用时报告；插件关闭后不能继续提交操作。

消息

• MessageResult 为 SENT、NOT_CONNECTED、NOT_READY、BACKPRESSURED。SENT 表示网络写入完成，不表示客户端已经显示；写入失败以异常完成。
• 使用纯文本组件和正确 JSON 转义。最多 1024 个 Unicode 码点，空消息允许。
• 登录/Forge 初次握手未就绪、转服交接期间返回 NOT_READY，避免把游戏消息插入协议过渡阶段。
• 每连接最多 64 条未完成消息；不可写或超过上限立即返回 BACKPRESSURED，不建立无限等待队列。名额在写入完成/拒绝/关闭后释放。
• 命令回复复用该实现，保持其尽力发送语义。

断开

• DisconnectResult 为 DISCONNECTED、NOT_CONNECTED。前者表示匹配连接已经清理并关闭；断开原因仅尽力交付。
• 根据前端实际 LOGIN/PLAY 阶段编码断开包，并复用当前加密链路。不会仅根据在线列表是否已发布推断协议阶段。
• 同一连接重复断开合并为一次流程。最多等待 5 秒排空写入，然后关闭；客户端提前关闭或写入失败也必须完成清理。
• 终止未决认证、准入、选服和转服，关闭候选后端，释放会话索引及缓冲；已发布玩家只发一次断线事件。
• 取消调用方的等待不撤销已提交的断开操作。断开过程阻止新的消息和转服请求。

2. 服务器列表

新增 status 配置：

status:
  motd: "MoonBridge"
  maxPlayers: 100
  # icon: "server-icon.png"

• motd 是纯文本，允许换行，最多 1024 个 Unicode 码点。
• maxPlayers 是展示上限（1–1,000,000）；实际接入资源限制仍使用 maxConnections。在线人数来自当前会话索引。
• 可选图标为 64×64 PNG，路径相对所用配置文件；启动时读取、校验、转为 data URL。图标文件读取上限为 64 KiB，图标与文本组合后的完整响应还须满足协议字符串 32,767 UTF-8 字节上限。错误配置使启动/配置校验失败。
• 静态响应字段预先构造；STATUS 请求仅填入当前在线人数，不做文件 I/O 或调用插件，不为此添加事件。
• 保持协议 5 状态查询与 Ping/Pong 行为。

3. 自动化验收

• 协议：文本/断开原因转义和非 ASCII；LOGIN/PLAY 包编码；在线连接加密可解码。
• 会话：消息到达客户端且正常转发继续；未就绪/背压/断线时返回明确结果；过期 identity 不影响重连。
• 断开：登录等待、正常 PLAY、候选后端登录和转服交接；重复调用、写失败/超时；候选连接、索引、缓冲和断线事件正确清理。
• 插件：停用后拒绝操作；后续回调不在 Netty I/O 线程执行；命令回复回归。
• STATUS：默认值、自定义文本/人数/图标、非法配置、响应转义和实时在线人数。
• 最终执行 gradlew check --offline，包含发行包帮助、版本和配置校验。

4. 后续验收与阶段

1. 使用已登录正版账号的 1.7.10 Forge 客户端，经 ONLINE_BUNGEE 连接到启用旧版 Bungee 身份转发的离线后端。核对真实 UUID、用户名、皮肤属性，及往返转服后的身份一致性。后端仅接受代理连接。
2. 验证 Mojang 不可达/超时、认证拒绝、目标服拒绝/断线等故障。真实服务测试和本地注入验证器的结果分别记录。
3. 使用用户提供的目标整合包进行反复登录/转服、长时间驻留和并发测量，记录内存、失败率与延迟；合成测试不替代目标环境验收。
4. 恢复 Runner Docker 后验证远端 CI。
5. 命令 Tab 补全、控制台命令和维护排空入口作为后续设计项，按实际运维需求推进。

真实认证需要可用的正版登录会话；目标整合包尚待提供。上述依赖未满足时，只报告代码和实际运行过的自动化测试结果。

5. 本轮交付（2026-09-26）

玩家消息/断开 API、命令回复复用、服务器列表配置均已实现。集成时修复了转发启动标记未复位、关闭代理与主动断开并发时返回 stage 可能不完成，以及宿主撤销监听器后准入链可能跳过策略而返回允许的问题。

gradlew.bat check --offline 通过：194 项测试（API 7、核心 174、DNS 6、Agent 7），失败、错误、跳过均为 0；发行包帮助、版本和配置校验通过。详细范围见验证记录。本轮未进行真实 Mojang 服务、目标整合包或生产容量测试。