可附着物

概述 ​

当我们设计自定义物品或方块时，Minecraft会基于模板构建模型以便在手持时显示。这表现为物品的精灵图以拉伸纹理网格形式呈现，或方块以其模型显示。通过使用可附着物系统，我们可以设计自己的模型来替代这些物品被持握时的显示效果。

是否曾想让木棍看起来像望远镜？或是挥舞一把带有旋转链条的巨型电锯？可附着物正是实现这些效果的途径！

本文档将介绍两种不同方法来创建可附着物，具体取决于所使用几何结构的构建方式。

系统原理 ​

可附着物是在装备物品或方块时渲染实体模型的系统。这意味着当物品被持握在主手、副手或装备槽时生效。

可附着物定义在设计上与客户端实体定义非常相似：允许我们定义纹理、材质、几何结构和动画来展示可附着物。

文件结构 ​

可附着物定义存放在'attachables'文件夹中。文件布局与自定义实体完全相同。

可附着物定义示例 ​

这是一个基础的可附着物定义示例：

{
    "format_version": "1.10.0",
    "minecraft:attachable": {
        "description": {
            "identifier": "minecraft:stick",
            "materials": {
                "default": "entity",
                "enchanted": "entity_alphatest_glint"
            },
            "textures": {
                "default": "textures/entity/steve",
                "enchanted": "textures/misc/enchanted_item_glint"
            },
            "geometry": {
                "default": "geometry.wiki.steve_head"
            },
            "animations": {
                "hold_first_person": "animation.steve_head.hold_first_person",
                "hold_third_person": "animation.steve_head.hold_third_person"
            },
            "scripts": {
                "animate": [
                    {
                        "hold_first_person": "context.is_first_person == 1.0"
                    },
                    {
                        "hold_third_person": "context.is_first_person == 0.0"
                    }
                ]
            },
            "render_controllers": ["controller.render.item_default"]
        }
    }
}

该定义中有几个关键点需要注意：

• 标识符需匹配现有方块或物品ID。当物品被装备时，这将激活可附着物并替换原始持握模型
• 包含了附魔光效的材质和纹理定义。若物品需要显示附魔光效，这部分内容必须保留

创建可附着物比制作客户端实体文件更复杂。我们需要正确装配几何结构的骨骼，使其在装备时显示正常。

方法一 - 骨骼附着法 ​

第一种方法是通过复制玩家骨骼结构，将模型附着到玩家骨骼的某个部位来构建可附着物。

此方案适用于仅针对单一类型生物/实体（特别是玩家）且仅涉及一个装备槽的模型。在Blockbench中预览效果较为直观。

骨骼设置 ​

我们需要重建玩家骨骼结构，使模型能正确绑定到目标骨骼，否则模型将无依附地漂浮在玩家周围。

使用文本编辑器，从提供的玩家骨骼文件中复制骨骼数据到您的几何文件中，然后将模型方块设为rightItem骨骼的子级。将此几何文件保存至资源包。

为方便起见，这里已准备好一个处理好的模型文件（已移除玩家模型的方块部分）：

显示设置 ​

让模型漂浮在玩家脚边显然不够理想。下一步是创建动画来正确定位模型。

创建两个新动画：第一人称持握和第三人称持握。调整第三人称动画的定位后保存至资源包。

这里提供一个示例动画文件（包含第一人称动画，具体制作方法见下文）：

第一人称动画制作 ​

要更轻松地创建第一人称动画，我们需要模拟第一人称视角下手臂的位置。

使用以下引导动画并导入Blockbench。它对右臂骨骼应用了(95, -45, 115)旋转和(13.5, -10, 12)位移，完美复现第一人称视角的手臂位置。

最终效果 ​

完成所有设置后，检查并删除玩家骨骼中残留的方块（保留骨骼）。现在可以在游戏中查看效果了！

方法二 - 骨骼绑定法 ​

第二种方法通过模型绑定构建可附着物几何结构。这种方式允许模型直接绑定到对应装备槽的骨骼上。Minecraft的三叉戟、望远镜、弓和盾牌等可附着物品均采用此技术。

虽然这种方法能使可附着物更动态地适应不同生物和装备槽，但模型绑定也存在一些特殊问题（下文将说明）。部分开发者可能会觉得此方法更难实现。

模型绑定 ​

首先需确保模型文件格式版本为"1.16.0"。如果是旧版文件，请先转换（Blockbench提供转换工具：文件→转换项目）。

接着修改几何结构的根骨骼，将其绑定到物品所在的装备槽。注意下面骷髅头几何文件摘录中的第4行：

// 骨骼定义
{
    "name": "skeleton_head",
    "binding": "q.item_slot_to_bone_name(context.item_slot)",
    "pivot": [0, 4, 0],
    "cubes": [
        {
            "origin": [-4, 0, -4],
            "size": [8, 8, 8],
            "uv": [0, 0]
        }
    ]
}

骨骼中的"parent"键接受字符串参数，指定的骨骼名称将作为当前骨骼的父级；子骨骼保持自身位置但会相对于父骨骼移动。

而"binding"键接受Molang表达式，指定骨骼的枢轴点将作为子骨骼继承的根位置。

我们使用Molang查询q.item_slot_to_bone_name作为"binding"的值，通过上下文变量context.item_slot将装备槽名称转换为玩家几何结构中的对应骨骼名称。具体转换如下：

• 'main_hand' → "rightitem"
• 'off_hand' → "leftitem"

将模型绑定应用到您的骨骼后，保存几何文件至资源包。

这里提供一个应用了此绑定的示例模型：

显示设置 ​

完成绑定后，下一步是设置第一人称和第三人称的显示动画。

创建两个新动画分别对应两种视角。

为简化制作流程，请按以下步骤操作：

1. 下载玩家骨骼模型作为视觉参考：

   📄 玩家骨骼文件

2. 用文本编辑器将您的模型骨骼和方块添加到玩家骨骼模型中，然后导入Blockbench

3. 将模型的根骨骼设为玩家骨骼中'rightItem'的子级

4. 下载引导动画文件并导入wiki.third_person_guide动画用于辅助定位：

   📄 可附着物引导文件

这些引导动画有个重要特性：对右物品骨骼应用了-24的y轴位移偏移，用于抵消Minecraft对绑定骨骼施加的类似偏移。目前尚不清楚产生此现象的原因。

同时播放两个动画并调整模型位置后，保存动画至资源包。

这里提供一个定位示例的动画文件：

第一人称动画 ​

参照第三人称动画的制作方法，从可附着物引导文件中导入wiki.first_person_guide动画到Blockbench。同时播放您的动画和引导的第一人称动画进行调整后保存。

示例资源包 ​

我们已将这两种方法编译成示例资源包，供您参考或直接查看实际效果。