World Dimension Loader 1.3.0 - Troubleshooting

============================================================
1. Imported world is not READY
============================================================
Check:
/wdl scan
/wdl list
/wdl status

Confirm:
- WDL_custom_dimensions/<id>/level.dat exists
- no accidental double folder
- dimensions.toml id is a bare WDL path such as test_world_01
- do not use worlddimensionloader:test_world_01 as the definition id
- source world is a copy and is readable

Malformed or namespaced definition IDs are rejected early.

============================================================
2. Gate does not activate
============================================================
Check:
- destination is READY
- frame/corner/size matches the definition
- allowed Igniter rules match
- selection_mode/dimensions is valid
- policy, Timed Session, cooldown, or Reset state is not sealing entry

For the minimal Gate:
[[gates]]
id = "test_world_01_gate"
dimensions = ["test_world_01"]

This infers LIST.

============================================================
3. Multiple Gates stopped working
============================================================
WDL rejects physically ambiguous Gate definitions fail-closed.

Two definitions can be ambiguous when they overlap in:
- frame block
- corner block
- size range
- applicable Igniters

Destination IDs do not distinguish the physical Gate.

Fix by changing frame/corner blocks, using non-overlapping size ranges, or different Igniter restrictions.

============================================================
4. Gate now selects only the listed Dimension
============================================================
In WDL 1.3.0, omitted selection_mode + non-empty dimensions intentionally resolves to LIST.

Older Config may have relied on historical omitted-mode ALL behavior.
If you intended ALL, add:
selection_mode = "ALL"

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

============================================================
5. ALL does not send me to Overworld
============================================================
This is expected. ALL means eligible READY WDL imported Dimensions only.

Use:
selection_mode = "LIST"
dimensions = ["minecraft:overworld"]

Do not mix Overworld and WDL IDs in one LIST.

============================================================
6. Reset seems to use huge disk space
============================================================
With the safe default:
defer_dimension_cleanup_until_restart = true

retired physical generations remain until the next game/server startup.
Repeated Reset before restart can temporarily multiply runtime world storage.

Restart so Startup GC can remove proved-safe retired generations.

Do not manually delete live runtime folders while the game/server is running.

============================================================
7. My builds/changes disappeared after Reset
============================================================
This is expected for resettable Dimensions.

Reset builds the next runtime generation from the imported source copy. Changes made while playing in the runtime Dimension can be discarded.

The imported source copy under WDL_custom_dimensions remains untouched.

If you need persistent player-built changes, do not enable reset_on_empty for that Dimension unless another preservation mechanism is used.

============================================================
8. I enabled live cleanup
============================================================
defer_dimension_cleanup_until_restart = false allows WDL to attempt live unload/delete.

This mode is not recommended. Other mods may keep Dimension references and cause Reset failure, crash, or data inconsistency.

If Valkyrien Skies is detected, WDL ignores live-cleanup intent and forces deferred cleanup.

============================================================
9. WDL_backups remains after backup=false
============================================================
Expected.

resident_gc_backup = false means WDL does not create/update a new Resident GC backup.
It does not delete an existing archive.

Backup path:
WDL_backups/resident_gc/<save-id>/latest.zip

Remove an old archive manually only when you are certain you no longer need it and the game/server is stopped.

============================================================
10. /wdl scan did not apply my change
============================================================
Some settings are STARTUP ONLY.

A full restart is required for startup-latched cleanup/retired-generation behavior and Advanced Dimension Igniter durability.

============================================================
11. Reset becomes FAILED_BLOCKED
============================================================
Do not force-delete runtime folders.

Use:
/wdl status
/wdl loaded
/wdl probe <id>

Save latest.log/debug.log. FAILED_BLOCKED is a fail-closed safety state and the blocking authority/reference must be diagnosed.

============================================================
12. Valkyrien Skies / Distant Horizons
============================================================
Current safety behavior was tested around Valkyrien Skies 2.4.11 and DH 3.2.0-b.

Unknown future versions are not guaranteed compatible.
For VS, detection forces deferred cleanup.

============================================================
13. Existing Config comments look old
============================================================
WDL never overwrites existing Config files.

To obtain current comments:
1) back up config/worlddimensionloader/
2) move old files aside
3) start once to regenerate
4) merge only intentional overrides
