World Dimension Loader (WDL) 1.4.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 IDs, Reset, and storage
============================================================
Per-Dimension Reset is disabled by default.

For a new/pristine runtime with reset_on_empty=false:
- physical Dimension ID: wdl:<id>
- storage path: dimensions/wdl/<id>/
- no timestamp is added.

This rule applies when a runtime is newly initialized.
If a timestamp generation is already current from 1.3.0 or another earlier run, changing Reset to false does not reverse-migrate it. Existing exact current authority wins and stays in place.

Important:
- Do not manually rename or move WDL runtime folders to force a fixed ID.
- WDL 1.4.0 does not provide automatic or manual in-place timestamp -> fixed-ID migration.
- If exact lifecycle authority is unavailable and multiple WDL physical candidates exist, WDL 1.4.0 fails closed instead of guessing. It does not silently move or delete those candidates.

A new runtime with reset_on_empty=true uses timestamp physical generations.
If an existing fixed-ID runtime is later changed to Reset ON, it is not renamed immediately. The first actual Reset rotates it to a timestamp generation.

Reset-enabled internal storage example:
dimensions/wdl/test_world_01/20260822123000/

Reset rebuilds the next runtime generation from the imported source copy. Builds, block changes, entities, and other runtime changes inside the resettable Dimension may therefore be lost. The imported source copy itself remains untouched.

Safe default cleanup:
defer_dimension_cleanup_until_restart = true

Retired generations remain until the next game/server startup. Startup GC deletes only generations that WDL can prove are safely retired. Repeating Reset before restart can temporarily use substantial disk space.

Live cleanup can be enabled with false, but is not recommended. Valkyrien Skies detection forces deferred cleanup for safety.

If a Reset transaction has already reached a destructive/recovery-authority stage, changing Reset to OFF does not simply cancel that in-progress transaction. Recovery/transaction safety takes precedence over the Config change.

Reset diagnostics:
- `WDL RESET DEFERRED` at INFO means the current Reset operation is intentionally waiting or retrying. The same reason is logged once per logical Dimension + operation + phase.
- `WDL RESET BLOCKED` at ERROR means WDL entered terminal fail-closed safety handling and the cause should be investigated before changing runtime files.

============================================================
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
============================================================
Valkyrien Skies (VS) and Distant Horizons (DH) are both optional.
WDL works in the normal baseline with neither VS nor DH installed.

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.4.0.txt
- WDL_CONFIG_GUIDE_EN_1.4.0.txt
- WDL_EXAMPLES_AND_PLAY_IDEAS_EN_1.4.0.txt
- WDL_TROUBLESHOOTING_EN_1.4.0.txt
