简单自定义传送门

允许你创建自定义传送门,专为整合包开发者设计

管理

Simple Custom Portal

向你的整合包添加自定义传送门方块:每个方块都会将你传送到你所选择的维度(例如自定义维度、下界、末地),并保持相同的 x、y、z 坐标。

面向整合包创作者: 使用 JSON 定义传送门(id、目的地、可选的底座/胶囊方块、声音、可用维度、默认返回)。文件放在一个可配置的目录中——默认为游戏目录下的 kubejs/external_scripts/simp_cm_portal_portals/。该路径可在模组配置中更改。游戏加载时,模组还会在该文件夹中写入一份 PORTALS.md,内容与下方的文档相同。无需 KubeJS;该路径名称只是默认值。

功能: 可选的传送目的地安全区建造、通过 usableIn 实现单向传送门、/simp_cm_portal_reload 可在不重启的情况下实时重载。


本页其余部分是完整文档(与自动生成的 PORTALS.md 相同,该文件会创建在你放置传送门 JSON 脚本的同一文件夹中)。


配置路径

传送门定义从以下位置的 JSON 文件加载:<游戏目录>/<externalScriptsPath>/simp_cm_portal_portals/。

externalScriptsPath 在模组配置中设置(默认为 kubejs/external_scripts)。只读取 .json 文件。

JSON 格式

每个 JSON 文件可以包含一个或多个传送门定义。根结构:

  • type(必填):"simp_cm_portal:portals" 或 "iska_utils:portals"。
  • overwritable(可选):目前未使用。
  • portals(必填):传送门对象数组。每个条目必须具有唯一的 id。

传送门对象

  • id(必填):唯一标识符(例如 "custom_dimensions-portal_void")。用于方块注册;只有游戏启动时加载的传送门才会获得方块。重载之后,只会更新现有 id 的逻辑。
  • destination(必填):传送门将玩家发送到的维度资源键(例如 "minecraft:overworld"、"custom_dimensions:void")。
  • baseBlock(可选):安全区胶囊地板的方块 id(例如 "minecraft:stone")。如果为空,则不替换地板。
  • capsuleBlock(可选):胶囊墙壁和天花板的方块 id(例如 "minecraft:glass")。如果为空,则不建造墙壁/天花板。
  • box(可选):碰撞箱(碰撞和视觉),为一个以方块为中心的尺寸可变盒子。格式:"width height depth",为 0 到 1 之间的分数,用空格或逗号分隔。示例:"1 1 1" 或省略 = 完整方块;"0.5 1 0.5" = 宽度和深度减半,高度完整;"0.5" = 0.5×0.5×0.5 的立方体。无效或为空 = 完整方块。
  • usableIn(可选):维度键数组。如果非空,则只有当玩家处于这些维度之一时才能使用该传送门。用于单向传送门(例如仅 ["minecraft:overworld"],这样目的地中的返回传送门将无法使用)。
  • defaultReturn(可选):当玩家已处于 destination 并使用没有存储返回位置的传送门时,他们将被发送到此维度。如果为空,则从目的地使用该传送门不会产生任何效果。
  • sound(可选):传送门方块的方块声音类型(放置、破坏、踩踏)。默认为 glass。见下方“支持的声音”。示例:"rock"。

支持的声音

sound 的有效值(省略或未知时默认为 glass)。示例:rock、glass、wood——完整列表见与脚本同一文件夹中生成的 PORTALS.md。

JSON 可以包含 // 和 /* */ 注释;它们会在解析前被去除。

示例

最小配置(双向,无安全区样式):

{
  "type": "simp_cm_portal:portals",
  "portals": [
    {
      "id": "my_portal_void",
      "destination": "custom_dimensions:void"
    }
  ]
}

带安全区、默认返回和自定义声音的双向传送门(例如主世界 ↔ 虚空):

{
  "type": "simp_cm_portal:portals",
  "portals": [
    {
      "id": "portal_void",
      "destination": "custom_dimensions:void",
      "baseBlock": "minecraft:stone",
      "capsuleBlock": "minecraft:glass",
      "sound": "rock",
      "usableIn": [],
      "defaultReturn": "minecraft:overworld"
    }
  ]
}

单向(仅从主世界到虚空;返回传送门无法使用):

{
  "type": "simp_cm_portal:portals",
  "portals": [
    {
      "id": "one_way_void",
      "destination": "custom_dimensions:void",
      "baseBlock": "minecraft:stone",
      "capsuleBlock": "minecraft:glass",
      "usableIn": ["minecraft:overworld"],
      "defaultReturn": ""
    }
  ]
}

自定义碰撞箱(细柱,宽度/深度减半,高度完整):

{
  "type": "simp_cm_portal:portals",
  "portals": [
    {
      "id": "slim_portal",
      "destination": "minecraft:the_nether",
      "box": "0.5 1 0.5"
    }
  ]
}

其他 box 示例:"1 1 1" 为完整方块;"0.5" 为居中的小立方体。

一个文件中的多个传送门:

{
  "type": "simp_cm_portal:portals",
  "portals": [
    {
      "id": "portal_overworld",
      "destination": "minecraft:overworld",
      "baseBlock": "minecraft:grass_block",
      "capsuleBlock": "minecraft:oak_planks",
      "defaultReturn": "custom_dimensions:void"
    },
    {
      "id": "portal_void",
      "destination": "custom_dimensions:void",
      "baseBlock": "minecraft:stone",
      "capsuleBlock": "minecraft:glass",
      "usableIn": ["minecraft:overworld"],
      "defaultReturn": "minecraft:overworld"
    }
  ]
}

行为

  • 点击: 右键点击传送门方块以传送。目标维度为:若该方块有存储的返回维度,则使用它;否则,若已处于 destination,则使用 defaultReturn;否则使用 destination。
  • 相同坐标: 目的地传送门(或胶囊)会创建在与所点击传送门相同的 x、y、z 坐标处。
  • 返回传送门: 当模组在目的地建造胶囊时,它会放置一个相同类型的传送门方块,并存储返回维度(你来自的地方)。该方块之后始终会将你送回。
  • 仅在需要时建造胶囊: 如果目的地维度中相同位置已经存在传送门,或在 32 格半径内存在具有相同返回维度的传送门,则玩家会被传送到那里,并且不会建造胶囊。
  • 安全区: 建造时,胶囊内部为 3×3×4,带有地板(baseBlock)、墙壁和天花板(capsuleBlock),返回传送门位于中心。

建造前验证

在建造胶囊之前,模组会检查区域内没有任何方块具有:

  • 原版标签 minecraft:features_cannot_replace
  • 方块为基岩
  • 爆炸抗性 ≥ 3,600,000(不可破坏)

如果任一项不满足,玩家会收到一条动作栏消息(例如“Invalid position for portal”),并且不会进行建造/传送。

命令

  • /simp_cm_portal_reload(权限等级 2):从传送门文件夹(即放置脚本的同一路径)中的所有 JSON 文件重新加载传送门定义,并刷新目的地映射。只会更新逻辑;JSON 中的新 id 在游戏重启之前不会获得新方块。

从 JSON 中移除的传送门

如果世界中的传送门方块仍然存在,但其 id 已从所有 JSON 中移除(例如重载之后),该方块不会产生任何效果,也不会崩溃:点击会返回 PASS。游戏重启后,该方块类型可能不再存在,具体取决于注册情况。