战斗切换

战斗切换

一款服务端可安装的PVP自愿加入系统，包含战斗标记、智能冷却和完整管理工具——适用于Minecraft 1.19.2 Forge。

战斗切换让服务器上的每位玩家都能自主选择是否可被攻击。对于“有些玩家想要PVP，有些不想”的问题，这是一个开箱即用的整合包解决方案——无需世界边界变通方案、无需区域插件、无需第三方依赖。安装在你的专用服务器上，原版客户端无需改动即可加入并使用/ct命令。

---

功能简介

• 和平模式 — 关闭PVP。其他玩家的箭矢、剑、药水和投掷物都会无害穿过。
• 战斗模式 — 开启PVP。你可以被攻击，也可以反击。
• 每位玩家独立决定。默认为和平——新玩家必须主动加入。
• 服务端可安装。 原版客户端可以加入并使用/ct切换模式，无需安装客户端。装有mod的客户端额外获得可改键的V键位和屏幕HUD指示器。

---

特性

核心功能

• 通用命令。 /ct、/combat、/peace和/combattoggle status可在任何客户端使用——无论是modded还是vanilla。
• 一键切换。 默认键位：V（仅限mod客户端）。每位客户端可完全自定义按键。
• HUD覆盖层。 51×19像素的像素风图标（和平为盾牌，战斗为交叉剑）。可配置位置（9锚点+自定义XY）、缩放和按模式显示。在物品栏和通过F1关闭HUD时自动隐藏。
• 战斗标记。 任何PVP对抗都会标记攻击者和受害者，持续可配置的时长（默认30秒）。被标记时，玩家无法切换到和平模式——无法通过切换来逃避战斗。
• 智能冷却。 默认情况下，冷却仅在PVP实际发生时开始，而不是玩家切换时。玩家在种田、建造或探索时可以自由切换模式。
• 持久化状态。 模式、标记计时器和冷却在退出登录、重生、跨维度传送和服务器重启后都得以保留。数据存储在序列化到玩家数据的Forge能力（Capability）上。
• 双重事件PVP执行。 主要取消在LivingAttackEvent（高优先级）——击退、受伤音效和PLAYER_HURT_ENTITY进度标准永远不会在和平目标上触发。LivingHurtEvent作为纵深防御。攻击者解析会追溯弹射物所有者、已点燃TNT所有者和驯服宠物，因此狼、雪傀儡和点燃的TNT都能被正确归属。

社交功能

• 名牌颜色。 战斗模式玩家显示红色名牌；和平模式玩家显示蓝色。如果你已经将记分板队伍用于其他用途，可禁用此功能。
• 表情/文本前缀。 可配置的符号（默认：交叉剑和咖啡杯）会出现在玩家名字前，从任何角度都能一目了然地看出状态。
• 限频反馈。 攻击和平目标时，攻击者会收到一行聊天消息，解释为什么没有任何效果（带限频，绝不会刷屏）。

玩家命令

无需权限。

命令	用途
/ct	切换战斗↔和平。
/combat	将自身设置为战斗模式。
/peace	将自身设置为和平模式。
/combattoggle status	显示自身的模式、标记和冷却。
/combattoggle help	列出你可以运行的所有命令（非管理员隐藏管理条目）。

管理命令

需要OP等级2。

命令	用途
/combattoggle get <玩家>	检查另一名玩家的状态。
/combattoggle set <玩家> <peace|combat> [bypass]	强制设置模式。bypass=true覆盖冷却和标记保护。
/combattoggle tag <玩家> [秒数]	手动施加战斗标记（1–3600秒）。
/combattoggle untag <玩家>	清除战斗标记。
/combattoggle resetcooldown <玩家>	清除切换和PVP冷却。
/combattoggle resync	刷新所有在线玩家的记分板队伍并重新同步HUD状态（/combattoggle reload是别名）。

服务器/整合包信息

• 基于能力的状态存储。 玩家数据存储在Forge能力（CombatToggleData）上；同一内存实例在整个玩家会话期间有效，无每调用NBT读写。目前没有公共API，但未来的次要版本可以无需重构架构即可暴露一个。
• 结构化的SLF4J日志记录，在DEBUG/INFO级别记录每个PVP决策、切换请求和命令调用。与运维流水线配合良好。
• 翻译驱动的消息。 每个面向玩家的字符串都是翻译键（combattoggle.msg.*）。无需代码补丁即可发布翻译。
• 兼容原版的网络握手。 频道使用NetworkRegistry.acceptMissingOr(PROTOCOL::equals)；原版客户端可以正常通过，同步数据包会静默丢弃给没有该频道的对端。

---

安装

1. 为Minecraft 1.19.2安装Minecraft Forge 43.3.0+。
2. 将combattoggle-1.2.0.jar放入服务器（或客户端）的mods/文件夹。
3. 启动。首次运行时，会在世界的serverconfig/目录生成combattoggle-server.toml，在客户端配置文件夹生成combattoggle-client.toml。

服务端可安装？ 是的。仅安装在专用服务器上，原版客户端即可加入并使用/ct、/combat、/peace和/combattoggle status，无需客户端安装。额外安装了客户端mod的玩家还能获得V键位和HUD指示器——在相同的服务器权威逻辑之上增加了视觉点缀。

---

配置

• combattoggle-server.toml

键	默认值	作用
cooldownSeconds	600	冷却时长（10分钟）。设为0完全禁用冷却。
combatTagSeconds	30	PVP事件后战斗标记持续的时间。
requireBothCombatEnabled	true	如果为true，仅当攻击者和目标都处于战斗模式时PVP才生效。
forceCombatWhileTagged	true	强制被标记玩家进入战斗模式。
allowToggleWhileTagged	false	如果为false，被战斗标记的玩家无法切换到和平模式。
cooldownTriggersOnPvp	true	玩家造成或受到PVP伤害时开始冷却。
cooldownTriggersOnToggle	false	玩家切换时开始冷却。
cooldownAppliesToPeaceOnly	true	冷却仅阻止战斗→和平切换；和平→战斗始终即时生效。
allowAdminBypassCooldown	true	/combattoggle set上的bypass=true实际生效。
useScoreboardTeams	true	禁用后完全不让战斗切换使用记分板。
useEmojiPrefixes / useNameplateColors	true / true	两种视觉效果的独立开关。
combatEmoji / peaceEmoji	⚔ / ☕	任意BMP Unicode字符。
combatTeamName / peaceTeamName	ct_combat / ct_peace	重命名以避免冲突。

• combattoggle-client.toml

键	默认值	作用
hudEnabled	true	HUD图标的總开关。
hudShowInCombatMode	true	在战斗模式下显示图标。
hudShowInPeaceMode	true	在和平模式下显示图标。
hudAnchor	TOP_CENTER	以下之一：TOP_LEFT、TOP_CENTER、TOP_RIGHT、CENTER_LEFT、CENTER、CENTER_RIGHT、BOTTOM_LEFT、BOTTOM_CENTER、BOTTOM_RIGHT、CUSTOM。
hudOffsetX	0	从锚点向内的像素偏移。如果hudAnchor=CUSTOM则为绝对屏幕X坐标。
hudOffsetY	6	从锚点向内的像素偏移。如果hudAnchor=CUSTOM则为绝对屏幕Y坐标。
hudScale	1.0	范围0.5–3.0。
hudShowTimers	true	在图标下方显示标记/冷却倒计时文本。

---

升级

• 模式会保留。 每位玩家上次所处的模式（战斗或和平）会在首次登录1.2.0时延续。
• 进行中的标记和冷却在首次登录1.2.0时重置。 1.1.x的持久化计时器使用挂钟毫秒，且没有时钟源保证；转换为新的游戏刻时钟不安全，因此会被丢弃。从1.2.0开始，新的标记/冷却使用单调、重启安全的游戏刻截止时间。
• showHud服务器配置键已移除。 HUD可见性现在完全由客户端侧通过combattoggle-client.toml中的hudEnabled控制。现有管理员配置在首次读取时会保留孤立键；Forge会记录未使用键警告。无害。
• 网络协议为"1"，适用于1.2.x系列。 1.1.x mod客户端无法连接到1.2.0服务器（握手拒绝）；他们需要升级。原版客户端不受影响。

---

兼容性

• Minecraft： 1.19.2
• Forge： 43.3.0或更新
• Java： 17
• 依赖： 无。不需要Kotlin、Architectury或Cloth Config。
• 其他PVP模组： 应与反作弊、区域保护和KubeJS共存。useScoreboardTeams=false可解决与占用记分板的mod的冲突。
• 仅限多人游戏？ 否。单人游戏可用；切换仍然适用于与敌对铁傀儡等的伤害交互（正如你对“启用/禁用PVP”的预期）。

---

已知限制

• 基于Mixin的伤害来源可能绕过强制检测。 战斗切换在LivingAttackEvent（主要）和LivingHurtEvent（备用）上都进行取消。少数mod通过自定义Mixin绕过两者来传输伤害——这些会命中和平目标。如果遇到此问题，请附带可复现的步骤提交issue。
• 无维度白名单。 PVP规则在所有维度中统一适用。
• /combat和/peace是常见的字面量命名空间。 如果另一个mod或插件注册了相同的根命令，行为取决于注册顺序——请改用/ct和/combattoggle <子命令>。
• 目前没有公共mod集成API。 玩家状态存储在内部Forge能力上；未来的次要版本可以无需重构架构即可暴露。
• 原版客户端没有HUD或键位。 请使用/ct。这是设计使然。

---

许可证与源码

• 许可证： GPL-3.0
• 源码与问题跟踪： https://github.com/otectus/combat-toggle
• 整合包归属： 为Runecraft 1.19.2 Forge整合包而构建。可放到任何其他整合包中——它是独立的。

欢迎提交拉取请求和错误报告。提交issue时请附上服务器日志、你的combattoggle-server.toml和最小复现步骤。