World Dimension Loader (WDL) 1.3.0
Minecraft 1.20.1 / Forge 47.4.22 / Java 17
Mod ID: worlddimensionloader

============================================================
1. What WDL does
============================================================
WDL imports COPIES of existing Minecraft worlds as WDL-managed Dimensions and connects them with configurable Gates.

Important:
- Always keep the original world backed up.
- Put a COPY under WDL_custom_dimensions.
- Existing Config files are never overwritten automatically.
- Reset can discard changes made inside a resettable runtime Dimension because the next generation is rebuilt from the imported source copy.

============================================================
2. Beginner setup
============================================================
1) Install WDL on the server and connecting clients. For single-player, install it normally in the client mods folder.
2) Start once so config/worlddimensionloader/ is created.
3) Put a copied world here:
   WDL_custom_dimensions/test_world_01/level.dat
4) dimensions.toml:

[[dimensions]]
id = "test_world_01"

5) gates.toml:

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

6) Run /wdl scan or restart.

The minimal Gate uses the normal obsidian defaults and targets only test_world_01.

WDL also ships a separate default Overworld Gate definition:
stone-brick frame, emerald corners, permanent opening, one emerald cost.

============================================================
3. Config files
============================================================
config/worlddimensionloader/
  common.toml
  dimensions.toml
  gates.toml

Generated Config is split into:
- ALL OPTIONS: every current option, default/inheritance, and short explanation.
- MINIMAL/PRACTICAL EXAMPLE: copy-ready beginner examples.
- LEGACY COMPATIBILITY: old keys that should not be used for new definitions.

To obtain new comments after updating WDL, back up the Config directory, move old files aside, start once, then merge only your intended overrides. WDL does not rewrite existing files.

============================================================
4. Gate destination behavior
============================================================
New beginner behavior:
- dimensions=[...] + omitted selection_mode -> LIST
- explicit selection_mode="LIST" -> LIST
- explicit selection_mode="ALL" -> all eligible READY WDL imported Dimensions
- omitted mode + no dimensions -> legacy ALL fallback

ALL does not automatically include Overworld. Use an explicit LIST for minecraft:overworld.

If multiple Gate definitions have overlapping frame/corner blocks, size ranges, and applicable Igniters, WDL rejects the ambiguous definitions fail-closed. Destination IDs alone do not distinguish physical Gates.

============================================================
5. Runtime Reset and storage
============================================================
Per-Dimension Reset is disabled by default.

When reset_on_empty=true, WDL creates a fresh physical runtime generation from the imported source copy after the Dimension becomes safely empty.

Consequences:
- builds/block changes and other runtime changes inside that Dimension may be lost on Reset;
- the imported source copy remains untouched;
- the logical Dimension ID remains stable while the physical runtime generation changes.

WDL stores runtime generations under an internal timestamp layout such as:
dimensions/wdl/test_world_01/20260822123000/

Safe default cleanup:
defer_dimension_cleanup_until_restart = true

Retired generations remain until the next game/server startup, then Startup GC removes proved-safe retired generations. Repeated Reset before restart can temporarily consume a large amount of disk space.

Live cleanup can be enabled with false, but is not recommended because other mods may keep Dimension references. Valkyrien Skies detection forces deferred cleanup for safety.

Resident GC backup is optional and defaults to false.

============================================================
6. Other major features
============================================================
- Dimensional Anchor arrival points.
- Return Scroll direct Overworld return with configurable XP cost.
- Inventory import/export policy.
- Travel import/export policy.
- Per-Dimension game mode, fixed time, difficulty, respawn and bed policy.
- Timed Sessions with PREVIOUS/OVERWORLD Forced Exit.
- Gate costs, reopen cooldowns, rarity/weight selection and Igniter restrictions.
- Gate travel history.

============================================================
7. Compatibility
============================================================
WDL's current safety work was tested around Valkyrien Skies 2.4.11 behavior. VS detection forces deferred cleanup.
Distant Horizons compatibility work was tested around DH 3.2.0-b behavior.

Unknown future versions are not guaranteed compatible.

============================================================
8. Useful commands
============================================================
/wdl scan
/wdl list
/wdl status
/wdl loaded
/wdl probe <id>

STARTUP ONLY settings require a full restart; /wdl scan does not change those active-process policies.

See:
- WDL_TUTORIAL_EN_1.3.0.txt
- WDL_CONFIG_GUIDE_EN_1.3.0.txt
- WDL_EXAMPLES_AND_PLAY_IDEAS_EN_1.3.0.txt
- WDL_TROUBLESHOOTING_EN_1.3.0.txt
