World Dimension Loader (WDL)

Load External Worlds as On-Demand Dimensions

World Dimension Loader (WDL) is a Forge mod for Minecraft 1.20.1 that allows existing Minecraft worlds to be registered and used as configurable, on-demand dimensions.

Instead of keeping every registered world loaded at the same time, WDL maintains a lightweight catalog and mounts external worlds only when they are actually needed.

This makes it possible to build setups containing many:

• Adventure maps
• Downloaded worlds
• Old survival worlds
• Dungeon maps
• Event worlds
• Custom maps
• Testing worlds

while keeping the number of active dimensions under control.

---

✨ What's New in WDL 1.1.0?

WDL 1.1.0 expands the dimension-travel system with player-specific return routes and optional per-dimension Bed Respawn.

🌀 Player Return History

WDL can now remember the path each player actually traveled through normal DIMENSION Gates.

Example:

Overworld
   ↓
World A
   ↓
World B
   ↓
World C

With the default configuration, a RETURN Gate can take the player back through that route:

World C
↓
World B
↓
World A
↓
Overworld

Return History is:

• Stored separately for each player
• Multiplayer-safe
• Persistent through logout/login
• Persistent through server restarts
• Configurable from 1 to 10 stored entries
• Default: 3 entries
• Recorded only after successful normal DIMENSION Gate travel

Return Gate travel itself does not create another return entry.

---

🔄 Loop Compression

Return History is not a raw travel log.

It represents the player's unfinished return path.

For example:

A → B → A

closes that route.

And:

A → B → C → A

also closes the loop.

This is especially useful when one dimension acts as a hub:

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

WDL does not fill the history with repeated copies of A.

If the journey originally started in the Overworld:

Overworld → A → B → A → C → A

the useful remaining return path is still the Overworld.

---

🚪 RETURN Gates Now Use Return History by Default

Default:

[return_history]
return_gate_uses_history = true

If valid Return History exists:

RETURN Gate
→ Previous WDL Gate origin

If no valid history exists:

RETURN Gate
→ Overworld fallback

If the previous dimension was Auto-Unloaded, WDL can Lazy Mount it before returning the player.

---

📜 Return Scroll Behavior Remains Safe by Default

The Return Scroll still behaves as an emergency Overworld escape by default:

return_scroll_uses_history = false

Default behavior:

WDL Dimension
↓
Return Scroll
↓
Overworld

You may optionally enable history-based Scroll return:

return_scroll_uses_history = true

Then the Scroll returns one step through the player's Return History.

Return Scroll XP cost is charged only after a successful return.

---

🛏️ Per-Dimension Bed Respawn

WDL dimensions can now individually allow Bed Respawn.

Example:

[dimensions.bed]
allow_bed_respawn = true

Default / omitted

allow_bed_respawn = false

or simply omit the section.

Behavior:

• Sleeping still works
• The WDL dimension does not become the player's death-respawn destination
• Existing safe WDL respawn behavior is preserved

Enabled

allow_bed_respawn = true

Behavior:

• Sleeping works
• Beds in that WDL dimension may be used as personal respawn points
• If the dimension has been Auto-Unloaded, WDL may Lazy Mount it for respawn
• If the bed was destroyed, blocked, disabled, or otherwise invalid, WDL falls back safely toward the Overworld

Dimensional Anchors are not death-respawn points.

Their roles remain separate:

Dimensional Anchor
= Gate arrival point

Bed
= Death respawn point when explicitly allowed

---

📘 New to WDL? Start Here!

English & Japanese Tutorials Are Included Inside the JAR

You do not need to figure out WDL's configuration by yourself.

The distributed WDL .jar contains detailed beginner-friendly documentation in English and Japanese:

WDL_README_EN.txt
WDL_README_JA.txt

Open the .jar as an archive using software such as 7-Zip or WinRAR.

The included guides explain WDL from the beginning, including:

• Installing WDL
• Singleplayer setup
• Dedicated server setup
• Where to place external worlds
• Registering your first external world
• Creating your first Dimension Gate
• Dimension Igniters
• common.toml
• dimensions.toml
• gates.toml
• Random destination Gates
• Rarity and weights
• Gate costs
• Multiple Gate definitions on one frame
• Dimensional Anchors
• Return Gates
• Return Scrolls
• Return History
• Loop compression
• Bed Respawn
• Auto-Unload
• Commands
• Config reload
• Troubleshooting

If you are unsure how to begin:

Download WDL
     ↓
Open the .jar as an archive
     ↓
Open WDL_README_EN.txt
or
WDL_README_JA.txt
     ↓
Follow the beginner tutorial

Japanese users: WDL_README_JA.txt contains the Japanese guide.

English users: WDL_README_EN.txt contains the English guide.

You do not need to understand every WDL feature before using the mod.

Start with one world and one Gate.

---

🚀 Quick Start

The simplest possible WDL setup is:

1 external world
+
1 DIMENSION Gate
+
1 Basic Dimension Igniter

Basic workflow:

Install WDL
↓
Start Minecraft / server once
↓
Place an external world in WDL_custom_dimensions/
↓
Register it in dimensions.toml
↓
Register a Gate in gates.toml
↓
Run /wdl scan
↓
Confirm READY with /wdl list
↓
Build the Gate
↓
Use an Igniter

---

External Worlds as Dimensions

Place external Minecraft worlds inside:

WDL_custom_dimensions/

Example:

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

Each world folder should contain its level.dat directly:

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

Avoid accidental double folders such as:

WDL_custom_dimensions/my_world/my_world/level.dat

Register each world in dimensions.toml.

WDL preserves imported world-generation information where possible, including existing chunks and the source world's generator.

---

Lazy Dimension Loading

Registered worlds are not automatically kept active as ServerLevel instances.

WDL separates:

Registered Worlds
        ↓
Lightweight Dimension Catalog
        ↓
Only when needed
        ↓
Lazy Mount
        ↓
Live Dimension

This means:

300 registered worlds

does not mean:

300 simultaneously loaded ServerLevels

The number of registered worlds and the number of live dimensions are intentionally separate.

---

Configurable Dimension Gates

WDL includes a highly configurable Gate system.

Gate definitions can control:

• Frame blocks
• Corner blocks
• Minimum Gate size
• Maximum Gate size
• Allowed Igniters
• Destination pools
• LIST / ALL selection
• Opening duration
• Permanent Gates
• Activation costs
• Random destination selection

Example:

[[gates]]
id = "adventure_gate"
display_name = "Adventure Gate"
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

---

Dimension Igniters

WDL includes three built-in Gate activators.

Basic Dimension Igniter

A consumable Gate activator.

Advanced Dimension Igniter

A reusable higher-tier Igniter with durability.

Creative Dimension Igniter

Unlimited administrative / testing Igniter.

If:

allowed_igniters = []

WDL allows all three built-in Igniters.

You may also explicitly restrict a Gate:

allowed_igniters = [
  "worlddimensionloader:advanced_dimension_igniter"
]

---

One Physical Frame, Multiple Gate Definitions

The same physical Gate frame can use different Gate definitions.

Example:

Basic Igniter
→ Normal world pool

Advanced Igniter
→ Dangerous / rare world pool

WDL resolves the Gate using:

• Frame block
• Corner block
• Actual frame size
• Used Igniter

This allows one structure to work like a dimensional terminal.

Ambiguous Gate configurations are rejected for safety instead of being resolved by config order.

Log marker:

WDL GATE_CONFIG_AMBIGUOUS

---

🎲 Random Dimensions, Rarity and Weight

A DIMENSION Gate can contain multiple destination worlds.

Supported selection modes:

LIST
ALL

Each dimension may use:

COMMON
UNCOMMON
RARE
EPIC
LEGENDARY
CUSTOM

Default rarity weights:

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

Higher values mean the dimension is more likely to be selected.

These values are weights, not direct percentages.

---

Weight Is Optional

You do not need to configure weight for every dimension.

This is valid:

rarity = "RARE"

If weight is omitted, WDL uses the configured RARE rarity weight.

Use an explicit weight only when you want to override the rarity:

rarity = "RARE"
weight = 8

Explicit weight overrides rarity.

---

Random Gates Reroll on Every New Activation

Example:

Gate opens
→ World A selected

Gate closes

Gate opens again
→ World C selected

A new destination is selected each time the Gate is newly activated.

For a permanent Gate:

open_time_seconds = -1

the selected destination remains fixed while that Gate stays open.

Close and reopen it to perform another selection.

---

Current Dimension Is Automatically Excluded

Example:

Current Dimension:
world_a

Configured pool:
world_a
world_b
world_c

Actual candidates:

world_b
world_c

This prevents a DIMENSION Gate from becoming a same-dimension spawn teleport.

If no valid destination remains, the Gate refuses to open without consuming the activation transaction.

---

Gate Costs

Gate activation can require one or more costs.

Supported:

• Items
• XP Levels
• XP Points
• Health
• Hunger

Example:

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

or:

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

Multiple costs can be combined.

WDL validates the transaction before committing the configured payment.

---

Dimensional Anchor

The Dimensional Anchor stores the preferred arrival point inside a WDL dimension.

Destination priority:

1. Dimensional Anchor
2. Imported World Spawn
3. Configured Fallback Coordinates

The Anchor stores position and player orientation.

Normal use:

Register Anchor

Shift-use:

Remove Anchor

The Anchor is reusable and is not consumed.

The Anchor controls Gate arrival. It is not a death-respawn point.

---

RETURN Gates

RETURN Gates provide dedicated return portals.

In WDL 1.1.0, the default is:

[return_history]
return_gate_uses_history = true

This means a RETURN Gate normally follows the player's Return History.

Example:

Overworld → A → B → C

Return Gate path:

C → B → A → Overworld

If no valid Return History exists, the Gate falls back to the Overworld.

RETURN Gates can still have:

• Their own frame design
• Their own Igniter rules
• Their own activation costs
• Timed opening
• Permanent opening

---

Return Scroll

The Return Scroll is reusable and supports:

• Global XP-level cost
• Per-dimension cost override
• Cost 0 for free return
• Creative Mode exemption
• Per-dimension disabling / sealing
• Optional Return History behavior

Default:

return_scroll_uses_history = false

So the Scroll remains a direct emergency escape to the Overworld.

Optional:

return_scroll_uses_history = true

Then it follows Return History one step backward.

---

🛏️ Bed Respawn

Bed Respawn is controlled per dimension.

Example:

[dimensions.bed]
allow_bed_respawn = true

Default

If the setting is omitted:

allow_bed_respawn = false

Behavior:

Sleep
→ Allowed

Set WDL Bed Respawn
→ Blocked

This keeps the default WDL behavior safe for Auto-Unload environments.

Enabled

allow_bed_respawn = true

allows the WDL dimension to become a personal Bed Respawn destination.

If required, WDL can Lazy Mount the target dimension after death.

If the bed or destination is no longer valid, WDL falls back safely toward the Overworld.

---

Respawn Handling

Without an explicitly allowed WDL Bed Respawn, WDL can redirect deaths in imported dimensions toward:

Personal Overworld Spawn
        ↓
Overworld World Spawn

Respawn behavior can also be configured per dimension.

Example:

[dimensions.respawn]
mode = "INHERIT"

INHERIT means the dimension uses the global WDL respawn behavior from common.toml.

---

Gate Lifecycle Safety

Active Gates continuously validate their loaded structure.

If a required frame block, corner block, or Portal block is broken or replaced:

Gate becomes invalid
        ↓
Portal is removed
        ↓
Active Gate session is cleared
        ↓
Gate fully closes

WDL also detects stale OPEN states.

A broken Gate should not remain permanently locked as "already open."

After restoring the frame, the Gate can be opened again.

---

Auto-Unload

Unused WDL dimensions can be automatically unloaded.

Example:

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

Example architecture:

100 registered external worlds
        ↓
Lightweight catalog
        ↓
Only currently needed worlds mounted
        ↓
Unused worlds may Auto-Unload

Return History and enabled Bed Respawn can remount an unloaded WDL dimension when necessary.

---

Configuration

Main configuration files:

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

External worlds:

WDL_custom_dimensions/

After changing WDL configuration, run:

/wdl scan

This reloads the WDL configuration and rebuilds the external-world catalog.

---

Important TOML Note

Do not leave values blank.

Incorrect:

weight =
fallback_x =

This is invalid TOML and may prevent the configuration from loading correctly.

For optional values such as weight, omit the line instead.

---

Commands

WDL includes administrative and diagnostic 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 WDL commands require permission level 2 or higher.

Normal Gate gameplay does not require manually mounting dimensions.

---

📘 Full Documentation Inside the JAR

WDL includes detailed setup guides:

WDL_README_EN.txt
WDL_README_JA.txt

These are not short notes.

They are intended to act as complete beginner-friendly configuration guides without requiring an external wiki.

Topics include:

• Quick setup
• Singleplayer
• Dedicated server
• External world placement
• Config reload
• common.toml
• dimensions.toml
• gates.toml
• Random Gates
• Rarity / Weight
• Optional weight behavior
• LIST / ALL
• Multiple Gate definitions
• Igniters
• Gate costs
• Anchors
• Return Gates
• Return Scroll
• Return History
• Loop compression
• Per-dimension Bed Respawn
• Auto-Unload
• Commands
• Troubleshooting
• Item recipes

If you are unsure how to configure WDL, checking the included README is strongly recommended.

---

Storage Mode

WDL 1.1.0 uses IMPORT as the stable storage path.

IMPORT = Stable
AUTO   = Uses the validated IMPORT behavior
DIRECT = Future / Experimental

DIRECT storage is not considered a stable WDL 1.1.0 feature.

---

Compatibility

Designed for:

• Minecraft 1.20.1
• Forge 47.4.22
• Java 17

WDL also includes compatibility work for unload / same-ID remount behavior in environments using Valkyrien Skies 2.4.11.

Because external worlds and heavily modded environments can vary dramatically:

Always back up important worlds before importing them.

---

Multiplayer

WDL supports dedicated-server use.

Install WDL on:

Server
+
Participating clients

Use the same WDL version on both sides.

External world folders only need to exist on the server.

WDL 1.1.0 Return History is stored separately for each player's UUID, so multiple players can travel through the same Gate network without overwriting each other's return path.

---

Recommended First Setup

If you are new to WDL:

1 external world
+
1 DIMENSION Gate
+
1 Basic Dimension Igniter

Confirm that this works first.

Then gradually add:

1. Multiple worlds
2. Random Gate pools
3. Rarity / Weight
4. Multiple Gate definitions
5. Gate costs
6. Return Gates
7. Return History
8. Bed Respawn
9. Auto-Unload

---

Play Ideas / Example Setups

WDL is intentionally configuration-driven.

The following are only examples.

---

🎲 Random Adventure Gate

Register several downloaded adventure maps behind one Gate.

One Gate
   ↓
COMMON world
COMMON world
RARE world
LEGENDARY world

Each activation can lead somewhere different.

---

🗝️ Rare Secret Dimension

Add a hidden world:

rarity = "LEGENDARY"

or give it a very low explicit weight.

Most Gate activations lead to normal worlds.

Occasionally:

Gate opens
↓
Secret Dimension

---

🧭 Multi-World Expedition

Example:

Main Base
↓
World A
↓
World B
↓
World C

With Return History:

World C
↓
World B
↓
World A
↓
Main Base

The Return Scroll can remain a direct emergency escape to the Overworld.

---

🏛️ Hub-and-Spoke Exploration

Use World A as a central hub:

A → Dungeon → A
A → City → A
A → Boss World → A

Return History loop compression prevents repeated hub visits from filling the history.

---

🛏️ Persistent Survival Dimension

For a dimension intended to act as a long-term home:

[dimensions.bed]
allow_bed_respawn = true

Players can sleep and use beds as personal respawn points there.

For temporary adventure maps, simply omit the setting and keep them sleep-only.

---

🌀 One Frame, Multiple Destination Pools

Use one physical frame:

Basic Igniter
→ Normal worlds

Advanced Igniter
→ Dangerous / Rare worlds

One structure can behave like a dimensional terminal.

---

⚔️ Gate Tiers

Create progression-based Gate designs:

Stone Gate
→ Cheap
→ COMMON

Obsidian Gate
→ XP + item cost
→ RARE

Ancient Gate
→ Expensive
→ EPIC / LEGENDARY

---

🧱 Permanent Hub Gates

Create permanent portal infrastructure:

open_time_seconds = -1

Possible categories:

Adventure Worlds
Dungeon Worlds
Building Worlds
Event Worlds
Rare Worlds

---

⏱️ Timed Portal Events

Use:

open_time_seconds = 10

to create short-lived portals.

Combine them with activation costs for server events.

---

📚 Large World Library

Example:

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

WDL keeps the worlds registered while only mounting what is needed.

---

AI-Assisted Development / Developer Note

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

I am not a professional software developer, and this project was developed with significant assistance from AI tools for programming, debugging, code review, documentation, testing workflows, and development planning.

AI assistance does not mean the mod was generated and published without testing.

WDL has gone through repeated builds, runtime tests, regression testing, bug fixing, and manual in-game verification during development.

However, WDL should still be treated as community-made software.

Please back up important worlds before using the mod, especially when testing new configurations or external worlds.

Bug reports are especially helpful when they include:

• WDL version
• Minecraft / Forge version
• Relevant configuration
• latest.log
• debug.log when applicable
• Clear reproduction steps

---

WDL 1.1.0 Configuration Defaults

Return History:

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

Per-dimension Bed Respawn:

[dimensions.bed]
allow_bed_respawn = false

Remember:

If allow_bed_respawn is omitted, it is treated as false.

---

World Dimension Loader (WDL)

Turn External Minecraft Worlds Into a Configurable Dimensional Network