
一款可定制的 Minecraft 捉迷藏小游戏插件,支持自定义物品、装备配置、外观装饰、多种游戏模式、天赋系统以及详尽的统计追踪。
目录
概述
HideAndSeek 是一款 Minecraft 小游戏插件,其中一队玩家扮演躲藏者(Hiders),另一队扮演搜寻者(Seekers)。躲藏者可以伪装成方块、缩小体型、穿着自定义皮肤,或者仅仅依靠优秀的隐蔽位置;而搜寻者则使用多样化的实用工具来追踪、揭露并淘汰躲藏者。该插件基于 MinigameFramework(同样由我开发)构建,后者负责处理阶段管理、队伍分配、物品注册以及玩家数据持久化。
本插件支持带有独立配置覆盖项的自定义地图、用于选择地图和游戏模式的大厅投票系统、持久的装备配置和外观皮肤系统、基于回合的天赋商店、详细的个人统计数据,以及由 MinigameFramework 提供的广泛的游戏内设置 GUI。
截图
方块模式:躲藏者伪装成方块并与环境融为一体。

装备配置界面。躲藏者和搜寻者拥有独立的物品池和代币预算。
方块选择器 GUI,用于选择和自定义你的方块伪装。
近距离传感器、摄像头系统和笼式陷阱的实际效果演示。
游戏模式
| 模式 |
描述 |
NORMAL |
躲藏者以自身形态在地图中隐藏。搜寻者使用剑和实用工具追捕他们。 |
BLOCK |
躲藏者伪装成可配置的方块,融入风景之中。搜寻者必须发现不一致之处。 |
SMALL |
躲藏者被缩放至可配置的大小,使其更难被发现。搜寻者也可以被调整大小(可选)。 |
SKIN |
躲藏者使用自定义皮肤(例如像方块或与环境匹配的皮肤)来融入景观。为了增加难度,也可以选择将他们缩小。 |
游戏模式可以通过游戏内设置 GUI 更改,或由大厅中的玩家投票决定。
功能特性
核心玩法
- 四种独特的游戏模式:普通、方块、缩小、皮肤
- 包含玩家就绪检查及地图/游戏模式/角色偏好投票的大厅
- 可配置的躲藏和搜寻阶段持续时间
- 支持世界边界,并提供每地图的边界配置
- 每回合结束后自动清理地图并返回大厅
- 积分和计分系统,回合结束时发放金币奖励
- 在搜寻阶段显示剩余躲藏者和搜寻者数量的 Boss 栏
- 反作弊可见性过滤:搜寻者只能看到配置范围内且视线内的躲藏者
- 躲藏者蹲点检测与惩罚系统
- 环境伤害上限控制(溺水、火焰、熔岩、窒息、冻结、接触伤害、高温地面),防止躲藏者通过危险区域逃脱
- “肾上腺素爆发”翻盘机制:当最后一名(或多名)躲藏者存活或时间紧迫时触发增益效果
地图系统
- 多张地图,每张地图均有独立配置(允许的方块、皮肤、计时、搜寻者数量、设置覆盖、自动售货机位置)
- 随机地图选择或玩家大厅投票
- 每回合自动复制和删除世界
- 每地图的世界边界、出生点和方块列表
- 回合开始时显示地图信息标题(可配置显示模式)
装备配置系统
- 玩家在每回合开始前在大厅自定义选择物品
- 代币预算系统,分为五个稀有度等级:普通、不常见、稀有、史诗、传说
- 独立的躲藏者和搜寻者装备槽位和代币池
- 槽位偏好:将物品类型分配到特定的物品栏槽位,并支持可配置的后备方案
- 管理员装备管理器 GUI:按角色过滤物品(黑名单/白名单)、锁定单个玩家的装备配置、定义管理员角色预设、强制所有玩家应用预设
- 装备数据通过数据库或 YAML 文件跨会话持久化存储
天赋系统
- 每轮奖励商店:每轮提供一组随机选择的增益效果
- 两种商店模式:物品栏行(物品直接放置在玩家的快捷栏中)或售货机(在配置的地图位置放置发射器)
- 躲藏者增益:自适应速度、追逐者警告、额外生命、暗影步、伪装、二段跳、陷阱感知
- 追逐者增益:死亡区域、随机交换、地图传送、重新定位、鞘翅冲刺、接近度计、气味轨迹、自动瞄准、命中显示、剑反弹
- 有限增益:每轮每队只能有一名玩家购买某些增益
- 可重复购买的追逐者增益:可通过配置冷却时间多次购买
- 所有增益成本、冷却时间、阈值和行为均可按设置配置
外观系统
- 使用从回合点数获得的硬币购买物品皮肤(变体)
- 每种物品拥有多种具有独特视觉外观的皮肤
- 击杀特效:当追逐者淘汰躲藏者时播放自定义特效
- 胜利皮肤:回合结束时为获胜队伍播放的特殊特效
- 死亡消息:自定义击杀/环境死亡消息格式
- 拥有基于稀有度的可配置价格的硬币商店
- 外观数据跨会话持久化
统计系统
- 跨所有回合追踪每位玩家的统计数据:胜场、负场、击杀、死亡、造成伤害、生存时间、游戏时长、嘲讽、最后存活的躲藏者回合数、获得的点数和硬币
- 追踪每件物品的使用情况(装备次数、使用次数)
- 追踪每张地图和每种游戏模式的游玩次数
- 追踪增益使用情况
- 方块模式:隐藏与暴露时间追踪
- 五标签统计 GUI:概览、战斗、物品、地图、增益
- 管理员
/mg stats 命令可查看任何玩家的统计数据
躲藏者物品
鞭炮、大鞭炮、烟花火箭、猫叫声、加速、击退棍、追踪十字弩、方块交换、
随机方块、烟雾弹、减速球、隐身衣、医疗包、不死图腾、幽灵精华 (仅限 NMS,
若无 NMS 则回退至有限行为)、远程网关
追逐者物品
追逐者的刀刃(可充能 + 投掷)、抓钩、墨水溅射、闪电冻结、发光指南针、诅咒法术、
方块随机化器、链式拉扯、接近传感器、笼式陷阱、幻影查看器、摄像头系统 (仅限 NMS,无
其支持时禁用)、追逐者助手 (仅限 NMS,无其支持时禁用)
要求
| 要求 |
版本 |
| Java |
21+ |
| Paper (或 Purpur) |
1.21.10+ |
| MinigameFramework |
1.0.0 |
MinigameFramework
[!IMPORTANT]
HideAndSeek 依赖于 MinigameFramework,这也是由我开发的配套库。目前它尚未公开
提供,无论是 JAR 文件还是源代码。
[!NOTE]
MinigameFramework 将在未来公开发布。届时将更新本节内容。
安装
- 确保您的服务器运行的是 Paper 1.21.10/11,并使用 Java 21 或更高版本。
- 等待
MinigameFramework.jar 发布后,将其放入 plugins/ 文件夹。
- 将
HideAndSeek-1.0-SNAPSHOT.jar 放入 plugins/ 文件夹。
- 启动服务器一次以生成配置文件。
- 通过 MinigameFramework 的团队配置设置至少两个记分板团队。
- 添加至少一张地图(参见 地图设置)。
- 重启服务器。
快速检查清单
- 服务器上使用 Java 21+
- Paper 1.21.10/11 服务器 jar 包
-
plugins/ 中包含 MinigameFramework.jar
-
plugins/ 中包含 HideAndSeek-1.0-SNAPSHOT.jar
- MinigameFramework 中已配置两个团队
-
plugins/HideAndSeek/maps.yml 中至少有一个地图条目
- 首次运行后重启了服务器
配置
插件会在首次运行时在 plugins/HideAndSeek/ 目录下生成 config.yml 和 maps.yml。
设置工作原理
所有游戏玩法设置都通过 MinigameFramework 提供的游戏内设置 GUI 进行管理。config.yml
文件仅用于覆盖设置的默认值。如果 config.yml 中不存在某项设置,则使用插件内置的默认值。GUI 中进行的更改会立即生效,但不会在重启后保留。
顶级配置键
# Hide & Seek 插件配置
# 可用地图世界名称列表
# 这些必须与 maps.yml 中的世界名称匹配
maps:
- "map1"
- "map2"
# 注意:特定于地图的配置(出生点、允许使用的方块、世界边界、首选模式)
# 保存在 maps.yml 中。请参阅该文件以获取每张地图的设置。
nms:
# 主开关:尝试加载 NMS 适配器。如果为 true,插件将在启动时尝试启用 NMS 功能
# 如果适配器缺失或失败,行为取决于回退机制。
enabled: true
persistence:
save-skin-data: true
save-loadout-data: true
inject-datapack: true
tab:
enable-header: true
enable-footer: true
server-ip: "yourserver.com"
# 头部配置
header:
# 动画文本的颜色渐变设置
title-colors:
- "#FF0000" # 红色
- "#FFFF00" # 黄色
title-speed: 0.5
ip-colors:
- "#00FF00" # 绿色
- "#00FFFF" # 青色
- "#0088FF" # 浅蓝色
ip-speed: 0.3
头部元素
elements:
- text: "Hello "
enabled: true
color: "#808080" # 灰色
animated: false
- text: "{player}"
enabled: true
color: "#FFFF00" # 黄色
animated: false
- text: "!"
enabled: true
color: "#808080" # 灰色
animated: false
- text: "\nYou are playing "
enabled: true
color: "#808080" # 灰色
animated: false
- text: "HideAndSeek"
enabled: true
color-list: "title-colors" # 使用颜色渐变
speed: "title-speed"
animated: true
- text: " on "
enabled: true
color: "#808080" # 灰色
animated: false
- text: "{server-ip}"
enabled: true
color-list: "ip-colors" # 使用颜色渐变
speed: "ip-speed"
animated: true
- text: "\n\n"
enabled: true
color: "#FFFFFF" # 白色
animated: false
页脚配置
footer:
# 页脚元素
elements:
- text: "\n角色: "
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{role}"
enabled: true
color: "{role-color}"
- text: " | "
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{mode}"
enabled: true
color: "#008000" # 绿色
- text: "\n玩家: "
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{players-total}"
enabled: true
color: "#FFFFFF" # 白色
- text: " ("
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{players-hiders}"
enabled: true
color: "#00AA00" # 绿色
- text: "|"
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{players-seekers}"
enabled: true
color: "#FF0000" # 红色
- text: ")"
enabled: true
color: "#A9A9A9" # 深灰色
- text: "\n分数: "
enabled: true
color: "#FFD700" # 金色
- text: "{points}"
enabled: true
color: "#FFD700" # 金色
- text: "\n金币: "
enabled: true
color: "#FFFF00" # 黄色
- text: "{coins}"
enabled: true
color: "#FFFF00" # 黄色
- text: "\n"
enabled: true
color: "#FFFFFF" # 白色
scoreboard:
enabled: true
title:
text: "HideAndSeek"
small-caps: true
underline: true
colors:
gradient:
- "#FF0000" # 红色
- "#FFFF00" # 黄色
animation:
enabled: true
speed: 0.15
formatting:
small-caps: true
padding: true
padding-amount: 3
lines:
- text: "角色:"
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{role}"
enabled: true
color: "#0000FF" # 蓝色
- text: "模式:"
enabled: true
color: "#A9A9A9" # 深灰色
- text: "{mode}"
enabled: true
color: "#008000" # 绿色
- text: "玩家: {players-total} ({players-hiders}|{players-seekers})"
enabled: true
color: "#A9A9A9,#FFFFFF,#00FF00,#FF0000"
- text: "分数: {points}"
enabled: true
color: "#FFD700" # 金色
- text: "金币: {coins}"
enabled: true
color: "#FFFF00" # 黄色
settings:
外观 GUI 中全局禁止的方块状态属性
disallowed-blockstates:
- "waterlogged"
- "conditional"
seeker-break-blocks:
- "SHORT_GRASS"
- "TALL_GRASS"
- "SEAGRASS"
- "TALL_SEAGRASS"
block-interaction-exceptions:
- "_DOOR"
- "_FENCE_GATE"
- "_TRAPDOOR"
- "_BUTTON"
- "*_LEVER"
block-physics-exceptions:
- "_DOOR"
- "_FENCE_GATE"
- "_TRAPDOOR"
- "_BUTTON"
- "*_LEVER"
### 覆盖设置默认值
在游戏内 GUI 中显示的任意设置,都可以在 `config.yml` 下的 `settings:` 键中覆盖其默认值。
例如:
```yaml
settings:
game.mode: BLOCK
game.hiding-time: 90
game.seeking-time: 240
game.hiders.health: 10
anticheat.seeking.visibility-range: 16.0
loadout.hider-max-items: 4
loadout.hider-max-tokens: 14
hider-items.speed-boost.cooldown: 15
seeker-items.glowing-compass.cooldown: 30
points.hider.survival.amount: 10
perks.enabled: true
perks.perks-per-round: 3
所有可用设置键的完整列表可以在
SettingRegistrar.java 中找到。
地图设置
地图定义在 plugins/HideAndSeek/maps.yml 中。每个键是内部地图名称,必须与服务器上存在的世界文件夹名称匹配。
map1:
pretty-name: "起始山谷"
description: "默认地图"
author: "服务器管理员"
size: "MEDIUM"
icon: "GRASS_BLOCK"
spawn-points:
- "0,65,0,0,0" # 格式:x,y,z,yaw,pitch
world-borders: [] # 格式:centerX,centerZ,size 或 centerX,centerZ,r:radius
preferred-modes:
- "BLOCK"
seeker-break-blocks:
- "SHORT_GRASS"
- "TALL_GRASS"
block-interaction-exceptions:
- "*_DOOR"
- "*_FENCE_GATE"
- "*_TRAPDOOR"
- "*_BUTTON"
- "*_LEVER"
block-physics-exceptions:
- "*_DOOR"
- "*_FENCE_GATE"
- "*_TRAPDOOR"
- "*_BUTTON"
- "*_LEVER"
setting-overrides:
hider-items:
firework-rocket:
target-y: 64
players:
min: 4
recommended: 8
max: 16
seekers:
min: 1
per-players: 8
max: 4
timings:
hiding-time: 60
seeking-time: 300
vending-machine-locations: # 在搜寻阶段放置的发射器方块,用于perk自动售货机商店模式
- "12,64,-8"
- "-40,71,22"
allowed-blocks: # 在 BLOCK 模式下使用
- "STONE"
- "OAK_LOG[*]"
- "*CANDLE{RED_CANDLE}"
- "OAK_TRAPDOOR[half,open,facing]"
allowed-skins: # 在 SKIN 模式下使用;引用 skins.yml 中定义的键
- "oak_log"
- "stone"
世界边界格式
如果出生点数量等于世界边界数量,则每个出生点按索引匹配其对应的边界。否则,所有出生点均使用第一个边界。
方块模式语法
allowed-blocks 列表接受一种模式 DSL,以灵活选择方块:
| 模式 |
含义 |
STONE |
精确匹配 STONE 材质 |
OAK_SLAB[type=bottom] |
橡木台阶锁定为特定的方块状态 |
OAK_SLAB[*] |
允许橡木台阶拥有任意方块状态 |
*SLAB{OAK_SLAB} |
所有台阶变体,默认为橡木台阶 |
*SLAB{OAK_SLAB}[type=bottom] |
所有台阶变体,默认为橡木台阶,锁定方块状态 |
#planks{OAK_PLANKS} |
Bukkit 标签 planks 中的所有方块,默认为橡木木板 |
{STONE,GRANITE,DIORITE} |
显式自定义材质列表 |
皮肤设置
SKIN 模式的自定义皮肤在 plugins/HideAndSeek/skins.yml 中定义:
oak_log:
name: "Oak Log"
icon: "minecraft:oak_log"
value: "<base64 skin texture value>"
signature: "<base64 skin texture signature>"
可以使用 Mineskin 等服务生成皮肤纹理。每个皮肤条目必须具有有效的签名 value/signature 对。
装备系统
玩家在每个回合开始前的大厅配置他们的装备。每个物品都有一个稀有度,决定其代币成本。
| 稀有度 |
默认代币成本 |
| Common |
1 |
| Uncommon |
2 |
| Rare |
4 |
| Epic |
6 |
| Legendary |
10 |
默认情况下,躲藏者拥有 12 个代币和最多 3 个物品槽。追踪者拥有 12 个代币和最多 4 个物品槽。所有值均可通过游戏内设置 GUI 或 config.yml 中的 settings.loadout.* 进行配置。
槽位偏好
玩家可以配置哪些物品 类型(例如 机动性、进攻、陷阱)放置在哪个物品栏槽位中,并为每个槽位设置一个备用类型。可以通过装备 GUI 中的“槽位偏好”按钮访问此功能。
管理员预设系统
管理员可以在管理员装备管理器 GUI (/mg loadout admin) 中为每个角色(躲藏者/追踪者)定义最多 5 个角色预设。预设可以:
- 启用/禁用 每个槽位
- 强制: 将该角色的所有玩家锁定到指定的预设
- 受限: 玩家只能从启用的管理员预设中选择,而不是自行构建装备
Perk 系统
在每个搜寻阶段开始时,会随机选择一组 perk(数量可配置)。玩家在 perk 商店花费他们累积的回合点数来购买 perk。
商店模式
- 背包: 在搜寻阶段,perk 物品直接放置在玩家第二个快捷栏行中。
- 自动售货机: 在
maps.yml 的 vending-machine-locations 下定义的位置放置发射器方块。
玩家与发射器交互即可打开商店。
躲藏者 Perk
| Perk |
描述 |
| Adaptive Speed |
当生命值低于可配置的阈值时,获得速度效果 |
| Seeker Warning |
当追踪者接近时,显示警告标题和边界脉冲 |
| Extra Life |
根据累积的点数获得相应的吸收之心 |
| Shadow Step |
当生命值危急时,自动传送到一个安全随机的位置 |
| Camouflage |
定期清除负面状态效果和发光效果 |
| Double Jump |
允许使用飞行键在空中进行第二次跳跃 |
| Trap Sense |
用粒子效果和警告标题高亮附近的陷阱 |
追踪者 Perk
| 特性 |
描述 |
| 死亡区域 |
打开地图选择器以绘制危险圆圈;躲在里面的玩家必须逃离否则将死亡 |
| 随机交换 |
将追捕者传送至随机躲藏者的位置(反之亦然) |
| 地图传送 |
打开地图选择器以选择传送目的地,落地时将陷入失明状态 |
| 重新定位 |
强制所有躲藏者离开当前位置,否则将死亡 |
| 鞘翅冲刺 |
使追捕者进入短暂的滑翔状态,并可通过配置调整发射推力 |
| 距离指示器 |
根据与最近躲藏者的距离显示“冷/热”提示音 |
| 气味轨迹 |
渲染粒子轨迹,显示最近的躲藏者移动路径 |
| 自动瞄准 |
被动效果:投掷时引导追捕者之刃朝向附近的躲藏者 |
| 命中显示 |
被动效果:蓄力期间显示剑的飞行轨迹 |
| 剑刃反弹 |
被动效果:每次击中后,被投掷的追捕者之刃会弹射至额外的躲藏者 |
所有特性的消耗、冷却时间、半径、持续时间及其他参数均可通过设置 GUI 中 perks.* 部分进行配置。
物品参考
躲藏者物品
| 物品 |
稀有度 |
无 NMS 支持 |
描述 |
| 鞭炮 |
普通 |
完整 |
放置小型爆炸蜡烛作为诱饵以获取积分 |
| 猫叫声 |
普通 |
完整 |
向所有在线玩家播放响亮的猫叫声 |
| 随机方块 |
普通 |
完整 |
重骰伪装方块(使用次数有限) |
| 速度提升 |
普通 |
完整 |
获得加速效果或速度爆发 |
| 追踪弩 |
普通 |
完整 |
射击追捕者以赚取积分并升级物品 |
| 击退棍 |
普通 |
完整 |
击退追捕者;当弩达到阈值时升级 |
| 烟花火箭 |
不常见 |
完整 |
发射高空烟花作为诱饵 |
| 迟缓球 |
不常见 |
完整 |
投掷一个减缓追捕者速度的投射物 |
| 烟雾弹 |
不常见 |
完整 |
投掷烟云以获得视觉掩护 |
| 方块交换 |
稀有 |
完整 |
与最近的另一名躲藏者交换伪装方块 |
| 大鞭炮 |
稀有 |
完整 |
产生大型爆炸,并伴有弹跳的小型鞭炮 |
| 医疗包 |
稀有 |
完整 |
按住方块进行持续治疗;提前释放以取消 |
| 幽灵精华 |
稀有 |
回退 |
短暂穿墙而过;若无 NMS 则回退为有限行为 |
| 远程网关 |
史诗 |
完整 |
放置成对的网关,在锚点之间传送直到回合结束 |
| 隐形斗篷 |
史诗 |
完整 |
变为隐身状态,持续时间为可配置 |
| 不死图腾 |
传说 |
完整 |
死亡时激活一次性的复活窗口 |
追捕者物品
| 物品 |
稀有度 |
无 NMS 支持 |
描述 |
| 抓钩 |
普通 |
完整 |
抛出并收回以将自己向前发射 |
| 诅咒咒语 |
不常见 |
完整 |
强化你的剑,击中躲藏者时施加诅咒 |
| 链式拉扯 |
不常见 |
完整 |
将你面前的躲藏者拉至你的位置 |
| proximity 传感器 |
稀有 |
完整 |
放置一个传感器,当躲藏者走入范围时会发光 |
| 墨水飞溅 |
稀有 |
完整 |
使半径内所有躲藏者失明 |
| 笼式陷阱 |
稀有 |
完整 |
放置一个隐藏陷阱,困住并 immobilise 一名躲藏者 |
| 幻影查看器 |
稀有 |
完整 |
从躲藏者视角捕捉粗略的地图快照 |
| 方块随机化器 |
史诗 |
完整 |
强制所有躲藏者立即重骰其方块 |
| 发光指南针 |
史诗 |
完整 |
通过发光效果揭示最近的躲藏者 |
| 相机 |
史诗 |
禁用 |
最多放置 5 台相机并通过它们进行观战 |
| 闪电冻结 |
传说 |
回退 |
将所有躲藏者原地冻结一小段时间 |
| 追捕者助手 |
传说 |
禁用 |
召唤一个 AI 狩猎生物,追踪并射击躲藏者 |
命令与权限
| 命令 |
权限 |
描述 |
/mg loadout |
hideandseek.command.loadout |
打开套装选择图形用户界面 |
/mg loadout admin |
hideandseek.command.loadout.admin |
打开管理员套装管理图形用户界面 |
/mg map <name> |
hideandseek.command.map |
设置或查看当前地图 |
/mg vote |
hideandseek.command.vote |
打开地图/游戏模式/角色投票图形用户界面 |
/mg ready |
hideandseek.command.ready |
在大厅中切换你的就绪状态 |
/mg skin |
hideandseek.command.skin |
打开物品皮肤商店 |
/mg unstuck |
hideandseek.command.unstuck |
传送到你上次的安全位置 |
/mg stats [player] |
hideandseek.command.stats |
打开你自己或其他玩家的统计信息图形用户界面 |
/mg debug <subcommand> |
(op) |
调试工具(点数、金币、皮肤、加成、配置验证、YAML 迁移) |
注意: 完整的权限节点和其他管理员命令将在 MinigameFramework 的命令 API 确定后记录。
角色权限
以下权限在回合期间自动分配,可用于其他插件或命令守卫:
| 权限 |
分配给 |
hideandseek.role.hider |
当前被分配为躲藏者的玩家 |
hideandseek.role.seeker |
当前被分配为寻找者的玩家 |
hideandseek.role.spectator |
活跃回合中的旁观者玩家 |
NMS 功能
| 能力 |
无 NMS 时的行为 |
| 客户端游戏模式伪装(在旁观模式下显示为生存模式) |
Ghost Essence 回退到有限行为 |
| 生物寻路 API |
Ghost Essence 回退;寻找者助手被禁用 |
| 客户端相机实体伪装 |
相机物品完全禁用 |
| 客户端实体发光数据包 |
相机夜视模式不可用;陷阱感知发光被禁用 |
| 客户端实体生成数据包 |
相机物品完全禁用 |
| 客户端实体移除数据包 |
相机物品完全禁用 |
| 客户端实体可见性数据包 |
反作弊可见性过滤器回退到服务器端的隐藏/显示 |
| 自定义实体 AI 目标 |
寻找者助手完全禁用 |
| 投射物实体射线检测用于命中判定 |
寻找者之刃投掷回退到原版射线检测 |
| 客户端闪电数据包 |
闪电冻结使用仅对目标可见的服务器端闪电束 |
| 客户端假世界边界警告 |
肾上腺素冲刺和寻找者警告加成的边界脉冲不显示 |
| 每玩家对话框注册表(Netty 数据包注入) |
游戏内快速操作对话框按钮不可用 |
| 旁观者库存 Netty 拦截 |
旁观者传送图形用户界面无法运作 |
NMS 实现目前针对 Paper 1.21.10 (nms-v1_21_10) 和 Paper 1.21.11 (nms-v1_21_11)。
添加对其他版本的支持需要一个新的 Gradle 模块来实现 NmsAdapter 接口并提供一个
NmsAdapterMeta,该元数据声明它支持哪些 Minecraft 版本。

A customizable Minecraft Hide and Seek minigame plugin, with custom items, loadouts,
cosmetics, multiple game modes, a perk system, and extensive stats tracking.
Table of Contents
Overview
HideAndSeek is a Minecraft minigame plugin in which one team hides while the other seeks. Hiders can disguise themselves
as blocks, shrink to a tiny size, wear custom skins, or simply rely on good hiding spots, while seekers use a diverse
arsenal of utility items to track, reveal, and eliminate them. The plugin is built on top of MinigameFramework (also
developed by me), which handles phase management, team assignment, item registration, and player data persistence.
The plugin supports custom maps with per-map setting overrides, a lobby voting system for maps and game modes, a
persistent loadout and cosmetic skin system, a round-based perk shop, detailed per-player statistics, and an extensive
in-game settings GUI provided by MinigameFramework.
Screenshots
Block mode: hiders disguise as blocks and blend into the environment.

The loadout screen. Hiders and seekers have separate item pools and token budgets.
Block Selector GUI for choosing and customizing your block disguise.
The Proximity Sensor, Camera System, and Cage Trap in action.
Game Modes
| Mode |
Description |
NORMAL |
Hiders hide in the map as themselves. Seekers hunt them down using their sword and utility items. |
BLOCK |
Hiders disguise as configurable blocks and blend into the scenery. Seekers must spot inconsistencies. |
SMALL |
Hiders are scaled down to a configurable size, making them much harder to spot. Seekers can optionally be resized too. |
SKIN |
Hiders disguise using custom skins (e.g. block-like or environment-matching skins) to blend into the landscape. They may also be optionally scaled down for increased difficulty. |
Game modes can be changed via the in-game settings GUI or voted on by players in the lobby.
Features
Core Gameplay
- Four distinct game modes: Normal, Block, Small, Skin
- Lobby with player readiness checks and map/gamemode/role-preference voting
- Configurable hiding and seeking phase durations
- World border support with per-map border configurations
- Automatic map cleanup and lobby return after each round
- Points and scoring system with round-end coin rewards
- Boss bar showing remaining hiders and seekers during the seeking phase
- Anti-cheat visibility filtering: seekers only see hiders within a configured range and line of sight
- Hider camping detection and punishment system
- Environmental damage capping (drowning, fire, lava, suffocation, freezing, contact, hot floor) to prevent hiders escaping through hazards
- Adrenaline Rush comeback mechanic: buffs trigger when the last hider(s) survive or time runs low
Map System
- Multiple maps with per-map configuration (allowed blocks, skins, timings, seeker count, setting overrides, vending machine locations)
- Random map selection or player lobby voting
- Automatic world copying and deletion per round
- Per-map world borders, spawn points, and block lists
- Map info title shown at round start (configurable display mode)
Loadout System
- Players customize their item selection in the lobby before each round
- Token budget system with five rarity tiers: Common, Uncommon, Rare, Epic, Legendary
- Separate hider and seeker loadout slots and token pools
- Slot preferences: assign item types to specific inventory slots with configurable fallbacks
- Admin loadout manager GUI: filter items per role (blacklist/whitelist), lock individual player loadouts, define admin role presets, force a preset on all players
- Loadout data persisted across sessions via database or YAML
Perk System
- Per-round perk shop: a random selection of perks is offered each round
- Two shop modes: inventory row (items placed directly in the player's hotbar) or vending machine (droppers placed at configured map locations)
- Hider perks: Adaptive Speed, Seeker Warning, Extra Life, Shadow Step, Camouflage, Double Jump, Trap Sense
- Seeker perks: Death Zone, Random Swap, Map Teleport, Relocate, Elytra Rush, Proximity Meter, Scent Trail, Auto Aim, Hit Display, Sword Bounce
- Finite perks: only one player per team can buy certain perks per round
- Seeker rebuyable perks: can be purchased multiple times with a configurable cooldown
- All perk costs, cooldowns, thresholds, and behaviours are configurable per-setting
Cosmetic System
- Item skins (variants) purchasable with coins earned from round points
- Each item has multiple skins with unique visual appearances
- Kill effects: custom effects played when a seeker eliminates a hider
- Win skins: special effects played for the winning team at round end
- Death messages: custom kill/environmental death message formatting
- Coin shop with configurable rarity-based prices
- Cosmetic data persisted across sessions
Statistics System
- Per-player stats tracked across all rounds: wins, losses, kills, deaths, damage dealt, survival time, playtime, taunts, last-hider-standing rounds, points and coins earned
- Per-item usage tracking (times equipped, times used)
- Per-map and per-game-mode play count tracking
- Perk usage tracking
- Block mode: hidden vs exposed time tracking
- Five-tab stats GUI: Overview, Combat, Items, Maps, Perks
- Admin
/mg stats command to view any player's stats
Hider Items
Firecracker, Big Firecracker, Firework Rocket, Cat Sound, Speed Boost, Knockback Stick, Tracker Crossbow, Block Swap,
Random Block, Smoke Bomb, Slowness Ball, Invisibility Cloak, Medkit, Totem of Undying, Ghost Essence (NMS only,
falls back to limited behaviour without NMS), Remote Gateway
Seeker Items
Seeker's Blade (chargeable + throwable), Grappling Hook, Ink Splash, Lightning Freeze, Glowing Compass, Curse Spell,
Block Randomizer, Chain Pull, Proximity Sensor, Cage Trap, Phantom Viewer, Camera System (NMS only, disabled without
it), Seeker's Assistant (NMS only, disabled without it)
Requirements
| Requirement |
Version |
| Java |
21+ |
| Paper (or Purpur) |
1.21.10+ |
| MinigameFramework |
1.0.0 |
MinigameFramework
[!IMPORTANT]
HideAndSeek depends on MinigameFramework, a companion library also developed by me. It is not currently publicly
available, neither the JAR nor the source code.
[!NOTE]
MinigameFramework will be released publicly in the future. This section will be updated when that happens.
Installation
- Ensure your server runs Paper 1.21.10/11 with Java 21 or newer.
- Wait until
MinigameFramework.jar is released and place it in your plugins/ folder.
- Place
HideAndSeek-1.0-SNAPSHOT.jar in your plugins/ folder.
- Start the server once to generate config files.
- Set up at least two scoreboard teams via MinigameFramework's team configuration.
- Add at least one map (see Map Setup).
- Restart the server.
Quick Checklist
- Java 21+ on the server
- Paper 1.21.10/11 server jar
-
MinigameFramework.jar in plugins/
-
HideAndSeek-1.0-SNAPSHOT.jar in plugins/
- Two teams configured in MinigameFramework
- At least one map entry in
plugins/HideAndSeek/maps.yml
- Server restarted after first run
Configuration
The plugin generates config.yml and maps.yml in plugins/HideAndSeek/ on first run.
How settings work
All gameplay settings are managed through the in-game settings GUI, provided by MinigameFramework. The config.yml
file only serves to override the default value of a setting. If a setting is not present in config.yml, the plugin's
built-in default is used instead. Changes made in the GUI take effect immediately but do NOT persist across restarts.
Top-level config keys
# Hide & Seek Plugin Configuration
# List of available map world names
# These must match the world names in maps.yml
maps:
- "map1"
- "map2"
# NOTE: Map-specific configuration (spawn-points, allowed-blocks, world-borders, preferred-modes)
# is saved in maps.yml. See that file for per-map settings.
nms:
# Master switch: attempt to load NMS adapter. If true, plugin will try to enable NMS features
# on startup. If adapter missing or fails, behavior depends on fallbacks.
enabled: true
persistence:
save-skin-data: true
save-loadout-data: true
inject-datapack: true
tab:
enable-header: true
enable-footer: true
server-ip: "yourserver.com"
# Header configuration
header:
# Color gradient settings for animated text
title-colors:
- "#FF0000" # Red
- "#FFFF00" # Yellow
title-speed: 0.5
ip-colors:
- "#00FF00" # Green
- "#00FFFF" # Aqua
- "#0088FF" # Light Blue
ip-speed: 0.3
# Header elements
elements:
- text: "Hello "
enabled: true
color: "#808080" # Gray
animated: false
- text: "{player}"
enabled: true
color: "#FFFF00" # Yellow
animated: false
- text: "!"
enabled: true
color: "#808080" # Gray
animated: false
- text: "\nYou are playing "
enabled: true
color: "#808080" # Gray
animated: false
- text: "HideAndSeek"
enabled: true
color-list: "title-colors" # Use color gradient
speed: "title-speed"
animated: true
- text: " on "
enabled: true
color: "#808080" # Gray
animated: false
- text: "{server-ip}"
enabled: true
color-list: "ip-colors" # Use color gradient
speed: "ip-speed"
animated: true
- text: "\n\n"
enabled: true
color: "#FFFFFF" # White
animated: false
# Footer configuration
footer:
# Footer elements
elements:
- text: "\nRole: "
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{role}"
enabled: true
color: "{role-color}"
- text: " | "
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{mode}"
enabled: true
color: "#008000" # Green
- text: "\nPlayers: "
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{players-total}"
enabled: true
color: "#FFFFFF" # White
- text: " ("
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{players-hiders}"
enabled: true
color: "#00AA00" # Green
- text: "|"
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{players-seekers}"
enabled: true
color: "#FF0000" # Red
- text: ")"
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "\nPoints: "
enabled: true
color: "#FFD700" # Gold
- text: "{points}"
enabled: true
color: "#FFD700" # Gold
- text: "\nCoins: "
enabled: true
color: "#FFFF00" # Yellow
- text: "{coins}"
enabled: true
color: "#FFFF00" # Yellow
- text: "\n"
enabled: true
color: "#FFFFFF" # White
scoreboard:
enabled: true
title:
text: "HideAndSeek"
small-caps: true
underline: true
colors:
gradient:
- "#FF0000" # Red
- "#FFFF00" # Yellow
animation:
enabled: true
speed: 0.15
formatting:
small-caps: true
padding: true
padding-amount: 3
lines:
- text: "Role:"
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{role}"
enabled: true
color: "#0000FF" # Blue
- text: "Mode:"
enabled: true
color: "#A9A9A9" # Dark Gray
- text: "{mode}"
enabled: true
color: "#008000" # Green
- text: "Players: {players-total} ({players-hiders}|{players-seekers})"
enabled: true
color: "#A9A9A9,#FFFFFF,#00FF00,#FF0000"
- text: "Points: {points}"
enabled: true
color: "#FFD700" # Gold
- text: "Coins: {coins}"
enabled: true
color: "#FFFF00" # Yellow
settings:
# Global disallowed blockstate properties for the appearance GUI
disallowed-blockstates:
- "waterlogged"
- "conditional"
seeker-break-blocks:
- "SHORT_GRASS"
- "TALL_GRASS"
- "SEAGRASS"
- "TALL_SEAGRASS"
block-interaction-exceptions:
- "*_DOOR"
- "*_FENCE_GATE"
- "*_TRAPDOOR"
- "*_BUTTON"
- "*_LEVER"
block-physics-exceptions:
- "*_DOOR"
- "*_FENCE_GATE"
- "*_TRAPDOOR"
- "*_BUTTON"
- "*_LEVER"
Overriding setting defaults
Any setting shown in the in-game GUI can have its default value overridden in config.yml under the settings: key.
For example:
settings:
game.mode: BLOCK
game.hiding-time: 90
game.seeking-time: 240
game.hiders.health: 10
anticheat.seeking.visibility-range: 16.0
loadout.hider-max-items: 4
loadout.hider-max-tokens: 14
hider-items.speed-boost.cooldown: 15
seeker-items.glowing-compass.cooldown: 30
points.hider.survival.amount: 10
perks.enabled: true
perks.perks-per-round: 3
A full list of available setting keys can be found in
SettingRegistrar.java.
Map Setup
Maps are defined in plugins/HideAndSeek/maps.yml. Each key is the internal map name and must match the name of a
world folder present on the server.
map1:
pretty-name: "Starter Valley"
description: "Default map"
author: "Server Admin"
size: "MEDIUM"
icon: "GRASS_BLOCK"
spawn-points:
- "0,65,0,0,0" # Format: x,y,z,yaw,pitch
world-borders: [] # Format: centerX,centerZ,size OR centerX,centerZ,r:radius
preferred-modes:
- "BLOCK"
seeker-break-blocks:
- "SHORT_GRASS"
- "TALL_GRASS"
block-interaction-exceptions:
- "*_DOOR"
- "*_FENCE_GATE"
- "*_TRAPDOOR"
- "*_BUTTON"
- "*_LEVER"
block-physics-exceptions:
- "*_DOOR"
- "*_FENCE_GATE"
- "*_TRAPDOOR"
- "*_BUTTON"
- "*_LEVER"
setting-overrides:
hider-items:
firework-rocket:
target-y: 64
players:
min: 4
recommended: 8
max: 16
seekers:
min: 1
per-players: 8
max: 4
timings:
hiding-time: 60
seeking-time: 300
vending-machine-locations: # Dropper blocks placed during seeking for the perk vending machine shop mode
- "12,64,-8"
- "-40,71,22"
allowed-blocks: # Used in BLOCK mode
- "STONE"
- "OAK_LOG[*]"
- "*CANDLE{RED_CANDLE}"
- "OAK_TRAPDOOR[half,open,facing]"
allowed-skins: # Used in SKIN mode; references keys defined in skins.yml
- "oak_log"
- "stone"
World Border Format
If spawn-point count equals world-border count, each spawn is matched to its corresponding border by index. Otherwise,
all spawns use the first border.
Block Pattern Syntax
The allowed-blocks list accepts a pattern DSL for flexible block selection:
| Pattern |
Meaning |
STONE |
Exactly the STONE material |
OAK_SLAB[type=bottom] |
Oak slab locked to a specific block state |
OAK_SLAB[*] |
Oak slab with any block state allowed |
*SLAB{OAK_SLAB} |
All slab variants, defaulting to Oak Slab |
*SLAB{OAK_SLAB}[type=bottom] |
All slab variants, default Oak Slab, locked block state |
#planks{OAK_PLANKS} |
All blocks in the planks Bukkit tag, default Oak Planks |
{STONE,GRANITE,DIORITE} |
Explicit custom material list |
Skin Setup
Custom skins for SKIN mode are defined in plugins/HideAndSeek/skins.yml:
oak_log:
name: "Oak Log"
icon: "minecraft:oak_log"
value: "<base64 skin texture value>"
signature: "<base64 skin texture signature>"
Skin textures can be generated using services such as Mineskin. Each skin entry must have a
valid signed value/signature pair.
Loadout System
Players configure their loadout in the lobby before each round. Each item has a rarity that determines its token cost.
| Rarity |
Default Token Cost |
| Common |
1 |
| Uncommon |
2 |
| Rare |
4 |
| Epic |
6 |
| Legendary |
10 |
By default, hiders have 12 tokens and up to 3 item slots. Seekers have 12 tokens and up to 4 item slots. All values are
configurable via the in-game settings GUI or under settings.loadout.* in config.yml.
Slot Preferences
Players can configure which item types (e.g. Mobility, Offense, Trap) are placed in which inventory slots, with a
fallback type per slot. This is accessible from the loadout GUI via the Slot Preferences button.
Admin Preset System
Admins can define up to 5 role presets per role (hider/seeker) in the Admin Loadout Manager GUI (/mg loadout admin).
Presets can be:
- Enabled/disabled per slot
- Forced: locks all players of that role to the specified preset
- Restricted: players may only choose from enabled admin presets rather than building their own loadout
Perk System
At the start of each seeking phase, a random pool of perks is selected (configurable count). Players spend their
accumulated round points in the perk shop to purchase perks.
Shop Modes
- Inventory: perk items are placed directly in the player's second hotbar row during the seeking phase.
- Vending Machine: dropper blocks are placed at positions defined in
maps.yml under vending-machine-locations.
Players interact with the dropper to open the shop.
Hider Perks
| Perk |
Description |
| Adaptive Speed |
Grants Speed when HP drops below a configurable threshold |
| Seeker Warning |
Displays a warning title and border pulse when a seeker approaches |
| Extra Life |
Earns absorption hearts proportional to points accumulated |
| Shadow Step |
Auto-teleports to a safe random location when HP drops critically |
| Camouflage |
Periodically cleanses negative status effects and glow |
| Double Jump |
Allows a mid-air second jump using the flight key |
| Trap Sense |
Highlights nearby traps with particles and a warning title |
Seeker Perks
| Perk |
Description |
| Death Zone |
Opens a map picker to draw a danger circle; hiders inside must escape or die |
| Random Swap |
Teleports the seeker to a random hider's position (and vice versa) |
| Map Teleport |
Opens a map picker to select a teleport destination, with a blindness landing |
| Relocate |
Forces every hider to move away from their current position or die |
| Elytra Rush |
Launches the seeker into a brief glide with a configurable launch boost |
| Proximity Meter |
Displays a hot/cold subtitle ping based on distance to the nearest hider |
| Scent Trail |
Renders a particle trail showing recent hider movement paths |
| Auto Aim |
Guides the Seeker's Blade toward nearby hiders on throw (passive) |
| Hit Display |
Shows the sword's projected flight curve while charging (passive) |
| Sword Bounce |
The thrown Seeker's Blade ricochets to additional hiders after each hit (passive) |
All perk costs, cooldowns, radii, durations, and other parameters are configurable via the settings GUI under the
perks.* sections.
Items Reference
Hider Items
| Item |
Rarity |
Without NMS |
Description |
| Firecracker |
Common |
Full |
Place a small exploding candle taunt for points |
| Cat Sound |
Common |
Full |
Play a loud cat sound to all online players |
| Random Block |
Common |
Full |
Reroll your disguise block (limited uses) |
| Speed Boost |
Common |
Full |
Gain a speed effect or velocity burst |
| Tracker Crossbow |
Common |
Full |
Shoot seekers to earn points and upgrade items |
| Knockback Stick |
Common |
Full |
Knock seekers away; upgrades when crossbow hits threshold |
| Firework Rocket |
Uncommon |
Full |
Launch a high-altitude firework taunt |
| Slowness Ball |
Uncommon |
Full |
Throw a projectile that slows seekers |
| Smoke Bomb |
Uncommon |
Full |
Throw a smoke cloud for visual cover |
| Block Swap |
Rare |
Full |
Swap block disguise with the nearest other hider |
| Big Firecracker |
Rare |
Full |
Large explosion with bouncing mini firecrackers |
| Medkit |
Rare |
Full |
Hold block to channel-heal; release early to cancel |
| Ghost Essence |
Rare |
Fallback |
Phase through walls briefly; falls back to limited behaviour without NMS |
| Remote Gateway |
Epic |
Full |
Place paired gateways that teleport between anchors until the round ends |
| Invisibility Cloak |
Epic |
Full |
Turn invisible for a configurable duration |
| Totem of Undying |
Legendary |
Full |
Activate a one-time revive window on death |
Seeker Items
| Item |
Rarity |
Without NMS |
Description |
| Grappling Hook |
Common |
Full |
Cast and reel in to launch yourself forward |
| Curse Spell |
Uncommon |
Full |
Empower your sword to curse hiders on hit |
| Chain Pull |
Uncommon |
Full |
Pull the hider in front of you to your position |
| Proximity Sensor |
Rare |
Full |
Place a sensor that glows hiders who walk into range |
| Ink Splash |
Rare |
Full |
Blind all hiders within a radius |
| Cage Trap |
Rare |
Full |
Place a hidden trap that cages and immobilises a hider |
| Phantom Viewer |
Rare |
Full |
Capture a rough map snapshot from a hider perspective |
| Block Randomizer |
Epic |
Full |
Force all hiders to immediately reroll their block |
| Glowing Compass |
Epic |
Full |
Reveal the nearest hider with a glow effect |
| Camera |
Epic |
Disabled |
Place up to 5 cameras and spectate through them |
| Lightning Freeze |
Legendary |
Fallback |
Freeze all hiders in place for a short duration |
| Seeker's Assistant |
Legendary |
Disabled |
Summon an AI hunting mob that tracks and shoots hiders |
Commands & Permissions
| Command |
Permission |
Description |
/mg loadout |
hideandseek.command.loadout |
Open the loadout selection GUI |
/mg loadout admin |
hideandseek.command.loadout.admin |
Open the admin loadout management GUI |
/mg map <name> |
hideandseek.command.map |
Set or view the current map |
/mg vote |
hideandseek.command.vote |
Open the map/gamemode/role voting GUI |
/mg ready |
hideandseek.command.ready |
Toggle your ready state in the lobby |
/mg skin |
hideandseek.command.skin |
Open the item skin shop |
/mg unstuck |
hideandseek.command.unstuck |
Teleport to your last safe position |
/mg stats [player] |
hideandseek.command.stats |
Open the stats GUI for yourself or another player |
/mg debug <subcommand> |
(op) |
Debug utilities (points, coins, skins, perks, config validation, YAML migration) |
Note: Full permission nodes and additional admin commands will be documented once MinigameFramework's command API
is finalized.
Role Permissions
The following permissions are assigned automatically during a round and can be used for other plugins or command guards:
| Permission |
Assigned to |
hideandseek.role.hider |
Players currently assigned as hiders |
hideandseek.role.seeker |
Players currently assigned as seekers |
hideandseek.role.spectator |
Players in spectator during an active round |
NMS Features
| Capability |
Behaviour without NMS |
| Client gamemode spoofing (appear in survival while in spectator) |
Ghost Essence falls back to limited behaviour |
| Mob pathfinding API |
Ghost Essence falls back; Seeker's Assistant is disabled |
| Client camera entity spoofing |
Camera item is disabled entirely |
| Client entity glowing packets |
Camera night-vision mode unavailable; Trap Sense glow disabled |
| Client entity spawning packets |
Camera item is disabled entirely |
| Client entity removal packets |
Camera item is disabled entirely |
| Client entity visibility packets |
Anti-cheat visibility filter falls back to server-side hide/show |
| Custom entity AI goals |
Seeker's Assistant is disabled entirely |
| Projectile entity raycast for hit detection |
Seeker's Blade throw falls back to vanilla raycast |
| Client lightning packet |
Lightning Freeze uses a server-side lightning bolt visible only to the target |
| Client fake world-border warning |
Adrenaline Rush and Seeker Warning perk border pulse are not shown |
| Per-player dialog registry (Netty packet injection) |
In-game quick-action dialog buttons not available |
| Spectator inventory Netty interception |
Spectator teleport GUI non-functional |
The NMS implementation currently targets Paper 1.21.10 (nms-v1_21_10) and Paper 1.21.11 (nms-v1_21_11).
Adding support for another version requires a new Gradle module implementing the NmsAdapter interface and providing an
NmsAdapterMeta that declares which Minecraft versions it supports.
评论 0
登录后参与评分
还没有评论,来抢沙发吧