# 方块躲猫猫（BlockHideAndSeek） > **Paper / Folia 1.19.4+ 高性能迷你游戏插件** ｜当前版本：**0.1.6** ｜开发团队：**星桅工作室（StarMastStudio）** > > 内测交流群：1093939989（QQ） > > ⚠️ **闭源声明**：本插件为闭源，未经授权禁止搬运、使用、反编译、二次分发。授权与使用期限说明见 [第 12 章](#12-使用期限与授权)。 >_**不想建图或找图测试？** 官方测试地图(1.21)与配套地图配置下载：https://wwbce.lanzouu.com/ifFS348982bi （密码：SM）_ > >_（方块躲猫猫官方测试包由星桅工作室创作，采用知识共享署名-非商业性使用-禁止演绎 4.0 国际 (CC BY-NC-ND 4.0) 许可协议。要查看此许可协议的副本，请访问 [https://creativecommons.org/licenses/by-nc-nd/4.0/ 。）](https://creativecommons.org/licenses/by-nc-nd/4.0/)_ > >**地图仅供测试，不做游戏平衡性保证** --- ## 目录 - [1. 插件概述](#1-插件概述) - [2. 功能特性](#2-功能特性) - [3. 运行环境要求](#3-运行环境要求) - [4. 部署步骤（分步详解）](#4-部署步骤分步详解) - [5. 插件目录结构](#5-插件目录结构) - [6. GUI 界面与地图创建向导](#6-gui-界面与地图创建向导) - [7. 配置文件详解与修改步骤](#7-配置文件详解与修改步骤) - [8. 游戏模式详解](#8-游戏模式详解) - [9. 命令与权限](#9-命令与权限) - [10. 数据存储与备份](#10-数据存储与备份) - [11. 配置自愈机制](#11-配置自愈机制) - [12. 使用期限与授权](#12-使用期限与授权) - [13. 常见问题排查](#13-常见问题排查) - [14. 更新日志](#14-更新日志) --- ## 1. 插件概述 **方块躲猫猫** 是一款专为 Paper 1.19.4+ 及 Folia 服务端打造的高性能迷你游戏插件。它将经典的"躲猫猫"玩法与 Minecraft 世界巧妙结合——**躲藏方**可以伪装成各种方块，融入环境中躲避追捕；**猎人**则需要利用弓弩和各类道具，在限定时间内找出并"消除"所有躲藏者。 ### 组件生态 | 组件 | 类型 | 说明 | |------|------|------| | **BlockHideAndSeek** | 主插件 (Paper/Folia) | 本文档对象：核心游戏逻辑、商店、数据存储等全部游戏功能 | | **StarMastMonitor** | 独立插件 (Spigot/Paper/Folia) | 生产级服务器性能监控（`/monitor`），本插件性能命令已移交至此 | | **BlockHideAndSeek-Velocity / Lobby / Matchmaker** | 代理端/匹配服务 | 跨服匹配组局支撑（暂不对外提供，通过 `proxy.yml` 匹配机链路接入） | > 主插件可独立运行于单服务器模式；除 StarMastMonitor 外，其余组件仅面向需要跨服匹配的服务器网络提供。 --- ## 2. 功能特性 ### 游戏机制 - **三种游戏模式**（按权重随机抽取，可独立启停）：经典模式、感染模式、黑夜迷雾模式 - **完整游戏阶段**：等待 → 倒计时 → 模式公布 → 准备 → 躲藏 → 搜寻 → 结束 - **智能队伍分配**：自动平衡躲藏方与猎人人数（VIP 可获更多候选方块） - **伪装系统**：支持全部原版 Material 与 MOD 命名空间方块（混合端），虚拟碰撞箱可放大（0.5~3.0 倍） - **暴露机制**：搜寻阶段定时暴露（烟花）、最后一分钟周期性暴露、暴露前提示 - **实体方块转换**：伪装方块 6 秒后实体化，可被物理碰撞 - **积分系统**：按阶段区间随机发放，VIP 倍率，伪装更换消耗积分 - **MVP 计算**：隐藏方/猎人分别计分（击杀、生存、道具使用、连杀等权重可配），自动结算与决胜 ### 商店系统内置 14 种全局道具 + 模式专属道具，GUI 购买： | 物品 | 效果 | 物品 | 效果 | |------|------|------|------| | 加速卷轴 | 提升移动速度 | 更换伪装物品 | 重新随机伪装方块 | | 传送门 | 瞬间传送至指定位置 | 分身陷阱 | 生成假分身迷惑敌人 | | 干扰器 | 干扰猎人追踪 | 暴露所有躲藏方 | 短暂暴露所有躲藏方位置 | | 闪光弹 | 致盲周围玩家 | 追踪钟表 | 追踪最近躲藏方方向 | | 自爆炸弹 | 范围伤害 | 箭矢 | 补充弓弩弹药 | | 透视药水 | 透视附近躲藏方 | 防爆盔甲 | 减免爆炸伤害 | | 陷阱 | 脚下布置陷阱 | 地震锤 | 范围震动效果 | 模式专属：黑夜迷雾 —— 夜视药水 / 灯笼 / 感知技能 / 照明弹；感染模式 —— 净化血清 / 免疫护盾。 ### 其他能力 - **存储系统**：JSON 本地存储（默认）/ MySQL / Redis，数据库故障自动降级，跨服数据同步（需 Redis） - **排行榜**：连胜榜、胜场榜、游戏时长榜、MVP 次数榜；玩家个人战绩（总场/胜败/连胜/MVP） - **地图系统**：多地图独立配置，每图可覆盖商店价格、伪装列表、时长、MVP 权重 - **代理支持**：BungeeCord / Velocity 自动识别与状态广播；可选 WebSocket 连接匹配机实现跨服组局 - **监控日志**：高频日志过滤、日志聚合摘要、错误收集、Delog 调试日志、bStats 统计 - **服务器锁定**：游戏进行中锁定服务器，仅管理员可加入，结束自动解锁 - **背包备份**：加入游戏自动备份背包/盔甲/副手，离场自动恢复 - **世界备份**：启动与 `/bhs reload` 时自动备份启用地图的世界 --- ## 3. 运行环境要求 | 项目 | 要求 | 说明 | |------|------|------| | Minecraft 服务端 | **Paper 1.19.4+** 或 **Folia** | 推荐 Paper 1.21.x；Purpur 兼容；Mohist/Arclight 混合端部分兼容 | | Java | **JDK 17+** | 低于 17 将无法加载（编译目标为 17） | | 内存 | ≥ 4GB（单局 20 人建议 6GB+） | 取决于游戏世界大小 | | 可选依赖 | MySQL 8.0+ / Redis 6.0+ | 仅在启用数据库/缓存时必需 | | 可选网络 | 能访问公网（国内信源） | 使用期限在线校验的容错基础（见 [第 12 章](#12-使用期限与授权)） | | 可选端口 | 8765（匹配机 WS）、3306（MySQL）、6379（Redis） | 按需放行 | 兼容性结论（基于代码事实）： | 服务端 | 兼容性 | 说明 | |--------|--------|------| | Paper 1.19.4+ | ✅ 完全兼容 | 推荐使用（TPS API 依赖 Paper） | | Purpur | ✅ 完全兼容 | Paper 衍生 | | Folia | ✅ 完全兼容 | `folia-supported: true`，自动探测区域调度器 | | Spigot | ⚠️ 有限兼容 | 使用 Paper API（如 `getTPS`），纯 Spigot 可能报错，建议用 Paper | | Mohist / Arclight | ⚠️ 部分兼容 | 支持 MOD 方块名解析，但混合端可能存在问题 | --- ## 4. 部署步骤（分步详解） ### 步骤 1：准备服务端 1. 安装 **Java 17+**（`java -version` 验证）。 2. 部署 **Paper 1.19.4+** 服务端（或 Folia）。 3. 关闭服务器，确认 `plugins/` 目录存在。 ### 步骤 2：放入插件 JAR 1. 将授权提供的 `BlockHideAndSeek-0.1.5.jar`（闭源混淆构建产物）放入 `plugins/` 目录。 2. 无需额外安装依赖：HikariCP、Jedis、Java-WebSocket、MySQL 驱动、Gson、Protobuf 均已内置并重定位（`net.starmast.lib.*`）。 ### 步骤 3：首次启动，自动初始化启动服务器，控制台预期出现： ``` [BlockHideAndSeek] 使用期限验证通过（在线时间校验），插件有效至 2027-06-30 23:59。 [BlockHideAndSeek] 存储系统配置已加载，数据库模式: 禁用 [BlockHideAndSeek] 已启用 JSON 文件存储模式 [BlockHideAndSeek] 正在检查配置文件... [BlockHideAndSeek] 配置检查完成，未发现问题。 [BlockHideAndSeek] 已加载地图: 经典模式示例地图 (sample-map.yml) [BlockHideAndSeek] 配置文件已自动更新，补全了缺失的配置项。 [BlockHideAndSeek] ===================================== [BlockHideAndSeek] 方块躲猫猫 (BlockHideAndSeek) [BlockHideAndSeek] 版本: 0.1.5 [BlockHideAndSeek] 作者: StarMastStudio [BlockHideAndSeek] 未经授权，禁止搬运、使用、反编译此代码产品 [BlockHideAndSeek] ===================================== ``` - 若显示"配置检查完成，发现 N 个问题"，请按 [第 13 章](#13-常见问题排查) 排查。 - 世界加载完成后（约 5 秒），自动执行启动世界备份、记分板初始化、匹配机状态确认（若启用）。 ### 步骤 4：修改配置（核心）最常见的三个文件： 1. `config.yml` —— 等待室/大厅/游戏世界坐标、人数上限、时长、伪装方块、商店（**必改**，见 7.1） 2. `maps/*.yml` —— 每张地图的世界与坐标（**必改**，见 7.2） 3. `database.yml` —— 开启 MySQL/Redis（可选，见 7.3） ### 步骤 5：生效方式 - **方式一（日常改数值）**：管理员执行 `/bhs reload`，重载配置与地图（不会重置进行中的游戏）。 - **方式二（改 YAML 结构/世界相关/存储/代理）**：重启服务器（`load: STARTUP` 保证世界加载后引用坐标；存储/代理/匹配机均在启动期初始化）。 ### 步骤 6：验证安装 1. `/bhs help` 出现帮助信息即安装成功。 2. `/bhs status` 查看实时游戏状态。 3. `/bhs join` 测试加入游戏。 > ⚠️ **务必完成地图配置**：自动生成的示例地图坐标为占位值（100,65,100 等），不代表你的实际世界。请在游戏内用 F3 记录真实坐标后填入 `maps/*.yml`（见 7.2）。 --- ## 5. 插件目录结构 ``` plugins/ └── BlockHideAndSeek/ ├── BlockHideAndSeek-0.1.5.jar ← 插件本体（闭源混淆产物） ├── config.yml ← 主配置文件（缺失项自动补全） ├── database.yml ← 数据库/缓存/连接池配置 ├── proxy.yml ← 代理与匹配机配置 ├── monitoring.yml ← 监控配置模板（预留，当前版本未解析） ├── notification.yml ← 通知配置模板（预留，当前版本未解析） ├── delog.yml ← Delog 调试日志配置（自动生成） ├── maps/ ← 地图配置（示例地图自动生成） ├── data/ ← JSON 模式下玩家数据（.json + .bak） └── logs/ └── delog/ ← Delog 调试日志（delog-YYYY-MM-DD.log）服务器根目录/ └── GameBackup/ ← 游戏世界自动备份（每张启用地图一个子目录） ``` --- ## 6. GUI 界面与地图创建向导 > 从 v0.1.5 起提供游戏内 GUI 面板，代替大部分命令行操作；面板内容**每 0.5 秒自动刷新**，随游戏状态（阶段/人数/地图/倒计时）动态变化。 ### 6.1 打开方式 - 玩家：输入 `/bhs` 或 `/bhs gui` 打开**用户主菜单**（默认所有玩家，需 `bhs.player`）。 - 管理员：在主菜单点击 **管理员面板** 进入管理视图（需 `bhs.admin`）。 ### 6.2 用户主菜单 | 按钮 | 功能 | |------|------| | 加入游戏 / 离开游戏 | 根据玩家状态动态切换：未加入时绿色羊毛「加入游戏」，已加入时红色羊毛「离开游戏」。不可加入时按钮变灰并显示原因（游戏已满 / 结算中 / 进行中 / 即将开始） | | 游戏状态 | 展示当前阶段、人数（当前/上限/最少）、地图、模式、倒计时；点击后在聊天栏输出完整状态详情 | | 我的数据 | 个人战绩面板：总场数、胜场、败场、胜率、当前连胜、最多连胜、累计时长、总 MVP（躲藏方/猎人）、击杀/死亡与 K/D；异步加载并缓存，面板内可手动刷新（30 秒冷却，与 `/bhs data me` 一致） | | 公共数据 | 排行榜面板：最多连胜 / 胜场 / 游戏时长 / MVP 四类榜单 Top10，底部按钮即时切换，可手动刷新 | | 管理员面板 | 仅拥有 `bhs.admin` 的玩家可见，点击进入管理视图 | ### 6.3 管理员面板 | 按钮 | 功能 | |------|------| | 强制开始游戏 | 要求处于等待阶段且人数 ≥ 最少人数；可用性随阶段动态提示（等效 `/bhs start`） | | 缓和停止游戏 | 正常结束流程、结算并恢复玩家状态、重置世界后重新开放（等效 `/bhs gentlestop`） | | 强制停止游戏 | 立即终止一切游戏逻辑、清零状态并恢复玩家背包，请谨慎使用（等效 `/bhs forcestop`） | | 重载配置 | 重载主配置与地图配置，并执行世界备份检查（等效 `/bhs reload`） | | 地图创建向导 | 进入下方一站式建图流程 | ### 6.4 地图创建向导（`/bhs setup`）令管理员不接触配置文件即可在游戏内快捷创建一张新地图，全部步骤有聊天栏可点击按钮引导： 1. **开始**：运行 `/bhs setup`（或管理员面板 → 地图创建向导，游戏进行中会被拦截）。 2. **输入名称**：按引导在聊天框输入地图名称（1~32 字符，支持颜色代码；输入 `cancel` 取消），输入后聊天栏出现「打开设置面板 / 保存并完成 / 取消创建」按钮。 3. **手持物品对空右键**：随时打开/刷新设置面板；**手持方块对空右键**会同时把该方块加入伪装方块列表；**手持方块右键方块**保持原版放置行为（便于边搭建边配置）。 4. **设置面板配置项**： | 配置项 | 操作 | |--------|------| | 地图名称 | 点击后在聊天框重新输入 | | 游戏模式 | 左键上一个、右键下一个：经典 / 感染 / 黑夜迷雾 | | 游戏世界 | 点击打开世界列表选择 | | 游戏出生点 / 猎人休息区 / 传送门位置 | 点击设为当前位置（三个点默认都取玩家当前位置，可分别到点设置） | | 伪装方块 | 点击打开方块管理面板（点击图标移除 / 添加手持方块）；上限 48 个 | | 躲藏时长 / 搜寻时长 | 左键 +30 秒、右键 -30 秒（范围 10~3600 秒） | | MVP 倍率 | 左键/右键在 1.0 / 1.5 / 2.0 间循环 | 5. **保存并完成**：点击「保存并完成」写入 `plugins/BlockHideAndSeek/maps/<名称>.yml` 并热加载生效，随后输出地图摘要与「再创建一张 / 完成」按钮。 6. **同名替换**：若目标地图文件已存在——名称为「默认 / default / 默认地图」时定向指向默认示例地图 `sample-map.yml`（即替换默认配置）——会先询问确认，点击聊天栏「确认替换」后执行，**替换前自动备份原文件为 `.yml.bak`**。 7. **随时中止**：点击「取消创建」（或 `/bhs setup cancel`）直接结束，未保存不产生任何文件；玩家退出服务器时进行中的会话自动清理。 > 已保存的地图会在下次对局随机抽取中被选中，无需重启服务器。 --- ## 7. 配置文件详解与修改步骤 ### 7.1 主配置 `config.yml` 所有缺失项首次启动自动补全；所有数值项启动时自动校验并修正不合理值（见 [第 11 章](#11-配置自愈机制)）。 #### ① 基础设置 ```yaml maps-enabled: true # 是否从 maps/ 加载地图 game: min-players: 4 # 最少玩家数（低于此人数不会开局） max-players: 20 # 单局上限 waiting-countdown: 60 # 等待阶段倒计时（秒，<10 会被修正为 10） prepare-time: 15 # 准备阶段（秒） hide-time: 60 # 躲藏阶段（秒，<10 会被修正为 10） seek-time: 480 # 搜寻阶段（秒，<30 会被修正为 30） vip-multiplier: 1.2 # 拥有 bhs.vip 权限玩家的积分倍率（<1.0 会被修正为 1.0） score-interval: 15 # 积分发放间隔（秒，<5 会被修正为 5） ``` **修改步骤**：直接改数字 → `/bhs reload`。若日志出现"已修正"字样，表示越界值被纠正，请改回合理范围。 #### ② 世界与坐标（三个基础世界） ```yaml waiting-room: # 玩家等待游戏开始的位置 world: "waiting_world" # 必须已存在于服务端 x: 0.0 y: 64.0 z: 0.0 yaw: 0.0 pitch: 0.0 lobby: # 游戏结束后返回的位置 world: "lobby_world" x: 0.0 y: 64.0 z: 0.0 ``` > `game-world`、`game-spawn`、`seeker-hideout` 三个顶层遗留键仍被读取兜底，但**实际对局坐标以 `maps/*.yml` 为准**。 #### ③ 伪装方块列表 ```yaml disguise-blocks: # 空列表将导致游戏无法进行（启动时强制警告） - "STONE" - "GRASS_BLOCK" - "OAK_PLANKS" - "BRICKS" - "SANDSTONE" - "RED_WOOL" - "OAK_LOG" - "COBBLESTONE" - "DIRT" - "SNOW_BLOCK" - "GLASS" - "BOOKSHELF" - "WHITE_CONCRETE" - "IRON_BLOCK" - "GOLD_BLOCK" ``` - 支持全部原版 Material（大写枚举名）与混合端 MOD 命名空间方块（如 `modid:custom_block`）。 - 重复项、无效项启动时告警并忽略。 - 候选数量：普通玩家 `normal-block-count`（默认 3），VIP（`bhs.vip`）`vip-block-count`（默认 6）。 #### ④ 商店配置 ```yaml shop-size: 9 # GUI 尺寸，仅 9/18/27/36/45/54 有效，其他会被修正为 9 shop-prices: # 全局默认价格（地图可覆盖） speed-scroll: 25 portal: 120 jammer: 60 flash-bang: 30 self-destruct: 100 xray-potion: 80 trap: 20 blast-armor: 20 quake-hammer: 200 reroll-blocks: 20 decoy: 80 expose-firework: 35 compass: 100 arrows: 2 shop-items: # true=可购买 false=禁用（与 shop-prices 一一对应） speed-scroll: true portal: true # ... shop-item-names: # 游戏内道具中文名（如 speed-scroll: "加速卷轴"） shop-use-effects: # 道具使用音效（需为有效 Sound 枚举） ``` 模式专属道具开关与价格位于 `shop.mode-items.*`（见 7.1 ⑦）。 #### ⑤ 积分与暴露 ```yaml hide-score-min: 5 # 躲藏方单次积分区间 hide-score-max: 20 seek-score-min: 6 # 猎人单次积分区间 seek-score-max: 15 initial-score: 10 # 初始积分 expose-notice-seconds: 10 # 暴露前提示秒数 final-minute-expose-interval: 15# 最后一分钟暴露间隔 expose-firework-time-1: 300 # 烟花暴露时间点（搜寻剩余秒，地图可覆盖） expose-firework-time-2: 180 last-countdown-seconds: 30 # 最后倒计时音效秒数（地图可覆盖） disguise-change-cost: 5 # 更换伪装消耗积分 solidify-time: 6 # 伪装实体化秒数（<1 修正为 1） hitbox-multiplier: 1.5 # 虚拟碰撞箱放大倍率（0.5~3.0，越界修正为 1.5） ``` #### ⑥ MVP 评分（`mvp-scoring`）首启自动写入，可按需调整隐藏方/猎人得分与惩罚权重、平分决胜顺序、结算奖励： ```yaml mvp-scoring: enabled: true hider: base-score: 100 survival-win: 50 survive-per-second: 0.2 # ... 细分权重与 penalties（早退 -100 等） seeker: base-score: 100 eliminate-hider: 50 # ... 连杀/追踪击杀/陷阱排除等权重 tie-breaker: # 平分决胜顺序 - KILLS - SURVIVAL_TIME - SHOP_PURCHASES - IS_VIP - RANDOM reward: currency: 200 # MVP 货币奖励 season-exp: 500 # MVP 赛季经验奖励 ``` #### ⑦ 游戏模式与模式专属道具三种模式按权重随机抽取（`chance` 之和为分母）： ```yaml game-modes: classic: # 经典模式 enabled: true chance: 60 infection: # 感染模式 enabled: true chance: 20 duration-seconds: 300 immunity-shield: { enabled: true, price: 120, duration-seconds: 3, cooldown-seconds: 60 } progression: { speed2-threshold: 3, resistance-threshold: 5 } # 击杀3人速度II / 5人抗性提升 mvp: { infection-conversion-score: 5.0, purification-score: 8.0, ... } alert: { interval-seconds: 30 } # 幸存者警报间隔 end-reward: { survivor-base: 10, survivor-per-alive: 5, infected-per-conversion: 2 } fog-of-night: # 黑夜迷雾模式 enabled: true chance: 20 hide-seconds: 30 seek-seconds: 360 time-value: 18000 # 午夜 rain-enabled: true rain-intensity: 1.0 lightning-min-interval-seconds: 4 lightning-max-interval-seconds: 6 flash-interval-seconds: 60 shop: mode-items: fog-of-night: flare: { enabled: true, price: 20 } # 照明弹 night-vision: { enabled: true, price: 40, duration-seconds: 10, cooldown-seconds: 15 } lantern: { enabled: true, price: 30, duration-seconds: 20, cooldown-seconds: 30, light-level: 15 } perception: { enabled: true, price: 100, check-interval-seconds: 5 } infection: serum: { enabled: true, price: 150, max-uses: 2 } # 净化血清 immunity-shield: { enabled: true, price: 120 } ``` > 某模式 `enabled: true` 但 `maps/` 无对应模式地图时，插件自动生成 `sample--map.yml`。 #### ⑧ 其他设置 ```yaml group-mode: false # 群组模式（与代理联动） main-lobby-server: "lobby" # 群组模式下主大厅服务器名 server-name: "§e§lStarMast §7Network" # 记分板服务器名（支持 § 颜色码） game-id-prefix: "BHS" # 对局编号前缀 game-id-random-length: 5 # 编号随机段长度 end-game-commands: [] # 游戏结束后执行的命令列表 end-game-cleanup-seconds: 30 # 结束后清理延迟（秒） sounds: # 各阶段音效（无效值启动时告警） hide-start: "ENTITY_PLAYER_LEVELUP" seek-start: "ENTITY_WITHER_SPAWN" # ... performance: arrow-detection-interval: 2 # 箭矢检测间隔（tick） disguise: use-hide-player-api: true # 是否使用 HidePlayer API（混合端兼容选项） ``` --- ### 7.2 地图配置 `maps/*.yml` 每张地图一个 `.yml` 文件。**游戏实际使用的世界与坐标全部在这里配置**。 #### 必填字段（缺失即整图跳过加载） | 字段 | 说明 | 取值示例 | |------|------|----------| | `name` | 地图名称 | `"城镇地图"` | | `game-mode` | 支持的模式 | `classic` / `infection` / `fog-of-night` / `all` | | `game-world` | 游戏世界与出生点 | `world: "game_world"` + `spawn.x/y/z` | #### 可选字段 | 字段 | 说明 | |------|------| | `enabled` | `false` 时跳过加载（推荐用此开关临时下架地图） | | `seeker-hideout` | 猎人躲藏/待命点（world/x/y/z/yaw/pitch） | | `game` | 覆盖全局时长：`hide-time`、`seek-time`、`expose-firework-time-1/2`、`last-countdown-seconds` | | `disguise-blocks` | 覆盖全局伪装方块列表 | | `shop-prices` / `shop-items` | 覆盖全局商店价格与开关 | | `portal-location` | 传送门目标点（world/x/y/z） | | `mvp-scoring` | 地图级 MVP 权重（格式同 6.1⑥） | | `commands.on-start` | 开局时执行的命令列表 | > ⚠️ **字段校验**：合法的顶层键仅限 `enabled/name/waiting-room/game-world/seeker-hideout/disguise-blocks/portal-location/game/shop-prices/shop-items/game-mode/mvp-scoring/commands`。**出现未知字段 → 整张地图跳过**；`waiting-room` 当前由 `config.yml` 统一管理，填了也会被忽略并告警。 #### 完整示例 ```yaml enabled: true name: "示例地图" game-mode: classic # 或 all / infection / fog-of-night game-world: world: "game_world" spawn: x: 100.0 y: 65.0 z: 100.0 seeker-hideout: world: "game_world" x: 200.0 y: 65.0 z: 200.0 yaw: 0.0 pitch: 0.0 game: hide-time: 60 seek-time: 480 disguise-blocks: - "STONE" - "GRASS_BLOCK" shop-prices: speed-scroll: 30 # 覆盖全局价格 portal-location: world: "game_world" x: 150.0 y: 70.0 z: 150.0 ``` #### 制作一张新地图的步骤 1. 服务端准备好游戏世界（如 `game_world`）并确保启动时已加载。 2. 游戏内用 **F3** 记录：出生点、等候室、猎人待命点、传送门点的（世界名 + XYZ + 朝向）。 3. `maps/` 下新建 `my-map.yml`，填入上表字段。 4. 其他地图可 `enabled: false` 或保留多图随机。 5. `/bhs reload` 或重启，观察"已加载地图: my-map"日志。 --- ### 7.3 数据库配置 `database.yml` #### 存储模式决策表 | `database.enabled` | `database.redis.enabled` | 效果 | |---|---|---| | `false`（默认） | 任意 | **JSON 本地文件存储**（`data/.json`），零额外依赖 | | `true` | `false` | MySQL 存储 + 本地内存缓存 | | `true` | `true` | MySQL 存储 + Redis 缓存 + 可选跨服同步 | | 任何 | – | MySQL 不可用时**自动降级** JSON，服务不中断；恢复后自动重连恢复 | #### 开启 MySQL ```yaml database: enabled: true # ← 改为 true mysql: host: "127.0.0.1" # MySQL 地址 port: 3306 database: "blockhideandseek" # 库名（不存在则自动创建） username: "root" password: "你的密码" # ← 必改 table-prefix: "bhs_" # 表前缀：多服共用库时隔离数据 use-ssl: false properties: useUnicode: true characterEncoding: "UTF-8" # 统一 UTF-8（utf8mb4 会被自动修正为 UTF-8） useSSL: false serverTimezone: "Asia/Shanghai" ``` - 自动创建数据库与数据表：`<前缀>player_stats`，列 `uuid`(PK)/`player_name`/`stats_data`(TEXT JSON)/`updated_at`；兼容历史列式表，自动补齐缺失列。 - MySQL 驱动已重定位内置，服务端无需另装。 #### 开启 Redis（缓存 + 跨服同步前提） ```yaml redis: enabled: true host: "127.0.0.1" port: 6379 password: "" # 无密码留空 database: 0 # 0~15，越界自动修正 timeout-ms: 5000 key-prefix: "bhs:" # 键前缀（多服隔离） sync: enabled: true # 跨服数据同步（必须 Redis.enabled=true 且数据库共用） channel: "bhs:sync" interval-seconds: 30 ``` #### 缓存 / 连接池 / 备份 ```yaml cache: local-ttl-seconds: 300 # 本地缓存 TTL redis-ttl-seconds: 3600 # Redis 缓存 TTL leaderboard-refresh-minutes: 60 # 排行榜刷新周期（<1 修正为 1） warmup-on-start: true # 启动预热 pool: # HikariCP 连接池 max-size: 10 # 最大连接数（<1 修正为 10） min-idle: 2 # 最小空闲（>max 自动钳制） timeout-ms: 30000 # 获取连接超时（<1000 修正为 30000） idle-timeout-ms: 600000 max-lifetime-ms: 1800000 validation-timeout-ms: 5000 backup: enabled: true # 玩家数据自动备份 interval-hours: 24 retention-count: 7 path: "backups" ``` > 存储相关改动保存后**建议重启服务器**（连接池/驱动在启动期初始化）；`/bhs reload` 仅重载主配置与地图。 --- ### 7.4 代理与匹配机配置 `proxy.yml` #### 单机模式（默认） ```yaml proxy: type: NONE # 单机固定 NONE，或留 AUTO 自动探测 server: id: "bhs-01" # 服务器唯一 ID（跨服通信识别） name: "§e躲猫猫 #1" matchmaker: enabled: false # 单机保持 false ``` #### 代理网络（BungeeCord / Velocity） ```yaml proxy: type: AUTO # AUTO=自动识别；也可直接指定 BUNGEECORD / VELOCITY ``` 插件消息通道由代理实现（`ProxyFactory/ProxyDetector`）自动注册；**修改代理类型后必须重启服务器**。 #### 匹配机（跨服组局，可选） ```yaml matchmaker: enabled: true # 游戏端通过 WebSocket 连接匹配机 host: "127.0.0.1" # 匹配机服务地址 port: 8765 ``` 启用后行为（`MatchClient`）： - 连接成功自动 **REGISTER** 注册本服务器（gamePhase=waiting）。 - 每 10 秒上报游戏阶段/在线人数/TPS，每 30 秒心跳。 - 接收 `PLAYER_JOIN` 指令 → 主线程执行自动入局 → 回传 `PLAYER_JOIN_ACK`（真实结果）。 - 断线后每 30 秒持续重连直至成功或插件关闭；插件关闭发送 `SERVER_SHUTDOWN`。 `servers` 列表用于跨服通信可选服务器展示： ```yaml servers: - id: "bhs-01" name: "躲猫猫 #1" - id: "bhs-02" name: "躲猫猫 #2" ``` ### 7.5 监控与通知配置（预留） `monitoring.yml` 与 `notification.yml` 随包分发，但**当前版本（0.1.5）运行期未解析这两个文件**——监控/告警由内置模块（`LogFilter`/`AggregatedLogger`/`ErrorHandler`）与独立插件 **StarMastMonitor** 承担： - 控制台高性能日志过滤、聚合摘要、错误收集：内置生效。 - 游戏内性能面板：安装 **StarMastMonitor** 后使用 `/monitor`（本插件 `/bhs tps|threads|perf` 已指向该插件提示）。 - `delog.yml`（自动生成）控制 Delog 调试日志：输出至 `logs/delog/delog-YYYY-MM-DD.log`，按配置保留/清理。 --- ## 8. 游戏模式详解 ### 经典模式 #### 玩法流程 1. **模式公布**：开局公布本局游戏模式 2. **准备阶段（15 秒）**：玩家传送至游戏世界，猎人进入躲藏点 3. **躲藏阶段（60 秒）**：躲藏方寻找位置伪装成方块，猎人等待 4. **搜寻阶段（480 秒）**：猎人出动，寻找并消除躲藏方 5. **游戏结束**：全部躲藏方被消除（猎人胜利）或时间结束（躲藏方胜利） #### 策略建议 - **躲藏方**：不要躲在明显位置，混入自然方块；利用商店道具干扰猎人 - **猎人**：注意异常方块（朝向不对、悬空、重复）；购买追踪钟表定位躲藏方 ### 感染模式 #### 玩法流程 1. **模式公布**：公布本局为感染模式 2. **游戏阶段（300 秒）**：开局随机指定一名感染者；感染者追逐并感染其他玩家；幸存者可购买净化血清逆转感染者 3. **游戏结束**：全部玩家被感染（感染者胜利）或至少一名幸存者存活到时间结束（幸存者胜利） #### 感染者进阶机制 | 击杀数 | 效果 | |--------|------| | 3 人 | 获得速度 II | | 5 人 | 获得抗性提升 | #### 策略建议 - **感染者**：优先追击落单玩家，利用速度优势逐个击破 - **幸存者**：抱团行动，互相掩护；购买免疫护盾和净化血清 ### 黑夜迷雾模式 #### 玩法流程 1. **模式公布**：公布本局为黑夜迷雾模式 2. **准备阶段**：玩家传送至游戏世界 3. **躲藏阶段（30 秒）**：黑夜中躲藏方迅速寻找位置 4. **搜寻阶段（360 秒）**：黑暗笼罩，猎人需利用光源搜寻 5. **游戏结束**：全部躲藏方被消除或时间结束 #### 环境效果 - **时间**：锁定午夜（18000 tick）；**天气**：强制降雨 - **闪电**：每 4~6 秒随机生成闪电短暂照亮战场 - **闪光弹**：每 60 秒自动闪光照亮全场 #### 专属商店物品 | 物品 | 价格 | 效果 | |------|------|------| | 夜视药水 | 40 积分 | 持续 10 秒夜视，冷却 15 秒 | | 灯笼 | 30 积分 | 持续 20 秒光照，冷却 30 秒，亮度 15 级 | | 感知技能 | 100 积分 | 每 5 秒显示附近躲藏方位置 | | 照明弹 | 20 积分 | 照亮指定区域 | #### 推荐客户端增强模组（可选，不装也能玩） | 模组 | 作用 | 推荐度 | |------|------|--------| | **DarkAroundMe** | 模拟真实黑暗环境 | ⭐⭐⭐⭐⭐ | | **Truly Dark** | 深度黑暗效果 | ⭐⭐⭐⭐⭐ | #### 策略建议 - **躲藏方**：利用黑暗掩护，选择阴影处伪装；购买夜视药水观察环境 - **猎人**：充分利用闪电光照的时间；感知技能是追踪关键；灯笼提供持续照明 --- ## 9. 命令与权限 ### 玩家命令（需 `bhs.player`，默认所有玩家） | 命令 | 说明 | |------|------| | `/bhs` 或 `/bhs gui` | 打开 GUI 主菜单 | | `/bhs help` | 显示帮助 | | `/bhs join` | 加入游戏（游戏进行中服务器锁定，普通玩家无法加入） | | `/bhs leave` | 离开游戏 | | `/bhs status` | 查看游戏状态 | | `/bhs data me` | 查看个人战绩（30 秒冷却） | | `/bhs data top [streak\|wins\|time\|mvp]` | 排行榜：连胜 / 胜场 / 时长 / MVP（30 秒冷却） | ### GUI 面板输入 `/bhs` 或 `/bhs gui` 打开主菜单，面板内容随游戏状态实时刷新（详细使用见 [第 6 章](#6-gui-界面与地图创建向导)）： | 面板 | 入口 | 功能 | |------|------|------| | 用户主菜单 | `/bhs` | 加入/离开游戏、游戏状态（阶段/人数/地图/倒计时）、我的数据、公共数据（排行榜） | | 我的数据 | 主菜单 → 我的数据 | 总场数/胜负/胜率/连胜/时长/MVP/K-D（30 秒冷却，面板内可刷新） | | 公共数据 | 主菜单 → 公共数据 | 连胜/胜场/时长/MVP 四类排行榜 Top10 | | 管理员面板 | 主菜单 → 管理员面板（需 `bhs.admin`） | 强制开始/缓和停止/强制停止/重载配置/地图创建向导 | ### 管理员命令（需 `bhs.admin`，默认 OP） | 命令 | 说明 | |------|------| | `/bhs start` | 强制开始游戏 | | `/bhs setup` | 一键地图创建向导（聊天引导 + 设置面板） | | `/bhs reload` | 重载配置 + 地图 + 世界备份检查 | | `/bhs forcestop` | 强制停止游戏逻辑（清零状态机，恢复背包并传送回大厅） | | `/bhs gentlestop` | 缓和停止（正常结算流程，平局） | | `/bhs forceshutdown` | 强制关闭插件（触发完整清理） | ### 地图创建向导（`/bhs setup`）详见 [第 6.4 节](#64-地图创建向导bhs-setup)：聊天框输入名称 → 手持物品对空右键打开设置面板（方块即时加入伪装方块）→ 配置模式/世界/坐标/伪装方块/时长/MVP → 保存并热加载；同名地图（名称为默认时指向 `sample-map.yml`）替换前确认并自动备份 `.yml.bak`，全程可随时中止。 ### 命令别名 `/bhs` 亦可用 `/blockhideandseek`、`/hideandseek`、`/has`。 ### 权限节点（`plugin.yml`） | 权限 | 默认 | 说明 | |------|------|------| | `bhs.player` | 所有玩家 | 加入/离开/状态查询 | | `bhs.vip` | OP | 积分加成 + 更多候选伪装方块 | | `bhs.admin` | OP | 管理命令 | | `bhs.admin.notify` | OP | 管理员通知（继承 `bhs.admin`） | | `bhs.admin.perf` | OP | 性能监控（继承 `bhs.admin`，配合 StarMastMonitor） | | `bhs.proxy.status` | OP | 查看代理状态 | | `bhs.match` / `bhs.match.crossserver` / `bhs.match.admin` | 见默认 | 匹配机链路权限（预置） | | `bhs.data` / `bhs.data.top` | 代码内校验 | `/bhs data` 系列数据查询 | > 建议在 LuckPerms 等权限插件中配置；默认值以 `plugin.yml` 为准。 --- ## 10. 数据存储与备份 ### 玩家数据 - **JSON 模式**（默认）：`plugins/BlockHideAndSeek/data/.json`；写入前自动生成 `.bak` 备份（最多保留 3 份），主文件损坏自动回滚备份。 - **MySQL 模式**：`<前缀>player_stats` 表（自动建表/补列），Redis 可选加速。 ### 排行榜排行榜缓存按 `cache.leaderboard-refresh-minutes`（默认 60 分钟）刷新，查询走 `LeaderboardCacheService`。 ### 世界备份 - 服务器启动与 `/bhs reload` 时对每张**启用**地图执行世界备份，输出至 `服务器根目录/GameBackup/<世界名>`（跳过已备份世界）。 - 玩家数据自动备份遵循 `database.yml → backup` 配置（`插件目录/backups/`）。 ### 迁移要点从 JSON 切 MySQL：先备份 `data/`，配置好 `database.yml` 后重启；旧 JSON 数据不会自动回灌，可联系开发团队协助迁移。多服共用库时务必设置不同 `table-prefix` 或分库隔离。 --- ## 11. 配置自愈机制插件内置配置自愈（`ConfigManager.updateConfig` / `validateConfig` / `DatabaseConfig.updateConfig`）： 1. **自动补全**：`config.yml`、`database.yml` 缺失项首启自动以默认值写回（升级后无需手工补新键）。 2. **自动修正**：越界值自动纠正并告警—— - `min-players > max-players` → 交换；`min-players < 2` → 修正为 2 - `waiting-countdown < 10`、`prepare-time < 5`、`hide-time < 10`、`seek-time < 30`、`score-interval < 5` - `vip-multiplier < 1.0`、`shop-size` 非法 GUI 尺寸、`solidify-time < 1`、`hitbox-multiplier` 超出 0.5~3.0 - `database.yml`：端口越界、`pool` 参数、Redis 库号 0~15、`sync.enabled` 而无 Redis 等 3. **完整性检查**：必需键缺失告警、未知顶层键告警（防拼写错误）、无效方块/音效名告警、重复方块告警。 > 若日志出现 N 个配置问题，**以日志为准逐个修正**；不可修正项（如空 `disguise-blocks`）会阻止正常对局。 --- ## 12. 使用期限与授权 - **闭源商业授权**：本文档面向已获授权的服务器运营者。未经授权禁止搬运、使用、反编译本产品。内测交流群：**1093939989（QQ）**。 - **使用期限**：有效至 **2027-06-30 23:59（Asia/Shanghai）**，到期自动停止服务，无需额外配置。 - **校验方式**（`TimeVerification`，自动无需配置）： - 启动时同步在线校验（多信源：百度/QQ/必应响应头 + 淘宝时间接口，取中位数防伪造）。 - 运行期每 15 分钟在线复核；在线不可用时以最近成功在线时间外推（72 小时窗），并检测本机时钟回拨（>2 小时判定篡改）与偏差（>24 小时告警）。 - 完全无网络时以本机时间兜底（24 小时容错窗）。 - **异常提示**：到期/离线超窗会在控制台输出 `[使用期限]` 前缀日志；请保证服务器可访问国内公网（至少一个信源可达）。 --- ## 13. 常见问题排查 | 现象 | 原因与处理 | |------|-----------| | 启动即"配置文件加载失败"，插件禁用 | YAML 语法错误。删除对应文件重启重新生成，或对照第 7 章修正 | | "使用期限"校验未通过 | 已到期；或服务器无法访问任何时间信源且本机时间超容错窗。检查网络与系统时间/NTP | | 地图被跳过（`skippedCount` 增加） | 缺少 `name`/`game-world`/`game-mode`，或含未知键。见 7.2 字段校验 | | 地图世界未加载告警 | 世界名拼写错误/未放入世界目录。确认启动时已加载（`load: STARTUP` 已延迟引用） | | 伪装方块无效告警 | `disguise-blocks` 写错名字；MOD 方块需命名空间格式 | | 数据库模式一直降级 JSON | 检查 MySQL 地址/端口/账号/库权限，确认 3306 可达、密码正确 | | 玩家进不来 | 游戏进行中服务器自动锁定（`ServerLockManager`），仅管理员可入，结束自动解锁 | | 排行榜为空 | 有战绩但缓存未刷新：调小 `leaderboard-refresh-minutes` 或等待刷新周期 | | 需要强制清场 | `/bhs forcestop`（重置状态机）或 `/bhs forceshutdown`（关闭插件重置） | | 修改代理/存储配置不生效 | 存储、代理、匹配机均在启动期初始化，**请重启服务器**，`/bhs reload` 不生效 | | 如何重置玩家数据 | JSON 模式删除 `data/` 对应文件；MySQL 模式清空 `player_stats` 表对应记录 | --- ## 14. 更新日志 ### 0.1.6（当前） - **新增游戏内 GUI 面板系统**：`/bhs` 或 `/bhs gui` 打开用户主菜单，替代大部分命令操作 - 用户面板：加入/离开游戏（按钮随状态动态切换并显示原因）、游戏状态（阶段/人数/地图/倒计时）、我的数据（个人战绩，异步加载 + 30 秒冷却刷新）、公共数据（连胜/胜场/时长/MVP 四类排行榜 Top10） - 管理员面板（主菜单内按 `bhs.admin` 显示）：强制开始、缓和停止、强制停止、重载配置、地图创建向导 - 面板内容每 0.5 秒自动刷新，随游戏状态动态变化；Paper/Folia 调度自适应 - **新增 `/bhs setup` 游戏内地图创建向导**：聊天栏可点击按钮全程引导，输入名称 → 手持物品对空右键打开设置面板（方块即时加入伪装方块列表）→ 面板内配置模式/世界/坐标点/伪装方块/时长/MVP → 保存并热加载；同名地图（含默认配置 `sample-map.yml`）替换前确认并自动 `.bak` 备份 - **修复 GUI 点击失效**：点击事件处理优先级从 HIGHEST+ignoreCancelled 调整为 LOWEST，解决游戏内玩家（InventoryListener 在 HIGH 无条件取消点击）面板按钮全部无响应、无反馈的问题 - **修复非等待阶段误加入**：加入闸门统一为 `isJoinablePhase()`（仅等待/等待倒计时可入），解决模式公布/准备/结算阶段 GUI 显示可加入、加入后被区域检测判定"离开游戏区域"立即踢出的问题（同步覆盖 `/bhs join`、GUI、匹配机自动入局三个入口） ### 0.1.x（稳定性与数据层增强） - 修复数据库表结构冲突与 MySQL 驱动加载问题（驱动已重定位内置） - 修复静态旗标导致的强制停止后游戏锁定、排行榜字段映射、连胜计算依赖顺序等缺陷 - 匹配机断线改为持久周期重连（每 30 秒） > 逐条 BUG 修复明细见 [CHANGELOG.md](CHANGELOG.md)（含世界备份、结束传送、重置循环、倒计时刷屏、背包备份、停止命令等）。 ### 0.1.1 - Folia 兼容调度层（自动探测 Paper/Folia） - API 兼容 Paper（及衍生）/ Folia 1.19.4 ~ 1.21.x - 黑夜迷雾模式完善（环境效果 + 专属商店物品） - 感染模式完善（进阶机制、警报、免疫护盾、净化血清、MVP 与结局奖励适配） ### 0.1.0（初始版本） - 完整游戏生命周期（等待 → 准备 → 躲藏 → 搜寻 → 结束）、三种模式、伪装系统、14 种商店物品、暴露机制、MVP 计算、多地图 - 存储：JSON / MySQL / Redis、排行榜、玩家统计、跨服同步、自动备份 - 代理支持：BungeeCord / Velocity / 自动检测、跨服匹配、游戏状态广播 - 监控：日志过滤聚合、Delog、告警通知 --- > **© 2025~2026 StarMastStudio（星桅工作室）** ｜本文档基于 v0.1.6 源码编写，最终解释权归开发团队所有。

星桅工作室

成员

方块躲猫猫

【Foila支持】高性能NPC插件-StarMastNPCs