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

============================================================
0. Introduction
============================================================
World Dimension Loader imports COPIES of existing Minecraft worlds as WDL-managed dimensions and connects them through configurable Gates.

WDL 1.2.2 keeps the 1.2.x runtime foundation and makes Config easier to maintain: default behavior is expressed by omission, generated files show a full commented option reference, and practical examples contain only intentional overrides.

Most important safety rules:
- Back up the source world first.
- Put a COPY in WDL_custom_dimensions. Do not point WDL at the only copy of an important world.
- Back up Config before a major WDL upgrade.

============================================================
1. Requirements and installation paths
============================================================
Supported environment:
- Minecraft 1.20.1
- Forge 47.4.22
- Java 17

Single player:
- JAR: .minecraft/mods/
- Config: .minecraft/config/worlddimensionloader/
- imported world copies: .minecraft/WDL_custom_dimensions/

Dedicated server:
- JAR: server-root/mods/
- Config: server-root/config/worlddimensionloader/
- imported world copies: server-root/WDL_custom_dimensions/

Multiplayer requires WDL on both the server and connecting clients. Imported world folders are server-side only; clients do not need copies of WDL_custom_dimensions.

============================================================
2. Config generation and the 1.2.2 layout
============================================================
When missing, these files are generated at Minecraft/Forge startup before a world is opened:
config/worlddimensionloader/common.toml
config/worlddimensionloader/dimensions.toml
config/worlddimensionloader/gates.toml

Core rule:
Default behavior is expressed by omission. Add only settings you intentionally want to change.

Each generated Config now has two layers:
- ALL OPTIONS TEMPLATE: a complete, fully commented, valid TOML reference.
- MINIMAL WORKING EXAMPLE / EXAMPLE OVERRIDES: practical examples that omit values already equal to WDL defaults.

common.toml may contain no active assignments at all. That is valid: every common option has a code default.
dimensions.toml has no active dimension by default.
gates.toml keeps the functional default Overworld Gate, but default-only fields are omitted.

Existing explicit 1.2.1 Config remains valid and is never rewritten automatically.
If you want the cleaner 1.2.2 layout, back up config/worlddimensionloader/, move the old files aside, start Minecraft once, then copy only intentional overrides into the regenerated files.

============================================================
3. Shortest setup path
============================================================
1. Copy a source world to .minecraft/WDL_custom_dimensions/my_world/ so level.dat is directly inside my_world.
2. Add only the settings you need to dimensions.toml:

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

Because folder defaults to id, enabled defaults to true, rarity defaults to COMMON, and destination/respawn/runtime/bed/anchor/Policy sections all have safe defaults, nothing else is required for this basic case.

3. Run /wdl scan and /wdl list. The entry must be READY.
4. Add a Gate. This example intentionally changes only the corner block, maximum size and destination:

[[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"]

Omitted values use the defaults: obsidian frame, enabled=true, minimum 2x3, 10-second open time, free cost and unrestricted normal WDL Dimension Igniters.

Current new Gate definitions do not use gate_type.

Gate shape for a 2 x 3 interior:

CFFC
F  F
F  F
F  F
CFFC

C = corner_block
F = frame_block
inside = empty

Test item:
/give @s worlddimensionloader:basic_dimension_igniter

Use the Igniter on the frame. WDL Lazy Mounts the destination when necessary.

For every available option, see the ALL OPTIONS TEMPLATE in the generated Config or WDL_CONFIG_GUIDE_EN_1.2.2.txt.

============================================================
4. Source WorldGen preservation
============================================================
WDL reads the imported world's overworld LevelStem / ChunkGenerator from level.dat and attempts to preserve the source generator, including superflat-style worlds.
With strict_validation=true, WDL refuses an unsafe mount when the source generator cannot be decoded instead of silently generating incompatible new chunks with the host Overworld generator.

============================================================
5. Destination selection
============================================================
selection_mode="LIST": choose from dimensions=[...].
selection_mode="ALL": choose from enabled/READY imported WDL dimensions only. Overworld is never added automatically.

Overworld Gate:
selection_mode = "LIST"
dimensions = ["minecraft:overworld"]

Same-dimension normal travel is excluded. If no candidate remains, activation fails without opening a Gate.

============================================================
6. Rarity / Weight / Random Gates
============================================================
Default rarity weights:
COMMON=100, UNCOMMON=60, RARE=25, EPIC=10, LEGENDARY=3.
They are relative weights, not direct percentages.
An explicit per-dimension weight overrides the rarity default. weight=0 removes that dimension from random selection.

============================================================
7. Igniters and shared physical frames
============================================================
allowed_igniters is optional. Omit it, or use [], for no restriction on normal WDL Dimension Igniters. A non-empty list restricts normal activation to the listed IDs. Ordinary Minecraft items are never enabled by this wildcard.

Example: Advanced-only
allowed_igniters = ["worlddimensionloader:advanced_dimension_igniter"]

Creative Dimension Igniter is the separate admin/master path. It can activate valid Gates without being listed, bypasses configured Gate costs, and the opened Gate Session bypasses Inventory/Travel Policy. Creative does NOT bypass physical frame validation, size limits, destination validity or same-frame ambiguity safety.

Multiple Gate definitions may share one physical frame only when the match stays unambiguous. Wildcard examples:
- unrestricted + unrestricted -> conflict
- unrestricted + Advanced-only -> conflict on Advanced
- Basic-only + Advanced-only -> separable for normal Igniters
- unrestricted + Creative-only -> no normal-Igniter conflict; explicit Creative can disambiguate Creative activation
Ambiguous matches fail closed; Config order does not win.

============================================================
8. Gate costs
============================================================
Supported types: ITEM, XP_LEVEL, XP_POINTS, HEALTH, HUNGER.
ITEM supports FIXED and RANGE.
For RANGE, the player must hold at least max items before the activation challenge starts; the actual consumed amount is rolled once from min..max. This prevents repeated clicking with only the minimum stock.
Costs are committed only when the destination is ready and the Gate can actually open.

============================================================
9. Gate lifecycle
============================================================
open_time_seconds=-1 means permanent; otherwise use 1 or greater.
WDL revalidates the active Gate boundary and portal interior. Breaking/replacing a required frame, corner or portal block closes the Gate Session and cleans remaining portal blocks. Stale OPEN states are reconciled safely.

============================================================
10. Gate Travel History
============================================================
History never chooses the destination.
Destination = Config / ActiveGate.
History = landing-point assistance only.

After successful normal Gate travel WDL stores player-local source/destination and source Gate frame/location data.
Only the latest exact reverse route may use the saved source Gate as the landing candidate:
history.source == current destination AND history.destination == current dimension.

A successful reverse route POPs that entry. WDL does not search arbitrary older matching entries.
If the saved frame is gone or no safe landing exists, normal destination fallback is used. Policy denial, inventory denial, mount waiting or teleport failure does not consume history.

Default:
[gate_history]
max_entries = 3
Range: 1..10.

Successful Return Scroll, death, successful /wdl tp and non-WDL-Gate dimension changes clear stale history. Logout/restart and Session Resume preserve it.

============================================================
11. Per-dimension Policy
============================================================
Inventory Import/Export modes: BLOCK_ALL, WHITELIST, BLACKLIST.
Inventory Policy is checked at actual traversal, not Gate activation, so carrying an Igniter does not by itself prevent opening a Gate.

Travel Import/Export modes: ALLOW_ALL, WHITELIST, BLACKLIST.
Travel Policy controls the route and is checked for activation/traversal. Sealed routes are denied with dedicated messages.

Overworld has no [[dimensions]] Policy block:
- Overworld -> WDL checks destination WDL Travel Import.
- WDL -> Overworld checks source WDL Travel Export.
History cannot bypass Policy.

============================================================
12. Return Scroll
============================================================
Return Scroll is a separate emergency direct-Overworld path. It checks per-dimension return_scroll.enabled, Inventory Export, Travel Export to minecraft:overworld and XP level cost. XP is charged only after committed travel. Creative Mode waives XP only, not Policy. Successful use clears Gate Travel History.

============================================================
13. Dimensional Anchor
============================================================
An Anchor registers the preferred landing point for that imported dimension.
Normal arrival preference: Anchor -> source world spawn -> fallback coordinates.
anchor.enabled=false blocks new registration and ignores a stored Anchor as an arrival candidate.
Anchor is not a death-respawn fallback.

============================================================
14. Bed and death respawn
============================================================
[dimensions.bed] allow_bed_respawn=false or omitted means beds may still be used for sleep but do not make that WDL dimension a death respawn target. Set true to opt in.
Common respawn mode OVERWORLD returns deaths in WDL dimensions to Overworld according to configured player-spawn/world-spawn fallback rules.

============================================================
15. Lazy Mount / keep_loaded / Auto-Unload
============================================================
Catalog size is independent from simultaneously live ServerLevels.
max_loaded_dimensions limits live WDL levels.
Per-dimension keep_loaded=true pins a READY dimension resident; it still consumes a max_loaded_dimensions slot and is not Auto-Unloaded.
auto_unload=true may unload idle safe dimensions after unload_delay_seconds.

============================================================
16. Session Resume
============================================================
When a player logs out inside a WDL dimension and reconnects after restart, WDL can Lazy Mount that dimension and restore the saved player position. A safe Overworld holding location is used while preparing the target. Permanently invalid targets fall back safely to Overworld.

============================================================
17. Built-in items
============================================================
Basic Dimension Igniter: worlddimensionloader:basic_dimension_igniter, stack 16, consumes one on successful activation.
Advanced Dimension Igniter: worlddimensionloader:advanced_dimension_igniter, default durability 100 (configurable 1..10000 via common.toml [items].advanced_dimension_igniter_durability; full restart required), loses one durability on successful activation.
Creative Dimension Igniter: worlddimensionloader:creative_dimension_igniter, no crafting recipe, admin/master tool.
Dimensional Anchor: worlddimensionloader:dimensional_anchor, not consumed.
Return Scroll: worlddimensionloader:return_scroll, not consumed.
See WDL_ITEMS_AND_RECIPES_EN_1.2.2.txt for exact recipes.

============================================================
18. Commands
============================================================
Permission level 2:
/wdl scan, /wdl list, /wdl status, /wdl anchors, /wdl loaded,
/wdl load <id>, /wdl mount <id>, /wdl unload <id>, /wdl probe <id>, /wdl tp <id>.
For normal setup, start with scan -> list -> status.

============================================================
19. Legacy compatibility
============================================================
Legacy Config is not destructively rewritten.
- gate_type="DIMENSION" -> normal Gate compatibility input.
- gate_type="RETURN" -> legacy alias converted internally to a normal Overworld destination Gate.
- old [dimensions.return_gate].enabled applies only as a compatibility guard to legacy RETURN aliases, not to new DIMENSION -> Overworld Gates.
- old [return_history].max_entries is a fallback only when new [gate_history].max_entries is absent.
- old Return History SavedData is not auto-converted because it lacks the destination information required by Gate Travel History.

============================================================
20. Troubleshooting quick list
============================================================
scan finds 0: check blank placeholders, folder nesting and level.dat location.
Gate will not open: check READY state, frame/corner, size, Igniter, costs, LIST IDs, same-dimension exclusion, ambiguity log and Travel Policy.
Does not return near original Gate: only latest exact reverse route is used; Return Scroll or /wdl tp clears history; a destroyed source frame falls back to normal landing.
Config changes not applied: run /wdl scan or restart; on dedicated servers edit server-side Config.
See WDL_TROUBLESHOOTING_EN_1.2.2.txt for the full checklist.

============================================================
21. Detailed documents
============================================================
WDL_TUTORIAL_EN_1.2.2.txt
WDL_CONFIG_GUIDE_EN_1.2.2.txt
WDL_ITEMS_AND_RECIPES_EN_1.2.2.txt
WDL_TROUBLESHOOTING_EN_1.2.2.txt
WDL_UPGRADE_GUIDE_EN_1.2.2.txt
WDL_COMMAND_GUIDE_EN_1.2.2.txt
WDL_RELEASE_NOTES_EN_1.2.2.txt


Gate destination limits:
Gate destinations support WDL imported dimensions and minecraft:overworld. Nether, End and third-party dimensions are not Gate destinations yet, and a LIST cannot mix Overworld with WDL IDs.
