first commit

2025-03-17 13:24:39 +08:00
commit 9a0334ee84
6410 changed files with 221907 additions and 0 deletions
--- a/docs/mcguide/20-玩法开发/15-自定义游戏内容/1-自定义物品/9-自定义3D物品/1-自定义3D物品（一）.md
+++ b/docs/mcguide/20-玩法开发/15-自定义游戏内容/1-自定义物品/9-自定义3D物品/1-自定义3D物品（一）.md
@@ -0,0 +1,179 @@
+# Json配置自定义3D物品
+
+
+在本节教程中，我们将围绕**如何自定义一个3D物品**的话题，教给大家如何仅使用JSON配置和附加包开发知识来快速创建你的第一个3D物品。
+
+
+
+> 温馨提示：开始读起这篇指南前，我们希望你对《我的世界》基岩版附加包有一定了解，有能力撰写JSON数据格式，并能够独立阅读《我的世界》开发者官网-开发指南或其他技术引用文档。
+
+
+
+**通过这节教程，你将学会：**
+
+•如何将一个现有的微软基岩版格式物品模型变为自定义物品的3D模型。
+
+•校对模型在模型空间的相对位置，以匹配并固定在玩家第三人称的手持位置。
+
+
+## 背景介绍
+
+模组API 2.0 （基岩版版本 1.17.2）开始，在资源包定义物品的附着物（Attachable）文件可以绑定微软原版模型至物品上。
+
+
+
+## 制作模型规范
+
+让人型生物（如 溺尸、尸壳、僵尸 或 玩家）手持3D物品模型时，我们推荐使模型骨骼遵守玩家模型骨骼布局。以便模型能优先保证在玩家手持的情况下，能够跟随肢体动画进行正常的幅度摆动。
+
+
+
+原版玩家模型使用一条root根骨骼作为基骨骼，子骨骼内使用waist骨骼控制上半身，rightLeg骨骼和leftLeg骨骼控制左腿和右腿。
+
+
+
+基岩版标识符推荐以小写数字母搭配下划线，因为在游戏中，使用rightLeg或rightleg效果是一致的。以下是玩家模型的骨骼树状图，锚点即模型格式内的pivot。
+
+```
+-root（锚点：[0, 0, 0]）
+--waist（锚点：[0, 12, 0]）
+---jacket（用于persona）
+---cape（披风）
+---body（锚点：[0, 24, 0]）
+----leftArm（锚点：[5, 22, 0]）
+-----leftSleeve（用于persona）
+-----leftItem（锚点：[6, 15, 1]）
+----rightArm（锚点：[-5, 22, 0]）
+-----rightSleeve（用于persona）
+-----rightItem（锚点：[-6, 15, 1]）
+--leftLeg（锚点：[-1.9, 12, 0]）
+---leftPants（用于persona）
+--rightLeg（锚点：[1.9, 12, 0]）
+---rightPants（用于persona）
+```
+
+
+
+## 校正模型在空间下对应第三人称手持的位置
+
+先在模型工程内点击 **【文件】** - **【保存项目】** 。
+
+![img](./images/1_0.png)
+
+新建一个人型模型工程，并根据骨骼树状图拉出人型模型格式。
+
+![img](./images/2_0.png)        
+
+选择 **【文件】** - **【导入】** 导入前面保存的3D模型项目。
+
+![img](./images/3_0.png)
+
+此时可以看到物品模型的贴图完全丢失。但不用担心，它默认援引了人型模型的材质，只要它的UV在前面的工程内已经分好，这边就无需多管。
+
+![img](./images/4_0.png)
+
+
+
+将物品模型基骨骼放入 **【root】** - **【waist】** - **【body】** - **【rightArm】** - **【rightItem】** 骨骼下。并删除除右手方块以外的其他模型方块体。
+
+![img](./images/5_0.png)
+
+
+
+继续调整3D物品模型，直至调整到一个满意的手持角度。此时删去右手模型方块体。这样一个有效的基础第三人称右手手持模型就做好了。
+
+![img](./images/6_0.png)
+
+## 将3D模型实装
+
+在附加包的自定义资源包内新建attachables文件夹，新建一个JSON文件。 
+
+![img](./images/7_0.png)
+
+- 渲染控制器：默认可填  **"controller.render.item_default"**  ，这是原版提供的一个物品渲染控制器。
+- 材质：填写  **"controller.render.item_default"**  后，必须新增 **"default"** 和 **"enchanted"** 键，其中前者对应物品模型默认的材质，后者对应附魔时物品携带的材质。  **"default"** 无特殊情况默认填写 **"entity_alphatest"** ，"enchanted"默认填写 **"entity_alphatest_glint"** 。
+- 贴图纹理：填写  **"controller.render.item_default"**  后，必须 **"default"** 和 **"enchanted"** 键， 其中前者对应自定义物品模型贴图，后者对应物品附魔时的附魔效果贴图（一般默认填写 **""textures/misc/enchanted_item_glint"** ）。 
+- 动画：附着物与实体一样可以添加动画和动画控制器，也可以添加粒子，但目前粒子默认会以实体脚底坐标发射粒子，暂时不能在粒子挂点（locator）上发射。
+- 几何体：附着物的模型，以自定义3D模型的geometry标识符为准。
+- 物品标识符：与行为包的自定义物品标识符一致即可。在这里预先填写一个自定义物品标识符 **"design:custom_golden_sword"** ，稍后将用一个自定义物品行为与之呼应。
+
+
+
+```json
+{
+    "format_version":"1.10.0",
+    "minecraft:attachable":{
+        "description":{
+            "identifier":"design:custom_golden_sword",
+            "materials":{
+                "default":"entity_alphatest",
+                "enchanted":"entity_alphatest_glint"
+            },
+            "textures":{
+                "default":"textures/entity/custom_golden_sword",
+                "enchanted":"textures/misc/enchanted_item_glint"
+            },
+            "geometry":{
+                "default":"geometry.custom_golden_sword"
+            },
+            "render_controllers":[
+                "controller.render.item_default"
+            ]
+        }
+    }
+}
+```
+
+接着在附加包的自定义行为包里，创建netease_items_beh文件夹，并创建子文件custom_golden_sword.json。有关更多自定义物品行为，请查看此链接：[自定义武器及工具](../2-自定义武器及工具.md)
+
+```json
+{
+    "format_version":"1.10",
+    "minecraft:item":{
+        "description":{
+            "identifier":"design:custom_golden_sword",
+            "register_to_create_menu":true,
+            "custom_item_type":"weapon",
+            "category":"Equipment"
+        },
+        "components":{
+            "minecraft:max_damage":700,
+            "minecraft:max_stack_size":1,
+            "netease:weapon":{
+                "type":"sword",
+                "level":0,
+                "attack_damage":7,
+                "enchantment":10
+            }
+        }
+    }
+}
+```
+
+我们还可以继续在资源包内的netease_items_res文件夹，为自定义物品添上2D的物品图标。有关更多自定义物品的基础内容，请查看此链接：[自定义基础物品](../1-自定义基础物品.md)
+
+```json
+{
+    "format_version":"1.10",
+    "minecraft:item":{
+        "description":{
+            "identifier":"design:custom_golden_sword",
+            "category":"Equipment"
+        },
+        "components":{
+            "minecraft:icon":"design:custom_golden_sword",
+            "minecraft:render_offsets":"tools"
+        }
+    }
+}
+```
+
+
+
+现在你就可以在游戏加载附加包完成后，使用这个自定义3D物品了！
+
+![img](./images/8_0.png)
+
+
+
+可以使用快速格式化Json等在线工具，定位到可能在撰写过程中出现的错误语法或结构。