原创 工具 服务器条款展示 1.5.0

[MD] # ServerTerms 1.5.0 Paper 服务端条款阅读与同意插件，适用于 **Paper / Purpur 1.21.x 与 26.x**及其Paper兼容分支。 - SHA-256：`048f71dcb17542e16eea63b7f413c273bcd8fe294e0964a75e590f477b0fb3cf` - 作者：**AAAlsc1145** > 升级注意：`plugins/` 里只能保留一个 ServerTerms jar。先删除旧的 `ServerTerms-1.4.0.jar` / 更早版本，再放入 1.5.0。 --- 1. **TUI 同意/拒绝命令增加会话 ID**：每次进入条款流程生成随机 32 位十六进制 ID；聊天按钮自动带上，旧 ID/缺少 ID 的 `/terms ui agree`、`/terms ui reject` 不执行。 2. 默认提示页最前面新增一句： > 一般情况下请先完成服务器登录再看条款。 老版本 `config.yml` 没有这句时，插件也会自动补在提示页最前面，不需要重新设书。 3. **未同意期间过滤新内容**： - 不显示其他玩家的公开聊天； - 不显示死亡消息； - 不显示成就/进度消息； - 不显示其他玩家的加入/退出消息； - 其他已同意玩家不受影响； - 登录插件等**直接发给玩家**的消息仍会显示（例如 AuthMe 的登录提示），这样不会影响先登录。 4. **TUI 每 5 秒自动刷新**： - 文本 TUI 会每 5 秒重新发送当前页，保持条款在聊天栏底部； - Dialog 是模态界面且会重置滑条，因此不自动重发；它的新内容已经由聊天过滤屏蔽。 5. 1.3.0/1.4.0 的 TUI 固定坐标/效果、TUI 玩家行/拒绝按钮、Dialog 无页码/玩家行/拒绝按钮、无管理员豁免、always/once 授权、内容过滤和提示页登录句继续保留。 --- ## 二、TUI（聊天框文本界面） 玩家未同意时，聊天栏会收到类似内容： ```text ──────────────────────────── 《服务器条款》 第 1 / 5 页 玩家：Steve 剩余 60 秒 一般情况下请先完成服务器登录再看条款。本服务器条款如下…… ──────────────────────────── 第 1 / 5 页 [ 下一页 ] [ 拒绝条款 ] 输入 /terms 可重新显示本页 ``` - 点击 `[ 下一页 ]` 翻页；最后一页显示 `[ 同意条款 ]`。 - 每页都有 `[ 拒绝条款 ]`；点击后按 `reject-message` 踢出，背包快照和原始坐标保留。 - 同意/拒绝按钮的点击命令会自动携带本次会话的 32 位十六进制 ID；手动输入时也必须带 ID，否则不执行。 - **TUI 期间固定坐标**： - 进入 TUI 后传送到原世界的 `0, 320, 0`； - 开启飞行并拦截位置移动（能转视角，不能位移）； - 持续施加无粒子黑暗 + 隐身； - 同意后传送回进入 TUI 前的原始坐标、恢复原飞行状态、清除黑暗/隐身、恢复背包； - 拒绝、超时、退出、服务器关闭时同样恢复原坐标并清除效果； - 原始坐标写入 `data/pending`，中途退出/重启后仍能恢复。 - **TUI 每 5 秒重发当前页**；聊天栏只保留条款页和登录等直接消息，其他公开聊天/死亡/成就/进退服消息不会发给未同意玩家。 - 文本 TUI 没有“箱子界面关闭/重开”的概念；页面会留在聊天记录中，`/terms` 可重新显示当前页。 --- ## 三、未同意期间的内容过滤 过滤仅对**尚未同意**的玩家生效；已同意玩家和未锁定玩家看到的内容不变。 | 内容 | 未同意玩家是否可见 | 说明 | |---|---|---| | 其他玩家公开聊天 | 否 | 通过 Paper `AsyncChatEvent` 移除未同意接收者 | | 死亡消息 | 否 | 从默认广播中去除，改发给其他玩家和后台 | | 成就/进度消息 | 否 | 同上 | | 其他玩家加入/退出消息 | 否 | 同上 | | TUI 条款页、TUI 自动刷新 | 是 | 插件直接发送 | | 登录插件/其他插件直接发给玩家的消息 | 是 | 例如登录提示；无法做通用过滤 | | 标题、ActionBar、BossBar、计分板、直接广播 | 通常是 | 不走上述事件；TUI 每 5 秒重发可覆盖聊天栏新内容 | 后台控制台仍会收到被手动转发的死亡/成就/进退服消息。TUI 每 5 秒刷新一次；Dialog 不刷新（避免重置滑条），但 Dialog 本身覆盖界面，且新内容已被过滤。 --- ## 四、Dialog - 使用 Paper Dialog API（Paper API 1.21.7+，对应 Minecraft 1.21.6+ 的客户端能力）。 - 条款正文完整显示在可滚动对话框中，**不显示页码**。 - 正文开头显示 `《条款标题》` 和 `玩家：<当前玩家名>`。 - 底部有： - 人机验证滑条（默认需要拉到 ≥ `dialog-slider-threshold`）； - `[ 同意条款 ]`； - `[ 拒绝条款 ]`。 - 点击“拒绝条款”会按 `reject-message` 踢出，不写同意记录，背包快照保留。 - 对话框不能按 ESC 关闭；超时由服务端踢出。 - 服务端不支持 Dialog API 或构建/显示失败时自动回退到文本 TUI。 - ViaVersion 低版本客户端不支持 Dialog，请 `/terms mode tui`。 `auto` 是默认值：支持 Dialog 就用 Dialog，否则用文本 TUI。想固定聊天文本界面请执行 `/terms mode tui`。 --- ## 五、授权方式 ### `auth-mode: always`（默认） - 每次进入服务器都保存背包、清空、阅读并同意。 - 每次同意都更新 `data/accepted/<uuid>.yml`。 - 管理员没有豁免，默认每次进服也要走一次；完成同意、背包恢复后再更新条款。 ### `auth-mode: once`（单次授权） - 已有同意记录的玩家直接进入，不再清空背包。 - 未同意或被 `/terms reset` 清除记录的玩家仍会进入条款流程。 - 切换用 `/terms auth once`；对下一次进入生效，当前已锁定的玩家仍完成本次流程。 --- ## 六、安装与首次设置 1. 删除 `plugins/` 中旧 ServerTerms jar。 2. 放入 `ServerTerms-1.5.0.jar`，重启服务器。 3. 首次安装且还没有条款时，不会锁定任何人。 4. 主手拿一本已写好内容的**成书**或**书与笔**，执行： ```text /terms set ``` 5. 条款保存到 `plugins/ServerTerms/terms.yml`，自动插入提示页，并同时转换到文本 TUI 和 Dialog。 6. 用普通玩家账号验收。 --- ## 七、指令与权限 | 指令 | 说明 | 权限 | |---|---|---| | `/terms` | 未同意时重新显示当前页；管理员无会话时显示帮助 | 无 | | `/terms ui next` | 文本界面下一页按钮（聊天按钮使用） | 无（需要会话） | | `/terms ui agree <会话ID>` | 文本界面同意按钮；需当前会话 ID，最后一页生效 | 无（需要会话） | | `/terms ui reject <会话ID>` | 文本界面拒绝按钮；需当前会话 ID，踢出并保留背包快照 | 无（需要会话） | | `/terms ui show` / `open` | 重新显示当前页 | 无（需要会话） | | `/terms set` | 把主手的书设为条款 | `serverterms.admin` | | `/terms reload` | 重载 config、modes 与条款，刷新界面 | `serverterms.admin` | | `/terms reset <玩家>` | 清除同意记录；once 模式强制重新同意 | `serverterms.admin` | | `/terms mode <auto\|tui\|dialog>` | 切换文本 TUI / Dialog；立即刷新 | `serverterms.admin` | | `/terms auth <always\|once>` | 每次进服同意 / 单次授权；下次进入生效 | `serverterms.admin` | | `/terms help` | 管理员帮助 | `serverterms.admin` | - 只有 `serverterms.admin`（默认 op）；**没有 bypass 权限**。 - `/terms` 命令本身开放给玩家用于文本界面；管理员子指令在命令内部校验权限。 - `/条款` 已删除。 --- ## 八、玩家流程 1. 未同意玩家加入服务器。 2. 背包（主背包、盔甲、副手、选中槽位）和原始坐标保存到 `data/pending`，然后清空背包。 3. 条款界面自动显示（`initial-open-delay-ticks` 后）： - **文本 TUI**：聊天栏显示页面；玩家被固定在原世界 `0,320,0`，飞行锁定，带无粒子黑暗/隐身；TUI 每 5 秒重发当前页； - **Dialog**：滚动阅读正文，拖动滑条到阈值以上，点击同意；或点击拒绝。 4. 未同意期间聊天/死亡/成就/进退服消息被过滤；登录等直接消息仍可见。 5. 同意后： - TUI：传送回原始坐标、恢复飞行、清除黑暗/隐身； - 写入同意记录并恢复背包。 6. 超时未同意（默认 60 秒，从界面首次显示开始）被踢出： > 你未同意本服务器条款，已将您踢出，若想继续游玩，请重新加入，请同意条款 7. 拒绝（TUI/Dialog）按 `reject-message` 踢出，背包快照和原始坐标保留。 8. TUI 的同意/拒绝必须使用当前页聊天按钮；按钮内含本次登录随机生成的 32 位十六进制会话 ID。缺少 ID、填错 ID 或使用上次进入的旧 ID 都不会执行。 --- ## 九、配置（plugins/ServerTerms/config.yml） | 键 | 默认 | 说明 | |---|---|---| | `intro` | 见下方 | 每本书最前面自动插入的提示页；登录提示句会自动保证出现在最前面 | | `book-title` | 服务器条款 | 来源是书与笔时使用的书名；成书优先使用自身书名 | | `terms-author` | AAAlsc1145 | 条款元数据作者（用于 `/terms set` 提示）；TUI/Dialog 界面显示当前玩家名 | | `ui-mode` | auto | auto / tui / dialog；可被 `data/modes.yml` 覆盖 | | `auth-mode` | always | always / once；可被 `data/modes.yml` 覆盖 | | `dialog-slider-threshold` | 95.0 | Dialog 人机验证滑条需要达到的值（0-100） | | `timeout-seconds` | 60 | 未同意最多停留秒数；0 表示不踢出 | | `kick-message` | 见下方 | 超时踢出提示，支持 `&` 颜色码 | | `reject-message` | 见下方 | TUI/Dialog 点击“拒绝条款”后的踢出提示 | | `prefix` | `&6[服务器条款] &r` | 聊天提示前缀 | | `allowed-commands` | login/l/register/reg/登录/注册 | 未同意期间允许的指令；`/terms` 始终允许 | | `initial-open-delay-ticks` | 2 | 首次显示界面前的延迟（刻）；有登录插件可调大 | | `line-width` | 44 | 文本 TUI 每行宽度（中文按 2 计），44 约 22 个汉字 | | `max-lines-per-page` | 16 | 文本 TUI 每页最多行数，超出自动分页 | | `prevent-damage` | true | 未同意期间禁止受伤 | 默认提示页（登录提示句会自动保证在最前面）： > 一般情况下请先完成服务器登录再看条款。本服务器条款如下，将其进行署名代表你同意该条款，将其翻到最后一页代表你已经阅读玩此条款，才能进行署名。 默认超时提示： > 你未同意本服务器条款，已将您踢出，若想继续游玩，请重新加入，请同意条款 默认拒绝提示： > 你拒绝了本服务器条款，已将您踢出；若想继续游玩，请重新加入并同意条款。 --- ## 十、书本输入与自动转换 - `/terms set` 只读取**主手**的书；支持成书和书与笔。 - 书页文字自动： - 最前面加入包含登录提示的提示页； - 转换为文本 TUI 的逐页聊天显示； - 转换为 Dialog 的可滚动正文。 - 书名优先使用成书标题；书与笔使用 `book-title`。 - TUI 和 Dialog 都显示 `玩家：<当前玩家名>`；`terms-author` 仍作为条款元数据/设置提示中的作者信息。插件作者为 AAAlsc1145。 - 源书本身不修改；`terms.yml` 保存来源页和标题，提示页运行时生成。 --- ## 十一、数据文件 目录：`plugins/ServerTerms/` - `terms.yml`：条款来源页、书名、更新信息。 - `data/pending/<uuid>.yml`：背包快照、`restored` 状态和原始坐标；**不要手动删除**。 - `data/accepted/<uuid>.yml`：同意记录（名字、UUID、时间、条款哈希、恢复状态）。 - `data/modes.yml`：指令切换后的 ui-mode / auth-mode 覆盖值。 说明： - 快照先成功落盘再清空背包；保存失败会跳过本次验证，避免丢物品。 - `restored: false` 表示快照尚未恢复；`true` 表示已恢复，可视为过期文件。 - 原始坐标写在 pending 中；玩家在 TUI 固定点退出或服务器重启后，下次进入会先恢复原坐标。 - 旧版本 pending 文件没有坐标字段，会按当前登录位置处理。 - 直接删除插件目录会丢失待恢复背包，请先备份。 --- ## 十二、登录插件 / ViaVersion 1. 文本 TUI 不占用聊天，玩家可输入 `/login` 等允许指令；登录插件的直接消息仍会显示。 2. Dialog 是模态界面，打开前主要依赖 `initial-open-delay-ticks`；文本 TUI 无此问题。 3. 保留 `allowed-commands` 中的登录/注册指令，按登录插件实际指令补充（如 `authme`）。 4. 登录插件如果必须通过 GUI 登录，本插件会拦截其他界面，需要额外兼容。 5. ViaVersion 低版本客户端不支持 Dialog，请 `/terms mode tui`。 --- ## 十三、兼容性与验证情况 - 编译目标：Paper API `1.21.11-R0.1-SNAPSHOT`，`release 21`（class 版本 65）。 - `plugin.yml`：`api-version: '1.21'`，可加载 26.x；Java 21+。 - Dialog 代码位于独立 `PaperDialogView`，通过反射检测按需加载；无 Dialog API 的版本只加载文本 TUI。 - 已核对 1.21.11 / 26.2 的 Dialog、聊天、死亡、成就、进退服消息 API。 - 已完成的离线验证： - `mvn -B -o clean package` 构建通过； - `PageRendererCheck` 分页/换行/颜色续接/模式解析断言通过； - SnakeYAML 解析 jar 内 `plugin.yml`、`config.yml` 通过； - jar 内容、class 版本（major 65）检查通过。 - **未在本机启动 Minecraft 服务端**；聊天过滤、TUI 5 秒刷新、坐标固定、无粒子效果、Dialog 滑条等需要你在 Paper/Purpur 上实测。 --- ## 十四、游戏内验收清单 1. 删除旧 jar，放入 1.5.0，重启；确认日志 `ServerTerms 已启用`。 2. 首次设置：管理员无条款时主手拿书，`/terms set`；确认提示页第一句包含“一般情况下请先完成服务器登录再看条款”。 3. `/terms mode tui`，普通账号进入： - 坐标被固定在原世界 `0,320,0`（F3 查看），能转视角但不能位移； - 有黑暗/隐身，且无粒子； - 聊天栏有页面和 `[ 下一页 ]`、`[ 拒绝条款 ]`；最后一页有 `[ 同意条款 ]`； - 每 5 秒页面会自动重发一次； - 另开一个玩家发公开聊天、死亡、完成成就、加入/退出，未同意玩家不应看到这些新内容； - 登录插件提示、`/terms` 等直接消息仍应可见； - 点击同意后回原坐标，飞行恢复，黑暗/隐身消失，背包恢复； - 点击聊天按钮可以同意/拒绝；手动输入 `/terms ui agree` 或 `/terms ui reject` 不带 ID 应提示缺少会话ID；使用错误或上次登录的旧 ID 应提示无效。 - 点击拒绝后按 `reject-message` 踢出，背包/坐标快照保留。 4. 固定点退出/重启：在 0,320,0 退出，重进后应恢复原坐标并继续流程。 5. `/terms mode dialog`： - 正文无页码，开头 `玩家：<名字>`； - 滑条未达标点同意应被拒绝并重开； - 达标同意成功； - 拒绝按 `reject-message` 踢出，快照保留； - ESC 不能关闭，超时踢出。 6. `/terms auth once`：完成一次后重进直接进入；`/terms reset <玩家>` 后再进重新要求；`/terms auth always` 恢复每次。 7. 超时测试：`timeout-seconds` 改 10，`/terms reload`，重进不操作，确认踢出提示。 8. 检查 `terms.yml`、`data/modes.yml`、`data/pending`（含坐标）、`data/accepted`。 --- ## 十五、版本历史 - **1.5.0**：TUI 同意/拒绝命令增加随机 32 位十六进制会话 ID；旧 ID/缺少 ID 不执行。 - **1.4.0**：提示页新增登录提示句；未同意期间过滤公开聊天/死亡/成就/进退服消息；TUI 每 5 秒自动刷新；保留 TUI 固定坐标/效果、TUI 玩家行/拒绝、Dialog 无页码/玩家行/拒绝。 - **1.3.0**：TUI 聊天文本界面；TUI 固定 0,320,0、飞行/移动锁定、无粒子黑暗+隐身、同意/拒绝/超时/退出恢复原坐标；TUI 玩家行与拒绝按钮；Dialog 保持无页码/玩家行/拒绝。 - **1.2.0**：TUI 改为聊天文本界面；移除 `/条款`；Dialog 无页码、玩家行、拒绝按钮；移除箱子 GUI 与 reopen 配置。 - **1.1.0**：去掉管理员豁免；always/once 授权；早期箱子 TUI/Dialog；滑条；书页转换。 - **1.0.0**：首个版本。 [/MD]