地下城数据与场景编写

原生地下城由服务端定义、拼图模板和世界中的已配置入口组成。遭遇、门和完成流程由脚本控制；仅选择模式不会自动生成这些遭遇。

文件放在哪里

定义路径为 data/<namespace>/dungeons/**/*.json。文件默认使用其资源 ID，也可通过 id 覆盖。拼图池与模板仍使用常规世界生成资源；标题和消息使用客户端语言文件。

随模组提供的定义为 isekaiexpansion:dark_delves（幽暗矿窟）、isekaiexpansion:sunken_sanctum（沉没圣所）和 isekaiexpansion:verdant_temple（翠影古殿）。内置的 isekaiexpansion:dungeon_instance 维度使用空的超平坦生成器，地板及所有可游玩方块都必须由模板提供。

最小示例

将下述精简自幽暗矿窟遭遇的配置保存为 data/example/dungeons/trial.json，再将入口设为 example:trial。它使用模组现有的起始池，在 100 刻（5 秒）后生成一只僵尸，并在危险遭遇清除后开始 600 刻（30 秒）的撤离倒计时。

{
  "difficulty": "uncommon",
  "modes": [
    "hazard"
  ],
  "structure": {
    "start_pool": "isekaiexpansion:dark_dungeon/dungeon_spawn",
    "start_jigsaw": "isekaiexpansion:spawn",
    "base_y": 80,
    "jigsaw_depth": 64
  },
  "scripts": [
    {
      "id": "example:opening",
      "trigger": "session_started",
      "actions": [
        {
          "type": "spawn_hazard",
          "offset": [
            7,
            0,
            0
          ],
          "waves": [
            {
              "entries": [
                {
                  "entity": "minecraft:zombie",
                  "count": 1,
                  "delay_ticks": 100
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "example:finish",
      "trigger": "hazard_cleared",
      "actions": [
        {
          "type": "complete",
          "completion_delay_ticks": 600
        }
      ]
    }
  ]
}

字段

解析器拥有的每层对象都会拒绝未知字段。数组与对象必须符合预期容器类型。枚举字符串去除首尾空白且不区分大小写；空白值使用对应枚举的默认值，未知值则拒绝。下表中的数值钳制发生在解析后；无法解析的数字仍会失败。

根对象

结构

脚本与动作

危险遭遇波次

强化池

nbt 与任务生成实体使用相同的类型化 JSON NBT 规则：复合对象、元素类型一致的列表，以及必要时显式指定数值类型的包装对象。它不是 SNBT 字符串。任意实体 NBT 仍遵循该实体自己的格式；地下城解析器校验 NBT 表示方式，不逐项校验实体专用键。

脚本何时执行

重放记录按会话与脚本 ID 保存。先执行动作，再记录重放状态，没有事务或逐动作回滚。repeatable 允许每次符合条件的分发；cooldown 保存下一次允许执行的游戏刻。

spawn_hazard 创建有序波次。同一波内各批按各自延迟生成；下一波等待所有已生成且受追踪的实体清除。已卸载实体的 UUID 会继续保留，不会被算作已击杀。生成位置搜索失败后，不会重试同一批次。所有危险遭遇清除时，还会为符合条件的参与者生成类 Rogue 强化选项，无需额外声明 offer_powerup 动作。

spawn_return_portal 创建出口，但不完成会话；must_complete 会阻止使用该出口。complete 开始撤离，并非立即授予完成。撤离期间停止新的区域脚本及危险遭遇、逐刻脚本处理；原有的限时截止时间先被检查，仍可能导致失败。最终完成还需等待至少一名在线参与者身处地下城。

unlock_gate 操作原点整数偏移处的控制器；控制器不存在或关联集合为空时记录警告，不会改为解锁其他位置。message 向在线参与者发送翻译消息。offer_powerup 要求 rogue_like 模式与非空强化池。

模式与成员边界

timed 创建初始截止时间；must_complete 阻止主动使用返回传送门，并选择原生地下城死亡重生流程。rogue_like 启用临时强化选项。common 和 hazard 不会自动创建敌人或完成规则。

同一实体入口会复用入口位置与地下城定义均匹配的活动会话。当前进入流程不比较进入者队伍与会话所记录的队伍键。因此，不能将 solo、party 或 open 视为访问控制或独立队伍隔离保证。已经绑定活动会话的玩家无法再开始另一场会话。

场景编写方块

编辑要求创造模式与权限等级 2。使用主手打开入口、触发器或控制器编辑器。四种方块与物品 ID 为 isekaiexpansion:dungeon_gateway、isekaiexpansion:dungeon_script_trigger、isekaiexpansion:dungeon_unlock_controller 和 isekaiexpansion:dungeon_unlockable。

1. 在世界入口结构内放置入口方块，并设置地下城 ID。非旁观者站在其范围内充能 40 刻（2 秒）；离开会清除充能，传送门冷却也会重置充能。
2. 在地下城模板内放置触发器，绑定 area_entered 脚本 ID。扫描使用球体范围、可选视线检查，以及 on_enter 或 while_present 激活方式；脚本仍受自身重放模式约束。
3. 对现有方块使用可解锁方块物品，将其方块状态保存为门的外观。保留的是方块状态，不包括原方块实体的物品栏或其他 NBT。外观不会替代门锁定时的完整方块碰撞。
4. 手持控制器物品，潜行使用控制器以选中它。再用该物品操作同维度的门单元，切换相对关联。
5. 配置控制器时序，并让 unlock_gate 动作指向它。新会话会重置定义中引用的控制器。解锁顺序取跨度最大的两个轴，从内向外顺时针展开；各单元直到自身动画结束才移除碰撞。

触发器每次扫描最多向一名玩家分发。占用者缓存不持久化，且只更新到本次分发前扫描过的玩家，因此 on_enter 不是可靠的逐玩家永久单次保证。需要持久的单次或冷却行为时，应使用脚本重放规则。

下列字段属于场景方块或控制器物品 NBT，与地下城定义 JSON 分开。编辑器会写入这些字段；表中也列出运行时字段，便于准确检查保存的结构。

入口、触发器与控制器几何对普通玩家不可见。可解锁单元锁定时保留外观，解锁后没有碰撞。触发器与控制器编辑更新要求玩家在 8 格以内；入口配置检查创造模式、管理员权限与方块类型，没有该距离检查。

内置临时强化

下列 ID 均使用 isekaiexpansion: 命名空间。每轮最多提供 3 个不同的可选强化，待选列表按参与者保存。未选择的列表会被复用；提交选择要求会话仍活动、玩家是参与者，且 ID 属于已提供选项。等级与待选列表在重新连接后恢复，离开或结算时清除等级。

这些事件效果要求玩家是身处会话维度的活动参与者。清除等级会停止后续钩子；已有的限时状态效果按自身时长到期。

完成进度

原生地下城成功完成时，会为在线参与者触发进度触发器 isekaiexpansion:dungeon_completed。其自定义条件字段如下；常规进度玩家谓词由 Minecraft 处理。此条件对象与严格的地下城定义格式分开。

校验

加载器逐文件捕获错误，并发布有效子集，即使其他文件失败也会替换。显式地下城 ID 重复时，保留加载器迭代顺序中首个成功插入的定义，并报告后续重复项。这不是回滚到旧目录的原子重载。

定义解析不会解析所有模板池、连接器、维度、脚本引用、实体类型或强化。进入时才规划拼图图结构，并拒绝缺失或空池、缺失起始连接器、不支持的结构片段，以及不包含锚点的布局。布局最多覆盖 256 个区块；预加载增加 1 个区块的边界，总上限为 1024 个区块。

初始入口搜索最多向水平方向搜索 8 格、垂直方向搜索 8 格，寻找脚部与头部无碰撞、无流体且下方有支撑碰撞形状的位置。参与者绑定前保存选定的脚部坐标。会话一旦有参与者，就保持该精确出生点；恢复损坏布局时不会静默改换位置。

在测试世界中验证成功进入和返回、各脚本重放模式、波次与门动画中途重启、缺失引用、生成位置失败，以及临近限时截止时的完成。应实际测试队伍准入，不要从 team_policy 推断隔离行为。

重载

定义使用服务端数据重载。有效条目替换旧目录；格式错误的条目可能在 /reload 后消失。活动会话在逐刻处理时查询当前定义，移除或使其定义失效会导致会话失败。已保存的原点、出生点、槽位与截止时间不会根据修改后的结构或时间字段重新计算。

编辑入口或触发器只修改已放置配置，不会改写 JSON 定义。定义重载不保证完整替换布局：已放置且到达点仍安全的会话可以继续使用现有方块。

相关页面

• 地下城运行时——生命周期、存档格式、钩子与命令。
• 进度数据——进度图定义。
• 任务目标——原生地下城完成目标与类型化 NBT。