Punchy × Essential Compat

问题

同时安装 Punchy 和 Essential 后，穿上覆盖手臂的装扮，你的手就会消失。你手持的物品会浮在你面前。

这两个模组本身都没有问题。它们只是对于由谁来绘制你的手臂存在分歧——结果就是没有人来画。

本模组的作用

它让两个模组分担工作，让装扮显示在你自己的手上：

• 你的装扮会绘制在第一人称手臂上。 袖子、手套、爪子——无论你的装饰品在手臂上添加了什么，你现在在第一人称视角下也能看到它。
• 它会跟随 Punchy 动作。 挥舞、挖掘、格挡、疾跑——装扮会跟随每个动画，而不是悬在半空。
• 没有袖子的装扮仍然有效。 如果没有东西覆盖你的手臂，你就会恢复正常的皮肤手臂。

在衣柜里更换装扮，你的手也会随之改变。无需任何设置，没有按键绑定，也没有菜单。

安装

1. 确保你已经安装了 Fabric Loader 0.19.3 或更高版本、Punchy 和 Essential。
2. 下载本模组，并将 .jar 文件放入你的 mods 文件夹。
3. 启动游戏。就这样。

仅客户端模组——无需在服务器上安装，并且可以在未安装本模组的服务器上运行。

兼容性

Minecraft	26.1, 26.1.1, 26.1.2, 26.2
加载器	Fabric
Punchy	2.6.1 和 2.7d
Essential	1.3.10.x 和 1.4.0.x
Java	25

Essential 是可选的。没有它，本模组只是闲置着不执行任何操作，因此可以安全地保留在整合包中。

不支持 1.20 或 1.21 版本。 Minecraft 在 26.0 中改变了渲染方式，本模组直接接入新系统。支持旧版本意味着需要从头重写一次。详情请参阅 TECHNICAL.md。

看起来有问题？

我的手仍然不可见

检查 Punchy 是否已启用（Mod Menu → Punchy → 模组自身的开关），以及本模组是否出现在你的模组列表中。如果两者都正常，请提交 issue，并附上日志——下一节会说明如何让它更有用。

装扮位置不对，或者我的皮肤透出来了

这值得报告。但在报告之前，请先检查它在第三人称视角下（按 F5）是否也看起来不对——如果是，那说明装饰品本身就存在问题，本模组无法修复。

如何正确报告 Bug

打开 config/punchy-essential-compat.json，将 "debugLogging" 设置为 true，重启游戏，穿上出问题的装扮，然后玩上几秒钟。你的 logs/latest.log 会列出你穿戴的所有装饰品及其覆盖范围。请将该日志连同截图一起附在 issue 中。

设置

你无需修改这些设置——默认值就是最佳配置。该文件在首次启动后出现在 config/punchy-essential-compat.json。

设置	默认值	作用
renderCosmeticsOnFirstPersonArms	true	将你的装扮绘制在第一人称手臂上。关闭则恢复为普通皮肤手臂。
unmaskFirstPersonArms	true	安全网，确保你的手永远不会隐形，即使发生意外情况。
debugLogging	false	将穿戴的装饰品报告写入日志。报告 Bug 时开启。
logErrors	true	将问题记录在日志中，而不是静默失败。
firstPersonParts	["LEFT_ARM", "RIGHT_ARM"]	要在第一人称视角下绘制的身体部位。请勿修改。

如果在绘制过程中出现问题，模组会在本次会话中关闭该部分，并回退到正常可见的手。它不会导致游戏崩溃。

使用 AI 辅助开发

本模组是在 AI（Claude）的帮助下编写的。通过拆解两个模组并阅读其实际行为来定位冲突，每个连接点都与真实的游戏文件进行了核对。

已测试和未测试的内容：

• ✅ Minecraft 26.2 搭配 Punchy 2.7d 和 Essential 1.4.0.3 —— 已在游戏中实际游玩。上面的录屏就是在该环境下录制的。
• ⚠️ Minecraft 26.1.x 搭配 Punchy 2.6.1 和 Essential 1.3.10.x —— 已对照相应文件进行核对，但尚未有人实际游玩过。理论上应该可以工作。如果不行，请告诉我。

面向开发者

TECHNICAL.md 有完整的说明：每个模组对渲染管线做了什么、它们为何冲突、修复如何接入，以及如何在没有 Gradle 的情况下构建它。

欢迎贡献——尤其是移植到旧版 Minecraft。

鸣谢

• Punchy 由 Punchy 团队开发
• Essential 由 ModCore Inc 开发

这是一个独立的兼容性补丁。它与上述任一项目均无关联、未经其认可或支持，并且不包含它们任何代码。

许可证

MIT——你可以随意使用。