世界维度加载器 (WDL) - 将外部世界作为维度加载

世界维度加载器 (WDL) - 将外部世界作为维度加载

将外部Minecraft世界作为轻量级、按需加载的维度导入。配置传送门、随机目的地池、稀有度/权重、返回旅行、锚点、重生规则和自动卸载。

World Dimension Loader (WDL)

将外部世界按需加载为维度

World Dimension Loader (WDL) 是一个适用于 Minecraft 1.20.1 的 Forge 模组，允许将现有的 Minecraft 世界注册为可配置的按需维度。

WDL 不会同时保持所有已注册世界加载状态，而是维护一个轻量级目录，并仅在真正需要时挂载外部世界。

这使得构建包含大量内容的整合包成为可能：

  • 冒险地图
  • 下载的世界
  • 旧生存世界
  • 地下城地图
  • 活动世界
  • 自定义地图
  • 测试世界

同时将活跃维度的数量保持在可控范围内。

✨ WDL 1.1.0 有哪些新内容？

WDL 1.1.0 扩展了维度传送系统，新增了玩家专属返回路线和可选的每维度床重生功能。

🌀 玩家返回历史

WDL 现在可以记住每个玩家通过普通维度传送门实际行进的路径。

示例：

主世界
   ↓
世界 A
   ↓
世界 B
   ↓
世界 C

在默认配置下，返回传送门可以带玩家沿该路线返回：

世界 C
↓
世界 B
↓
世界 A
↓
主世界

返回历史具有以下特性：

  • 为每个玩家单独存储
  • 多人游戏安全
  • 登出/登录后仍会保留
  • 服务器重启后仍会保留
  • 可配置存储条目数量为 1 到 10
  • 默认值：3 个条目
  • 仅在成功进行普通维度传送门旅行后记录

返回传送门旅行本身不会创建新的返回条目。

🔄 循环压缩

返回历史不是原始的旅行日志。

它代表玩家的未完成返回路径。

例如：

A → B → A

会关闭该路线。

同样：

A → B → C → A

也会关闭该循环。

当一个维度作为枢纽时，这一点特别有用：

A → B → A → C → A → D → A

WDL 不会用重复的 A 副本填满历史记录。

如果旅程最初从主世界开始：

主世界 → A → B → A → C → A

仍然有用的返回路径还是主世界。

🚪 返回传送门现在默认使用返回历史

默认配置：

[return_history]
return_gate_uses_history = true

如果存在有效的返回历史：

返回传送门
→ 上一个 WDL 传送门起点

如果不存在有效的历史记录：

返回传送门
→ 主世界回退

如果之前的维度已自动卸载，WDL 可以在返回玩家之前延迟挂载它。

📜 返回卷轴默认保持安全行为

返回卷轴默认仍然作为紧急返回主世界的逃生工具：

return_scroll_uses_history = false

默认行为：

WDL 维度
↓
返回卷轴
↓
主世界

您可以选择启用基于历史的卷轴返回：

return_scroll_uses_history = true

然后卷轴将按照玩家的返回历史后退一步。

返回卷轴的经验值消耗仅在成功返回后收取。

🛏️ 每维度床重生

WDL 维度现在可以单独允许床重生。

示例：

[dimensions.bed]
allow_bed_respawn = true

默认 / 省略

allow_bed_respawn = false

或者直接省略该段落。

行为：

  • 睡觉仍然可用
  • WDL 维度不会成为玩家的死亡重生目的地
  • 现有的安全 WDL 重生行为得以保留

启用

allow_bed_respawn = true

行为：

  • 睡觉可用
  • 该 WDL 维度中的床可以用作个人重生点
  • 如果维度已自动卸载，WDL 可能会为重生延迟挂载它
  • 如果床被破坏、阻挡、禁用或其他方式失效，WDL 会安全地回退到主世界

维度锚点不是死亡重生点。

它们的角色保持分离：

维度锚点
= 传送门到达点

床
= 明确允许时的死亡重生点

📘 WDL 新手？从这里开始！

JAR 内置了英文和日文教程

您无需自己摸索 WDL 的配置。

发布的 WDL .jar 文件包含详细的初学者友好文档，支持英文和日文：

WDL_README_EN.txt
WDL_README_JA.txt

使用 7-Zip 或 WinRAR 等软件将 .jar 文件作为压缩包打开。

内置指南从头开始解释 WDL，包括：

  • 安装 WDL
  • 单人游戏设置
  • 专用服务器设置
  • 外部世界放置位置
  • 注册您的第一个外部世界
  • 创建您的第一个维度传送门
  • 维度点火器
  • common.toml
  • dimensions.toml
  • gates.toml
  • 随机目的地传送门
  • 稀有度和权重
  • 传送门费用
  • 一个框架上的多个传送门定义
  • 维度锚点
  • 返回传送门
  • 返回卷轴
  • 返回历史
  • 循环压缩
  • 床重生
  • 自动卸载
  • 命令
  • 配置重载
  • 故障排除

如果您不确定如何开始：

下载 WDL
     ↓
将 .jar 作为压缩包打开
     ↓
打开 WDL_README_EN.txt
或
WDL_README_JA.txt
     ↓
跟随新手教程

日文用户： WDL_README_JA.txt 包含日文指南。

英文用户： WDL_README_EN.txt 包含英文指南。

您不需要在使用模组之前理解 WDL 的每个功能。

从一个世界和一个传送门开始。

🚀 快速开始

最简单的 WDL 设置是：

1 个外部世界
+
1 个维度传送门
+
1 个基础维度点火器

基本流程：

安装 WDL
↓
启动 Minecraft / 服务器一次
↓
将外部世界放入 WDL_custom_dimensions/
↓
在 dimensions.toml 中注册它
↓
在 gates.toml 中注册一个传送门
↓
运行 /wdl scan
↓
使用 /wdl list 确认 READY
↓
建造传送门
↓
使用点火器

外部世界作为维度

将外部 Minecraft 世界放置在：

WDL_custom_dimensions/

示例：

WDL_custom_dimensions/
├─ adventure_map/
├─ old_survival_world/
├─ dungeon_world/
└─ event_world/

每个世界文件夹应直接包含其 level.dat：

WDL_custom_dimensions/
└─ my_world/
   ├─ level.dat
   ├─ region/
   ├─ data/
   └─ ...

避免意外出现双重文件夹，例如：

WDL_custom_dimensions/my_world/my_world/level.dat

在 dimensions.toml 中注册每个世界。

WDL 会尽可能保留导入的世界生成信息，包括现有区块和源世界的生成器。

延迟维度加载

已注册的世界不会自动作为 ServerLevel 实例保持活跃。

WDL 将以下过程分离：

已注册世界
        ↓
轻量级维度目录
        ↓
仅在实际需要时
        ↓
延迟挂载
        ↓
活跃维度

这意味着：

300 个已注册世界

不意味着：

300 个同时加载的 ServerLevel

已注册世界的数量和活跃维度的数量是有意分开的。

可配置的维度传送门

WDL 包含一个高度可配置的传送门系统。

传送门定义可以控制：

  • 框架方块
  • 角落方块
  • 最小传送门尺寸
  • 最大传送门尺寸
  • 允许的点火器
  • 目的地池
  • LIST / ALL 选择
  • 开启时长
  • 永久传送门
  • 激活费用
  • 随机目的地选择

示例：

[[gates]]
id = "adventure_gate"
display_name = "冒险传送门"
enabled = true
gate_type = "DIMENSION"

frame_block = "minecraft:obsidian"
corner_block = "minecraft:crying_obsidian"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 8
max_inner_height = 8

allowed_igniters = []

selection_mode = "LIST"
dimensions = ["world_a", "world_b", "world_c"]

open_time_seconds = 10

维度点火器

WDL 包含三种内置的传送门激活器。

基础维度点火器

一种消耗性的传送门激活器。

高级维度点火器

一种可重复使用的、具有耐久度的高级点火器。

创造模式维度点火器

无限使用的管理/测试点火器。

如果：

allowed_igniters = []

WDL 允许所有三种内置点火器。

您也可以明确限制某个传送门：

allowed_igniters = [
  "worlddimensionloader:advanced_dimension_igniter"
]

一个物理框架，多个传送门定义

同一个物理传送门框架可以使用不同的传送门定义。

示例：

基础点火器
→ 普通世界池

高级点火器
→ 危险 / 稀有世界池

WDL 根据以下信息解析传送门：

  • 框架方块
  • 角落方块
  • 实际框架尺寸
  • 使用的点火器

这使得一个建筑可以像维度终端一样工作。

为避免安全问题，歧义的传送门配置会被拒绝，而不是按配置顺序解析。

日志标记：

WDL GATE_CONFIG_AMBIGUOUS

🎲 随机维度、稀有度和权重

一个维度传送门可以包含多个目的地世界。

支持的选择模式：

LIST
ALL

每个维度可以使用：

COMMON
UNCOMMON
RARE
EPIC
LEGENDARY
CUSTOM

默认稀有度权重：

COMMON = 100
UNCOMMON = 60
RARE = 25
EPIC = 10
LEGENDARY = 3

数值越高表示该维度被选中的可能性越大。

这些数值是权重，不是直接百分比。

权重是可选的

您不需要为每个维度配置 weight。

这样是有效的：

rarity = "RARE"

如果省略 weight，WDL 使用配置的 RARE 稀有度权重。

仅在您想要覆盖稀有度时才使用显式权重：

rarity = "RARE"
weight = 8

显式权重会覆盖稀有度。

随机传送门每次新激活都会重新随机

示例：

传送门开启
→ 选择世界 A

传送门关闭

传送门再次开启
→ 选择世界 C

每次传送门被新激活时都会选择一个新目的地。

对于永久传送门：

open_time_seconds = -1

在该传送门保持开启期间，所选目的地保持固定。

关闭并重新打开它以进行新的选择。

当前维度自动排除

示例：

当前维度：
world_a

配置的池：
world_a
world_b
world_c

实际候选：

world_b
world_c

这防止维度传送门变成同维度的出生点传送。

如果没有有效目的地剩余，传送门将拒绝开启，且不消耗激活交易。

传送门费用

传送门激活可以要求一项或多项费用。

支持的费用类型：

  • 物品
  • 经验等级
  • 经验值
  • 生命值
  • 饥饿值

示例：

[[gates.costs]]
type = "XP_LEVEL"
amount = 5

或：

[[gates.costs]]
type = "ITEM"
item = "minecraft:ender_pearl"
amount_mode = "FIXED"
amount = 2

可以组合多项费用。

WDL 在提交配置的支付之前会验证交易。

维度锚点

维度锚点存储 WDL 维度内的首选到达点。

目的地优先级：

1. 维度锚点
2. 导入的世界出生点
3. 配置的回退坐标

锚点存储位置和玩家朝向。

正常使用：

注册锚点

Shift-使用：

移除锚点

锚点可重复使用，不会被消耗。

锚点控制传送门到达位置。它不是死亡重生点。

返回传送门

返回传送门提供专门的返回传送门。

在 WDL 1.1.0 中，默认配置为：

[return_history]
return_gate_uses_history = true

这意味着返回传送门通常会遵循玩家的返回历史。

示例：

主世界 → A → B → C

返回传送门路径：

C → B → A → 主世界

如果不存在有效的返回历史，传送门会回退到主世界。

返回传送门仍然可以拥有：

  • 自己的框架设计
  • 自己的点火器规则
  • 自己的激活费用
  • 定时开启
  • 永久开启

返回卷轴

返回卷轴可重复使用，支持：

  • 全局经验等级消耗
  • 每维度费用覆盖
  • 费用 0 表示免费返回
  • 创造模式豁免
  • 每维度禁用 / 封印
  • 可选的返回历史行为

默认配置：

return_scroll_uses_history = false

因此卷轴仍然是直接返回主世界的紧急逃生工具。

可选配置：

return_scroll_uses_history = true

然后它会按返回历史后退一步。

🛏️ 床重生

床重生按维度控制。

示例：

[dimensions.bed]
allow_bed_respawn = true

默认

如果省略该设置：

allow_bed_respawn = false

行为：

睡觉
→ 允许

设置 WDL 床重生
→ 阻止

这使默认 WDL 行为在自动卸载环境中保持安全。

启用

allow_bed_respawn = true

允许 WDL 维度成为个人床重生目的地。

如果需要，WDL 可以在死亡后延迟挂载目标维度。

如果床或目的地不再有效，WDL 会安全地回退到主世界。

重生处理

如果没有明确允许 WDL 床重生，WDL 可以将导入维度中的死亡重定向到：

个人主世界出生点
        ↓
主世界世界出生点

重生行为也可以按维度配置。

示例：

[dimensions.respawn]
mode = "INHERIT"

INHERIT 表示该维度使用 common.toml 中的全局 WDL 重生行为。

传送门生命周期安全

活跃的传送门会持续验证其加载的结构。

如果必需的框架方块、角落方块或传送门方块被破坏或替换：

传送门变为无效
        ↓
传送门被移除
        ↓
活跃传送门会话被清除
        ↓
传送门完全关闭

WDL 还会检测过期的 OPEN 状态。

一个被破坏的传送门不应永久保持为"已开启"锁定状态。

恢复框架后，传送门可以再次开启。

自动卸载

未使用的 WDL 维度可以自动卸载。

示例：

[runtime]
max_loaded_dimensions = 4
auto_unload = true
unload_delay_seconds = 300

示例架构：

100 个已注册的外部世界
        ↓
轻量级目录
        ↓
仅挂载当前需要的世界
        ↓
未使用的世界可能自动卸载

返回历史和启用的床重生可以在需要时重新挂载已卸载的 WDL 维度。

配置

主要配置文件：

config/worlddimensionloader/common.toml
config/worlddimensionloader/dimensions.toml
config/worlddimensionloader/gates.toml

外部世界：

WDL_custom_dimensions/

更改 WDL 配置后，运行：

/wdl scan

这将重载 WDL 配置并重建外部世界目录。

重要 TOML 说明

不要留空值。

错误的做法：

weight =
fallback_x =

这是无效的 TOML，可能会阻止配置正确加载。

对于 weight 等可选值，请省略该行。

命令

WDL 包含管理和诊断命令：

/wdl scan
/wdl list
/wdl status
/wdl loaded
/wdl anchors
/wdl load <id>
/wdl mount <id>
/wdl unload <id>
/wdl tp <id>
/wdl probe <id>

大多数 WDL 命令需要权限等级 2 或更高。

正常的传送门游戏玩法不需要手动挂载维度。

📘 JAR 内的完整文档

WDL 包含详细的设置指南：

WDL_README_EN.txt
WDL_README_JA.txt

这些不是简短的注释。

它们旨在作为完整的初学者友好配置指南，无需外部 Wiki。

主题包括：

  • 快速设置
  • 单人游戏
  • 专用服务器
  • 外部世界放置
  • 配置重载
  • common.toml
  • dimensions.toml
  • gates.toml
  • 随机传送门
  • 稀有度 / 权重
  • 可选权重行为
  • LIST / ALL
  • 多个传送门定义
  • 点火器
  • 传送门费用
  • 锚点
  • 返回传送门
  • 返回卷轴
  • 返回历史
  • 循环压缩
  • 每维度床重生
  • 自动卸载
  • 命令
  • 故障排除
  • 物品配方

如果您不确定如何配置 WDL，强烈建议查看内置的 README。

存储模式

WDL 1.1.0 使用 IMPORT 作为稳定的存储路径。

IMPORT = 稳定
AUTO   = 使用经过验证的 IMPORT 行为
DIRECT = 未来 / 实验性

DIRECT 存储不被视为 WDL 1.1.0 的稳定功能。

兼容性

设计用于：

  • Minecraft 1.20.1
  • Forge 47.4.22
  • Java 17

WDL 还包含在使用了 Valkyrien Skies 2.4.11 的环境中卸载 / 相同 ID 重新挂载行为的兼容性工作。

由于外部世界和重度模组环境差异巨大：

在导入重要世界之前，请务必备份。

多人游戏

WDL 支持专用服务器使用。

在以下位置安装 WDL：

服务器
+
参与客户端

双方使用相同的 WDL 版本。

外部世界文件夹只需要在服务器上存在。

WDL 1.1.0 的返回历史按每个玩家的 UUID 单独存储，因此多个玩家可以穿越同一个传送门网络而不会互相覆盖返回路径。

推荐的首个设置

如果您是 WDL 新手：

1 个外部世界
+
1 个维度传送门
+
1 个基础维度点火器

先确认这能正常工作。

然后逐步添加：

  1. 多个世界
  2. 随机传送门池
  3. 稀有度 / 权重
  4. 多个传送门定义
  5. 传送门费用
  6. 返回传送门
  7. 返回历史
  8. 床重生
  9. 自动卸载

玩法创意 / 示例设置

WDL 有意采用配置驱动的方式。

以下仅为示例。

🎲 随机冒险传送门

在一个传送门后面注册多个下载的冒险地图。

一个传送门
   ↓
COMMON 世界
COMMON 世界
RARE 世界
LEGENDARY 世界

每次激活都可能去往不同的地方。

🗝️ 稀有秘密维度

添加一个隐藏世界：

rarity = "LEGENDARY"

或者给它一个非常低的显式权重。

大多数传送门激活会到达普通世界。

偶尔：

传送门开启
↓
秘密维度

🧭 多世界远征

示例：

主基地
↓
世界 A
↓
世界 B
↓
世界 C

使用返回历史：

世界 C
↓
世界 B
↓
世界 A
↓
主基地

返回卷轴可以保持为直接返回主世界的紧急逃生工具。

🏛️ 枢纽辐射式探索

使用世界 A 作为中央枢纽：

A → 地下城 → A
A → 城市 → A
A → Boss 世界 → A

返回历史的循环压缩可防止重复的枢纽访问填满历史记录。

🛏️ 持久生存维度

对于旨在作为长期家园的维度：

[dimensions.bed]
allow_bed_respawn = true

玩家可以在那里睡觉并使用床作为个人重生点。

对于临时冒险地图，只需省略该设置，保持仅可睡觉。

🌀 一个框架，多个目的地池

使用一个物理框架：

基础点火器
→ 普通世界

高级点火器
→ 危险 / 稀有世界

一个建筑可以表现得像维度终端。

⚔️ 传送门等级

创建基于进度的传送门设计：

石制传送门
→ 便宜
→ COMMON

黑曜石传送门
→ 经验 + 物品费用
→ RARE

远古传送门
→ 昂贵
→ EPIC / LEGENDARY

🧱 永久枢纽传送门

创建永久传送门基础设施：

open_time_seconds = -1

可能的分类：

冒险世界
地下城世界
建筑世界
活动世界
稀有世界

⏱️ 定时传送门事件

使用：

open_time_seconds = 10

创建短暂存在的传送门。

结合激活费用用于服务器活动。

📚 大型世界库

示例：

WDL_custom_dimensions/
├─ adventure_map_01
├─ adventure_map_02
├─ old_survival_world
├─ build_showcase
├─ dungeon_map
├─ event_2025
└─ event_2026

WDL 保持世界已注册，同时只挂载需要的内容。

AI 辅助开发 / 开发者说明

WDL 是一个由独立业余开发者创建的个人项目。

我不是专业软件开发者，这个项目在编程、调试、代码审查、文档编写、测试流程和开发规划方面得到了 AI 工具的显著帮助。

AI 辅助并不意味着模组未经测试就生成并发布。

WDL 在开发过程中经历了反复的构建、运行时测试、回归测试、错误修复和游戏内手动验证。

然而，WDL 仍应被视为社区制作的软件。

在使用模组之前，请务必备份重要的世界，尤其是在测试新配置或外部世界时。

包含以下信息的错误报告尤其有用：

  • WDL 版本
  • Minecraft / Forge 版本
  • 相关配置
  • latest.log
  • 适用时的 debug.log
  • 清晰的复现步骤

WDL 1.1.0 配置默认值

返回历史：

[return_history]
max_entries = 3
return_gate_uses_history = true
return_scroll_uses_history = false

每维度床重生：

[dimensions.bed]
allow_bed_respawn = false

请记住：

如果省略 allow_bed_respawn，则视为 false。

World Dimension Loader (WDL)

将外部 Minecraft 世界变为可配置的维度网络