五根手指

真身与五指模组 —— 架构与技术概览

1. 执行摘要

真身与五指模组 (RealBody & FiveFinger Mod) 是一个为我的世界 1.20.1 (Forge 47.x) 构建的客户端视觉增强模组。

其主要目的是在不改变或要求修改标准玩家皮肤的前提下，将我的世界僵硬的方块状玩家模型转变为真实、符合解剖学轮廓的人体形状。

与那些会破坏自定义皮肤或强制使用预烘焙3D纹理的典型3D盔甲或大修模组不同，此模组动态读取玩家现有的 64×64（或 128×128）皮肤纹理并采样精确的UV坐标。它将此皮肤投影到符合解剖学比例的几何结构上——包括每只手五个可活动的指关节、自然的关节隆起（肘部和膝盖）、颈部轮廓以及柔化的头部斜面。

---

2. 核心架构支柱

A. 基于图层的非破坏性几何注入（RenderLayer 注入）

• 零核心类替换：此模组不替换我的世界原版中的PlayerRenderer 或 PlayerModel（这可能会与诸如 Epic Fight、Better Combat 或 Jujutsu Craft 等动画和战斗模组产生严重的不兼容性），而是通过 Forge 的EntityRenderersEvent.AddLayers 事件挂钩到渲染管线中。
• 附加图层：
  1. <button class="select-none inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium text-foreground p-0.5 cursor-pointer hover:bg-secondary data-[popup-open]:bg-secondary transition-[background-color,opacity]" title="c:\Users\oguog\.gemini\antigravity\scratch\fivefinger-mod\src\main\java\com\fivefinger\client\renderer\RealBodyLayer.java" draggable="true" data-uri="file:///c%3A/Users/oguog/.gemini/antigravity/scratch/fivefinger-mod/src/main/java/com/fivefinger/client/renderer/RealBodyLayer.java">RealBodyLayer</button>：渲染补充的解剖轮廓、自然的关节隆起和过渡网格。
  2. <button class="select-none inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium text-foreground p-0.5 cursor-pointer hover:bg-secondary data-[popup-open]:bg-secondary transition-[background-color,opacity]" title="c:\Users\oguog\.gemini\antigravity\scratch\fivefinger-mod\src\main\java\com\fivefinger\client\renderer\FingerRenderLayer.java" draggable="true" data-uri="file:///c%3A/Users/oguog/.gemini/antigravity/scratch/fivefinger-mod/src/main/java/com/fivefinger/client/renderer/FingerRenderLayer.java">FingerRenderLayer</button>：处理第三人称的五指关节网格。
  3. <button class="select-none inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium text-foreground p-0.5 cursor-pointer hover:bg-secondary data-[popup-open]:bg-secondary transition-[background-color,opacity]" title="c:\Users\oguog\.gemini\antigravity\scratch\fivefinger-mod\src\main\java\com\fivefinger\client\renderer\HandRenderer.java" draggable="true" data-uri="file:///c%3A/Users/oguog/.gemini/antigravity/scratch/fivefinger-mod/src/main/java/com/fivefinger/client/renderer/HandRenderer.java">HandRenderer</button>：拦截第一人称手部渲染（RenderHandEvent 和 RenderArmEvent）。

---

3. 详细组件分解

1. 可活动五指手部系统

• 解剖学比例：
  • 每只手有 5 个不同的手指：拇指、食指、中指、无名指和小指。
  • 手指使用多节段运动学结构（基础关节和远端指骨）构建，以实现逼真的弯曲、指向和抓握动作。
  • 中指稍长，而小指和拇指则按比例模仿自然人手的形态。
  • 缩放至适合纤细的人类手腕直径（手掌宽度约2.6像素），而非匹配原版手臂的完整 4×4像素方块。
• 动态UV皮肤采样：
  • 自动采样手臂纹理的最低边缘（皮肤模板上的texOffs(44, 30)）。这可确保肤色保真度，并消除不自然的黑色边框或变色。
• 物品同步与抓握：
  • 空手：向侧面旋转，手掌自然向内朝向身体。
  • 持有物品/武器时：与原版的ItemInHandLayer 变换矩阵（XP.rotationDegrees(-90)、YP.rotationDegrees(180)）同步。手指自动过渡到 HOLDING_POSE（握持姿势），自然地环绕物品/武器握把，而不会消失或穿透模型。
• 第一人称与第三人称一致性：
  • 第一人称手部会缩放（放大1.45倍）并偏移，以便在挖掘、挥动或闲置动画期间舒适地适配相机视图。

2. 解剖学关节系统（肘部和膝盖）

• 肘关节（olecranon）：
  • 位于每只手臂的中心（Y=2.5～5.5）。
  • 特点是有一个朝后的 4×3×1像素 突起，上下边缘均带有 45度 斜切过渡坡面。
  • 从背后或侧面观察时，重现了人类鹰嘴突（肘部骨骼）的自然隆起。
• 膝关节（patella / 膝盖骨）：
  • 位于每条腿的前方（Y=4.5～7.5）。
  • 增加了一个微妙的向前突起（4×3×1像素），带有斜切的上、下小平面。
  • 消除了我的世界原版腿部僵硬、平坦的表面，在奔跑和弯曲时提供自然的膝关节轮廓。

3. 头部与颈部柔化几何结构

• 头角斜切：
  • 在头部立方体的垂直棱边处添加微妙的 1×8×1像素 小平面的斜切条。
  • 减少生硬的90度盒状外观，使其接近八角形/圆润的头骨形状。
• 圆柱形颈部柱体：
  • 将躯干（Y=0）向上连接到头骨底部（Y=-3）。
  • 使用内部核心和4个有角度的角条建模为八角棱柱，消除了头部漂浮在胸部上方、显得脱节的错觉。

---

4. 动画与姿势同步管线

• 网络架构：
  • <button class="select-none inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium text-foreground p-0.5 cursor-pointer hover:bg-secondary data-[popup-open]:bg-secondary transition-[background-color,opacity]" title="c:\Users\oguog\.gemini\antigravity\scratch\fivefinger-mod\src\main\java\com\fivefinger\network\NetworkHandler.java" draggable="true" data-uri="file:///c%3A/Users/oguog/.gemini/antigravity/scratch/fivefinger-mod/src/main/java/com/fivefinger/network/NetworkHandler.java">NetworkHandler</button> 注册双向自定义 Forge 网络数据包：
    • HandPosePacket（客户端 → 服务器）
    • HandPoseSyncPacket（服务器 → 所有追踪的客户端）
  • 玩家选择的手部姿势和手指状态通过网络传输并在多人游戏中同步，使其他玩家能够看到自定义姿势和手势。
• 按键绑定与平滑插值：
  • 可配置的按键绑定允许在预编程的手势（张开、握拳、指向、和平手势、领域展开 / 无边界、宿傩手势 等）之间切换。
  • <button class="select-none inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium text-foreground p-0.5 cursor-pointer hover:bg-secondary data-[popup-open]:bg-secondary transition-[background-color,opacity]" title="c:\Users\oguog\.gemini\antigravity\scratch\fivefinger-mod\src\main\java\com\fivefinger\client\animation\HandAnimator.java" draggable="true" data-uri="file:///c%3A/Users/oguog/.gemini/antigravity/scratch/fivefinger-mod/src/main/java/com/fivefinger/client/animation/HandAnimator.java">HandAnimator</button> 在关节矩阵上运行平滑的数学插值（smoothStep + lerp），以确保骨骼旋转过渡流畅而非突然跳动。

---

5. 技术规格摘要