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

注意:ActorUseItemClientEvent(ActorUseItemServerEvent)与ClientItemTryUseEvent(ServerItemTryUseEvent)的先后顺序与使用的物品有关。
# 注册
以demo CustomItemsMod为例
在behavior中新建
netease_items_beh
目录在目录下新建一个json,编写物品的定义。
- json中至少有一个component
- identifier分为命名空间及物品名,命名空间推荐与mod名称一致,identifier必须全局唯一。mod中其他地方都是用这个identifier与这个自定义物品对应上。identifier由小写字母以及下划线组成,请勿使用大写字母。
下面开始操作resource包。
将物品的贴图放到
textures\items
中在textures中新建
item_texture.json
,编写资源名与贴图的对应关系。资源名的命名必须满足全局唯一。json格式可参考“Mod PC开发包”的data\resource_packs\vanilla\textures\item_texture.json
在resource中新建一个
netease_items_res
文件夹,在文件夹中添加json,用于配置物品的表现属性,例如贴图。category字段需要与behavior包中的设置一致或者不填,否则可能出现错误。这个json的identifier需要与behavior中的一致,贴图的值需要与上一步
item_texture.json
中配置的资源名对应。json格式可参考“Mod PC开发包”的data\resource_packs\vanilla\items
在
texts\zh_CN.lang
中配置物品的中文名称。键的格式为item.物品identifier.name
重复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的物品在合成配方中被识别为不同的合成原料。
- 不同aux的物品可以使用SpawnItemToPlayerInv接口生成到玩家背包。
- 该组件在物品无法和耐久度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_duration
、variable.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:foil、netease: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后再进入时:
对玩家背包中的自定义物品:
物品会消失。若重新加载mod,对卸载期间登录过的玩家,物品不会恢复;没登录过的玩家,物品可以保留
对地图上容器内的自定义物品:
物品会消失。若重新加载mod,对卸载期间进行探索过的区域内的容器,物品不会恢复;未探索区域的容器,物品可以保留
对地图上未捡起的掉落物:
掉落物会消失。若重新加载mod,对卸载期间进行探索过的区域,掉落物不会恢复(除非subchunk内没有其他任何entity);未探索区域的掉落物可以保留。
# 常见报错
JSON: xxx has an error
一般为json格式有问题,检查是否漏写或多写逗号,括号是否对应等