GroovyScripts 是 HNCore 当前最适合服主直接上手的功能模块。你可以把它理解成：一套可以按需启用、按需组合的服务器功能脚本集合。

设计缘起

HNCore 中的 GroovyScripts 概念，我最早是在 LegendCore 中看到的，也正因为如此，才更坚定地把它带进 HN 系列里。我一直认为这是一种很好的设计：前置库不应该只停留在“被依赖”的层面，也可以主动提供一组可持续扩展的脚本能力，用来承接那些零散、碎片化、却又很常见的服务器需求。

对用户来说，这意味着 HN 系列不只是不断做“插件加法”，而是尽量把一些适合抽到前置层的能力沉淀下来，让大家的插件列表可以开始做减法，不必为了一个很小的需求再四处寻找单独插件。

也感谢 LegendCore 在这个方向上带来的启发。很多好设计本来就值得被看见、被继承、再结合新的场景继续打磨；如果 HNCore 的 GroovyScripts 也能让更多服主和开发者因此受益，那就是这份灵感最好的延续。

目录关系

• GroovyScripts/：脚本文件目录
• GroovyConfig/：脚本配置目录
• GroovyConfig/README.txt：默认脚本说明与快速参考

脚本与配置通常按同名对应，例如：

• KeepInventory.groovy
• KeepInventory.yml

需要注意的是，这两个目录名本身也来自 config.yml：

• feature-scripts.script-directory
• feature-scripts.config-directory

如果你改了目录名，排查时就不要再默认去找 GroovyScripts/ 和 GroovyConfig/。

一个脚本真正生效需要满足什么

一个脚本要真正生效，通常要同时满足下面三层条件：

1. feature-scripts.enabled = true
2. feature-scripts.groovy.enabled = true
3. 对应脚本配置里的 enabled = true

因此，“文件已经生成”不等于“脚本已经生效”。

当前内置脚本一览

世界保护

脚本	作用	关键配置
WorldProtect	按世界阻止破坏、放置、交互	worlds、prevent-break、prevent-place、prevent-interact
ExplosionProtect	阻止 TNT / 苦力怕爆炸破坏方块	prevent-tnt-block-damage、prevent-creeper-block-damage
NoFireSpread	阻止火焰蔓延、点燃扩散与方块被烧毁	prevent-ignite-spread、prevent-fire-spread、prevent-block-burn
NoRain	让指定世界始终保持晴天，不再下雨或打雷	worlds、clear-existing-weather、clear-weather-duration
NoWorldGrowth	暂停世界生长规则（植物、树叶、冰雪、铜氧化等）	blockGrowth、leavesDecay、iceSnowMelt、copperOxidation 等
NoWaterFlow	让水/岩浆停止流动	worlds、blockWater、blockLava

生物保护

脚本	作用	关键配置
EndermanProtect	阻止末影人搬起或放下方块	worlds
MobSpawnControl	按世界分别控制敌对 / 友好生物生成，默认只阻止敌对生物，并默认放行 MythicMobs 与命令 / 怪物蛋 / 工具箱召唤	block-hostile-mobs、block-friendly-mobs、allow-mythicmobs、allowed-spawn-reasons

玩家保护

脚本	作用	关键配置
KeepInventory	死亡保留背包，并控制等级、掉落物与经验	keep-level、clear-drops、dropped-exp
VoidProtect	玩家受到虚空伤害时取消伤害并拉回安全点	use-respawn-location、heal-to-max、reset-food
NoFallDamage	让玩家不再受到摔落伤害	worlds、bypass-permission、message-cooldown-ms
NoLavaDamage	不再受到岩浆/火焰伤害	worlds、cancelLavaDamage、cancelFireDamage、cancelFireTickDamage

物品保护

脚本	作用	关键配置
NoDrop	阻止玩家主动丢弃物品	worlds、bypass-permission、message
DurabilityProtect	阻止装备、工具、武器、盾牌、鞘翅损失耐久	protect-armor、protect-tools、protect-weapons

体验优化

脚本	作用	关键配置
AutoRespawn	玩家死亡后自动复活	message
NoHunger	固定玩家饥饿、饱和度与疲劳值	food-level、saturation、exhaustion、fill-on-join
PvpControl	按世界关闭玩家互伤，覆盖投射物、驯服生物与 TNT 来源伤害	bypass-permission、message
FixedTime	让指定世界时间固定不再流动	worlds、time、disable-daylight-cycle、update-interval-ticks
NoMiningExp	挖掘时不再掉落经验	worlds、blocks
ClearDroppedItems	周期清理指定世界掉落物，并提供手动清理命令	worlds、scheduled-cleanup.enabled、scheduled-cleanup.interval-ticks、command.aliases
NoDamageIndicator	移除原版 DAMAGE_INDICATOR 伤害提示粒子	worlds、warn-on-missing-protocollib
Elevator	跳跃或潜行在垂直方向快速移动到上下同类方块	elevatorBlocks、distance.min、distance.max、sound、particle

当前版本的脚本生命周期

HNCore 现在按统一生命周期加载脚本。

对脚本作者来说，最重要的是：

• 载入时会寻找 onGroovyRegister
• 卸载时会寻找 onGroovyUnregister
• 重载时会先注销旧脚本，再按当前配置重新注册

这意味着脚本已经不只是“执行一次就结束”的片段，而是 可以参与监听器注册、运行时状态创建与卸载清理 的完整功能模块。

如果你只是服主，不自己写脚本，可以把这理解成：/hncore reload scripts 现在会做更完整的装载 / 卸载同步。

常见工作流

第一步：找到要调整的功能

例如：

• 想固定饥饿值：看 NoHunger
• 想让玩家死亡不掉物：看 KeepInventory
• 想限制某些世界的交互与拆放：看 WorldProtect
• 想保留爆炸表现但不炸坏方块：看 ExplosionProtect
• 想死亡后自动回到流程：看 AutoRespawn
• 想防止末影人搬运方块：看 EndermanProtect
• 想让装备和工具不掉耐久：看 DurabilityProtect
• 想避免玩家掉进虚空后直接死亡：看 VoidProtect
• 想在大厅或主城关闭玩家互伤：看 PvpControl
• 想按世界控制敌对 / 友好生物生成：看 MobSpawnControl
• 想阻止玩家乱丢物品：看 NoDrop
• 想防止火势扩散或烧毁建筑：看 NoFireSpread
• 想让展示世界不再下雨：看 NoRain
• 想让跑酷或大厅免摔伤：看 NoFallDamage
• 想把某些世界固定在白天或黑夜：看 FixedTime
• 想定时回收地面掉落物：看 ClearDroppedItems
• 想让战斗画面减少原版伤害粒子干扰：看 NoDamageIndicator
• 想让挖矿不掉经验：看 NoMiningExp
• 想暂停世界生长（植物、树叶、冰雪等）：看 NoWorldGrowth
• 想让水或岩浆停止流动：看 NoWaterFlow
• 想让玩家不受岩浆伤害：看 NoLavaDamage
• 想实现简易电梯功能：看 Elevator

第二步：修改对应配置文件

到脚本配置目录中打开对应 yml，把 enabled 改为 true，并按需要细调世界、消息或功能参数。

第三步：执行重载

/hncore reload scripts

第四步：确认最终结果

/hncore scripts enabled

文件存在但功能没生效，通常说明什么？

最常见的是下面两种情况：

1. 脚本系统总开关没开
2. 脚本自己的 enabled 没开

所以排查时建议总是按这个顺序看：

/hncore scripts list
/hncore scripts enabled

删除脚本文件和 enabled: false 的区别

enabled: false

• 脚本仍保留在目录中
• 方便日后再次开启
• 更适合日常运维

删除脚本文件

• 服务端不会再加载该脚本
• 执行 reload scripts 后会停止对应脚本
• 适合你明确不再需要这个脚本时

如果你只是“暂时不用”，通常更推荐改 enabled: false。

补充提醒

• ClearDroppedItems 适合做地面掉落物保洁，也适合给管理组保留手动清理入口
• NoDamageIndicator 依赖 ProtocolLib，如果服务器没装 ProtocolLib，这个脚本会跳过注册

继续阅读

• 想先直接上手：看 快速开始
• 想理解脚本系统开关：看 config.yml 配置说明
• 想理解脚本级重载和核心重载的区别：看 命令说明
• 想排查为什么脚本没生效：看 常见问题