World Dimension Loader (WDL) 1.1.3
English README / Beginner Setup & Configuration Guide
Minecraft 1.20.1 / Forge 47.4.22 / Java 17

============================================================
0. Start Here
============================================================

World Dimension Loader (WDL) is a Forge mod that lets you register
external Minecraft worlds as dimensions, then enter them through
configurable Gates.

WDL does NOT keep every registered world active as a ServerLevel.

Registered worlds are kept in a lightweight catalog, and only the
dimensions that are actually needed are Lazy Mounted.

WDL 1.1.3 adds the following on top of the 1.0.0 Gate / Random Dimension /
Auto-Unload system:

- Per-player Return History
- Return Gates that can send players back along the path they came from
- Per-dimension Bed Respawn permission
- Multiplayer-safe individual return histories


------------------------------------------------------------
Supported Environment
------------------------------------------------------------

Minecraft : 1.20.1
Forge     : 47.4.22
Java      : 17
Mod ID    : worlddimensionloader

Stable storage mode:
IMPORT

AUTO also uses the validated IMPORT path in WDL 1.1.3.

DIRECT is reserved for future / experimental work.
Use AUTO or IMPORT for normal play.


------------------------------------------------------------
If you only want the shortest setup
------------------------------------------------------------

You do NOT need to read the entire README before using WDL.

For your first test:

1. Install WDL and start Minecraft / the server once
2. Put one external world inside WDL_custom_dimensions
3. Register it in dimensions.toml
4. Register one Gate in gates.toml
5. Run /wdl scan and confirm READY with /wdl list
6. Build the frame and open it with a Basic Dimension Igniter

If one world + one Gate works, your basic setup is complete.

After that, add features only when you need them:

- multiple dimensions
- random Gates
- rarity / weight
- Return History
- Return Gates
- Bed Respawn
- Auto-Unload
- per-dimension keep_loaded
- Creative master/admin Igniter behavior
- Session Resume after logout/restart


============================================================
1. File Locations
============================================================

[SINGLEPLAYER]

WDL:
.minecraft/mods/WDL-1.1.3.jar

Configuration:
.minecraft/config/worlddimensionloader/

External worlds:
.minecraft/WDL_custom_dimensions/


[DEDICATED SERVER]

WDL:
server-root/mods/WDL-1.1.3.jar

Configuration:
server-root/config/worlddimensionloader/

External worlds:
server-root/WDL_custom_dimensions/


For multiplayer, install the same WDL version on both the server and
participating clients.

The external world folders belong on the server.
Clients do not need their own copies of those worlds.


============================================================
2. Upgrading from an Older WDL Version
============================================================

WDL 1.1.3 remains compatible with existing WDL configuration files.

For a normal update, you do NOT need to delete:

    config/worlddimensionloader/

If a newer option is missing from an older config, WDL uses a safe default.

Examples:

[dimensions.runtime]
keep_loaded = false

omitted
-> treated as false

[dimensions.bed]
allow_bed_respawn = false

omitted
-> treated as false


------------------------------------------------------------
If you want the newest generated comments and options
------------------------------------------------------------

New WDL versions may add settings and explanatory comments to freshly
generated configuration files.

Recommended procedure:

1. Fully stop Minecraft / the server.
2. Back up `config/worlddimensionloader/`.
3. Move the existing `worlddimensionloader` config folder somewhere safe.
4. Start WDL 1.1.3 once.
5. Confirm the newest config files were generated.
6. Stop Minecraft / the server again.
7. Copy your own Dimension / Gate definitions from the old config into the newly generated files.
8. Keep the new settings and comments.
9. Start again and run `/wdl scan` then `/wdl list` and confirm READY.


Important:

Do NOT simply overwrite the newly generated files with the old config files,
because that also removes the new options and comments.

Copy the actual Dimension / Gate definitions into the new files instead.


============================================================
3. First Setup
============================================================

This example registers:

    my_world


------------------------------------------------------------
STEP 1 : Place the external world
------------------------------------------------------------

Put the world here:

WDL_custom_dimensions/my_world/


Correct:

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


Important:

level.dat must exist directly inside my_world.


Common mistake:

WDL_custom_dimensions/my_world/my_world/level.dat

Correct:

WDL_custom_dimensions/my_world/level.dat


------------------------------------------------------------
STEP 2 : dimensions.toml
------------------------------------------------------------

Open:

config/worlddimensionloader/dimensions.toml

Add:


[[dimensions]]
id = "my_world"
display_name = "My World"
enabled = true
folder = "my_world"
rarity = "COMMON"

[dimensions.destination]
prefer_anchor = true
prefer_world_spawn = true
fallback_x = 0
fallback_y = 80
fallback_z = 0
fallback_yaw = 0.0
fallback_pitch = 0.0

[dimensions.respawn]
mode = "INHERIT"

[dimensions.return_scroll]
enabled = true
xp_level_cost = 5


[IMPORTANT: keep_loaded / Bed Respawn are opt-in]

For normal use, you do not need to write either of these sections.
When omitted, both settings are treated as false.

Only add this when you want a dimension to remain loaded:

[dimensions.runtime]
keep_loaded = true

Only add this when you want beds in that WDL dimension to become
death-respawn points:

[dimensions.bed]
allow_bed_respawn = true

If you want normal Lazy Mount behavior and sleep-only beds, omit the
[dimensions.runtime] and [dimensions.bed] sections entirely.


[IMPORTANT: weight]

weight is optional.

This is valid:

rarity = "RARE"

If weight is omitted, WDL uses the matching rarity weight from common.toml.

Only add a per-dimension weight when you want a custom selection weight:

weight = 8


[IMPORTANT: do not leave TOML values blank]

Do NOT write:

weight =
fallback_x =

Blank TOML values are invalid and can prevent the config from loading.

If an optional field is not needed, omit that line instead of leaving
the value empty.


------------------------------------------------------------
STEP 3 : /wdl scan
------------------------------------------------------------

After saving the config, run:

/wdl scan

Then:

/wdl list


A successful entry should appear as:

[READY] my_world


Common statuses:

READY
  Available.

DISABLED
  enabled = false.

MISSING_FOLDER
  The configured folder does not exist.

MISSING_LEVEL_DAT
  level.dat is not directly inside the configured world folder.

INVALID_PATH
  The configured path escapes the allowed dimension root.


------------------------------------------------------------
STEP 4 : gates.toml
------------------------------------------------------------

Open:

config/worlddimensionloader/gates.toml

Add:


[[gates]]
id = "my_world_gate"
display_name = "My World 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 = ["my_world"]

open_time_seconds = 10


If:

allowed_igniters = []

normal Gate rules allow the built-in Basic and Advanced Igniters:

- basic_dimension_igniter
- advanced_dimension_igniter

The Creative Dimension Igniter is a master/admin Igniter in 1.1.2, so it remains usable regardless of allowed_igniters.


To allow only one:

allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter"
]


------------------------------------------------------------
STEP 5 : Build the Gate
------------------------------------------------------------

With the example above:

Corners:
crying_obsidian

Edges:
obsidian


Minimum interior:
2 x 3


◆■■◆
■    ■
■    ■
■    ■
◆■■◆

◆ = crying obsidian
■ = obsidian
blank = Gate interior


------------------------------------------------------------
STEP 6 : Open the Gate
------------------------------------------------------------

Use an allowed Igniter on the frame.

Test command:

/give @s worlddimensionloader:basic_dimension_igniter


If valid, WDL Portal blocks appear inside the frame.

If the destination dimension is currently unloaded, WDL Lazy Mounts it
when needed.


============================================================
4. Configuration Files
============================================================

config/worlddimensionloader/
├─ common.toml
├─ dimensions.toml
└─ gates.toml


common.toml
  Global WDL behavior:
  runtime, Auto-Unload, respawn, Return History, Return Scroll,
  rarity weights, etc.

dimensions.toml
  Per-dimension settings:
  folder, rarity, weight, destination, Bed Respawn, Return Scroll, etc.

gates.toml
  Gate frames, Igniters, destination pools, random selection, costs, etc.


After changing WDL configuration, run:

/wdl scan


============================================================
5. common.toml
============================================================

------------------------------------------------------------
[general]
------------------------------------------------------------

strict_validation = true

Recommended:
true

If WDL cannot safely use the source world's world-generation data,
strict validation refuses an unsafe mount instead of silently replacing
the generator.


debug_logging = false

Normal:
false

Troubleshooting:
true


default_gate_open_time_seconds = 10

Default Gate open duration when a Gate does not specify its own value.


------------------------------------------------------------
[paths]
------------------------------------------------------------

dimension_root_folder = "WDL_custom_dimensions"

Root folder for external worlds.


------------------------------------------------------------
[runtime]
------------------------------------------------------------

storage_mode = "AUTO"

Recommended:
AUTO or IMPORT

DIRECT:
Future / experimental


max_loaded_dimensions = 4

Maximum number of live WDL dimensions.

This is NOT the maximum number of registered dimensions.

Example:

Registered dimensions = 300
max_loaded_dimensions = 4

WDL can still catalog all 300 worlds.


auto_unload = false

true:
Automatically unload eligible unused WDL dimensions.

false:
Do not automatically unload them.


unload_delay_seconds = 300

Delay before an eligible dimension is auto-unloaded.


vs_remount_cooldown_ticks = 100

Safety cooldown for the Valkyrien Skies 2.4.11 same-ID remount path.


------------------------------------------------------------
[respawn]
------------------------------------------------------------

mode = "OVERWORLD"

Common values:

OVERWORLD
VANILLA


OVERWORLD:
WDL handles respawn back toward the Overworld for deaths in WDL dimensions.

VANILLA:
WDL does not apply its normal respawn override.


prefer_overworld_player_spawn = true

Prefer the player's valid Overworld personal spawn.


fallback_to_overworld_world_spawn = true

Fall back to the Overworld world spawn when needed.


------------------------------------------------------------
[return_history]  <- WDL 1.1.0+
------------------------------------------------------------

max_entries = 3

Maximum number of stored return-history entries per player.

Range:
1 to 10

Default:
3


return_gate_uses_history = true

true:
RETURN Gates use the player's previous WDL Gate path when possible.

false:
RETURN Gates do not use Return History and return to the Overworld.


return_scroll_uses_history = false

false (default):
Return Scroll behaves as an emergency Overworld return.

true:
Return Scroll also uses Return History and goes back one step.


============================================================
6. Return History  <- WDL 1.1.0+
============================================================

WDL 1.1.3 stores a small per-player history of unresolved Gate return paths.

It is NOT a raw movement log.

Only successful normal DIMENSION Gate travel is recorded.


Recorded:

DIMENSION Gate
-> destination chosen
-> mount succeeds
-> teleport succeeds
-> source added to Return History


Not recorded:

- Return Gate travel
- Return Scroll travel
- death respawn
- /wdl tp
- vanilla /tp
- Anchor registration


------------------------------------------------------------
RETURN Gate behavior
------------------------------------------------------------

Default:

return_gate_uses_history = true


Example:

Overworld -> A -> B -> C

History:
Overworld
A
B


Use a Return Gate in C:

C -> B

Then:

B -> A
A -> Overworld


This creates a natural "go back the way I came" path.


------------------------------------------------------------
No valid history
------------------------------------------------------------

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


------------------------------------------------------------
Return Scroll
------------------------------------------------------------

Default:

return_scroll_uses_history = false


So Return Scroll stays an emergency direct Overworld escape.

A successful direct Overworld return clears the old Return History.


------------------------------------------------------------
Loop compression
------------------------------------------------------------

Return History stores unresolved return paths, not every movement.

Example:

A -> B -> A

Returning to A closes the A -> B branch.


Example:

A -> B -> C -> A

Returning to A closes the entire loop.


Hub example:

A -> B -> A -> C -> A -> D -> A

does not fill the history with repeated A entries.


If the journey started in the Overworld:

Overworld -> A -> B -> A -> C -> A

the remaining useful return path is still the Overworld entry.


------------------------------------------------------------
Multiplayer
------------------------------------------------------------

Return History is stored per player UUID.

Two players can use the same Gates without overwriting each other's
return path.

History survives logout/login and server restart.


------------------------------------------------------------
Returning to an Auto-Unloaded dimension
------------------------------------------------------------

If a history destination is currently unloaded,
WDL can Lazy Mount it before returning the player.

The history entry is consumed only after a successful teleport.

A temporary mount / teleport failure does not erase the entry first.


============================================================
7. dimensions.toml
============================================================

Example:


[[dimensions]]
id = "ancient_city"
display_name = "Ancient City"
enabled = true
folder = "ancient_city"
rarity = "RARE"

[dimensions.destination]
prefer_anchor = true
prefer_world_spawn = true
fallback_x = 0
fallback_y = 80
fallback_z = 0
fallback_yaw = 0.0
fallback_pitch = 0.0

[dimensions.respawn]
mode = "INHERIT"

[dimensions.runtime]
keep_loaded = false

[dimensions.bed]
allow_bed_respawn = false

[dimensions.return_scroll]
enabled = true
xp_level_cost = 5


------------------------------------------------------------
id / folder / display_name
------------------------------------------------------------

id:
Internal WDL dimension ID.
Gate dimensions = [...] entries use this value.

folder:
Real folder name inside WDL_custom_dimensions.

display_name:
Human-readable name.


------------------------------------------------------------
rarity
------------------------------------------------------------

Supported:

COMMON
UNCOMMON
RARE
EPIC
LEGENDARY
CUSTOM


If weight is omitted, WDL uses the matching value from common.toml
[rarity_weights].


------------------------------------------------------------
weight
------------------------------------------------------------

weight is optional.

Example:

rarity = "RARE"

uses the standard RARE weight.


Custom override:

rarity = "RARE"
weight = 8

The explicit weight overrides rarity.


weight = 0

excludes the dimension from weighted random selection.


------------------------------------------------------------
[dimensions.destination]
------------------------------------------------------------

Normal arrival priority:

1. Dimensional Anchor
2. Imported world spawn
3. Fallback coordinates


------------------------------------------------------------
[dimensions.respawn]
------------------------------------------------------------

mode = "INHERIT"

Values:

INHERIT
OVERWORLD
VANILLA


INHERIT:
Use common.toml respawn settings.

OVERWORLD:
Use WDL Overworld respawn behavior for this dimension.

VANILLA:
Do not use WDL's normal respawn override for this dimension.


------------------------------------------------------------
[dimensions.runtime]  <- WDL 1.1.2+
------------------------------------------------------------

Advanced per-dimension runtime policy.

Most users should omit this section or keep:

[dimensions.runtime]
keep_loaded = false


keep_loaded = false

- Normal Lazy Mount behavior
- Mount only when needed
- May be Auto-Unloaded when eligible

Omitted also means false.


keep_loaded = true

- Automatically requests the dimension to be mounted
- Keeps it loaded even with zero players
- Prevents Auto-Unload / capacity eviction
- Intended for a small number of hub, base, or always-active worlds


Example:

[dimensions.runtime]
keep_loaded = true


Important:

keep_loaded dimensions still consume `max_loaded_dimensions` slots.

With `max_loaded_dimensions = 4`, WDL cannot keep five or more resident
dimensions mounted at the same time.

Use this for a small number of important worlds rather than an entire
large catalog.

After changing the setting, run `/wdl scan` to reconcile the runtime policy.


------------------------------------------------------------
[dimensions.bed]  <- WDL 1.1.0+
------------------------------------------------------------

allow_bed_respawn = false


[IMPORTANT: omitted also means false]


Omitted / false:

- Beds can still be used for sleeping
- The WDL dimension is not used as a Bed Respawn destination
- Death uses the normal WDL respawn rules


true:

- Beds can be used for sleeping
- The dimension may be used for Bed Respawn
- If the dimension is unloaded, WDL may Lazy Mount it to perform respawn


Example:

[dimensions.bed]
allow_bed_respawn = true


If the Bed Respawn destination is:

- removed
- broken
- invalid
- disabled
- impossible to mount

WDL safely falls back toward the Overworld.


Dimensional Anchor is NOT a death-respawn fallback.

Anchor:
Gate arrival position

Bed:
Death respawn position only when explicitly allowed


------------------------------------------------------------
[dimensions.return_scroll]
------------------------------------------------------------

enabled = true

false:
Return Scroll is disabled in that dimension.


xp_level_cost = 5

Per-dimension XP level cost.

Omitted:
Use common.toml default_xp_level_cost.


============================================================
8. Rarity / Weight / Random Gates
============================================================

Default weights:

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


Higher numbers are more likely to be selected.

These are weights, not direct percentages.


Example:

World A:
COMMON -> 100

World B:
RARE -> 25

World C:
LEGENDARY -> 3


Total:
128

Each world is selected according to its share of that total weight.


------------------------------------------------------------
Rarity only is valid
------------------------------------------------------------

Example:

rarity = "RARE"

You do not need to specify weight.


------------------------------------------------------------
Per-dimension override
------------------------------------------------------------

rarity = "LEGENDARY"
weight = 50

uses 50 for selection.


============================================================
9. gates.toml
============================================================

DIMENSION Gate example:


[[gates]]
id = "random_gate"
display_name = "Random 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


------------------------------------------------------------
allowed_igniters
------------------------------------------------------------

Empty:

allowed_igniters = []

uses the normal built-in Basic + Advanced Igniters.
The Creative Dimension Igniter remains available implicitly as the master/admin Igniter.


Specific:

allowed_igniters = [
  "worlddimensionloader:advanced_dimension_igniter"
]


------------------------------------------------------------
selection_mode
------------------------------------------------------------

LIST:
Choose only from dimensions = [...]

ALL:
Choose from all eligible WDL dimensions.


------------------------------------------------------------
Random Gate behavior
------------------------------------------------------------

A random Gate performs a new weighted selection each time it is activated.

Example:

First activation:
world_a

Gate closes

Second activation:
world_c


Permanent Gate:

open_time_seconds = -1

keeps its originally selected destination while it stays open.

Close and reopen it to perform a new selection.


------------------------------------------------------------
Current dimension exclusion
------------------------------------------------------------

Current:
world_a

Pool:
world_a
world_b
world_c

Actual candidates:
world_b
world_c


If the current dimension is the only possible destination,
the Gate does not open.

The failed activation does not consume the Gate cost or Igniter.


============================================================
10. Multiple Gate Definitions on One Frame
============================================================

The same physical frame may use different Gate definitions based on
the Igniter and frame size.

Example:

Basic Igniter
-> normal pool

Advanced Igniter
-> rare pool


WDL resolves a Gate from:

- frame_block
- corner_block
- actual frame size
- held Igniter


Ambiguous definitions are disabled for safety.

Log marker:

WDL GATE_CONFIG_AMBIGUOUS


WDL does NOT use "first config entry wins" behavior.


============================================================
11. RETURN Gate
============================================================

Example:


[[gates]]
id = "return_gate_default"
display_name = "Return Gate"
enabled = true
gate_type = "RETURN"

frame_block = "minecraft:stone_bricks"
corner_block = "minecraft:emerald_block"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 32
max_inner_height = 32

allowed_igniters = []

open_time_seconds = -1

[[gates.costs]]
type = "ITEM"
item = "minecraft:emerald"
amount_mode = "FIXED"
amount = 1


In WDL 1.1.3, the default is:

return_gate_uses_history = true


So if valid Return History exists, a RETURN Gate goes back along the
player's previous Gate path instead of always going directly to the Overworld.

If there is no valid history, it falls back to the Overworld.


============================================================
12. Gate Costs
============================================================

Supported:

ITEM
XP_LEVEL
XP_POINTS
HEALTH
HUNGER


Example:

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


Multiple costs may be combined.

WDL validates the activation first and consumes the transaction only
when the Gate can actually open.


============================================================
13. Dimensional Anchor
============================================================

ID:

worlddimensionloader:dimensional_anchor


Purpose:

Stores the preferred Gate arrival position for a WDL dimension.


Normal use:
Register current position

Shift-use:
Remove Anchor


Consumption:
None


Arrival priority:

1. Anchor
2. World Spawn
3. fallback


Anchor is NOT a death-respawn point.


============================================================
14. Return Scroll
============================================================

ID:

worlddimensionloader:return_scroll


Consumption:
None

XP cost:
Configured


Default:

return_scroll_uses_history = false


So normal behavior is:

WDL dimension
-> Return Scroll
-> Overworld


If:

return_scroll_uses_history = true

the Scroll uses Return History and goes back one step instead.


============================================================
15. Bed Respawn  <- WDL 1.1.0+
============================================================

Configured per dimension.


Default:

allow_bed_respawn = false


Omitted also means false.


false:

Bed
-> sleeping works
-> WDL dimension is NOT used as the respawn point


true:

Bed
-> sleeping works
-> that WDL dimension may be used for death respawn


Example:

[dimensions.bed]
allow_bed_respawn = true


If a dimension used to have true and is later changed to false,
WDL checks the current config.

Old player respawn data alone does not force WDL to mount a dimension
whose Bed Respawn is now disabled.


------------------------------------------------------------
Session Resume / Logging Out Inside a WDL Dimension
------------------------------------------------------------

Since WDL 1.1.1, players can log out inside a Lazy-Mounted WDL dimension
and return to that dimension after reconnecting or restarting.

Basic flow:

Log out in WDL Dimension A
-> WDL stores the player's dimension ID, position, yaw and pitch
-> restart / reconnect
-> if A is not mounted yet, WDL Lazy Mounts it
-> player is restored to the previous WDL dimension and position


While preparing the target, WDL uses a safe Overworld holding position
instead of leaving the player at stale WDL coordinates underground.

Session Resume is separate from Return History and does not push, pop,
or clear Gate history by itself.

If the target was removed, disabled, is no longer READY, or cannot mount,
WDL safely falls back to the Overworld.


============================================================
16. Gate Lifecycle
============================================================

While a Gate is open, breaking or replacing:

- a required frame block
- a corner block
- a WDL Portal block

causes:

Portal removal
-> Active Session removal
-> Gate closes


This also applies to permanent Gates.


============================================================
17. Auto-Unload / Large World Collections
============================================================

WDL separates:

registered dimension count

from:

live ServerLevel count


Example:

300 worlds registered
max_loaded_dimensions = 4

means WDL may catalog all 300 worlds while limiting live WDL ServerLevels
to 4.


Example:

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


============================================================
18. Built-in Items / Recipes
============================================================

------------------------------------------------------------
Basic Dimension Igniter
------------------------------------------------------------

ID:
worlddimensionloader:basic_dimension_igniter

On successful Gate activation:
Consumes 1

Stack:
16


Recipe:

[ ][A][ ]
[E][F][E]
[ ][A][ ]

A = Amethyst Shard
E = Ender Pearl
F = Flint and Steel


------------------------------------------------------------
Advanced Dimension Igniter
------------------------------------------------------------

ID:
worlddimensionloader:advanced_dimension_igniter

Durability:
100

On successful Gate activation:
Loses 1 durability


Recipe:

[ ][D][ ]
[N][S][N]
[ ][D][ ]

D = Diamond
N = Nether Star
S = Basic Dimension Igniter


------------------------------------------------------------
Creative Dimension Igniter
------------------------------------------------------------

ID:
worlddimensionloader:creative_dimension_igniter

Purpose:
Creative / administration / testing master Igniter.

Crafting:
None

Uses:
Unlimited

Since WDL 1.1.2, it can activate a valid Gate even when it is not listed
in `allowed_igniters`.

It also bypasses configured Gate costs.

It does NOT bypass structural or destination safety. The frame, size,
destination, current-dimension exclusion, and same-frame resolver must
still be valid.

If multiple Gate definitions physically match and Creative cannot safely
identify one, activation fails closed instead of choosing by config order.

You can explicitly list Creative in exactly one matching Gate definition
to use it as a disambiguation hint.


------------------------------------------------------------
Dimensional Anchor
------------------------------------------------------------

Consumption:
None


Recipe:

[ ][A][ ]
[E][C][E]
[ ][A][ ]

A = Amethyst Shard
E = Eye of Ender
C = Compass


------------------------------------------------------------
Return Scroll
------------------------------------------------------------

Shapeless:

Book x1
Emerald x1

Item consumption:
None


============================================================
19. Commands
============================================================

Most WDL commands require permission level 2 or higher.


/wdl scan
Reload WDL config + rescan external worlds


/wdl list
Show dimension status


/wdl status
Show catalog / READY / loaded summary


/wdl anchors
List Anchors


/wdl loaded
Show runtime states


/wdl load <id>
Prepare runtime data


/wdl mount <id>
Mount dimension


/wdl unload <id>
Unload dimension


/wdl tp <id>
Administrative / test teleport


/wdl probe <id>
Diagnostic information


============================================================
20. Troubleshooting
============================================================

------------------------------------------------------------
/wdl scan finds 0 dimensions
------------------------------------------------------------

Check dimensions.toml.

Especially avoid invalid blank values such as:

weight =
fallback_x =


Also check for a double folder:

WDL_custom_dimensions/world/world/level.dat


------------------------------------------------------------
Gate does not open
------------------------------------------------------------

Check:

1. /wdl scan
2. /wdl list
3. Destination is READY
4. frame / corner blocks
5. frame size
6. held Igniter
7. Gate costs
8. LIST dimension IDs
9. current dimension is not the only remaining candidate
10. latest.log for GATE_CONFIG_AMBIGUOUS


------------------------------------------------------------
Return Gate goes to the Overworld
------------------------------------------------------------

If Return History is empty or contains no usable entry,
the Return Gate falls back to the Overworld.


------------------------------------------------------------
Bed Respawn does not work
------------------------------------------------------------

Check:

[dimensions.bed]
allow_bed_respawn = true


If the setting is omitted, it is false.


------------------------------------------------------------
keep_loaded=true does not stay resident
------------------------------------------------------------

Check:

1. `/wdl list` shows the target as READY.
2. The target dimension contains:

   [dimensions.runtime]
   keep_loaded = true

3. Run `/wdl scan`.
4. Run `/wdl loaded` and confirm `keep_loaded=true`.
5. Confirm `max_loaded_dimensions` is large enough for all resident worlds.


------------------------------------------------------------
Config changes do not apply
------------------------------------------------------------

Run:

/wdl scan


On a dedicated server, edit the server-side config.


============================================================
21. Recommended Initial Settings
============================================================

[general]
strict_validation = true
debug_logging = false

[paths]
dimension_root_folder = "WDL_custom_dimensions"

[runtime]
storage_mode = "AUTO"
max_loaded_dimensions = 4
auto_unload = false
unload_delay_seconds = 300
vs_remount_cooldown_ticks = 100

[respawn]
mode = "OVERWORLD"
prefer_overworld_player_spawn = true
fallback_to_overworld_world_spawn = true

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

[return_scroll]
default_xp_level_cost = 5

[rarity_weights]
COMMON = 100
UNCOMMON = 60
RARE = 25
EPIC = 10
LEGENDARY = 3


Recommended per-dimension default:

[dimensions.bed]
allow_bed_respawn = false


============================================================
22. WDL 1.1.3 Important Behavior Summary
============================================================

- Place external worlds in WDL_custom_dimensions
- Existing configs remain compatible and do not need to be deleted
- To see new generated options/comments, back up the old config, regenerate, then copy your definitions into the new files
- Run /wdl scan after config changes
- Do not leave TOML values blank
- weight is optional
- rarity alone is enough for weighted random selection
- allowed_igniters = [] uses Basic + Advanced normally; Creative remains available implicitly as the master/admin Igniter
- LIST and ALL are supported
- Random Gates reroll on each new activation
- Current WDL dimension is removed from its own destination pool
- Multiple Gate definitions may share one physical frame
- Ambiguous Gate definitions are disabled for safety
- Breaking a frame / Portal closes the Gate session
- Anchor controls Gate arrival
- Return History is stored per player
- Return Gate uses Return History by default
- Return Scroll goes directly to the Overworld by default
- Return History compresses completed loops
- Multiplayer players have independent histories
- Bed Respawn can be enabled per dimension
- Omitted allow_bed_respawn means false
- Beds still allow sleeping when Bed Respawn is false
- Enabled Bed Respawn can Lazy Mount the destination when required
- Registered dimension count is separate from live ServerLevel count
- IMPORT is the stable storage path
- DIRECT is future / experimental


============================================================
23. Final Notes
============================================================

If you are new to WDL, start small.

Use:

1 world
+
1 Gate


Then expand gradually:

Random Gate
-> Rarity / Weight
-> Return Gate
-> Return History
-> Bed Respawn
-> Auto-Unload


When something does not work, begin with:

/wdl scan
/wdl list
/wdl status
/wdl loaded


World Dimension Loader (WDL) 1.1.3
End of English README
