1. 自定义物品

1.1 概述

该功能不需要开启实验性玩法。

开发者可以通过在addon中配置json来添加自定义物品。添加的自定义物品支持“MOD SDK文档”中与物品相关的所有事件及接口。

 

1.2 注册

以demo CustomItemsMod为例

1. 在behavior中新建netease_items_beh目录

   

2. 在目录下新建一个json，编写物品的定义。json的格式可参考官方wiki。

   • json中至少有一个component
   • identifier分为命名空间及物品名，命名空间推荐与mod名称一致，identifier必须全局唯一。mod中其他地方都是用这个identifier与这个自定义物品对应上。

   

   

3. 下面开始操作resource包。

   将方块的贴图放到textures\items中

   

4. 在textures中新建item_texture.json，编写资源名与贴图的对应关系。资源名的命名必须满足全局唯一。json格式可参考“Mod PC开发包”的data\resource_packs\vanilla\textures\item_texture.json

   

   

5. 在resource中新建一个netease_items_res文件夹，在文件夹中添加json，用于配置物品的表现属性，例如贴图。

   这个json的identifier需要与behavior中的一致，贴图的值需要与上一步item_texture.json中配置的资源名对应。json格式可参考“Mod PC开发包”的data\resource_packs\vanilla\items

   

   

6. 在texts\zh_CN.lang中配置物品的中文名称。

   键的格式为item.物品identifier.name

   

   

7. 重复1-6编写其他自定义物品

    

1.3 JSON组件

description

键	类型	默认值	解释
identifier	str		包括命名空间及物品名。需要全局唯一。 建议使用mod名称作为命名空间
register_to_create_menu	bool	false	是否注册到创造栏
category	str	Nature	注册到创造栏的分类，可选的值有： Construction Nature Equipment Items

原版components

支持的微软原版component包括：（参数及解释见官方wiki）

• minecraft:foil

  可以使物品拥有类似附魔的闪烁效果

• minecraft:max_damage

  可以使物品拥有耐久度

  若物品堆叠数量大于1时，耐久度的变更对整一叠的物品生效。并且耐久度为0后，每次消耗耐久度的行为会使数量减一

• minecraft:max_stack_size

  设置物品最大堆叠数量，注意：该值不能超过64

网易components

• netease:show_in_hand

  （格式和微软的component不一样，里面多了一个“value"，可以参考CustomItemsMod\CustomItemsMod_behavior\netease_items_beh\customitems_test1.json

  键	类型	默认值	解释
  value	bool		手持时是否显示

   

1.4 附属功能

python事件及接口

支持“MOD SDK文档”中所有与物品相关的事件及组件，包括旧版自定义物品支持的全部功能。与旧版自定义物品不同，现在的事件及接口使用“itemName”传递物品identifier来区分不同的物品。

自定义配方

见“自定义配方”文档，材料及结果都支持填写自定义物品的identifier。可参考CustomItemsMod行为包的netease_recipes

自定义食品

原版apple json结构：

{
					
					
  "format_version": "1.10",
					
  "minecraft:item": {
					
    "description": {
					
      "identifier": "minecraft:apple"
					
    },
					
    "components": {
					
      "minecraft:use_duration": 32,
					
      "minecraft:food": {
					
        "nutrition": 4,
					
        "saturation_modifier": "low"
					
      }
					
    }
					
  }
					
}
				
			
		
	
	
	

	

	
	
	

食品类的json结构需要包含在minecraft:item -> components中包含minecraft:food节点，下面对minecraft:food节点进行解释说明。

json字段	举例	含义
nutrition	"nutrition": 2	营养值
saturation_modifier	"saturation_modifier": "low"	饱和度等级，有poor，low，normal，good，max，supernatural六个等级，系数分别是0.1，0.3，0.6，0.8，1.0，1.2
using_converts_to	"using_converts_to": "bowl"	使用后转化为的Item，如使用甜菜汤后留下碗
on_use_action	"on_use_action": "chorus_teleport"	使用食品产生的动作，目前仅支持传送到其他位置
on_use_range	"on_use_range": [0, 10, 4]	传送位置x,y,z的偏移值
cooldown_type	"cooldown_type": "chorusfruit"	冷却类型
cooldown_time	"cooldown_time": 1	冷却时间
can_always_eat	"can_always_eat": true	是否可以一直使用
effects	"effects": [ { "name": "regeneration", "chance": 1.0, "duration": 30, "amplifier": 4 }, { "name": "absorption", "chance": 1.0, "duration": 120, // 2 * 60 "amplifier": 3 }]	使用后的效果

 

村民交易

可将行为包的交易配置中的item修改为自定义物品的identifier。可参考CustomItemsMod行为包的trading\economy_trades\butcher_trades.json，里面将新手级屠夫的其中一个交易项替换为绿宝石兑换customitems:test0物品

loot_table

自定义物品的identifier可用作loot_table配置掉落物。可参考CustomItemsMod行为包的loot_tables\entities\zombie.json，里面将僵尸的掉落物由腐肉改为customitems:test0物品

 

1.5 demo解释

CustomItemsMod中定义了2个自定义物品：

• customitems:test0

  平平无奇的只替换了贴图的自定义物品。

  演示了"村民交易"， “loot_table”的功能

• customitems:test1

  无法堆叠，拥有耐久度，手持时不渲染的自定义物品

  演示了“自定义配方”的功能

   

1.6 Mod卸载

若使用了自定义物品的存档卸载mod后再进入时：

2. 对玩家背包中的自定义物品：

   物品会消失。若重新加载mod，对卸载期间登录过的玩家，物品不会恢复；没登录过的玩家，物品可以保留

3. 对地图上容器内的自定义物品：

   物品会消失。若重新加载mod，对卸载期间进行探索过的区域内的容器，物品不会恢复；未探索区域的容器，物品可以保留

4. 对地图上未捡起的掉落物：

   掉落物会消失。若重新加载mod，对卸载期间进行探索过的区域，掉落物不会恢复（除非subchunk内没有其他任何entity）；未探索区域的掉落物可以保留。

    

1.7 常见报错

• JSON: xxx has an error

  一般为json格式有问题，检查是否漏写或多写逗号，括号是否对应等

 

 

2. 自定义武器/工具

2.1 概述

属于特殊的自定义物品，在支持自定义物品所有特性的基础上，还具有武器或工具相关的功能。

 

2.2 注册

1. 与自定义物品的注册1-6步相同

2. 在”1.2 注册“第2步behavior创建的json中添加武器/工具相关的定义，包括：

   一个netease:weapon组件，必填。组件的参数见“2.3 JSON组件"

   设置最大堆叠数量，可选

   设置耐久度，可选

 

​x
{
	
	
  "format_version": "1.10",
	
  "minecraft:item": {
	
    "description": {
	
      "identifier": "customitems:test_sword",
	
      "register_to_create_menu":true
	
    },
	
​
	
    "components": {
	
      "minecraft:max_stack_size":1,
	
      "minecraft:max_damage":153,
	
      "netease:weapon":{
	
        "type":"sword",
	
        "level":3,
	
        "speed":8,
	
        "attack_damage":7,
	
        "enchantment":10
	
      }
	
    }
	
  }
	
}
	
	
	
	
	
	

	

	
	
	

 

2.3 JSON组件

description

键	类型	默认值	解释
category	str	Equipment	与普通物品不同，武器/工具的默认分类是Equipment

原版components

• minecraft:max_stack_size

  自定义武器/工具只支持设置为1

网易components

• netease:weapon

键	类型	默认值	解释
type	str		武器/工具的类型,目前支持类型有： sword：剑 shovel：铲 pickaxe：镐 hatchet：斧 hoe：锄头
level	int		1. 对于镐，对应挖掘等级 即当使用镐挖掘某些方块时，镐子的挖掘等级大于等于方块的挖掘等级，才会产生掉落物。 对于原版镐子，木镐与金镐是0，石镐是1，铁镐是2，钻石镐是3 2. 并且该值与铁砧的修复材料有关。 level为0：当速度为2对应木板,否则对应金锭 level为1：对应石头 level为2：对应铁锭 level为3：对应钻石 level大于3：无法使用铁砧修复
speed	int	0	对采集工具生效，表示挖掘方块时的基础速度
attack_damage	int	0	攻击伤害
enchantment	int	0	附魔能力。该值的解释见官方wiki

 

2.4 demo解释

CustomItemsMod中定义了一个自定义武器：

• customitems:test_sword

  剑类型的自定义武器

   

 

3. 自定义盔甲

3.1 概述

属于特殊的自定义物品，在支持自定义物品所有特性的基础上，还具有盔甲相关的功能。

3.2 注册

1. 与自定义物品的注册1-6步相同

2. 在”1.2 注册“第2步 目录netease_item_beh中创建新json文件，内容如下。参数详见"3.3 json组件"

   xxxxxxxxxx
   			
   			
   
   			
   
   			
   
   				
   
   					
   
   					
   
   					
   {
   				
   				
     "format_version": "1.10",
   				
     "minecraft:item": {
   				
       "description": {
   				
         "identifier": "customitems:modarmor1",
   				
         "register_to_create_menu":true
   				
       },
   				
       "components": {
   				
         "netease:armor":{
   				
           "defense": 10,
   				
           "enchantment":4,
   				
           "armor_slot":0
   				
         }
   				
       }
   				
     }
   				
   }
   			
   			
   			
   			
   			
   			
   
   			
   
   			
   			
   			

    

3. 添加模型贴图到资源包的textures\models

   与微软内置盔甲贴图一致，自定义盔甲的贴图也需要设置贴图。

    

4. 在”1.2 注册“第5步netease_item_res目录下创建新json中添加盔甲物品的贴图，参数详见自定义物品注册中贴图的设置解释

   xxxxxxxxxx
   			
   			
   
   			
   
   			
   
   				
   
   					
   
   					
   
   					
   {
   				
   				
     "format_version": "1.10",
   				
     "minecraft:item": {
   				
       "description": {
   				
         "identifier": "customitems:modarmor1",
   				
         "category": "Equipment"
   				
       },
   				
       "components": {
   				
         "minecraft:icon": "customitems:modarmor1"
   				
       }
   				
     }
   				
   }
   			
   			
   			
   			
   			
   			
   
   			
   
   			
   			
   			

5. 在resource目录下创建attachables目录，创建新json描述文件，其中可配置的参数详见3.3json组件

   xxxxxxxxxx
   			
   			
   
   			
   
   			
   
   				
   
   					
   
   					
   
   					
   {
   				
   				
     "format_version": "1.8.0",
   				
     "minecraft:attachable": {
   				
       "description": {
   				
         "identifier": "customitems:modarmor1",
   				
         "materials": {
   				
           "default": "armor",
   				
           "enchanted": "armor_enchanted"
   				
         },
   				
         "textures": {
   				
           "default": "textures/models/diamond_1",
   				
           "enchanted": "textures/misc/enchanted_item_glint"
   				
         },
   				
         "geometry": {
   				
           "default": "geometry.customitems_modarmor1"
   				
         },
   				
         "scripts": {
   				
           "parent_setup": "variable.chest_layer_visible = 0.0;"
   				
         },
   				
         "render_controllers": [ "controller.render.armor" ]
   				
       }
   				
     }
   				
   }
   			
   			
   			
   			
   			
   			
   
   			
   
   			
   			
   			

    

6. 在resource/models目录下增加entity目录，增加对应的geometry描述文件

   可配置的参数主要为根节点描述符geometry.modid_modarmor1，这个值与第五步中的geometry文件值对应。

   xxxxxxxxxx
   			
   			
   
   			
   
   			
   
   				
   
   					
   
   					
   
   					
   {
   				
   				
     "format_version": "1.8.0",
   				
     "minecraft:attachable": {
   				
       "description": {
   				
         "identifier": "customitems:modarmor1",
   				
         "materials": {
   				
           "default": "armor",
   				
           "enchanted": "armor_enchanted"
   				
         },
   				
         "textures": {
   				
           "default": "textures/models/diamond_1",
   				
           "enchanted": "textures/misc/enchanted_item_glint"
   				
         },
   				
         "geometry": {
   				
           "default": "geometry.customitems_modarmor1"
   				
         },
   				
         "scripts": {
   				
           "parent_setup": "variable.helmet_layer_visible = 0.0;"
   				
         },
   				
         "render_controllers": [ "controller.render.armor" ]
   				
       }
   				
     }
   				
   }
   			
   			
   			
   			
   			
   			
   
   			
   
   			
   			
   			

    

3.3 JSON组件

netease_item_beh文件

description

键	类型	默认值	解释
category	str	Equipment	与普通物品不同，盔甲的默认分类是Equipment

网易components

• netease:armor（行为包）

键	类型	默认值	解释
defense	int	0	盔甲的防御值
enchantment	int	0	盔甲的附魔能力。该值的解释见官方wiki
armor_slot	int		盔甲槽位，详见枚举值文档的ArmorSlotType

 

attachables文件

键	类型	描述
identifier	str	盔甲的唯一描述符，与之前注册流程中的物品描述符保持一致
textures/default	str	盔甲对应的贴图路径设置
geometry/default	str	盔甲对应的模型描述文件路径设置
scripts/parent_setup	str	盔甲对应部位影响玩家渲染的设置参数

parent_setup

微软内置的盔甲对应设置的值为以下几种：

variable.helmet_layer_visible 玩家是否显示

variable.chest_layer_visible 玩家上半身是否显示

variable.leg_layer_visible 玩家腿部是否显示

variable.boot_layer_visible 玩家脚部是否显示

一般而言，当设置对应的部位的盔甲，需要设置在scripts/parent_setup 设置对应的变量值为0

geometry/default

需要设置成盔甲对应位置的geometry，例如geometry.humanoid.armor.boots。如果是头盔，只需要修改最后一个后缀为helmet

3.4 附属功能

除了支持自定义物品的所有功能外，还支持盔甲的python事件及接口，包括OnNewArmorExchangeServerEvent事件及armorslot组件

 

3.5 demo解释

CustomItemsMod中定义了一个自定义装备：

• customitems:modarmor1

  头盔类型的自定义装备

 

3.6 自定义模型设置建议

• 盔甲模型的基础参考文件为：data\resource_packs\vanilla\models目录下的mobs.json文件中的geometry.humanoid。

• 模型制作工具，推荐使用BlockBench，导出的模型JSON文件格式与要求的格式相近。

• 使用BlockBench制作模型并导出为JSON文件后，按照我们提供的装备物品Demo的JSON样式进行调整； 需注意的是，请尽量使用JSON范例中key的顺序，避免出现比较奇怪的Bug。

• 如果Cube和已有的模型或者Cube之间有重叠的面，重叠部分可能会无法显示或者闪烁；可通过调整每个Cube的inflate（可为负数）来避免这种情况。inflate的作用是让Cube向各个方向膨胀一定数值，同时不会影响贴图坐标。

• 注意：对于溺尸，不能使用SetArmorNew接口装备自定义盔甲，该行为会造成游戏闪退。

   

4 自定义生物蛋

4.1 概述

属于特殊的自定义物品，在支持自定义物品所有特性的基础上，还具有右键可以生成自定义生物的功能。自定义生物详见”3-2 自定义生物文档“。支持刷怪箱和发射器。

 

4.2 注册

1. 与自定义物品的注册1-6步相同

2. 在”1.2 注册“第2步behavior创建的json中添加生物蛋相关的定义，包括：

   一个netease:egg组件，必填。组件的参数见“4.3 JSON组件"

 

4.3 JSON组件

网易components

• netease:egg

  键	类型	默认值	解释
  entity	str		生物的identifier

 

4.4 demo解释

CustomItemsMod中定义了一个自定义生物蛋：

• customitems:test_egg

  右键时会生成自定义生物"minecraft:mod{customitems:chicken}"