方块躲猫猫 (BlockHideAndSeek)

Paper / Folia 1.19.4+ 高性能迷你游戏插件 | 作者：StarMastStudio | 版本：0.1.1

插件概述

什么是方块躲猫猫？

方块躲猫猫 是一款专为 Paper 1.19.4+ 及 Folia 服务端打造的高性能迷你游戏插件。它将经典的"躲猫猫"玩法与 Minecraft 世界巧妙结合——躲藏方可以伪装成各种方块，融入环境中躲避追捕；猎人则需要利用弓弩和各类道具，在限定时间内找出并"消除"所有躲藏者。

主插件与附属插件

本项目由两个组件构成，协同工作以实现完整的游戏体验：

组件	类型	说明
BlockHideAndSeek	主插件 (Paper/Folia 服务端)	核心游戏逻辑、管理、商店、数据存储等所有游戏功能
~~BlockHideAndSeek-Bungee~~	附属插件 (BungeeCord 代理端)	跨服匹配、玩家传送、服务器状态同步（暂不对外提供）

提示：主插件可独立运行于单服务器模式。若需跨服匹配功能，则需在 BungeeCord 代理端部署附属插件。

功能特性

主插件核心特性

游戏机制

三种游戏模式
- 经典模式 — 躲藏方伪装成方块，猎人用弓箭找出他们
- 感染模式 — 一名感染者对抗所有幸存者，被箭矢击中会被转化
- 黑夜迷雾模式 — 黑暗笼罩战场，视野受限，利用光源和照明弹搜寻躲藏方
完整的游戏阶段：等待 → 模式公布 → 准备 → 躲藏 → 搜寻 → 结束
智能队伍分配：自动平衡躲藏方与猎人人数
伪装系统：躲藏方可伪装成多种方块（如石头、草方块、木板、砖块等），并支持定期更换
暴露机制：搜寻阶段后期或特定条件下，躲藏方会被周期性暴露位置
碰撞箱放大：虚拟方块碰撞箱放大倍率可调（默认 1.5 倍），使方块更易被击中
实体方块转换：伪装方块 6 秒后实体化，可被物理碰撞

三种游戏模式详解

经典模式

默认游戏模式，抽选概率 60%
躲藏方伪装成方块，利用环境隐蔽
猎人使用弓剑和道具追踪并消除躲藏方
熟悉道具系统后可以打出精妙的配合

感染模式

抽选概率 20%
感染者：开局随机指定一名玩家作为感染者，拥有速度加成和抗性提升
- 击杀 3 名玩家后获得速度 II
- 击杀 5 名玩家后获得抗性提升
幸存者：其他玩家为幸存者，需躲避感染者的追捕
净化血清：幸存者可购买血清道具，将感染者变回幸存者
免疫护盾：购买后免疫感染 3 秒
警报系统：每 30 秒提示幸存者剩余人数和感染者位置
游戏结束：全部幸存者被感染（感染者胜利）或幸存者坚持到时间结束（幸存者胜利）
MVP 评分：根据感染转化数、净化次数、生存时间等综合计算

黑夜迷雾模式

抽选概率 20%
环境效果：
- 时间锁定为午夜（18000 tick）
- 强制降雨，视野极度受限
- 闪电随机生成（每 4~6 秒，间隔随机）
- 闪光弹每 60 秒照亮全场
商店专属物品：
- 夜视药水 — 40 积分，持续 10 秒，冷却 15 秒
- 灯笼 — 30 积分，持续 20 秒，冷却 30 秒，提供 15 级光照
- 感知技能 — 100 积分，每 5 秒显示附近躲藏方位置
- 照明弹 — 20 积分，照亮指定区域
游戏阶段：躲藏阶段 30 秒，搜寻阶段 360 秒
推荐客户端模组（增强黑夜体验）：
- DarkAroundMe — 模拟真实黑暗，伸手不见五指
- Truly Dark — 深度黑暗效果，洞穴和黑夜更加真实

商店系统

内置丰富的道具商店，支持 14 种功能性物品：

物品	类型	效果
加速卷轴	消耗品	短时间内提升移动速度
传送门	消耗品	瞬间传送至指定位置
干扰器	消耗品	干扰猎人的追踪能力
闪光弹	消耗品	致盲周围所有玩家
自爆炸弹	消耗品	对周围玩家造成范围伤害
透视药水	消耗品	短时间内透视附近躲藏方
陷阱	消耗品	在脚下布置陷阱
防爆盔甲	装备	减免爆炸伤害
地震锤	武器	造成范围震动效果
更换伪装物品	消耗品	重新随机伪装方块列表
分身陷阱	消耗品	生成假的分身迷惑敌人
暴露所有躲藏方	消耗品	短时间内暴露所有躲藏方位置
追踪钟表	装备	追踪最近的躲藏方方向
箭矢	弹药	补充弓弩弹药

数据存储系统

多模式存储：支持本地 JSON 文件存储和 MySQL 数据库存储
Redis 缓存：可选用 Redis 加速数据读写
排行榜系统：连胜榜、胜场榜、游戏时长榜、MVP 次数榜
玩家统计：记录总场数、胜场、败场、连胜、MVP 次数等
跨服数据同步：支持跨服务器间的数据共享（需搭配代理使用）
自动备份：支持定时备份玩家数据

代理/跨服支持

多代理兼容：支持 BungeeCord 和 Velocity 代理端
自动检测：插件可自动检测代理类型
跨服匹配：玩家可跨服务器进行匹配对战
游戏状态广播：跨服务器同步游戏状态信息
玩家传送：支持跨服务器玩家传送

监控与性能

实时性能监控
- TPS（每秒游戏刻）监控，支持告警阈值
- MSPT（每游戏刻毫秒数）监控
- 内存使用率监控
- 线程队列深度监控
性能面板：管理员可通过 /bhs perf 查看完整的性能面板
智能日志系统
- 高频方法日志过滤（自动抑制重复日志）
- 日志聚合与摘要输出
- 错误日志自动收集与上报
通知系统：支持游戏内公告和控制台输出双通道通知
Delog 调试系统：专为开发者设计的调试日志系统

MVP 计算

自动计算每局游戏的 MVP（最佳玩家）
分别统计躲藏方 MVP 和猎人 MVP
支持自定义 MVP 积分倍率

地图系统

多地图支持，每张地图独立配置
地图配置包含：游戏世界、出生点、猎人躲藏地点等
每张地图可独立覆盖商店价格和物品开关
支持地图级游戏模式覆盖
自动世界备份

记分板系统

实时显示游戏状态信息
可自定义服务器名称显示

服务端兼容性

服务端类型	兼容性	说明
Paper 1.19.4+	✅ 完全兼容	推荐使用
Spigot 1.19.4+	✅ 完全兼容	基础功能可用
Purpur 1.19.4+	✅ 完全兼容	推荐使用
Folia 1.19.4+	✅ 完全兼容	自动检测使用区域调度器
Mohist / Arclight	⚠️ 部分兼容	混合端可能存在兼容问题

BungeeCord 附属插件特性

跨服玩家传送：在服务器间无缝传送玩家
消息路由：在服务端和代理端之间路由插件消息
服务器管理器：跟踪和管理游戏子服务器状态（大厅、游戏服务器）
跨服匹配服务：提供跨服务器的玩家匹配功能
服务器健康检查：定期检查下游服务器的健康状态
负载均衡：自动将玩家分配到负载较轻的游戏服务器
可配置的游戏服务器列表：灵活配置大厅和游戏服务器

安装指南

系统要求

项目	要求
Minecraft 服务端	Paper 1.19.4+、Folia 1.19.4+ 或兼容分支
Java	JDK 17 或更高版本
可选依赖	MySQL 8.0+、Redis 6.0+
可选代理	BungeeCord 或 Velocity

安装步骤

1. 安装主插件

下载 BlockHideAndSeek-0.1.1.jar
将 JAR 文件放入服务端的 plugins/ 目录
启动服务器，插件会自动生成配置文件和目录结构
根据需要修改 plugins/BlockHideAndSeek/config.yml 配置文件
使用 /bhs reload 重载配置，或重启服务器

2. 安装 BungeeCord 附属插件（可选）

仅在需要跨服匹配功能时需要安装

下载 BlockHideAndSeek-Bungee-0.1.0.jar
将 JAR 文件放入 BungeeCord 代理端的 plugins/ 目录
启动或重启 BungeeCord 代理端
根据需要修改 plugins/BlockHideAndSeek-Bungee/config.yml

3. 配置依赖关系

BungeeCord 代理端
├── BlockHideAndSeek-Bungee (附属插件)
│
└── 下游子服务器
    ├── server_lobby_1 (大厅服务器)
    │   └── BlockHideAndSeek (主插件)
    ├── server_game_1 (游戏服务器)
    │   └── BlockHideAndSeek (主插件)
    └── server_game_2 (游戏服务器)
        └── BlockHideAndSeek (主插件)

4. 验证安装

启动服务器后，在控制台或游戏中输入 /bhs help，如果显示帮助信息则安装成功。

配置说明

主配置文件 `config.yml`

位于 plugins/BlockHideAndSeek/config.yml

基本设置

# 地图开关
maps-enabled: true

# 游戏基础设置
game:
  min-players: 4        # 游戏最少玩家数
  max-players: 20       # 游戏最大玩家数
  waiting-countdown: 60 # 等待阶段倒计时（秒）
  prepare-time: 15      # 准备阶段时长（秒）
  hide-time: 60         # 躲藏阶段时长（秒）
  seek-time: 480        # 搜寻阶段时长（秒）
  vip-multiplier: 1.2   # VIP 玩家积分倍率
  score-interval: 15    # 积分发放间隔（秒）

参数	默认值	说明
`game.min-players`	4	开始游戏所需的最少玩家数
`game.max-players`	20	单局游戏最大容纳玩家数
`game.waiting-countdown`	60	等待阶段倒计时（最小值 10 秒）
`game.prepare-time`	15	准备阶段持续时间
`game.hide-time`	60	躲藏阶段持续时间（经典模式）
`game.seek-time`	480	搜寻阶段持续时间（经典模式）
`game.vip-multiplier`	1.2	VIP 玩家积分获取倍率
`game.score-interval`	15	每次发放积分的间隔秒数

等候室与大厅

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

参数	说明
`waiting-room.world`	等候室所在世界
`waiting-room.x/y/z`	等候室出生坐标
`lobby.world`	大厅所在世界
`lobby.x/y/z`	大厅返回坐标

伪装方块列表

disguise-blocks:
  - "STONE"
  - "GRASS_BLOCK"
  - "OAK_PLANKS"
  - "BRICKS"
  - "SANDSTONE"

可自由添加或移除方块，支持所有 Material 枚举值。

商店配置

shop-size: 9  # 商店 GUI 大小（9 或 27）

# 商店物品价格
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-size`	商店界面大小，支持 9（单行）或 27（三行）
`shop-prices`	各物品的默认价格
`shop-items`	各物品是否可购买

积分系统

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         # 最后倒计时秒数

伪装相关

solidify-time: 6           # 实体方块转换时间（秒）
hitbox-multiplier: 1.5     # 碰撞箱放大倍率
disguise-change-cost: 5    # 伪装更换消耗积分
normal-block-count: 3      # 普通玩家候选方块数
vip-block-count: 6         # VIP 玩家候选方块数

游戏模式配置

游戏模式配置位于 game-modes 节点下，每个模式独立配置：

# 游戏模式基础配置
game-modes:
  # 经典模式
  classic:
    enabled: true
    chance: 60           # 抽选概率（百分比）

  # 感染模式
  infection:
    enabled: true
    chance: 20           # 抽选概率（百分比）
    duration-seconds: 300      # 感染模式持续时间（秒）
    infection-speed-threshold: 3  # 感染速度提升所需击杀数
    immunity-shield:           # 免疫护盾道具配置
      enabled: true
      price: 120
      duration-seconds: 3
      cooldown-seconds: 60
    progression:
      speed2-threshold: 3     # 达到速度 II 所需击杀数
      resistance-threshold: 5 # 达到抗性提升所需击杀数
    mvp:
      infection-conversion-score: 5.0  # 感染转化得分
      purification-score: 8.0          # 净化得分
      survival-per-second: 0.1         # 生存每秒得分
      initial-infected-bonus: 3.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    # 游戏内时间（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       # 免疫护盾价格

群组模式

group-mode: false              # 是否启用群组模式
main-lobby-server: "lobby"    # 主大厅服务器名称

记分板服务器名称

server-name: "§e§lStarMast §7Network"

音效配置

sounds:
  hide-start: "ENTITY_PLAYER_LEVELUP"
  seek-start: "ENTITY_WITHER_SPAWN"
  expose: "ENTITY_FIREWORK_ROCKET_BLAST"
  buy-success: "BLOCK_DISPENSER_DISPENSE"
  buy-fail: "ENTITY_ENDERMAN_TELEPORT"
  eliminate: "ENTITY_LIGHTNING_BOLT_THUNDER"
  team-assigned: "ENTITY_EXPERIENCE_ORB_PICKUP"
  countdown-tick: "BLOCK_NOTE_BLOCK_HAT"

游戏编号设置

game-id-prefix: "BHS"        # 游戏编号前缀
game-id-random-length: 5     # 随机部分长度

日志系统

logging:
  enabled: true
  filter:
    high-frequency:
      - "updateBlockDisplayPosition"
      - "checkSolidify"
      - "handlePlayerMove"
      - "updateScoreboard"
    suppression-interval-ms: 5000
    aggregate-errors: true
    summary-interval-seconds: 5

性能告警配置

performance:
  enabled: true
  check-interval-ticks: 20
  alerts:
    tps:
      warning: 18.0      # TPS 警告阈值
      critical: 15.0     # TPS 严重阈值
    mspt:
      warning: 50        # MSPT 警告阈值（毫秒）
      critical: 100      # MSPT 严重阈值（毫秒）
    memory-percent:
      warning: 70        # 内存警告阈值（%）
      critical: 85       # 内存严重阈值（%）
    thread-queue:
      warning: 100       # 线程队列警告阈值
      critical: 500      # 线程队列严重阈值

数据库配置文件 `database.yml`

位于 plugins/BlockHideAndSeek/database.yml

MySQL 配置

database:
  enabled: false    # 启用后将使用 MySQL 存储数据

  mysql:
    host: "localhost"
    port: 3306
    database: "blockhideandseek"
    username: "root"
    password: "password"
    table-prefix: "bhs_"
    use-ssl: false
    properties:
      useUnicode: true
      characterEncoding: "utf8mb4"
      serverTimezone: "Asia/Shanghai"

Redis 配置

  redis:
    enabled: false
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    timeout-ms: 5000
    key-prefix: "bhs:"

缓存与连接池配置

cache:
  local-ttl-seconds: 300           # 本地缓存有效期
  redis-ttl-seconds: 3600          # Redis 缓存有效期
  leaderboard-refresh-minutes: 60  # 排行榜刷新间隔
  warmup-on-start: true            # 启动时预热缓存

pool:
  max-size: 10              # 最大连接数
  min-idle: 2               # 最小空闲连接数
  timeout-ms: 30000         # 连接超时
  idle-timeout-ms: 600000   # 空闲连接超时
  max-lifetime-ms: 1800000  # 最大生命周期

backup:
  enabled: true           # 启用自动备份
  interval-hours: 24      # 备份间隔（小时）
  retention-count: 7      # 保留备份数量
  path: "backups"         # 备份存储路径

代理配置文件 `proxy.yml`

位于 plugins/BlockHideAndSeek/proxy.yml

proxy:
  type: AUTO  # 代理类型：AUTO（自动检测）、BUNGEECORD、VELOCITY、NONE

server:
  id: "bhs-01"          # 服务器唯一标识
  name: "§e躲猫猫 #1"   # 服务器显示名称

matching:
  enabled: true           # 启用跨服匹配
  timeout-seconds: 60     # 匹配超时（秒）
  min-players: 2          # 匹配最少玩家数
  max-players: 16         # 匹配最多玩家数

servers:
  - id: "bhs-01"
    name: "躲猫猫 #1"
  - id: "bhs-02"
    name: "躲猫猫 #2"

地图配置文件

位于 plugins/BlockHideAndSeek/maps/ 目录下，每张地图一个 .yml 文件。

# 是否启用此地图（设为 false 则跳过加载）
enabled: true

name: "示例地图"              # 地图名称

# 等候室位置（可选，不设置则使用全局配置）
waiting-room:
  world: "waiting_world"
  x: 0.0
  y: 64.0
  z: 0.0
  yaw: 0.0
  pitch: 0.0

# 游戏世界配置
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
  expose-firework-time-1: 300
  expose-firework-time-2: 180
  last-countdown-seconds: 30

# 地图特有伪装方块（可选，覆盖全局配置）
disguise-blocks:
  - "STONE"
  - "OAK_PLANKS"

# 地图特有商店价格覆盖（可选）
shop-prices:
  speed-scroll: 30
  portal: 150

# 地图特有商店物品开关（可选）
shop-items:
  speed-scroll: true
  portal: true

# 传送门目标位置（可选）
portal-location:
  world: "game_world"
  x: 150.0
  y: 70.0
  z: 150.0

游戏模式详解

经典模式

玩法流程

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

策略建议

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

感染模式

玩法流程

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

感染者进阶机制

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

策略建议

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

黑夜迷雾模式

玩法流程

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

环境效果

时间：锁定为午夜（18000 tick），伸手不见五指
天气：强制降雨，进一步降低视野
闪电：每 4~6 秒随机生成闪电，短暂照亮战场
闪光弹：每 60 秒自动闪光，短暂照亮全场

专属商店物品

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

策略建议

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

使用教程

基础命令

命令	权限	说明
`/bhs help`	`bhs.player`	显示帮助信息
`/bhs join`	`bhs.player`	加入游戏
`/bhs leave`	`bhs.player`	离开游戏
`/bhs status`	`bhs.player`	查看游戏状态
`/bhs match`	`bhs.match`	加入匹配队列
`/bhs match cancel`	`bhs.match`	取消匹配
`/bhs match status`	`bhs.match`	查看匹配状态
`/bhs match info`	`bhs.match`	查看匹配详情
`/bhs data me`	`bhs.data`	查看个人游戏数据
`/bhs data top <type>`	`bhs.data.top`	查看排行榜
`/bhs start`	`bhs.admin`	强制开始游戏
`/bhs reload`	`bhs.admin`	重载配置文件
`/bhs tps`	`bhs.admin.perf`	查看 TPS 和 MSPT
`/bhs threads`	`bhs.admin.perf`	查看线程状态
`/bhs perf`	`bhs.admin.perf`	查看完整性能面板

权限节点

权限节点	默认	说明
`bhs.player`	所有人	普通玩家权限
`bhs.vip`	OP	VIP 玩家权限（积分加成、更多候选方块）
`bhs.admin`	OP	管理员权限
`bhs.admin.notify`	OP	管理员通知权限（继承 `bhs.admin`）
`bhs.admin.perf`	OP	性能监控权限（继承 `bhs.admin`）
`bhs.match`	所有人	允许加入匹配队列
`bhs.match.crossserver`	所有人	允许跨服匹配
`bhs.match.admin`	OP	匹配管理权限
`bhs.proxy.status`	OP	查看代理状态
`bhs.data`	所有人	查询个人数据
`bhs.data.top`	所有人	查询排行榜

排行榜类型

类型	说明
`streak`	最多连胜排行
`wins`	胜场排行
`time`	游戏时长排行
`mvp`	MVP 次数排行

使用示例

玩家快速上手

1. 输入 /bhs join       → 加入当前服务器的游戏
2. 等待游戏开始          → 自动分配队伍
3. 躲藏阶段             → 寻找合适位置伪装成方块
4. 搜寻阶段             → 利用商店道具进行对抗
5. 游戏结束             → 查看排名和统计数据

管理员操作

# 强制开始游戏
/bhs start

# 重载配置（修改 config.yml 后使用）
/bhs reload

# 查看服务器性能
/bhs perf

# 查看 TPS 状态
/bhs tps

使用匹配系统

# 加入匹配队列
/bhs match

# 查看匹配状态
/bhs match status

# 查看匹配详情（排队位置、预计等待时间）
/bhs match info

# 取消匹配
/bhs match cancel

数据查询

# 查看个人游戏数据
/bhs data me

# 查看连胜排行榜
/bhs data top streak

# 查看 MVP 排行榜
/bhs data top mvp

常见问题解答

Q: 插件加载失败，提示"配置文件加载失败"？

A: 检查 config.yml 的 YAML 语法是否正确，确保缩进和格式无误。也可删除配置文件后重启服务器重新生成。

Q: 如何添加更多伪装方块？

A: 在 config.yml 的 disguise-blocks 列表中添加对应方块材质名称（如 "DIAMOND_BLOCK"），然后使用 /bhs reload 重载配置。

Q: 跨服匹配无法正常工作？

A: 请检查以下步骤：

确保 BungeeCord 代理端已安装 BlockHideAndSeek-Bungee 附属插件
确认 proxy.yml 中的代理类型配置正确（设为 AUTO 或 BUNGEECORD）
确保下游子服务器的 proxy.yml 中 matching.enabled 为 true
检查 BungeeCord 的 config.yml 中服务器列表配置是否正确

Q: 商店物品价格为 0 或无法购买？

A: 检查 config.yml 中的 shop-prices 和 shop-items 配置，确认价格不为 0 且物品已启用。如果使用地图配置，请检查地图文件中的价格覆盖设置。

Q: 数据库连接失败？

A: 检查 database.yml 中的连接参数是否正确，确认 MySQL 服务已启动且可从服务器访问。如不需要数据库，可将 database.enabled 设为 false 使用本地文件存储。

Q: 如何重置玩家数据？

A: 如果使用本地存储（JSON），删除 plugins/BlockHideAndSeek/data/ 目录下的对应文件。如果使用 MySQL，清空对应数据表即可。

Q: 游戏开始后玩家无法移动或操作？

A: 确保游戏世界已正确加载，且世界类型为普通世界（不是超平坦、下界等特殊世界类型）。检查 maps/ 目录下的地图配置文件中的 game-world 参数是否正确。

Q: 性能告警频繁触发？

A: 可在 config.yml 的 performance 部分调整告警阈值，或关闭不需要的监控项目。

Q: 插件在 Folia 上无法加载？

A: 插件已内置 Folia 兼容支持，启动时自动检测服务端类型。如果遇到问题，请确保使用 Paper 1.19.4+ 或 Folia 的兼容分支。

更新日志

0.1.1 (当前版本)

Folia 兼容支持
- 新增调度器兼容层，自动检测 Paper/Folia 服务端
- 无需额外配置，即插即用
API 版本兼容
- 兼容 Paper(及衍生服务端)/Folia 1.19.4 ~ 1.21.x
黑夜迷雾模式完善
- 环境设置（时间锁定、强制降雨、闪电生成）
- 专属商店物品（夜视药水、灯笼、感知技能、照明弹）
- 夜视效果阶段分配（躲藏方/猎人）
感染模式完善
- 感染者进阶机制（速度 II、抗性提升）
- 幸存者警报系统
- 免疫护盾道具
- 净化血清道具
- MVP 评分适配
- 结局奖励调整

0.1.0 (初始开发版本)

核心功能
- 实现完整的游戏生命周期管理（等待 → 准备 → 躲藏 → 搜寻 → 结束）
- 三种游戏模式：经典模式、感染模式、黑夜迷雾模式
- 方块伪装系统，支持自定义伪装方块列表
- 14 种商店物品，支持 GUI 购买
- 暴露机制（定时暴露、烟花暴露、最后一分钟暴露）
- MVP 计算与追踪系统
- 多地图支持，每张地图独立配置
存储系统
- JSON 本地文件存储
- MySQL 数据库存储（可选）
- Redis 缓存加速（可选）
- 排行榜系统
- 玩家数据统计
- 跨服数据同步
- 自动备份
代理/跨服支持
- BungeeCord 代理支持
- Velocity 代理支持
- 代理类型自动检测
- 跨服匹配系统
- 游戏状态跨服广播
监控系统
- TPS/MSPT 实时监控
- 内存使用率监控
- 线程状态监控
- 性能告警（支持多级阈值）
- 智能日志过滤与聚合
- Delog 调试日志系统
- 游戏内通知与控制台通知
BungeeCord 附属插件（暂不对外提供）
- 跨服玩家传送
- 消息路由
- 服务器管理（大厅/游戏服务器）
- 跨服匹配服务
- 服务器健康检查

版权声明

未经授权，禁止搬运、反编译或反混淆此代码产品。

内测交流群：754526134（QQ）

© 2025~2026 StarMastStudio. All rights reserved.

模组	作用	推荐度
DarkAroundMe	模拟真实黑暗环境，让黑夜真正黑暗	⭐⭐⭐⭐⭐
Truly Dark	深度黑暗效果，洞穴和夜晚更加真实	⭐⭐⭐⭐⭐

方块躲猫猫

方块躲猫猫

基本信息

我的世界Java版本

平台

运行环境

分类

其他链接

创作团队

详情信息

方块躲猫猫 (BlockHideAndSeek)

目录

插件概述

什么是方块躲猫猫？

主插件与附属插件

功能特性

主插件核心特性

游戏机制

三种游戏模式详解

经典模式

感染模式

黑夜迷雾模式

商店系统

数据存储系统

代理/跨服支持

监控与性能

MVP 计算

地图系统

记分板系统

服务端兼容性

BungeeCord 附属插件特性

安装指南

系统要求

安装步骤

1. 安装主插件

2. 安装 BungeeCord 附属插件（可选）

3. 配置依赖关系

4. 验证安装

配置说明

主配置文件 config.yml

基本设置

等候室与大厅

伪装方块列表

商店配置

积分系统

暴露机制

伪装相关

游戏模式配置

模式专属商店物品

群组模式

记分板服务器名称

音效配置

游戏编号设置

日志系统

性能告警配置

数据库配置文件 database.yml

MySQL 配置

Redis 配置

缓存与连接池配置

代理配置文件 proxy.yml

地图配置文件

游戏模式详解

经典模式

玩法流程

策略建议

感染模式

玩法流程

感染者进阶机制

策略建议

黑夜迷雾模式

玩法流程

环境效果

专属商店物品

推荐客户端增强模组

策略建议

使用教程

基础命令

权限节点

排行榜类型

使用示例

主配置文件 `config.yml`

数据库配置文件 `database.yml`

代理配置文件 `proxy.yml`