适用源码：
fd73c2ee0dac31c7b7a96560623207e15046cd1c。本页记录当前实现与扩展边界。
结构
com.flrv.logic.war 按职责分层：核心会话（core）、类型（type）、阵营组合（side）、目标（objective）、规则（rule）、积分（score）、大厅与持久化（lobby/negotiation/service）。战争类型、胜利目标、阵营组成、敌我标记和积分板互相独立，新增玩法不需要把规则写进控制器。
规则配置
分别编辑 war/TownBattle.yml 与 war/NationWar.yml 的 WAR.rule。每个类型文件还包含 WAR.warname（必须与类型标识一致）、WAR.description、WAR.sides.attacker/defender（TOWN 或 NATION）。当前 TownBattle 支持城镇对城镇，NationWar 支持国家对国家；配置为混合类型时明确拒绝开战。
宣战条件放在 WAR.declaration：玩家大厅总是走双方领导确认；require-both-sides 默认 false，开启时管理员旧命令也须改走申请；request-expire-seconds 控制持久化申请的有效期。开战损耗放在 WAR.start-cost：enabled 默认 false，启用损耗时大厅和管理员命令都会拒绝开战，不会无声跳过。
核心概念
| 组件 | 职责 |
|---|---|
WarType |
类型 ID、TOWN/NATION 范围、权限规则、生命周期、目标与阵营组成器 |
WarObjective |
解析目标、初始血量、失败判定、目标校验 |
WarSideComposer |
把命令参数解析成 SideSelection |
WarService |
战争会话、血量、伤害、结束事件和城镇/中心索引 |
WarRelation |
FRIENDLY / ALLY / ENEMY / NEUTRAL |
TownWarController |
命令入口、异步中心校验、开战/停止、通知 |
WarMarkerService |
每个观察者视角的 TextDisplay 标记；默认不发光 |
阵营与关系
WarService.Side 区分 coreTownIds（核心友军）、alliedTownIds（盟友）和敌对阵营。彩色关系由头顶 TextDisplay 标记承担，标记实体默认不可见，通过 Player#showEntity/hideEntity 按观察者显示，并设置 seeThrough。
TownBattle 的核心为命令指定的城镇，严格 1v1；NationWar 的核心为本国所有成员城镇，盟友为直接盟友国家的城镇。国家战盟友可通过 WAR.include-allies 关闭。盟友同时与双方结盟、与本国为敌或已在其他战争中时，会保持中立或被跳过。
积分板
积分为右侧 sidebar，通过 PacketWarSidebar 的 Mojang 映射数据包适配器渲染，不调用 Folia 不支持的 getNewScoreboard()；服务器版本不兼容时记录明确错误，不退回 ActionBar。
WarScore：战争 ID、类型、双方名称、当前/最大血量。WarScoreboard：update(Player, WarScore)/hide(Player)。WarScores：从WarService.Snapshot与WarService.Side生成快照。PacketWarSidebar：按观察者发送 sidebar 数据包。NoopWarScoreboard：禁用渲染时的空实现。
领地快照与恢复
压缩的整领地快照保存在 war_terrain_plots，批次在 war_terrain_batches，状态为 PREPARING、ACTIVE、RESTORING。战斗中不生成逐方块日志。结束、取消或停服均转入恢复；启动时对上一进程的 ACTIVE/RESTORING 批次继续恢复，PREPARING 批次只清理而不回滚。
实际地形复原调用 Towny 的 PlotBlockData.restoreNextBlock()。每个领地在所属区域线程逐 tick 调用，恢复期间持有区块 ticket，最多并行处理四块领地，每 tick 每块最多调用 128 次。快照仅包含方块数据字符串，不读取或保存容器库存及其他方块实体 NBT。
数据模型
当前约束：每方一个 WarTarget、每方一个血量、defeatedTown 返回一个目标城镇。单目标接口保持稳定，新类型可以只实现自己的 WarObjective。
扩展方式
WarType.rules() 返回默认 rule.WarRules，可覆盖的单场规则在开战时冻结；战前快照及战后恢复固定启用。TemporaryDestructionRule 只判断安全破坏范围并执行无掉落破坏；WarPermissionPolicy 判断阵营与领地。扩展调用底层 WarService.start 前必须先通过 WarTerrainRestoration.prepare 完成双方快照，否则发布守卫拒绝开战。
运维与兼容
TestWar已移除，统一为TownBattle。- 战争不持久化，类型改名不影响重启后的活动战争。
- 旧
test_war_blocks、war_plot_snapshots仅用于一次性数据迁移。 - 战争目标未配置时，
WarService.start和命令都会拒绝开战。
来源
docs/war-architecture.md；代码根 folia_plugin/src/main/java/com/flrv/：logic/war/、event/war/、ui/war/、infrastructure/persistence/war/。