战斗切换

战斗切换

一个服务器可安装的PvP选择加入系统，包含战斗标记、智能冷却时间和完整的管理工具包——适用于Minecraft 1.19.2 Forge。

战斗切换让服务器上的每位玩家都能选择自己是否能被攻击。这是一个即装即用的模组包解决方案，解决“有些玩家想玩PvP，有些不想”的问题——无需世界边界变通方法、无需区域插件、无需第三方依赖。将其安装在你的专用服务器上，原版客户端即可加入并使用/ct命令，无需修改他们的游戏。

---

功能概述

• 和平模式 — PvP关闭。其他玩家的箭矢、剑、药水和投射物会无效穿过。
• 战斗模式 — PvP开启。你可以被攻击，也可以反击。
• 每位玩家独立决定。默认是和平模式——新玩家必须主动选择加入。
• 服务器可安装。原版客户端可以加入并使用/ct命令切换模式，无需安装客户端。安装了模组的客户端还可以额外获得可重新绑定的V键位和屏幕HUD指示器。

---

特性

核心功能

• 通用命令。/ct、/combat、/peace和/combattoggle status可在任何客户端（模组版或原版）上使用。
• 一键切换。默认键位：V（仅限安装了模组的客户端）。每位客户端可完全重新绑定。
• 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 <player>	检查其他玩家的状态。
/combattoggle set <player> <peace|combat> [bypass]	强制设置模式。bypass=true可覆盖冷却时间和标记限制。
/combattoggle tag <player> [seconds]	手动应用战斗标记（1–3600秒）。
/combattoggle untag <player>	清除战斗标记。
/combattoggle resetcooldown <player>	清除切换和PvP冷却时间。
/combattoggle resync	刷新计分板队伍并重新同步所有在线玩家的HUD状态（/combattoggle reload 为其别名）。

面向服务器所有者与模组包作者

• 基于能力的状态。玩家数据存储在Forge能力（Capability）上（CombatToggleData）；玩家整个会话期间使用同一内存实例，无每次调用的NBT写入。目前没有公共API，但未来的次要版本可以公开它，而无需重新架构。
• 结构化的SLF4J日志记录，针对每个PvP决策、切换请求和命令调用，提供DEBUG/INFO级别日志。与运维流程配合良好。
• 翻译驱动的消息。每个面向玩家的字符串都是一个翻译键（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命令，无需任何客户端安装。额外在客户端安装了模组的玩家，可在此基础上获得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.1.x升级

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

---

兼容性

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

---

已知限制

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

---

许可与源码

• 许可： GPL-3.0
• 源码与问题： https://github.com/otectus/combat-toggle
• 模组包主页： 为Runecraft 1.19.2 Forge模组包构建。也可将其放入任何其他模组包——它是独立运行的。

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