World Dimension Loader (WDL)

Turn Existing Minecraft Worlds Into Playable Dimensions

World Dimension Loader (WDL) is a Forge mod for Minecraft 1.20.1 that lets you import existing Minecraft world saves and use them as separate Dimensions inside your current game or server.

You can use WDL with:

• Adventure maps
• Old survival worlds
• Dungeon maps
• Event worlds
• Challenge maps
• Building or showcase worlds
• Persistent secondary worlds
• Resettable dungeon worlds
• Timed challenge worlds

The basic idea is simple:

Register multiple worlds, but only load the Dimensions that are actually needed.

Current Versions

Stable Release

WDL 1.4.0

This is the recommended version if you want the most stable experience.

Beta Release

WDL 1.4.1-beta3

This beta adds the new in-game WDL Workbench GUI and several administration improvements.

The beta has passed Build, package verification, startup, Protocol 11, and generated-Config checks.

However, it is still a beta release.

If you experience problems with 1.4.1-beta3, especially GUI-related problems, please try WDL 1.4.0.

Documentation Is Included in the JAR

WDL includes detailed English and Japanese documentation directly inside the JAR file.

If you are using WDL for the first time, start with the included Tutorial.

For WDL 1.4.1-beta3:

docs/EN/WDL_TUTORIAL_EN_1.4.1-beta3.txt
docs/JA/WDL_TUTORIAL_JA_1.4.1-beta3.txt

The Tutorial explains how to create your first WDL Dimension using either:

• the Workbench GUI
• or direct Config editing

The JAR also includes guides for:

• GUI settings
• Config options
• Commands
• Items and recipes
• Examples and play ideas
• Troubleshooting
• Updating from older versions

You can open the JAR with 7-Zip, WinRAR, or another archive tool to read the documentation.

The generated Config files also include comments and examples.

You do not need to understand every WDL feature before starting. Start with one world, one Dimension, and one Gate.

Quick Start

For your first WDL setup, start with:

1 copied Minecraft world
+
1 WDL Dimension
+
1 Gate

Place a copy of your Minecraft world here:

WDL_custom_dimensions/test_world_01/

Make sure this file exists:

WDL_custom_dimensions/test_world_01/level.dat

You can then configure the Dimension using either:

• the WDL Workbench GUI in 1.4.1-beta3;
• or the Config files directly.

WDL 1.4.1-beta3 Workbench GUI

1.4.1-beta3 introduces the WDL Workbench.

It can be used to manage:

• Dimensions
• Gates
• Common settings

You can create and edit WDL definitions without manually editing every TOML file.

The Workbench is intended for administrators and requires:

• Creative mode
• Permission level 2 or higher

Dimension definition deletion is not available from the Workbench in this beta.

Gate definition deletion is available with confirmation and safety checks.

Important GUI Support Notice

The in-game GUI was a particularly difficult and time-consuming feature to implement for this project.

Because of this, the Workbench GUI is provided on a best-effort basis.

GUI-specific problems may not be fixed or supported.

If the GUI does not work correctly in your environment, please use the Config-based setup method instead.

If you continue to have problems with WDL 1.4.1-beta3, please try the stable WDL 1.4.0 release.

Reports involving serious issues such as crashes, world-data problems, or problems affecting WDL outside of the GUI are still useful.

Config-Based Setup

You can use WDL without the Workbench.

Minimal dimensions.toml:

[[dimensions]]
id = "test_world_01"

Minimal gates.toml:

[[gates]]
id = "test_world_01_gate"
dimensions = ["test_world_01"]

After editing the Config files, run:

/wdl scan

or restart Minecraft / the server.

With the minimum Gate Config:

• frame_block defaults to minecraft:obsidian
• corner_block defaults to the same block as frame_block

So if both settings are omitted, the Gate uses obsidian for both the frame and corners.

Dimension Gates

Players normally enter WDL Dimensions through configurable Gates.

The physical Gate appearance is configured directly in gates.toml.

Default Gate Blocks

[[gates]]
id = "adventure_gate"
dimensions = ["adventure_world"]

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

frame_block controls the main Gate frame.

corner_block controls the four corner blocks.

The defaults are:

frame_block = "minecraft:obsidian"

If corner_block is omitted, it automatically uses the same block as frame_block.

So this minimum Gate:

[[gates]]
id = "adventure_gate"
dimensions = ["adventure_world"]

uses:

Frame  = minecraft:obsidian
Corner = minecraft:obsidian

Custom Gate Blocks

The frame and corners can be configured separately.

Example:

[[gates]]
id = "adventure_gate"
frame_block = "minecraft:stone_bricks"
corner_block = "minecraft:gold_block"
dimensions = ["adventure_world"]

This creates a Gate using:

Frame  = Stone Bricks
Corner = Gold Block

Another example:

[[gates]]
id = "magic_gate"
frame_block = "minecraft:crying_obsidian"
corner_block = "minecraft:amethyst_block"
dimensions = ["magic_world"]

This makes it easy to give different Gate types their own visual identity.

You can also configure:

• Specific destinations
• Multiple destinations
• Random destinations
• Gate size
• Opening duration
• Reopen cooldown
• Allowed Igniters
• Item costs
• XP costs
• Health costs
• Hunger costs

When creating several Gates, different frame/corner combinations can also help distinguish physical Gate definitions.

Lazy Dimension Loading

WDL does not keep every registered world loaded all the time.

Registered Worlds
↓
WDL Catalog
↓
Player Needs a Dimension
↓
Dimension Loads
↓
Player Enters

This allows several worlds to be registered without keeping all of them active at once.

Persistent and Resettable Dimensions

WDL supports both persistent and resettable worlds.

Persistent World

[dimensions.runtime]
reset_on_empty = false

Use this when changes inside the Dimension should remain.

Good for:

• Secondary survival worlds
• Building worlds
• Colony worlds
• Technology worlds
• Magic worlds
• Persistent hubs

Resettable World

[dimensions.runtime]
reset_on_empty = true
reset_delay_seconds = 30

When everyone leaves the Dimension, WDL can create a fresh Runtime generation from the imported source world.

Good for:

• Repeatable dungeons
• Loot runs
• Boss arenas
• Event worlds
• Challenge maps

Important

Changes made inside a resettable Runtime Dimension may be lost after Reset.

The original source copy inside:

WDL_custom_dimensions/<world-id>/

is kept separately.

Timed Dimensions

WDL supports Timed Sessions.

Example:

[dimensions.time_limit]
minutes = 10
exit_destination = "PREVIOUS"

This can be used for:

• Timed dungeons
• Survival challenges
• Events
• Escape maps
• Boss encounters

Players can be returned to their previous location or the Overworld when the timer ends.

Inventory and Travel Rules

WDL can restrict:

• Items entering a Dimension
• Items leaving a Dimension
• Allowed source Dimensions
• Allowed destination Dimensions

This can be useful for adventure maps, challenge worlds, progression systems, and server events.

Other Features

WDL also includes support for:

• Dimensional Anchors
• Return Scrolls
• Optional bed respawn
• Gate travel history
• Random destination weights
• Rarity-based destinations
• Per-Dimension game mode
• Per-Dimension difficulty
• Fixed world time
• Runtime Reset recovery
• Startup cleanup
• Restart recovery

Ways to Play

1. Simple Adventure World

Overworld
↓
Adventure Gate
↓
Adventure Map

[[dimensions]]
id = "adventure_world"

[[gates]]
id = "adventure_gate"
dimensions = ["adventure_world"]

Good for downloaded adventure maps, old saves, puzzle maps, and exploration worlds.

2. Persistent Secondary Survival World

Overworld
↓
Secondary Survival World
↓
Build / Explore / Progress
↓
Progress remains

[[dimensions]]
id = "secondary_survival"

[dimensions.runtime]
reset_on_empty = false

Useful for long-term secondary worlds, colonies, technology, magic, and building worlds.

3. Resettable Dungeon

Enter Dungeon
↓
Explore / Fight / Loot
↓
Everyone leaves
↓
Reset
↓
Fresh Dungeon

[[dimensions]]
id = "dungeon_01"

[dimensions.runtime]
reset_on_empty = true
reset_delay_seconds = 30

Useful for repeatable dungeons, loot runs, boss arenas, and server events.

4. Timed Challenge Dungeon

Enter
↓
10 minute challenge
↓
Time expires
↓
Player is returned
↓
Dungeon resets

[[dimensions]]
id = "timed_dungeon"

[dimensions.runtime]
reset_on_empty = true
reset_delay_seconds = 30

[dimensions.time_limit]
minutes = 10
exit_destination = "PREVIOUS"

Useful for speed challenges, escape maps, timed loot runs, and boss fights.

5. Random Adventure Gate

Mystery Gate
├─ Forest Adventure
├─ Desert Dungeon
├─ Rare Challenge
└─ Secret World

Multiple destinations can be combined with WDL's random selection, rarity, and weight settings.

This works well for:

• Random adventures
• Roguelike-style progression
• Server events
• Mystery portals
• Rare secret worlds

6. Custom Gate Designs

Gate appearances are defined using the same Config format used by WDL.

Adventure Gate:

[[gates]]
id = "adventure_gate"
frame_block = "minecraft:mossy_stone_bricks"
corner_block = "minecraft:chiseled_stone_bricks"
dimensions = ["adventure_world"]

Magic Gate:

[[gates]]
id = "magic_gate"
frame_block = "minecraft:crying_obsidian"
corner_block = "minecraft:amethyst_block"
dimensions = ["magic_world"]

Treasure Gate:

[[gates]]
id = "treasure_gate"
frame_block = "minecraft:deepslate_tiles"
corner_block = "minecraft:gold_block"
dimensions = ["treasure_world"]

This allows a hub or server to use different Gate appearances for different destinations.

7. Equipment-Restricted Challenge

Main World
↓
Challenge Gate
↓
Limited Equipment
↓
Find Equipment Inside
↓
Return With Allowed Rewards

Inventory Policies can control what players may bring into or take out of the Dimension.

8. One-Way Progression

Overworld
↓
Stage 1
↓
Stage 2
↓
Stage 3
↓
Final World

Travel Policies can be used to create controlled progression routes.

9. Central Dimension Hub

Overworld
   ↓
Central Hub
   ├─ Survival World
   ├─ Adventure Map
   ├─ Random Dungeon
   ├─ Timed Challenge
   ├─ Equipment Challenge
   └─ Secret Rare World

Each Gate can use its own frame_block and corner_block combination.

Turn separate Minecraft worlds into parts of one connected game.

How WDL Stores Runtime Worlds

WDL keeps the imported source world and the playable Runtime world separate.

Your imported source copy stays under:

WDL_custom_dimensions/<world-id>/

When WDL creates the playable Runtime Dimension, its data is stored inside the Minecraft save under:

dimensions/wdl/

For example:

WDL_custom_dimensions/adventure_world/

can produce Runtime data under:

<save>/dimensions/wdl/adventure_world/

This allows WDL to preserve the imported source while managing the playable Runtime copy separately.

Persistent Worlds and Physical IDs

For persistent Dimensions with Reset disabled, WDL uses a stable physical Dimension ID.

Example:

Logical WDL Dimension:
worlddimensionloader:survival_world

Physical Runtime Dimension:
wdl:survival_world

Runtime storage:
dimensions/wdl/survival_world/

Reset Worlds and Timestamp Generations

Reset-enabled Dimensions use timestamp-based Runtime generations.

For example:

wdl:dungeon_01/20260916031542

with storage such as:

dimensions/wdl/dungeon_01/20260916031542/

After another Reset:

dimensions/wdl/dungeon_01/20260916040218/

may become the next active generation.

Older generations can then be retired and cleaned up when WDL determines that it is safe.

Why Reset Worlds Still Use Timestamps

During development, significant effort was made to remove timestamp-based Runtime Dimension IDs and use stable physical IDs everywhere.

For persistent, Reset-disabled worlds, this was successfully implemented.

For Reset-enabled worlds, however, completely removing timestamp generations could not be done safely enough.

Minecraft or other mods may still hold references to the previous Runtime Dimension when a Reset occurs.

Immediately replacing the same physical Dimension can introduce risks such as:

• Stale Dimension references
• Cached world data
• Unload timing problems
• Other-mod references
• Reset conflicts
• Restart/recovery problems

Because of these safety and compatibility concerns, Reset-enabled worlds continue to use timestamp generations.

In short:

Persistent / Reset OFF
→ Stable physical ID
→ dimensions/wdl/<id>/

Reset ON
→ Timestamp generations
→ dimensions/wdl/<id>/<timestamp>/

The goal was to remove timestamps completely, but for Reset-enabled worlds this could not be achieved without compromising the safety model.

For WDL, protecting Runtime/world data is more important than having a simpler folder structure.

Reset Storage and Disk Usage

Because old timestamp generations cannot always be removed immediately, frequent Reset use may temporarily increase disk usage.

Current generation
↓
Reset
↓
New timestamp generation
↓
Old generation becomes retired
↓
Safe cleanup later

If you use large resettable worlds or reset them frequently, monitor available disk space.

Do not manually delete Runtime generation folders while Minecraft or the server is running.

Useful Commands

/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>

Most administrative commands require permission level 2 or higher.

Some settings require a full Minecraft/server restart.

Multiplayer

WDL supports dedicated servers.

Install the same WDL version on:

Server
+
Participating Clients

The imported external world folders only need to exist on the server.

Compatibility

Designed for:

• Minecraft 1.20.1
• Forge 47.4.22+
• Java 17

WDL includes Runtime lifecycle handling intended for heavily modded environments.

Additional compatibility handling exists for environments using mods such as:

• Valkyrien Skies
• Distant Horizons

These mods are optional.

Compatibility with every mod or future mod version cannot be guaranteed.

Back Up Your Worlds

Before importing worlds, updating WDL, changing Runtime settings, or testing a beta version, back up:

Minecraft save
WDL_custom_dimensions/
config/worlddimensionloader/

Do not manually rename, move, or delete WDL Runtime Dimension folders unless you understand the consequences.

When WDL cannot safely determine which Runtime data is authoritative, it may intentionally stop instead of guessing.

Updating

Using WDL 1.4.0

WDL 1.4.0 is the current stable release.

If stability is more important than the new Workbench GUI, use 1.4.0.

Testing WDL 1.4.1-beta3

1.4.1-beta3 is a beta release.

Back up your world before testing it.

If the beta or its GUI causes problems:

1. stop Minecraft / the server;
2. restore your backup if necessary;
3. try WDL 1.4.0.

Do not assume that every beta Config or Runtime state can safely be downgraded automatically.

AI-Assisted Development

WDL is a personal project created by an independent hobby developer.

I am not a professional software developer.

WDL has been developed with significant assistance from AI tools for:

• Programming
• Debugging
• Code review
• Documentation
• Testing workflows
• Development planning

The mod has also gone through repeated Build and in-game testing.

Useful bug reports include:

• WDL version
• Minecraft version
• Forge version
• Relevant Config files
• latest.log
• debug.log when applicable
• Clear reproduction steps

Please note again that GUI-specific issues in WDL 1.4.1-beta3 may not receive support or fixes.

World Dimension Loader

Take Minecraft worlds that were originally separate and connect them into one larger game.