# 自定义基础物品

# 概述

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

# 组件事件流程

流程

注意:ActorUseItemClientEvent(ActorUseItemServerEvent)与ClientItemTryUseEvent(ServerItemTryUseEvent)的先后顺序与使用的物品有关。

# 注册

以demo CustomItemsMod为例

  1. 在behavior中新建netease_items_beh目录

    avatar

  2. 在目录下新建一个json,编写物品的定义。

    • json中至少有一个component
    • identifier分为命名空间及物品名,命名空间推荐与mod名称一致,identifier必须全局唯一。mod中其他地方都是用这个identifier与这个自定义物品对应上。identifier由小写字母以及下划线组成,请勿使用大写字母。

    avatar

    avatar

  3. 下面开始操作resource包。

    将物品的贴图放到textures\items

    avatar

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

    avatar

    avatar

  5. 在resource中新建一个netease_items_res文件夹,在文件夹中添加json,用于配置物品的表现属性,例如贴图。category字段需要与behavior包中的设置一致或者不填,否则可能出现错误。

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

    avatar

    avatar

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

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

    avatar

    avatar

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

# JSON说明

# format_version

请填写1.10

# description

类型 默认值 解释
identifier str 包括命名空间及物品名。需要全局唯一。
建议使用mod名称作为命名空间
category str items 注册分类,可选的值有:
construction:注册到建筑
equipment:注册到装备
items:注册到物品
nature:注册到自然
commands:只有指令和API可获取
none:只有API可获取
以及自定义分页名称
custom_item_type str 自定义物品类别,可选值有:
weapon
armor
egg
ranged_weapon
bucket
projectile_item
shield

# 原版components

网易版物品支持的微软原版component包括:(参数及解释见开发wiki (opens new window)微软文档 (opens new window)

# minecraft:foil

使物品拥有附魔光效

"minecraft:foil": true,

# minecraft:food

自定义食品组件

"minecraft:food": {
	"nutrition": 4,
	"saturation_modifier": "low"
},

# minecraft:hand_equipped

使手持物品按武器的方式渲染,即竖直的拿在手里

"minecraft:hand_equipped": true,

# minecraft:hover_text_color

该组件为资源包组件,需在资源包netease_items_res的物品JSON中定义

设置物品悬浮文本的颜色,需要填对应颜色的名称,详见颜色代码 (opens new window)

"minecraft:hover_text_color": "gold",

# minecraft:icon

该组件为资源包组件,需在资源包netease_items_res的物品JSON中定义

设置物品的贴图,贴图具体路径需定义在item_texture.json中

"minecraft:icon": "apple",

# minecraft:max_damage

使物品拥有耐久度,范围为[0, 32767]

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

"minecraft:max_damage": 1561,

# minecraft:max_stack_size

设置物品最大堆叠数量,注意:该值无法超过64

"minecraft:max_stack_size": 16,

# minecraft:seed

设置物品的农作物属性

类型 默认值 解释
crop_result string 种植放置出的方块
plant_at array(string) 可被种植的方块列表

plant_at列表中需要保持格式一致,如["minecraft:grass", "minecraft:dirt"]或["grass", "dirt"],否则在相邻自定义农作物种植新的农作物会导致上一个农作物被破坏

"minecraft:seed": {                                  
	"crop_result": "sweet_berry_bush",
	"plant_at": ["grass", "dirt", "podzol"]
},   

# minecraft:stacked_by_data

设置不同aux值的物品是否能够堆叠,例如aux值为1的燃料无法和aux值为2的燃料堆叠在一起,此外,该组件也会导致不同aux的物品在合成配方中被识别为不同的合成原料。

  1. 不同aux的物品可以使用SpawnItemToPlayerInv接口生成到玩家背包。
  2. 该组件在物品无法和耐久度minecraft:max_damage组件共存。
"minecraft:stacked_by_data": true,

# minecraft:tags

设置物品的标签,用于游戏的逻辑判断

类型 默认值 解释
tags array(string) tags列表
"minecraft:tags": {
	"tags": ["minecraft:transform_templates"]
},

# minecraft:use_animation

该组件为资源包组件,需在资源包netease_items_res的物品JSON中定义

定义右键或长按使用物品时播放的动画及声音。可填内容包括eat、drink、bow、block、camera、crossbow、brush。如原版吃苹果时会播放eat动画,喝药水时会播放drink动画。

"minecraft:use_animation": "eat",

# minecraft:use_duration

设置物品最大使用时长,例如食物要吃多久,蓄力物品最多能蓄力多久,并决定和use_duration有关的molang变量值,如query.item_remaining_use_durationvariable.item_use_normalized

"minecraft:use_duration": 32,

# 网易components

# netease:allow_offhand

设置物品是否可以放在副手

类型 默认值 解释
value bool 是否可以放在副手
"netease:allow_offhand": {
	"value": true
},
  • 备注:格式和微软的component不一样,里面多了一个“value"
  • 可以参考CustomItemsMod示例行为包的netease_items_beh/customitems_test_offhand.json
  • 目前基岩版原版副手功能较弱,大多数时候都无法使用物品,主要用于装饰和在mod中判断副手中是否持有某物品来执行特定逻辑
  • 副手不支持一些其他组件,如minecraft:foilnetease:render_offsets

# netease:armor

自定义盔甲组件,使用时需要将custom_item_type设为armor。

"netease:armor":{
	"defense": 10,
	"enchantment": 4,
	"armor_slot": 0
},

# netease:bucket

自定义桶组件,使用时需要将custom_item_type设为bucket。

"netease:bucket": {
	"fill_liquid": "flowing_green_water"
},

# netease:compostable

设置物品是否可以堆肥,使用形式如:"netease:compostable": 48。其中,48表示堆肥成功概率48%。

"netease:compostable": 48,

# netease:cooldown

定义物品冷却时间

类型 默认值 解释
category string "item" 物品的冷却类型,同种类型冷却会互相影响
duration int 0 这个物品能够再次使用前的冷却时间
"netease:cooldown": {
	"category": "item",
	"duration": 10
},
  • 备注:自定义食品(minecraft:food)的冷却时间需定义在minecraft:food中

# netease:customtips

定义物品描述信息

类型 默认值 解释
value string "" 物品的描述信息
"netease:customtips": {
	"value": "§8右键可发射"
},

# netease:egg

自定义生物蛋组件,使用时需要将custom_item_type设为egg。

类型 默认值 解释
entity str 生成生物的identifier
"netease:egg": {
	"entity": "customitems:chicken"
},

# netease:enchant_material

设置物品是否可以当附魔材料

类型 默认值 解释
value bool false 是否可以当附魔材料
  • 可以参考CustomItemsMod示例行为包的netease_items_beh\customitems_test_enchantmaterial.json
"netease:enchant_material": {
	"value": true
},

# netease:fire_resistant

设置物品是否防火,防火的物品会与下界合金一样,不会被火烧毁,掉进岩浆时会弹走

类型 默认值 解释
value bool 是否防火
  • 可以参考CustomItemsMod示例行为包的netease_items_beh\customitems_test_sword.json
"netease:fire_resistant": {
	"value": true
},

# netease:frame_anim_in_scene

该组件为资源包组件,需在资源包netease_items_res的物品JSON中定义

自定义物品贴图使用序列帧动画组件

"netease:frame_anim_in_scene": {
	"texture_path": "textures/items/watch_atlas",
	"ticks_per_frame": 1
},

# netease:frame_animation

该组件为资源包组件,需在资源包netease_items_res的物品JSON中定义

自定义蓄力物品组件

"netease:frame_animation": {
	"frame_count": 3,
	"texture_name": "bow_pulling",
	"animate_in_toolbar": true
},

# netease:fuel

设置物品的燃料属性,允许该物品作为燃料在熔炉中燃烧

类型 默认值 解释
duration float 0.0 该物品可提供的熔炉燃烧时长(秒)
"netease:fuel": {
	"duration": 3
},

# netease:initial_user_data

定义物品初始userData,用于创建自带数据的物品

类型 默认值 解释
display object 物品的显示信息。其中可以添加Name、Lore和ShowInHand,Name类型为str,Lore类型为list(string),ShowInHand类型为bool
ench array(object) 物品的附魔信息。其中的object必须包含id和lvl两个short属性。指定自定义附魔时,需要将id设为255,并添加string类型的modEnchant属性用于传入自定义附魔的identifier
minecraft:keep_on_death bool false 物品在死亡时是否保留
minecraft:item_lock byte 0 物品的锁定模式。0:不锁定,1:无法移动,2:无法丢弃
其他userData中的键 包括但不限于上方的四种键,详见基岩版物品格式 (opens new window)
  • 备注:byte和short类型的值需要使用__type__指定类型,byte的__type__为1,short为2

例如,一个自带死亡不掉落、击退10附魔、攻击力为20的物品:

"netease:initial_user_data": {
	"display": {
		"Name": "同铁砧命名",
		"Lore": ["第一行描述", "第二行描述"]
	},
	"ench": [{
		"id": {
			"__type__":2,
			"__value__":12
		},
		"lvl": {
			"__type__":2,
			"__value__":10
		}
	}],
	"minecraft:keep_on_death": true,
	"ModAttackDamage": 20
},

可以用以下指令获取对应nbt的物品:

  • 冒险放置:/give @s lever 1 0 {"minecraft:can_place_on":{"blocks":["stone", "grass"]}}
  • 冒险破坏:/give @s apple 1 0 {"minecraft:can_destroy":{"blocks":["stone", "grass"]}}
  • 无法移动:/give @s apple 1 0 {"minecraft:item_lock":{"mode":"lock_in_slot"}}
  • 无法丢弃:/give @s apple 1 0 {"minecraft:item_lock":{"mode":"lock_in_inventory"}}
  • 死亡不掉落:/give @s apple 1 0 {"minecraft:keep_on_death":{}}

# netease:projectile

自定义抛射物组件,定义右键发射的抛射物id,使用时需要将custom_item_type设为projectile_item。

"netease:projectile": "customrangedweapon:custom_arrow"

# netease:render_offsets

设置右手物品的渲染偏移

类型 默认值 解释
controller_position_adjust array [0.0,0.0,0.0] 物品位置调整
controller_rotation_adjust array [0.0,0.0,0.0] 物品旋转调整
controller_scale float 1.0 物品大小调整
"netease:render_offsets": {
	"controller_position_adjust": [0.0, 0.1, 0.0],
	"controller_rotation_adjust": [0.0, -45.0, 0.0],
	"controller_scale": 1
},

# netease:shield

自定义盾牌组件,使用时需要将custom_item_type设为shield。

"netease:shield":{
	"defence_damage_source_list": ["drowning"],//防御的伤害类型,如果不配或者配置为空则走原生的格挡伤害逻辑
	"undefence_damage_source_list": ["entity_attack"],//不防御的伤害类型,和上面这个不能有相同元素,如果有相同则优先防御该伤害类型
	"is_consume_damage": false//是否消耗耐久度,false则不消耗
},

# netease:show_in_hand

设置物品拿在手上时是否显示

类型 默认值 解释
value bool 手持时是否显示
  • 备注:格式和微软的component不一样,里面多了一个“value"
  • 可以参考CustomItemsMod行为包的netease_items_beh\customitems_test1.json
"netease:show_in_hand": {
	"value": false
},

# netease:weapon

自定义武器组件,使用时需要将custom_item_type设为weapon。

"netease:weapon":{
	"type": "sword",
	"level": 3,
	"speed": 8,
	"attack_damage": 7,
	"enchantment": 10
},

# 附属功能

# python事件及接口

支持“API文档”中所有与物品相关的事件及组件。

# 自定义配方

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

# 自定义食品

原版apple json结构:

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "minecraft:apple"
    },
    "components": {
	  "minecraft:tags": {
        "tags": ["minecraft:is_food"]
      },
      "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" 使用后转化为的物品,如使用甜菜汤后留下碗
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
}]
使用后的效果

饱和度是一个隐藏数值,玩家的各种行动会消耗饱和度,消耗完后,才开始消耗饥饿值。食物回复的饱和度 = 食物增加的饥饿值 * 饱和度系数 * 2,饱和度最大不超过当前饥饿值。

# 村民交易

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

# loot_table

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

# demo解释

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

  • customitems:test0

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

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

  • customitems:test1

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

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

# Mod卸载

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

  1. 对玩家背包中的自定义物品:

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

  2. 对地图上容器内的自定义物品:

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

  3. 对地图上未捡起的掉落物:

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

# 常见报错

  • JSON: xxx has an error

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

avatar