World Dimension Loader 1.2.2 - First Setup Tutorial

Goal: import one external world, enter it from an Overworld Gate, then return near that original Gate.

1. Requirements
Minecraft 1.20.1 / Forge 47.4.22 / Java 17.
Multiplayer requires WDL on server and clients. Imported world folders are server-side only.

2. Generate Config
Put the WDL JAR in mods and start to the title screen. Missing common.toml, dimensions.toml and gates.toml are generated before opening a world. Existing files are not overwritten.

1.2.2 uses this rule: default behavior is expressed by omission.
The generated files contain a fully commented ALL OPTIONS TEMPLATE plus minimal practical examples. Add only the settings you intentionally want to change.

3. Copy the source world
Back it up, then copy it to:
.minecraft/WDL_custom_dimensions/my_world/level.dat
Do not create an accidental my_world/my_world/level.dat nesting.

4. Register the dimension
Add this minimal entry to dimensions.toml:

[[dimensions]]
id = "my_world"
display_name = "My World"

folder defaults to id, enabled defaults to true, rarity defaults to COMMON and all optional sections have safe defaults.
If you want a non-default rarity, add for example:
rarity = "RARE"

Do not copy every line from the ALL OPTIONS TEMPLATE into a normal definition. It is a reference dictionary, not a requirement.

5. Check readiness
/wdl scan
/wdl list
/wdl status
Continue when my_world is READY.

6. Register a Gate
Add a minimal LIST Gate:

[[gates]]
id = "my_world_gate"
display_name = "My World Gate"
corner_block = "minecraft:crying_obsidian"
max_inner_width = 8
max_inner_height = 8
selection_mode = "LIST"
dimensions = ["my_world"]

The omitted fields use their defaults:
- enabled = true
- frame_block = minecraft:obsidian
- minimum inner size = 2x3
- open_time_seconds = 10
- no cost block = free
- allowed_igniters omitted = unrestricted normal WDL Dimension Igniters

To make an Advanced-only Gate, add:
allowed_igniters = ["worlddimensionloader:advanced_dimension_igniter"]

Current new Gates do not use gate_type.
Gate destinations are WDL imported dimensions or minecraft:overworld.
minecraft:the_nether, minecraft:the_end and third-party dimensions are not supported Gate destinations.
Do not mix minecraft:overworld and WDL imported IDs in the same LIST.

7. Build the frame
For a 2 x 3 interior:
CFFC
F  F
F  F
F  F
CFFC
C=corner, F=frame, inside=empty.

/give @s worlddimensionloader:basic_dimension_igniter
Use it on the frame.

8. Use the default Overworld Gate
A newly generated gates.toml already contains `overworld_gate_default`.
Use or edit that definition first instead of adding an identical second Gate.

Default definition:
- frame = minecraft:stone_bricks
- corners = minecraft:emerald_block
- inner size = 2x3 .. 32x32
- Basic / Advanced Dimension Igniter
- selection_mode = LIST
- dimensions = ["minecraft:overworld"]
- open_time_seconds = -1 (permanent)
- cost = emerald x1

Adding another Gate with the same frame/corners, overlapping size range and same Igniter conditions
would make the physical frame ambiguous and WDL fails closed. If you need another Overworld Gate,
differentiate the frame/corners, size range or Igniter conditions.
There is no new-format RETURN Gate type.

9. Test Gate Travel History
Travel Overworld A Gate -> my_world. Then use a normal Overworld Gate from my_world. If the latest history entry is the exact reverse route, WDL uses the Overworld A Gate as the landing candidate.
History never changes the configured destination. Return Scroll, /wdl tp, death or non-WDL-Gate dimension changes clear stale history. Destroying the saved source frame causes normal landing fallback.

10. Anchor
/give @s worlddimensionloader:dimensional_anchor
Use it in an imported dimension to register its preferred arrival point. Anchor is not a death respawn point.

11. Return Scroll
/give @s worlddimensionloader:return_scroll
This is an emergency direct-Overworld path, not history traversal. Inventory Export, Travel Export and XP cost apply. Successful use clears Gate Travel History.

12. Random Gate
LIST with multiple dimensions or ALL may use rarity/weight selection. ALL includes READY imported WDL dimensions only and never adds Overworld automatically.

13. Dedicated server
Edit server-root/config/worlddimensionloader/ and place imported worlds in server-root/WDL_custom_dimensions/. Clients need the WDL mod but not copies of the imported worlds.

14. Major upgrade workflow
Stop -> backup Config -> move old Config aside -> start once -> regenerate -> copy required values -> scan/list/status -> test Gate/Policy/Scroll/Anchor.

Next: WDL_CONFIG_GUIDE_EN_1.2.2.txt, WDL_ITEMS_AND_RECIPES_EN_1.2.2.txt, WDL_TROUBLESHOOTING_EN_1.2.2.txt.
