Combat Toggle
适用于 Minecraft 1.19.2 Forge 的服务端 PvP 可选加入系统,具备战斗标记、智能冷却和完整的管理员工具包。
Combat Toggle 允许服务器上的每位玩家选择自己是否可以被攻击。这是一个“即装即用”的整合包解决方案,用于解决“部分玩家想要 PvP,部分玩家不想要”的问题——无需世界边界(world-border)变通方案,无需区域插件,无需第三方依赖。将其安装到专用服务器上,原版客户端即可加入并使用 /ct 命令,无需任何客户端模组。
功能介绍
- 和平模式(Peace mode) — PvP 关闭。其他玩家的箭矢、剑、药水和投射物将无法造成伤害。
- 战斗模式(Combat mode) — PvP 开启。你可以受到攻击,也可以反击。
- 每位玩家独立决定。默认为和平模式——新玩家必须主动选择加入战斗。
- 服务端安装即可。 原版客户端可以加入并使用
/ct 切换模式,无需安装任何客户端模组。模组客户端额外获得一个可重新绑定的 V 键绑定以及屏幕上的 HUD 指示器。
特性
核心功能
- 通用命令。
/ct、/combat、/peace 和 /combattoggle status 在任何客户端(模组或原版)中均可使用。
- 一键切换。 默认键位:
V(仅限模组客户端)。支持按客户端自定义重新绑定。
- HUD 叠加层。 51×19 像素艺术图标(和平模式为盾牌,战斗模式为交叉的双剑)。可配置位置(9点锚定 + 自定义 XY)、缩放比例以及各模式的可见性。在打开物品栏时自动隐藏,并在按下
F1 隐藏 HUD 时隐藏。
- 战斗标记(Combat tagging)。 任何 PvP 交战都会给攻击者和受害者打上持续时间的标记(默认 30 秒)。在被标记期间,玩家无法切换到和平模式——防止通过切换模式进行“战斗逃跑”。
- 智能冷却。 默认情况下,冷却仅在 PvP 实际发生时才开始计算,而不是在玩家切换模式时开始。玩家在刷怪、建造或探索时可以自由切换模式。
- 状态持久化。 模式、标记计时器和冷却时间会在登出、重生、维度变更和服务端重启后保留。存储在序列化到玩家数据的 Forge capability 中。
- 双重事件 PvP 执行。 在
LivingAttackEvent(高优先级)进行主要取消——和平目标不会触发击退、受伤音效以及 PLAYER_HURT_ENTITY 进度判定。LivingHurtEvent 作为纵深防御运行。攻击者解析会遍历投射物所有者、引燃 TNT 所有者和驯服宠物,因此狼、雪傀儡和被引燃的 TNT 会被正确归因于攻击者。
社交功能
- 名字标签着色。 处于战斗模式的玩家显示红色名字标签;和平玩家显示蓝色。如果你已经使用计分板队伍处理其他事务,可以禁用此功能。
- Emoji/文本前缀。 配置文件中的符号(默认:交叉双剑和咖啡杯)出现在玩家名字之前,以便从任何角度都能明确识别其状态。
- 节流反馈。 击中和平模式目标的攻击者会收到一条单行聊天消息,解释为什么没有发生任何事情(已进行节流处理,避免刷屏)。
玩家命令
无需权限。
| 命令 |
用途 |
/ct |
切换战斗模式 ↔ 和平模式。 |
/combat |
将自己设置为战斗模式。 |
/peace |
将自己设置为和平模式。 |
/combattoggle status |
显示你自己的模式、标记和冷却时间。 |
/combattoggle help |
列出所有你可以运行的命令(非 OP 用户隐藏管理员条目)。 |
管理员命令
需要 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 是其别名)。 |
服务器/整合包信息
- 基于 Capability 的状态管理。 玩家数据存储在 Forge 的 Capability(
CombatToggleData)中;整个会话期间使用相同的内存实例,避免了每次调用都产生 NBT 读写开销。目前暂无公开 API,但未来的小版本更新可以在不重构架构的前提下暴露 API。
- 结构化的 SLF4J 日志记录。 针对每一次 PvP 决策、切换请求和命令执行,均在 DEBUG/INFO 级别记录日志。与运维流水线完美兼容。
- 基于翻译的消息系统。 所有面向玩家的字符串均为翻译键(
combattoggle.msg.*)。无需修改代码即可发布翻译内容。
- 兼容原版网络握手。 频道使用
NetworkRegistry.acceptMissingOr(PROTOCOL::equals);原版客户端可正常通过,同步数据包会被静默丢弃给未安装该频道的对端。
安装方法
- 为 Minecraft 1.19.2 安装 Minecraft Forge 43.3.0+。
- 将
combattoggle-1.2.0.jar 放入服务器(或客户端)的 mods/ 文件夹中。
- 启动游戏。首次运行时,会在世界的
serverconfig/ 目录下生成 combattoggle-server.toml,并在客户端配置文件夹中生成 combattoggle-client.toml。
是否支持仅服务端安装? 是的。仅在专用服务器上安装,原版客户端即可加入并使用 /ct、/combat、/peace 和 /combattoggle status 命令,无需在客户端安装模组。如果玩家在客户端也安装了该模组,则会获得 V 键绑定以及顶部的 HUD 指示器——这只是覆盖在相同服务端权威逻辑之上的视觉装饰。
配置
| Key |
默认值 |
作用 |
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 |
将其设为 false 可将战斗切换完全排除在记分板之外。 |
useEmojiPrefixes / useNameplateColors |
true / true |
分别控制两种视觉效果(前缀表情符号和名字标签颜色)的独立开关。 |
combatEmoji / peaceEmoji |
⚔ / ☕ |
任何 BMP Unicode 字符均可。 |
combatTeamName / peaceTeamName |
ct_combat / ct_peace |
可重命名以避免冲突。 |
| Key |
默认值 |
作用 |
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 开始的新标签/冷却时间使用单调递增、重启安全的 game-tick 截止时间。
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 的伤害来源可能绕过强制执行。 Combat Toggle 在
LivingAttackEvent(主要)和 LivingHurtEvent(备用)处均进行取消。少数模组通过自定义 mixin 路由伤害,从而绕过 两者 —— 这些伤害将作用于和平模式目标。如果遇到此情况,请提交包含复现步骤的 Issue。
- 无维度白名单。 PvP 规则在所有维度中统一适用。
/combat 和 /peace 是常见的字面命名空间。 如果另一个模组或插件注册了相同的根命令,行为取决于注册顺序——请回退到 /ct 和 /combattoggle <subcmd>。
- 目前尚无公开的模组集成 API。 玩家状态存储在内部的 Forge capability 上;未来的小版本可以在不重新架构的情况下暴露它。
- 原版客户端没有 HUD 或快捷键。 请使用
/ct。这是设计如此。
许可与源码
- 许可证: GPL-3.0
- 源码与问题反馈:
- 整合包主页: 专为 Runecraft 1.19.2 Forge 整合包构建。可放入任何其他整合包——它是独立运行的。
欢迎提交 Pull Request 和 Bug 报告。提交 Issue 时请附上服务器日志、你的 combattoggle-server.toml 以及最小化的复现环境。
Combat Toggle
A server-installable PvP opt-in system with combat tagging, smart cooldowns, and a full admin toolkit — for Minecraft 1.19.2 Forge.
Combat Toggle lets every player on your server choose whether they can be attacked. It's a ship-it-on-a-modpack solution for the "some players want PvP, some don't" problem — no world-border workarounds, no region plugins, no third-party dependencies. Install it on your dedicated server and vanilla clients can join and use /ct without touching their game.
What it does
- Peace mode — PvP is off. Other players' arrows, swords, potions, and projectiles pass harmlessly.
- Combat mode — PvP is on. You can be hit, and you can hit back.
- Each player decides independently. The default is Peace — new players must opt in.
- Server-installable. Vanilla clients can join and use
/ct to flip modes with no client install. Modded clients additionally get a rebindable V keybind and an on-screen HUD indicator.
Features
Core
- Universal commands.
/ct, /combat, /peace, and /combattoggle status work from any client — modded or vanilla.
- One-key toggle. Default keybind:
V (modded clients only). Fully rebindable per-client.
- HUD overlay. 51×19 pixel-art icon (shield for Peace, crossed swords for Combat). Configurable position (9-anchor + custom XY), scale, and per-mode visibility. Hides automatically in inventories and when the HUD is toggled off with
F1.
- Combat tagging. Any PvP engagement tags both attacker and victim for a configurable duration (default 30s). While tagged, a player cannot switch to Peace mode — no combat-logging via the toggle.
- Smart cooldowns. By default, the cooldown starts only when PvP actually happens, not when players toggle. Players can freely switch modes while farming, building, or exploring.
- Persistent state. Mode, tag timer, and cooldown survive logouts, respawns, dimension changes, and server restarts. Stored on a Forge capability serialized to player data.
- Dual-event PvP enforcement. Primary cancel at
LivingAttackEvent (HIGH priority) — knockback, hurt sound, and the PLAYER_HURT_ENTITY advancement criterion never fire on Peace targets. LivingHurtEvent runs as defence-in-depth. Attacker resolution walks projectile owners, primed-TNT owners, and tamed pets, so wolves, snow golems, and ignited TNT are correctly attributed.
Social
- Nameplate coloring. Players in Combat mode get red nameplates; Peace players get blue. Disable if you already use scoreboard teams for something else.
- Emoji/text prefixes. Configurable glyphs (defaults: crossed swords and a coffee mug) appear before the player name so the state is unmistakable from any angle.
- Throttled feedback. Attackers who hit a peace-mode target get a one-line chat message explaining why nothing happened (throttled so it never spams).
Player commands
No permissions required.
| Command |
Purpose |
/ct |
Toggle Combat ↔ Peace. |
/combat |
Set yourself to Combat mode. |
/peace |
Set yourself to Peace mode. |
/combattoggle status |
Show your own mode, tag, and cooldown. |
/combattoggle help |
List every command you can run (admin entries hidden for non-OP). |
Admin commands
Require OP level 2.
| Command |
Purpose |
/combattoggle get &amp;lt;player&amp;gt; |
Inspect another player's state. |
/combattoggle set &amp;lt;player&amp;gt; &amp;lt;peace|combat&amp;gt; [bypass] |
Force a mode. bypass=true overrides cooldown + tag guard. |
/combattoggle tag &amp;lt;player&amp;gt; [seconds] |
Apply a combat tag manually (1–3600s). |
/combattoggle untag &amp;lt;player&amp;gt; |
Clear a combat tag. |
/combattoggle resetcooldown &amp;lt;player&amp;gt; |
Clear both toggle and PvP cooldowns. |
/combattoggle resync |
Refresh scoreboard teams and resync HUD state for everyone online (/combattoggle reload is an alias). |
Server/Modpack Info
- Capability-backed state. Player data lives on a Forge capability (
CombatToggleData); same in-memory instance for the player's whole session, no per-call NBT churn. There's no public API today, but a future minor can expose one without re-architecting.
- Structured SLF4J logging at DEBUG/INFO for every PvP decision, toggle request, and command invocation. Plays nicely with ops pipelines.
- Translation-driven messages. Every player-facing string is a translation key (
combattoggle.msg.*). Ship translations without code patches.
- Vanilla-tolerant network handshake. The channel uses
NetworkRegistry.acceptMissingOr(PROTOCOL::equals); vanilla clients pass through, sync packets are dropped silently to peers without the channel.
Installation
- Install Minecraft Forge 43.3.0+ for Minecraft 1.19.2.
- Drop
combattoggle-1.2.0.jar into your server's (or client's) mods/ folder.
- Launch. On first run,
combattoggle-server.toml is generated in your world's serverconfig/ directory and combattoggle-client.toml in the client config folder.
Server-installable? Yes. Install on the dedicated server only and vanilla clients can join and use /ct, /combat, /peace, and /combattoggle status with no client-side install. Players who additionally install the mod client-side get the V keybind and the HUD indicator on top — eye candy over the same server-authoritative logic.
Configuration
| Key |
Default |
What it does |
cooldownSeconds |
600 |
Cooldown duration (10 min). Set to 0 to disable cooldown entirely. |
combatTagSeconds |
30 |
How long a combat tag lasts after a PvP event. |
requireBothCombatEnabled |
true |
If true, PvP only works when both attacker and target are in Combat. |
forceCombatWhileTagged |
true |
Force tagged players into Combat mode. |
allowToggleWhileTagged |
false |
If false, Combat-tagged players cannot switch to Peace. |
cooldownTriggersOnPvp |
true |
Cooldown starts when a player deals or takes PvP damage. |
cooldownTriggersOnToggle |
false |
Cooldown starts when a player toggles. |
cooldownAppliesToPeaceOnly |
true |
Cooldown only blocks Combat→Peace; Peace→Combat is always instant. |
allowAdminBypassCooldown |
true |
bypass=true on /combattoggle set actually works. |
useScoreboardTeams |
true |
Disable to keep Combat Toggle out of the scoreboard entirely. |
useEmojiPrefixes / useNameplateColors |
true / true |
Independent toggles for the two visual effects. |
combatEmoji / peaceEmoji |
⚔ / ☕ |
Any BMP Unicode. |
combatTeamName / peaceTeamName |
ct_combat / ct_peace |
Rename to avoid clashes. |
| Key |
Default |
What it does |
hudEnabled |
true |
Master switch for the HUD icon. |
hudShowInCombatMode |
true |
Show the icon while in Combat mode. |
hudShowInPeaceMode |
true |
Show the icon while in Peace mode. |
hudAnchor |
TOP_CENTER |
One of TOP_LEFT, TOP_CENTER, TOP_RIGHT, CENTER_LEFT, CENTER, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT, CUSTOM. |
hudOffsetX |
0 |
Inward pixel offset from the anchor. Absolute screen X if hudAnchor=CUSTOM. |
hudOffsetY |
6 |
Inward pixel offset from the anchor. Absolute screen Y if hudAnchor=CUSTOM. |
hudScale |
1.0 |
Range 0.5–3.0. |
hudShowTimers |
true |
Show tag/cooldown countdown text below the icon. |
Upgrading
- Mode is preserved. Whatever mode (Combat or Peace) each player was last in carries through on first 1.2.0 login.
- In-flight tags and cooldowns reset on first 1.2.0 login. The 1.1.x persistent timers were wall-clock milliseconds with no clock-source guarantee; converting them to the new game-tick clock isn't safe, so they're dropped. New tags/cooldowns from 1.2.0 onward use a monotonic, restart-safe game-tick deadline.
- The
showHud server config key is gone. HUD visibility is purely client-side now via hudEnabled in combattoggle-client.toml. Existing operator configs keep the orphan key on first read; Forge logs an unused-key warning. Harmless.
- Network protocol is
"1" for the 1.2.x line. 1.1.x modded clients cannot connect to a 1.2.0 server (handshake rejects); they need to upgrade. Vanilla clients are unaffected.
Compatibility
- Minecraft: 1.19.2
- Forge: 43.3.0 or newer
- Java: 17
- Dependencies: None. No Kotlin, no Architectury, no Cloth Config.
- Other PvP mods: Should coexist with anti-cheat, region protection, and KubeJS.
useScoreboardTeams=false resolves conflicts with mods that own the scoreboard.
- Multiplayer-only? No. Single-player works; the toggle still applies to damage interactions with hostile iron golems, etc. (as you'd expect for "PvP enabled/disabled").
Known Limits
- Mixin-based damage sources may bypass enforcement. Combat Toggle cancels at both
LivingAttackEvent (primary) and LivingHurtEvent (fallback). A handful of mods route damage through custom mixins that bypass both — those will hit Peace targets. Open an issue with a reproduction if you hit this.
- No dimension allowlist. PvP rules apply uniformly across every dimension.
/combat and /peace are common literal namespaces. If another mod or plugin registers the same root, behavior depends on registration order — fall back to /ct and /combattoggle <subcmd>.
- No public mod-integration API today. Player state lives on an internal Forge capability; a future minor can expose it without re-architecting.
- Vanilla clients have no HUD or keybind. Use
/ct. By design.
License & Source
- License: GPL-3.0
- Source & issues:
- Modpack home: Built for the Runecraft 1.19.2 Forge modpack. Drop it into anything else — it's standalone.
Pull requests and bug reports welcome. Please include server logs, your combattoggle-server.toml, and a minimal repro when filing an issue.
评论 0
登录后参与评分
还没有评论,来抢沙发吧