适用源码：fd73c2ee0dac31c7b7a96560623207e15046cd1c。本页描述当前实现，默认配置不等于实服配置。

入口

城镇大厅管理 → 第二行中央「大厅领域效果」。镇长或 Towny 管理员可以配置；普通居民不能花费公库资金。效果仅在该城镇的 Towny 领地内对玩家生效，不影响地块产权、居民身份或国家关系。

配置

插件首次启动生成 town-hall-buffs.yml。buffs 是完整 Buff 目录，正面、负面效果不分组；目录存在不等于已经解锁。每项 buffid 是稳定引用 ID（读取时统一为大写），effect 是对应原版效果名，可以与 buffid 不同，也允许多个不同 ID 对应同种效果。不要随意更换已经使用的 ID。

列表每页 18 种，超过后自动分页，未解锁显示灰色。原版效果使用大写名称，所有 Buff 固定为 I 级，仅选择类型。max-active-effects 控制同时启用数量，default-cost-per-period 为默认周期价格，每项 cost-per-period 可覆盖价格。新出现的服务端原版持续效果会自动补入配置文件，使用固定 I 级和默认价格，但不会自动解锁；瞬时治疗/伤害不属于持续状态。

unlocks.initial 列出初始解锁的 buffid，默认 SPEED、HASTE、SLOWNESS。unlocks.hall-levels 按城镇大厅设施等级列出该等级新增的 buffid，累计合并而不替换已有列表；默认 2 级 RESISTANCE、WEAKNESS，3 级 REGENERATION、MINING_FATIGUE，4 级 STRENGTH、BLINDNESS。这不是 Towny 按居民数计算的城镇等级。不在任何默认解锁列表中的 Buff（如中毒、凋零）当前不会解锁。未知 ID、重复 ID 及无效引用会在加载时报告。

操作

大厅界面第一行显示已选 Buff，点击移除；第二行同列单独切换该 Buff 的作用目标；第三行放状态与翻页；第四、五行每页 18 项可选 Buff，点击选择类型，重复点击已选类型不会升级；最底行放启动、停止及其他管理操作。先关闭才能修改效果类型、目标或模式。选好后点击启用，核对周期价格后确认。

费用是所有已选效果的 cost-per-period 之和，与领地内玩家数量无关，无玩家时持续启用仍计费。

作用目标

• OWN_TOWN：只影响本镇居民，不推断同国或盟友关系。
• ALL：影响领地内所有玩家，包括外镇和无城镇玩家。

负面效果的解锁不会自动识别敌军，ALL 目标会影响己方及访客。

模式

ALWAYS 持续生效；WAR_ONLY 仅在本镇参加战争时续加和购买新周期，和平时暂停。大厅必须放置完成、运行中、核心完整、归属有效且所在区块加载。核心损坏或卸载时暂停，不强制加载区块；已买周期按自然时间到期。

费用与持久化

默认每 60 秒先扣城镇公库，扣款成功且持久提交后才施加该周期效果。仅打开启用开关不会授予效果，扣款失败或结果不确定也不会授予效果。药水刷新时长不超过当前已付周期剩余时间，避免续费失败后仍由本模块续加免费效果。公库不足自动关闭，补足后手动重新启用。关闭不退款，同一配置重新启用可使用原周期剩余时间；修改配置会使原周期失效。停服不补扣离线时间，重启保留配置和已买周期，离线到期只购买一个新周期。单价配置为 0 表示服主明确允许免费效果。

外部公库扣款前先持久提交意图；结果不确定时停止生效，不自动重扣。OP 在大厅界面可选择“已确认扣款成功”或“已确认未扣款”，核对公库记录后通过确认弹窗解除检查点。成功核对保留原有截止时间，不额外赠送时长；核对后仍须手动启用。

效果和线程

周期以墙钟时间结算。玩家每秒在其实体线程检测领地并刷新 3 秒效果；离开、关闭或停战后最多约 3 秒自然消退。不主动移除原有效果，也不覆盖其他来源更强或超过 3 秒的长时效果。旁观者和死亡玩家不生效。设施完整性只在核心所属区域检查，公库结算串行执行。

旧配置迁移

旧 levels 或平铺 effects 配置会先备份成 town-hall-buffs.yml.catalogue-backup-<时间戳>，再转成 buffs 目录；同名效果采用原最高档配置，保留自定义名称及价格，删除 Buff 强度配置，同时效果上限取旧配置的最大值。旧选择和已付周期不会重置或重复扣费；若旧选择不满足新的解锁规则，会停止生效和续费。

来源

docs/town-hall-buffs.md、folia_plugin/src/main/resources/town-hall-buffs.yml；代码根 folia_plugin/src/main/java/com/flrv/：logic/townbuff/、infrastructure/persistence/facility/TownBuffRepository.java。