自定义传送门方块
自定义传送门方块允许玩家站上去后传送到指定的维度，类似原版下界传送门。你可以通过 base_block: "portal" 和 netease:portal 组件快速创建一个维度传送入口，并配置目标维度、粒子特效和动画纹理。
概述
自定义传送门的核心流程：在行为包中通过 base_block: "portal" 声明方块类型，然后在 netease:portal 组件中配置目标维度和粒子特效。方块放入世界后，玩家站在上面即可触发维度传送。
传送门方块通常需要动态纹理（类似原版紫色传送门的流动效果），可通过资源包的 flipbook_textures.json 实现。
关键特性：
- 只有玩家能通过自定义传送门传送，生物和其他实体不会触发传送
- 当前维度与目标维度相同时不会发生传送
- 同一玩家存在传送冷却时间，短时间内不会连续传送
- 传送前后玩家的坐标不发生改变（不同于原版下界传送门的坐标换算）
netease:portal 组件
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
target_dimension | int | — | 必填，目标维度 ID |
particle_east_west | string | — | 可选，方块延伸方向与 Z 轴同向时播放的粒子特效标识符 |
particle_north_south | string | — | 可选，方块延伸方向与 X 轴同向时播放的粒子特效标识符 |
target_dimension 取值规则
| 值 | 说明 |
|---|---|
0 | 主世界（Overworld） |
1 | 下界 — 引擎会视作 0 处理，不可使用 |
2 | 末地 — 引擎会视作 0 处理，不可使用 |
3 ~ 20 | 原版预留维度 ID，不建议使用 |
≥ 21 | 自定义维度 ID，需要先注册对应维度 |
注意
target_dimension 设为 1（下界）或 2（末地）时，引擎内部会将其替换为 0（主世界）。如果你需要传送到下界或末地，请使用脚本接口而非传送门方块。
方块朝向与 aux 值
传送门方块拥有两种朝向，通过附加值（aux）控制：
| aux 值 | 朝向 | 播放的粒子 |
|---|---|---|
1 | 延伸方向与 X 轴相同 | particle_north_south |
2 | 延伸方向与 Z 轴相同 | particle_east_west |
避免 aux = 0
手动放置（右键放置）的传送门方块 aux 始终为 0，此时方块朝向和粒子表现异常。不建议通过手动放置创建传送门方块，应使用 /setblock 指令或脚本的 SetBlockNew 接口，并明确指定 aux 为 1 或 2。
setblock 指令示例：
/setblock 100 65 200 mymod:blue_portal 2Python 脚本放置示例：
import server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(levelId)
blockDict = {'name': 'mymod:blue_portal', 'aux': 2}
comp.SetBlockNew((100, 65, 200), blockDict, dimensionId=0)动画纹理
传送门方块通常需要动态纹理效果。在资源包的 textures/flipbook_textures.json 中配置帧动画：
[
{
"flipbook_texture": "textures/blocks/blue_portal",
"atlas_tile": "mymod:blue_portal",
"ticks_per_frame": 4,
"frames": [0, 1, 2, 3, 4, 5, 6, 7],
"replicate": 1,
"blend_frames": true
}
]贴图文件为竖向排列的帧动画图片，每帧大小相同（如 16×16），整张图片高度 = 帧高 × 帧数。放在 textures/blocks/blue_portal.png。
完整 JSON 示例
以下示例创建一个蓝色传送门，传送到自定义维度 21。
行为包 — 方块定义
文件路径：行为包/netease_blocks/blue_portal.json
{
"format_version": "1.10.0",
"minecraft:block": {
"description": {
"identifier": "mymod:blue_portal",
"base_block": "portal",
"register_to_create_menu": true,
"category": "Nature"
},
"components": {
"netease:portal": {
"target_dimension": 21,
"particle_east_west": "mymod:blue_portal_particle_ew",
"particle_north_south": "mymod:blue_portal_particle_ns"
}
}
}
}资源包 — terrain_texture.json
文件路径：资源包/textures/terrain_texture.json
{
"resource_pack_name": "mymod",
"texture_name": "atlas.terrain",
"texture_data": {
"mymod:blue_portal": {
"textures": "textures/blocks/blue_portal"
}
}
}资源包 — blocks.json
文件路径：资源包/blocks.json
{
"mymod:blue_portal": {
"textures": "mymod:blue_portal",
"sound": "glass"
}
}资源包 — flipbook_textures.json
文件路径：资源包/textures/flipbook_textures.json
[
{
"flipbook_texture": "textures/blocks/blue_portal",
"atlas_tile": "mymod:blue_portal",
"ticks_per_frame": 4,
"frames": [0, 1, 2, 3, 4, 5, 6, 7],
"replicate": 1,
"blend_frames": true
}
]资源包 — 本地化
文件路径：资源包/texts/zh_CN.lang
tile.mymod:blue_portal.name=蓝色传送门常见问题
玩家站在传送门上没有被传送
排查步骤：
- 确认
target_dimension的值合法（不为 1 或 2，且对应维度已注册） - 确认玩家当前维度与目标维度不同（同维度不会触发传送）
- 确认方块的
aux值为1或2（不是0） - 确认传送冷却时间已过（短时间内多次进出不会重复传送）
传送门没有粒子特效
原因： particle_east_west 和 particle_north_south 是可选字段。如果需要粒子效果，请配置对应的粒子标识符，并确保粒子资源已在资源包中注册。
传送门贴图没有动画效果
原因： 未配置 flipbook_textures.json，或贴图帧数与 frames 数组不匹配。
确认贴图文件是竖向排列的帧动画图，帧数与 JSON 配置一致。
传送后坐标不对
自定义传送门传送时不会改变玩家坐标。如果你需要在传送后将玩家移动到特定位置，请在脚本中监听维度切换事件并手动设置坐标。
提示
如果需要实现更复杂的传送逻辑（如坐标映射、传送前确认 UI、多人同步传送等），建议使用脚本接口配合普通方块的 netease:on_entity_inside 组件自行实现传送逻辑，而非使用 base_block: "portal"。