方块躲猫猫（BlockHideAndSeek）

Paper / Folia 1.19.4+ 高性能迷你游戏插件 ｜当前版本：0.1.6 ｜开发团队：星桅工作室（StarMastStudio）

内测交流群：1093939989（QQ）

⚠️ 闭源声明：本插件为闭源，未经授权禁止搬运、使用、反编译、二次分发。授权与使用期限说明见第 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/ 。）

地图仅供测试，不做游戏平衡性保证

1. 插件概述
2. 功能特性
3. 运行环境要求
4. 部署步骤（分步详解）
5. 插件目录结构
6. GUI 界面与地图创建向导
7. 配置文件详解与修改步骤
8. 游戏模式详解
9. 命令与权限
10. 数据存储与备份
11. 配置自愈机制
12. 使用期限与授权
13. 常见问题排查
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 章）
可选端口	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：准备服务端

安装 Java 17+（java -version 验证）。
部署 Paper 1.19.4+ 服务端（或 Folia）。
关闭服务器，确认 plugins/ 目录存在。

步骤 2：放入插件 JAR

将授权提供的 BlockHideAndSeek-0.1.5.jar（闭源混淆构建产物）放入 plugins/ 目录。
无需额外安装依赖：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 章排查。
世界加载完成后（约 5 秒），自动执行启动世界备份、记分板初始化、匹配机状态确认（若启用）。

步骤 4：修改配置（核心）

最常见的三个文件：

config.yml —— 等待室/大厅/游戏世界坐标、人数上限、时长、伪装方块、商店（必改，见 7.1）
maps/*.yml —— 每张地图的世界与坐标（必改，见 7.2）
database.yml —— 开启 MySQL/Redis（可选，见 7.3）

步骤 5：生效方式

方式一（日常改数值）：管理员执行 /bhs reload，重载配置与地图（不会重置进行中的游戏）。
方式二（改 YAML 结构/世界相关/存储/代理）：重启服务器（load: STARTUP 保证世界加载后引用坐标；存储/代理/匹配机均在启动期初始化）。

步骤 6：验证安装

/bhs help 出现帮助信息即安装成功。
/bhs status 查看实时游戏状态。
/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 模式下玩家数据（<uuid>.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`）

令管理员不接触配置文件即可在游戏内快捷创建一张新地图，全部步骤有聊天栏可点击按钮引导：

开始：运行 /bhs setup（或管理员面板 → 地图创建向导，游戏进行中会被拦截）。
输入名称：按引导在聊天框输入地图名称（1~32 字符，支持颜色代码；输入 cancel 取消），输入后聊天栏出现「打开设置面板 / 保存并完成 / 取消创建」按钮。
手持物品对空右键：随时打开/刷新设置面板；手持方块对空右键会同时把该方块加入伪装方块列表；手持方块右键方块保持原版放置行为（便于边搭建边配置）。
设置面板配置项：

配置项	操作
地图名称	点击后在聊天框重新输入
游戏模式	左键上一个、右键下一个：经典 / 感染 / 黑夜迷雾
游戏世界	点击打开世界列表选择
游戏出生点 / 猎人休息区 / 传送门位置	点击设为当前位置（三个点默认都取玩家当前位置，可分别到点设置）
伪装方块	点击打开方块管理面板（点击图标移除 / 添加手持方块）；上限 48 个
躲藏时长 / 搜寻时长	左键 +30 秒、右键 -30 秒（范围 10~3600 秒）
MVP 倍率	左键/右键在 1.0 / 1.5 / 2.0 间循环

保存并完成：点击「保存并完成」写入 plugins/BlockHideAndSeek/maps/<名称>.yml 并热加载生效，随后输出地图摘要与「再创建一张 / 完成」按钮。
同名替换：若目标地图文件已存在——名称为「默认 / default / 默认地图」时定向指向默认示例地图 sample-map.yml（即替换默认配置）——会先询问确认，点击聊天栏「确认替换」后执行，替换前自动备份原文件为 .yml.bak。
随时中止：点击「取消创建」（或 /bhs setup cancel）直接结束，未保存不产生任何文件；玩家退出服务器时进行中的会话自动清理。

已保存的地图会在下次对局随机抽取中被选中，无需重启服务器。

7. 配置文件详解与修改步骤

7.1 主配置 `config.yml`

所有缺失项首次启动自动补全；所有数值项启动时自动校验并修正不合理值（见第 11 章）。

① 基础设置

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。若日志出现"已修正"字样，表示越界值被纠正，请改回合理范围。

② 世界与坐标（三个基础世界）

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 为准。

③ 伪装方块列表

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）。

④ 商店配置

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 ⑦）。

⑤ 积分与暴露

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`）

首启自动写入，可按需调整隐藏方/猎人得分与惩罚权重、平分决胜顺序、结算奖励：

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 之和为分母）：

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-<mode>-map.yml。

⑧ 其他设置

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 统一管理，填了也会被忽略并告警。

完整示例

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

制作一张新地图的步骤

服务端准备好游戏世界（如 game_world）并确保启动时已加载。
游戏内用 F3 记录：出生点、等候室、猎人待命点、传送门点的（世界名 + XYZ + 朝向）。
maps/ 下新建 my-map.yml，填入上表字段。
其他地图可 enabled: false 或保留多图随机。
/bhs reload 或重启，观察"已加载地图: my-map"日志。

7.3 数据库配置 `database.yml`

存储模式决策表

`database.enabled`	`database.redis.enabled`	效果
`false`（默认）	任意	JSON 本地文件存储（`data/<uuid>.json`），零额外依赖
`true`	`false`	MySQL 存储 + 本地内存缓存
`true`	`true`	MySQL 存储 + Redis 缓存 + 可选跨服同步
任何	–	MySQL 不可用时自动降级 JSON，服务不中断；恢复后自动重连恢复

开启 MySQL

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（缓存 + 跨服同步前提）

  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

缓存 / 连接池 / 备份

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`

单机模式（默认）

proxy:
  type: NONE              # 单机固定 NONE，或留 AUTO 自动探测
server:
  id: "bhs-01"            # 服务器唯一 ID（跨服通信识别）
  name: "§e躲猫猫 #1"
matchmaker:
  enabled: false          # 单机保持 false

代理网络（BungeeCord / Velocity）

proxy:
  type: AUTO              # AUTO=自动识别；也可直接指定 BUNGEECORD / VELOCITY

插件消息通道由代理实现（ProxyFactory/ProxyDetector）自动注册；修改代理类型后必须重启服务器。

匹配机（跨服组局，可选）

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 列表用于跨服通信可选服务器展示：

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. 游戏模式详解

经典模式

玩法流程

模式公布：开局公布本局游戏模式
准备阶段（15 秒）：玩家传送至游戏世界，猎人进入躲藏点
躲藏阶段（60 秒）：躲藏方寻找位置伪装成方块，猎人等待
搜寻阶段（480 秒）：猎人出动，寻找并消除躲藏方
游戏结束：全部躲藏方被消除（猎人胜利）或时间结束（躲藏方胜利）

策略建议

躲藏方：不要躲在明显位置，混入自然方块；利用商店道具干扰猎人
猎人：注意异常方块（朝向不对、悬空、重复）；购买追踪钟表定位躲藏方

感染模式

玩法流程

模式公布：公布本局为感染模式
游戏阶段（300 秒）：开局随机指定一名感染者；感染者追逐并感染其他玩家；幸存者可购买净化血清逆转感染者
游戏结束：全部玩家被感染（感染者胜利）或至少一名幸存者存活到时间结束（幸存者胜利）

感染者进阶机制

击杀数	效果
3 人	获得速度 II
5 人	获得抗性提升

策略建议

感染者：优先追击落单玩家，利用速度优势逐个击破
幸存者：抱团行动，互相掩护；购买免疫护盾和净化血清

黑夜迷雾模式

玩法流程

模式公布：公布本局为黑夜迷雾模式
准备阶段：玩家传送至游戏世界
躲藏阶段（30 秒）：黑夜中躲藏方迅速寻找位置
搜寻阶段（360 秒）：黑暗笼罩，猎人需利用光源搜寻
游戏结束：全部躲藏方被消除或时间结束

环境效果

时间：锁定午夜（18000 tick）；天气：强制降雨
闪电：每 4~6 秒随机生成闪电短暂照亮战场
闪光弹：每 60 秒自动闪光照亮全场

专属商店物品

物品	价格	效果
夜视药水	40 积分	持续 10 秒夜视，冷却 15 秒
灯笼	30 积分	持续 20 秒光照，冷却 30 秒，亮度 15 级
感知技能	100 积分	每 5 秒显示附近躲藏方位置
照明弹	20 积分	照亮指定区域

策略建议

躲藏方：利用黑暗掩护，选择阴影处伪装；购买夜视药水观察环境
猎人：充分利用闪电光照的时间；感知技能是追踪关键；灯笼提供持续照明

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 章）：

面板	入口	功能
用户主菜单	`/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 节：聊天框输入名称 → 手持物品对空右键打开设置面板（方块即时加入伪装方块）→ 配置模式/世界/坐标/伪装方块/时长/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/<uuid>.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）：

自动补全：config.yml、database.yml 缺失项首启自动以默认值写回（升级后无需手工补新键）。
自动修正：越界值自动纠正并告警——
- 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 等
完整性检查：必需键缺失告警、未知顶层键告警（防拼写错误）、无效方块/音效名告警、重复方块告警。

若日志出现 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（含世界备份、结束传送、重置循环、倒计时刷屏、背包备份、停止命令等）。

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 源码编写，最终解释权归开发团队所有。

模组	作用	推荐度
DarkAroundMe	模拟真实黑暗环境	⭐⭐⭐⭐⭐
Truly Dark	深度黑暗效果	⭐⭐⭐⭐⭐

方块躲猫猫

方块躲猫猫

基本信息

我的世界Java版本

平台

运行环境

分类

其他链接

创作团队

详情信息

方块躲猫猫（BlockHideAndSeek）

目录

1. 插件概述

组件生态

2. 功能特性

游戏机制

商店系统

其他能力

3. 运行环境要求

4. 部署步骤（分步详解）

步骤 1：准备服务端

步骤 2：放入插件 JAR

步骤 3：首次启动，自动初始化

步骤 4：修改配置（核心）

步骤 5：生效方式

步骤 6：验证安装

5. 插件目录结构

6. GUI 界面与地图创建向导

6.1 打开方式

6.2 用户主菜单

6.3 管理员面板

6.4 地图创建向导（/bhs setup）

7. 配置文件详解与修改步骤

7.1 主配置 config.yml

① 基础设置

② 世界与坐标（三个基础世界）

③ 伪装方块列表

④ 商店配置

⑤ 积分与暴露

⑥ MVP 评分（mvp-scoring）

⑦ 游戏模式与模式专属道具

⑧ 其他设置

7.2 地图配置 maps/*.yml

必填字段（缺失即整图跳过加载）

可选字段

完整示例

制作一张新地图的步骤

7.3 数据库配置 database.yml

存储模式决策表

开启 MySQL

开启 Redis（缓存 + 跨服同步前提）

缓存 / 连接池 / 备份

7.4 代理与匹配机配置 proxy.yml

单机模式（默认）

代理网络（BungeeCord / Velocity）

匹配机（跨服组局，可选）

7.5 监控与通知配置（预留）

8. 游戏模式详解

经典模式

玩法流程

策略建议

感染模式

玩法流程

感染者进阶机制

策略建议

黑夜迷雾模式

玩法流程

环境效果

专属商店物品

推荐客户端增强模组（可选，不装也能玩）

策略建议

9. 命令与权限

玩家命令（需 bhs.player，默认所有玩家）

GUI 面板

管理员命令（需 bhs.admin，默认 OP）

地图创建向导（/bhs setup）

命令别名

权限节点（plugin.yml）

10. 数据存储与备份

玩家数据

6.4 地图创建向导（`/bhs setup`）

7.1 主配置 `config.yml`

⑥ MVP 评分（`mvp-scoring`）

7.2 地图配置 `maps/*.yml`

7.3 数据库配置 `database.yml`

7.4 代理与匹配机配置 `proxy.yml`

玩家命令（需 `bhs.player`，默认所有玩家）

管理员命令（需 `bhs.admin`，默认 OP）

地图创建向导（`/bhs setup`）

权限节点（`plugin.yml`）