World Dimension Loader 1.3.0 - Upgrade Guide

============================================================
1. Existing Config files
============================================================
WDL does not overwrite existing Config files.

Before upgrading:
1) back up config/worlddimensionloader/
2) back up important worlds
3) keep your old Config until the new build is verified

To see current generated comments:
- move old Config files aside
- start once
- compare regenerated files
- merge only intentional overrides

============================================================
2. Important Gate selection migration
============================================================
Older parsing treated omitted selection_mode as ALL even when dimensions=[...] was present.

WDL 1.3.0 changes this ambiguous shape:

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

It now resolves to LIST.

If an existing Gate intentionally relied on ALL, add:

selection_mode = "ALL"

If both selection_mode and dimensions are omitted, legacy ALL fallback remains.

Explicit invalid selection_mode values are rejected rather than silently normalized.

============================================================
3. Minimal Config
============================================================
Dimension:

[[dimensions]]
id = "test_world_01"

Gate:

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

============================================================
4. Cleanup key migration
============================================================
Current key:
runtime.defer_dimension_cleanup_until_restart

Legacy:
runtime.resident_reset_compatibility

The current key wins when present. Legacy is used only if the current key is absent.

Current safe default is true.

============================================================
5. History key migration
============================================================
Current:
gate_history.max_entries

Legacy:
return_history.max_entries

Current key wins when present.

============================================================
6. Legacy RETURN Gate
============================================================
gate_type="RETURN" remains readable for compatibility.
It forces LIST -> minecraft:overworld.

Do not use gate_type in new definitions.

============================================================
7. Runtime storage layout
============================================================
WDL 1.3.0 uses internal timestamp physical generations under the active save, for example:
dimensions/wdl/test_world_01/20260822123000/

This is internal runtime storage.

Your imported source copy remains under:
WDL_custom_dimensions/test_world_01/

Do not move the imported source into the runtime generation tree.

============================================================
8. Reset behavior
============================================================
Reset rebuilds a fresh runtime generation from the imported source copy.
Runtime changes may be discarded.

Safe default cleanup retains retired generations until restart, which may temporarily use significant disk space.

Live cleanup is not recommended. Valkyrien Skies detection forces deferred cleanup.

============================================================
9. STARTUP ONLY settings
============================================================
/wdl scan does not switch startup-latched behavior in the current process.

Restart after changing startup-only cleanup/retired-generation behavior or Advanced Dimension Igniter durability.

============================================================
10. Compatibility
============================================================
Current protection/testing was centered on Valkyrien Skies 2.4.11 and Distant Horizons 3.2.0-b behavior.
Unknown future versions are not guaranteed compatible.
