World Dimension Loader 1.3.0 - Config Guide

Config directory:
config/worlddimensionloader/

Files:
- common.toml
- dimensions.toml
- gates.toml

Missing files are generated. Existing files are never overwritten automatically.
Generated Config comments are English-only and are split into ALL OPTIONS, example, and LEGACY COMPATIBILITY zones.

============================================================
1. common.toml
============================================================

[general]

strict_validation = true
Default: true
Rejects unsafe imported-world generator fallback when source generator data cannot be decoded safely.

debug_logging = false
Default: false
Enables additional WDL diagnostics.

default_gate_open_time_seconds = 10
Default: 10
Normal default Gate open duration in seconds.

default_min_inner_width = 2
Default: 2
Effective range: 2..32.

default_min_inner_height = 3
Default: 3
Effective range: 3..32.

default_max_inner_width = 32
Default: 32
Clamped to at least the configured minimum and at most 32.

default_max_inner_height = 32
Default: 32
Clamped to at least the configured minimum and at most 32.

[paths]

dimension_root_folder = "WDL_custom_dimensions"
Default: WDL_custom_dimensions
Root folder for imported source-world copies.

[items]

advanced_dimension_igniter_durability = 100
Default: 100
Range: 1..10000
STARTUP ONLY. Full restart required.

[runtime]

storage_mode = "AUTO"
Default: AUTO
Normal supported values: AUTO, IMPORT
DIRECT is reserved/unavailable in WDL 1.3.0.

max_loaded_dimensions = 8
Default: 8
Minimum: 1
Counts currently loaded logical WDL Dimensions only. Retired Resident physical generations are outside this budget.

auto_unload = false
Default: false
Allows eligible unused WDL Dimensions to unload automatically.

unload_delay_seconds = 300
Default: 300
Minimum: 10 seconds.

vs_remount_cooldown_ticks = 100
Default: 100
Minimum: 20
Expert compatibility cooldown.

defer_dimension_cleanup_until_restart = true
Default: true
STARTUP ONLY.
true is the recommended safe mode: retired physical generations stay until the next startup.
false permits live unload/delete attempts and is not recommended because other mods may keep Dimension references.
Valkyrien Skies detection forces the effective behavior to true.

resident_gc_backup = false
Default: false
Optional Startup GC backup.
When true, WDL stores the latest successful archive for the save at:
WDL_backups/resident_gc/<save-id>/latest.zip
Backup failure cancels candidate deletion for that startup.
Disabling backup does not delete an existing archive.

resident_retired_generation_limit = 100
Default: 100
Minimum: 0
No WDL-defined maximum.
STARTUP ONLY.
Counts RETIRED + LIVE_ORPHAN + in-flight rotation reservations.
0 disables same-process Resident rotation and requires restart/offline Reset progression.

IMPORTANT RESET STORAGE WARNING:
With the safe default cleanup policy, repeated Reset before restart can temporarily create multiple physical generations and use a large amount of disk space. Live cleanup can reduce retention but is not recommended for compatibility/safety reasons.

[respawn]

mode = "OVERWORLD"
Default: OVERWORLD
Values: OVERWORLD, VANILLA

prefer_overworld_player_spawn = true
Default: true

fallback_to_overworld_world_spawn = true
Default: true

[return_scroll]

default_xp_level_cost = 5
Default: 5
Minimum: 0

[gate_history]

max_entries = 3
Default: 3
Range: 1..10

[rarity_weights]

COMMON = 100
UNCOMMON = 60
RARE = 25
EPIC = 10
LEGENDARY = 3
Defaults shown above. Values are clamped to non-negative numbers.

Legacy common keys:
runtime.resident_reset_compatibility
Used only when defer_dimension_cleanup_until_restart is absent.

return_history.max_entries
Used only when gate_history.max_entries is absent.

============================================================
2. dimensions.toml
============================================================

Minimal definition:

[[dimensions]]
id = "test_world_01"

id
Required.
Use a bare lowercase WDL ResourceLocation path such as test_world_01.
Do not use worlddimensionloader:test_world_01 as the definition id.
Malformed or namespaced definition IDs are rejected early.

display_name
Default: id

enabled
Default: true

folder
Default: id
Folder below common.paths.dimension_root_folder.

rarity
Default: COMMON
Values: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY, CUSTOM

weight
Default: omitted
When omitted, common rarity weight is used.
CUSTOM without explicit weight ultimately uses fallback weight 1.

[dimensions.destination]

prefer_anchor = true
Default: true

prefer_world_spawn = true
Default: true

fallback_x = 0
fallback_y = 80
fallback_z = 0
fallback_yaw = 0.0
fallback_pitch = 0.0
Defaults shown above.

[dimensions.respawn]

mode = "INHERIT"
Default: INHERIT
Values: INHERIT, OVERWORLD, VANILLA
INHERIT uses common.toml.

[dimensions.environment]

game_mode = "INHERIT"
Default: INHERIT
Values: INHERIT, SURVIVAL, CREATIVE, ADVENTURE, SPECTATOR

fixed_time
Default: omitted
Range when present: 0..23999
Omitted means normal time progression.

difficulty = "INHERIT"
Default: INHERIT
Values: INHERIT, PEACEFUL, EASY, NORMAL, HARD

SPECTATOR warning:
Normal Gate/Return Scroll interaction may be unavailable while spectating. Provide an independent recovery method before forcing SPECTATOR.

[dimensions.time_limit]

No duration key means disabled.
Set exactly one when enabled:
seconds
minutes
hours
minecraft_days
Each must be >=1.

exit_destination = "PREVIOUS"
Default: PREVIOUS
Values: PREVIOUS, OVERWORLD

[dimensions.runtime]

keep_loaded = false
Default: false

reset_on_empty = false
Default: false

reset_delay_seconds = 30
Default: 30
Range: 0..2147483647

RESET WARNING:
Reset creates the next runtime physical generation from the imported source copy. Builds, block changes, entities, and other runtime changes inside the resettable Dimension may be discarded when Reset occurs.
The imported source copy itself is not reset/deleted.
With safe deferred cleanup, retired generations remain until restart and disk use can temporarily grow substantially.

[dimensions.bed]

allow_bed_respawn = false
Default: false

[dimensions.return_scroll]

enabled = true
Default: true

xp_level_cost
Default: omitted -> inherit common.return_scroll.default_xp_level_cost

[dimensions.anchor]

enabled = true
Default: true

[dimensions.inventory.import]
[dimensions.inventory.export]

mode = "BLACKLIST"
Default: BLACKLIST
Values: BLOCK_ALL, WHITELIST, BLACKLIST

items = []
Default: []
BLACKLIST + empty list allows all items.

[dimensions.travel.import]
[dimensions.travel.export]

mode = "ALLOW_ALL"
Default: ALLOW_ALL
Values: ALLOW_ALL, WHITELIST, BLACKLIST

dimensions = []
Default: []

Travel policy references are separate from Gate destination restrictions.

Legacy Dimension key:
[dimensions.return_gate]
enabled = true
Compatibility guard for old gate_type="RETURN" behavior only. Do not add to new definitions.

============================================================
3. gates.toml
============================================================

Canonical minimal imported-world Gate:

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

With a non-empty dimensions list and no selection_mode, LIST is inferred.

id
Required.

display_name
Default: id

enabled
Default: true

frame_block
Default: minecraft:obsidian

corner_block
Default: frame_block

min_inner_width
Default: common default (2)

min_inner_height
Default: common default (3)

max_inner_width
Default: common default (32)

max_inner_height
Default: common default (32)

selection_mode
Values: LIST, ALL

Current behavior:
- explicit LIST + non-empty dimensions -> LIST
- explicit LIST + empty dimensions -> Gate rejected
- explicit ALL -> ALL
- omitted + non-empty dimensions -> LIST
- omitted + empty/omitted dimensions -> legacy ALL fallback
- explicit invalid value -> Gate rejected with ERROR

ALL means all eligible READY WDL imported Dimensions. It does not automatically include Overworld.

dimensions
Default: []
LIST supports WDL imported IDs or exactly minecraft:overworld.
Do not mix minecraft:overworld with WDL IDs in one LIST.
Arbitrary third-party/native Gate destinations are unsupported.

open_time_seconds
Default: common default (10)
-1 = permanent
0 or values below -1 are invalid.

reopen_cooldown_seconds
Default: 0
Minimum: 0

allowed_igniters
Default: omitted/[]
Means unrestricted normal WDL Dimension Igniters.
Creative Dimension Igniter is a separate admin/master path.

GATE AMBIGUITY:
Two enabled Gate definitions can be rejected fail-closed if their physical matching conditions overlap. Physical matching includes frame block, corner block, size range, and applicable Igniters. Different destination IDs do not make the physical Gate unique.
When creating multiple Gates, change frame/corner blocks, use non-overlapping sizes, or restrict Igniters.

============================================================
4. Gate costs
============================================================

No [[gates.costs]] blocks = free Gate.
Multiple blocks are cumulative; all configured costs must be valid/payable.

type = "ITEM"
Default: ITEM
Values: ITEM, XP_LEVEL, XP_POINTS, HEALTH, HUNGER

item = "minecraft:air"
Parser fallback for ITEM. Configure a real item ID for meaningful ITEM costs.

amount_mode = "FIXED"
Default: FIXED
Values: FIXED, RANGE
FIXED/RANGE applies to supported cost types, not only ITEM.

amount = 0
Default: 0

min = amount
max = amount
Defaults shown above for RANGE.

If RANGE has min > max, that cost is ignored by the current parser.
ITEM RANGE additionally requires the configured maximum stock before activation can reserve/pay safely.

============================================================
5. Default Overworld Gate
============================================================

WDL ships an active default Overworld Gate separate from the minimal imported-world example:
- stone-brick frame
- emerald-block corners
- LIST -> minecraft:overworld
- permanent
- one emerald ITEM cost

============================================================
6. Existing Config migration
============================================================

Important behavior refinement:
Older WDL treated selection_mode omission as ALL even when dimensions=[...] was present.
WDL 1.3.0 interprets omitted mode + non-empty dimensions as LIST so the minimal Gate is intuitive.

If an existing Gate intentionally relied on ALL while omitting selection_mode, add:
selection_mode = "ALL"

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

Existing files are not overwritten. To get current comments:
1) back up config/worlddimensionloader/
2) move old Config files aside
3) start once
4) merge intentional overrides

============================================================
7. /wdl scan vs restart
============================================================

/wdl scan reloads/rescans reloadable Config/catalog state.
STARTUP ONLY settings do not switch active-process behavior and require a full restart.
This includes startup-latched cleanup/retired-generation policy and Advanced Dimension Igniter durability.

============================================================
8. Compatibility
============================================================

Valkyrien Skies safety behavior was validated around VS 2.4.11 and forces deferred cleanup when detected.
Distant Horizons compatibility work was validated around DH 3.2.0-b.

Unknown future versions are not guaranteed compatible.

============================================================
9. Examples / Play Ideas
============================================================
For practical combinations of these options, see WDL_EXAMPLES_AND_PLAY_IDEAS_EN_1.3.0.txt.

It contains ten copy-ready recipes covering the minimal Gate, LIST/ALL selection, rarity/weight, Timed Sessions, Runtime Reset, Inventory/Travel Policy, and multiple Gates with costs.
