1. 概述2. 注册3. JSON组件3.1 原版componentsminecraft:loot minecraft:destroy_time minecraft:block_light_emission minecraft:explosion_resistance minecraft:block_light_absorption minecraft:map_color 3.2 网易componentsnetease:tiernetease:aabbnetease:face_directionalnetease:render_layernetease:solidnetease:pathable4. 功能4.1 获取及设置某个位置的方块4.2 物品形式的生成及获取4.3 方块及物品事件4.4 自定义配方4.5 方块组合4.6 村民交易4.7 构成自定义群系4.8 详细属性方块形状 声音 亮度 挖掘 多面向 4.9 特殊方块自定义刷怪箱自定义传送门方块5. demo解释6. Mod卸载7. 常见报错
1. 概述
该功能不需要开启实验性玩法。
开发者可以通过在addon中配置json来添加自定义方块。添加的自定义方块支持“MOD SDK文档”中与方块及物品相关的所有事件及接口。
2. 注册
以demo CustomBlocksMod为例
在行为包中新建
netease_blocks目录
在目录下新建一个json，编写方块的定义。json的格式可参考官方wiki。
- json中至少有一个component
- identifier分为命名空间及方块名。命名空间推荐与mod名称一致。其中的方块名必须全局唯一，可以加上mod名的前缀来保证唯一。mod中其他地方都是用这个identifier与这个自定义方块对应上。
将方块的贴图放到
textures\blocks中可以支持高于16x16分辨率的高清贴图，但需要注意过高的分辨率会导致手机端（尤其是低端机）上无法进入游戏。
在textures中新建
terrain_texture.json，编写资源名与贴图的对应关系。资源名的命名必须满足全局唯一。json格式可参考“Mod PC开发包”的data\resource_packs\vanilla\textures\terrain_texture.json
在resource中新建一个
blocks.json，编写方块贴图及声音，贴图的值需要与上一步terrain_texture.json中配置的资源名对应。json格式可参考“Mod PC开发包”的data\resource_packs\vanilla\blocks.json
在
texts\zh_CN.lang中配置方块中文名称。键的格式为tile.方块identifier.name
重复1-6编写其他自定义方块
3. JSON组件
目前行为包中自定义方块json中支持的component如下：
3.1 原版components
支持的微软原版component包括：（参数及解释见官方wiki）
minecraft:loot
可用于使用loot table控制掉落物
可参考CustomBlocksMod的customblocks:customblocks_test_ore方块
minecraft:destroy_time
可用于控制挖掘所需的时间。该值的含义与官方wiki的“硬度”一致
主要用于挖掘的功能
minecraft:block_light_emission
可用于设置方块亮度。关于亮度及方块光源可参考官方wiki
主要用于亮度的功能
minecraft:explosion_resistance
可用于设置爆炸抗性。原版方块的爆炸抗性见官方wiki
minecraft:block_light_absorption
可用于设置方块的透光率。具体可参考官方wiki
主要用于亮度的功能
minecraft:map_color
可用于设置方块显示在地图上的颜色
3.2 网易components
netease:tier
用于设置与挖掘相关的属性
主要用于挖掘的功能
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| digger | string | 必须设置。表示方块使用此工具挖掘时有速度加成。 可选的值有： shovel：铲 pickaxe：镐 hatchet：斧 | |
| destroy_special | bool | false | 可选。当设置为true时，表示只有使用digger设置的工具进行挖掘才会产生掉落物。 |
| level | int | 0 | 可选。当destroy_special为true时才会生效。表示挖掘所需的工具等级，若手持工具等级小于该值，则不会产生掉落物。 原版工具的等级： 空手/其他非工具物品：0 木制/金制工具：0 石制工具：1 铁制工具：2 钻石工具：3 |
netease:aabb
用于设置方块的碰撞盒
注意事项：
- 无碰撞箱的方块请将collision的值都设置为0
- 有碰撞箱的方块，clip的范围需要小于或等于collision的范围，否则弹射物命中时会异常
可参考CustomBlocksMod的customblocks:customblocks_test_fire方块。
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| collision | AABB | 计算与物体碰撞时用的碰撞盒 | |
| clip | AABB | 计算射线检测时用的碰撞盒。如准心选取及弹射物碰撞。 （那么当该AABB没有体积时，准心与弹射物都会无视这个方块） |
AABB的结构：
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| min | [float, float, float] | [0, 0, 0] | min的三个值必须小于等于max的三个值 |
| max | [float, float, float] | [1, 1, 1] |
netease:face_directional
用于设置方块的多面向
主要用于多面向的功能
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| type | string | direction：四面向方块 facing_direction：六面向方块 |
netease:render_layer
用于设置方块渲染时使用的材质
可参考CustomBlocksMod的customblocks:customblocks_test_fire方块。
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| value | string | 目前支持的材质有： opaque：不透明，即“terrain_opaque”材质。默认为此项 alpha：全透明，即“terrain_alpha”材质，如火焰，树叶。 blend：半透明，即“terrain_blend”材质，如彩色玻璃 |
netease:solid
用于设置方块是否为实心方块主要与生物在方块内时是否受到窒息伤害有关。
可参考CustomBlocksMod的customblocks:customblocks_test_fire方块。
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| value | bool | true | 为true时，生物在方块内会受到窒息伤害 为false时，生物在方块内不会受到窒息伤害 |
netease:pathable
用于设置游戏内AI在进行寻路时，方块是否被当作障碍物。
可参考CustomBlocksMod的customblocks:customblocks_test_fire方块。
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| value | bool | false | 为true时，寻路时被当作空气 为false时，寻路时被当作障碍物，并且可在其上方行走 |
4. 功能
4.1 获取及设置某个位置的方块
获取见服务端blockInfo组件的GetBlockNew接口
设置见服务端blockInfo组件的SetBlockNew接口
4.2 物品形式的生成及获取
支持“自定义物品”文档中所有类型的接口及事件，其中的物品identifier对应方块identifier。
4.3 方块及物品事件
支持“MOD SDK文档”中所有与方块相关的事件，其中添加了“fullName”字段返回对应的方块identifier
支持"MOD SDK文档"中所有与物品相关的事件，其中添加了“itemName”字段返回对应的方块identifier。
4.4 自定义配方
见“自定义配方”文档，材料及结果都支持填写方块identifier。可参考CustomBlocksMod行为包的netease_recipes
4.5 方块组合
见"MOD SDK文档"的服务端block组件，defines项支持填写自定义方块的identifier。可参考CustomBlocksMod脚本的CustomBlocksServer.RegisterBlockPattern
4.6 村民交易
可将行为包的交易配置中的item修改为自定义方块的identifier。可参考CustomBlocksMod行为包的trading\economy_trades\armorer_trades.json，里面将新手级盔甲商的其中一个交易项替换为绿宝石兑换customblocks:customblocks_test0方块
4.7 构成自定义群系
阅读这条前请先阅读“自定义生物群系”文档。
可通过修改minecraft:overworld_surface字段来使用自定义方块生成区块。可参考CustomBlocksMod行为包的netease_biomes\dm5，里面在自定义群系demo（CustomBiomesMod）中dm5维度的基础上进行修改，将该维度的dm5_cold_beach、dm5_frozen_ocean、dm5_frozen_river、dm5_ice_plains、dm5_river几个群系的地表方块进行了替换。
4.8 详细属性
方块形状
可在resource包的blocks.json中添加"blockshape"的键值进行配置。
可参考CustomBlocksMod的customblocks:customblocks_test_fire方块。
目前支持的方块形状：
| string | 解释 |
|---|---|
| fire | 与原版火方块一致（若附近没有其他方块附着则不会渲染） |
| facing_block | 配合多面向使用 |
声音
resource包中blocks.json配置方块的sound。
可以使用原版sounds.json中block_sounds里的类型。不支持添加自定义block_sounds类型
亮度
行为包中使用minecraft:block_light_emission可将方块设置为光源。
可参考CustomBlocksMod的customblocks:customblocks_test_fire方块。
minecraft:block_light_absorption可设置方块透光率，值的范围为0-16
挖掘
挖掘的详细介绍可参考官方wiki
挖掘时间可使用minecraft:destroy_time配置
挖掘工具可使用netease:tier配置
可参考CustomBlocksMod的customblocks:customblocks_test_ore方块
多面向
行为包中使用netease:face_directional配置。
需要在resource包中把方块的blockshape设置为“facing_block”
四面向可参考CustomBlocksMod的customblocks:customblocks_test_face4方块
六面向可参考CustomBlocksMod的customblocks:customblocks_test_face6方块
对于两种面向，当玩家进行放置时，都是north的贴图面向玩家。
方块的面向等于north贴图面向的方向（即玩家放置时准心的反方向）。
当设置为四面向时，方块面向与auxvalue的关系为：
| 方块面向 | auxvalue |
|---|---|
| south | 0 |
| west | 1 |
| north | 2 |
| ease | 3 |
当设置为六面向时，方块面向与auxvalue的关系为：
| 方块面向 | auxvalue |
|---|---|
| down | 0 |
| up | 1 |
| north | 2 |
| south | 3 |
| west | 4 |
| east | 5 |
4.9 特殊方块
开发者可通过在方块定义json中添加base_block来修改方块的基础行为。
自定义刷怪箱
- 自定义刷怪箱方块的base_block需要设为mob_spawner，并在blocks.json中进行如下设置：
- 可在netease:mob_spawner中设置刷怪的类型，目前支持原生生物、网易自定义生物与微软自定义生物。
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| type | string | 必须设置，用于控制生成的生物类型 |
- 原生生物type为其Namespaced ID，可参考官方wiki中各Mob的详细信息。
- 网易自定义生物type为"minecraft:identifier"中的"id"，详见 3-2 自定义生物文档。
- 微软自定义生物type为"minecraft:entity"中"description"的"identifier"项，可参考3-2 自定义生物文档及CustomBlocksMod中的customblocks_test_mobspawner1.json。
自定义传送门方块
- 自定义传送门方块的base_block需要设为portal。
- 可通过在
resource/textures/flipbook_textures.json中配置动画纹理使其贴图拥有动态效果，属于微软功能。 - 传送门方块拥有两种朝向，其方块延伸方向分别与X轴、Z轴相同，如下图所示：
- 可在netease:portal中设置传送门方块上播放的粒子特效以及目标维度。粒子特效应放置于
resource/particles，粒子特效编写可参考官方关于粒子组件的说明。目标维度为0或3-20的整数（0为主世界，3-20为自定义维度），其余值会被视作0来处理。
| 键 | 类型 | 默认值 | 解释 |
|---|---|---|---|
| particle_east_west | string | 可选，对应于粒子json文件中的identifier，用于控制方块与Z轴同向时播放的粒子特效 | |
| particle_north_south | string | 可选，对应于粒子json文件中的identifier，用于控制方块与X轴同向时播放的粒子特效 | |
| target_dimension | int | 必须设置，用于控制进入传送门方块后到达的目标维度 |
- 若通过服务端blockInfo组件的SetBlockNew接口放置传送门方块。当'aux'设为1时，该方块延伸方向与X轴相同，播放particle_north_south对应的粒子；'aux'设为2时，该方块延伸方向与Z轴相同，播放particle_east_west对应的粒子。
- 手动放置的传送门方块'aux'始终为0，无论它朝向哪里。
- 目标维度与当前维度相同时，将不会进行传送。
- 只有玩家才能够通过自定义传送门方块进行传送。
- 同一玩家存在一定的传送冷却时间，不会连续传送。
- 传送前后玩家坐标不发生改变。
5. demo解释
CustomBlocksMod中定义了以下自定义方块：
customblocks:customblocks_test0
上表面与其他面不同的方块。
在
resource/blocks.json中将isotropic的up设置为true，使其上表面在放置时会随机旋转，可以达到视觉上没有明显的贴图重复的效果，属于微软自定义方块的功能演示了构成自定义群系，村民交易，自定义配方，方块组合的功能
customblocks:customblocks_test_ore
性质与矿物相似的自定义方块
演示了挖掘，掉落物的功能
customblocks:customblocks_test_fire
外观与原版火焰相似的方块
通过在
resource/textures/flipbook_textures.json中配置动画纹理使其贴图拥有动态效果，属于微软功能。演示了方块形状，亮度，碰撞盒，渲染材质，构成自定义群系，是否实心，是否可寻路的功能
customblocks:customblocks_test_face4
拥有4个面向的方块
演示了多面向中四面向的功能
customblocks:customblocks_test_face6
拥有6个面向的方块
演示了多面向中六面向的功能
customblocks:customblocks_test_mobspawner
自定义刷怪箱方块-原生生物
演示了“特殊方块-自定义刷怪箱”中生成原生生物的功能
customblocks:customblocks_test_mobspawner1
自定义刷怪箱方块-微软自定义生物
演示了“特殊方块-自定义刷怪箱”中生成微软自定义生物的功能
customblocks:customblocks_test_portal_blue
前往维度3的自定义传送门方块
演示了“特殊方块-自定义传送门方块”的功能
6. Mod卸载
若使用了自定义方块的存档卸载mod后再进入时：
对地图上已存在的自定义方块：
自定义方块会变为空气。若某个subchunk未进行过方块更新，那么重新加载mod时，自定义方块会保留。但一旦subchunk进行了方块更新，即使重新加载mod，自定义方块会永远消失。
对玩家背包中的自定义方块：
物品会消失。若重新加载mod，对卸载期间登录过的玩家，物品不会恢复；没登录过的玩家，物品可以保留
对地图上容器内的自定义方块：
物品会消失。若重新加载mod，对卸载期间进行探索过的区域内的容器，物品不会恢复；未探索区域的容器，物品可以保留
对地图上未捡起的掉落物：
掉落物会消失。若重新加载mod，对卸载期间进行探索过的区域，掉落物不会恢复（除非subchunk内没有其他任何entity）；未探索区域的掉落物可以保留。
7. 常见报错
JSON: xxx has an error
一般为json格式有问题，可以检查一下逗号时候漏写或多写，括号是否对应。
图为多写逗号的报错
