World Dimension Loader 1.2.2 - Detailed Config Guide

Automatically generated Config and bundled examples/templates use English-only comments in 1.2.2. Existing Config is never auto-overwritten.

Config directory: config/worlddimensionloader/ with common.toml, dimensions.toml and gates.toml. Missing files are generated at game startup; existing files are never overwritten. Backup + regeneration is recommended for major upgrades.

1.2.2 core rule: default behavior is expressed by omission.
- ALL OPTIONS TEMPLATE = complete, fully commented option reference.
- MINIMAL WORKING EXAMPLE / EXAMPLE OVERRIDES = practical examples that omit default-only values.
- Existing explicit default values are still valid.
- common.toml may contain no active assignments at all.
- .template.toml files are now valid comment-only TOML and are safe to leave untouched.

Important omission defaults:
Dimension:
- display_name -> id
- folder -> id
- enabled -> true
- rarity -> COMMON
- weight -> rarity weight
- respawn.mode -> INHERIT
- runtime.keep_loaded -> false
- bed.allow_bed_respawn -> false
- anchor.enabled -> true
- return_scroll -> enabled + common XP cost
- Inventory Policy omitted -> allow all
- Travel Policy omitted -> allow all

Gate:
- display_name -> id
- enabled -> true
- frame_block -> minecraft:obsidian
- corner_block -> frame_block
- size -> common defaults
- allowed_igniters -> unrestricted normal WDL Igniters
- selection_mode -> ALL
- open_time_seconds -> common default
- no cost block -> free

A. common.toml
[general]
strict_validation=true: reject mounting when the imported LevelStem/WorldGen cannot be decoded safely. false may fall back to the host Overworld generator, so new chunks may differ. Gate ambiguity/invalid Gate definitions still fail closed regardless. Recommended true.
debug_logging=false: extra diagnostics.
default_gate_open_time_seconds=10 and default min/max inner sizes: used when Gate values are omitted.

[paths]
dimension_root_folder="WDL_custom_dimensions".

[items]
advanced_dimension_igniter_durability=100: Advanced Dimension Igniter maximum durability, range 1..10000, default 100.
This is fixed at Item registration. After changing it, fully restart the game/server; /wdl scan cannot apply it.

[runtime]
storage_mode=AUTO / IMPORT / DIRECT. AUTO currently uses validated IMPORT behavior. DIRECT is reserved and unavailable; use AUTO or IMPORT.
max_loaded_dimensions=4 limits simultaneous live WDL ServerLevels, not catalog size.
auto_unload=false and unload_delay_seconds=300 control idle unload.
vs_remount_cooldown_ticks=100 is the same-ID Valkyrien Skies remount safety delay.

[respawn]
mode=OVERWORLD / VANILLA plus player-spawn/world-spawn fallback flags.

[return_scroll]
default_xp_level_cost=5; 0 is free.

[gate_history]
max_entries=3, range 1..10.

[rarity_weights]
COMMON=100, UNCOMMON=60, RARE=25, EPIC=10, LEGENDARY=3. Explicit per-dimension weight overrides the rarity default.

B. dimensions.toml
Each [[dimensions]] block is one external world copy.
id: internal WDL ID used by Gates/Policy.
folder: real folder under dimension_root_folder.
display_name: display text.
enabled=false disables the catalog entry.
rarity: COMMON / UNCOMMON / RARE / EPIC / LEGENDARY / CUSTOM.
weight: optional explicit selection weight; 0 excludes from random selection.

[dimensions.destination]
prefer_anchor -> prefer_world_spawn -> fallback coordinates.

[dimensions.respawn]
INHERIT / OVERWORLD / VANILLA.

[dimensions.runtime]
keep_loaded=true keeps the READY dimension resident, consumes a max_loaded_dimensions slot and prevents Auto-Unload.

[dimensions.bed]
allow_bed_respawn=false/omitted means sleep only; true opts in to WDL bed death-respawn.

[dimensions.return_scroll]
enabled and optional xp_level_cost.

[dimensions.anchor]
enabled=false blocks new Anchor registration and ignores stored Anchor as an arrival candidate.

Inventory Import/Export modes: BLOCK_ALL / WHITELIST / BLACKLIST with items=[...].
Travel Import/Export modes: ALLOW_ALL / WHITELIST / BLACKLIST with dimensions=[...].
Short WDL ID "hub" normalizes to worlddimensionloader:hub. Use full minecraft:overworld for Overworld.
Overworld has no [[dimensions]] Policy block: Overworld->WDL checks WDL destination import; WDL->Overworld checks WDL source export.

Legacy [dimensions.return_gate].enabled is only a compatibility guard for legacy gate_type=RETURN aliases. It does not disable new normal DIMENSION->Overworld Gates.

C. gates.toml
Current new Config omits gate_type.
Supported Gate destinations are WDL imported dimensions or minecraft:overworld.
minecraft:the_nether, minecraft:the_end and third-party dimensions are not currently supported Gate destinations.
A LIST mixing minecraft:overworld and WDL imported IDs is invalid.
Core fields: id/display_name/enabled, frame_block/corner_block, min/max inner sizes, selection_mode, dimensions and open_time_seconds. allowed_igniters is optional.
Rectangle rule: four corners use corner_block and the remaining boundary uses frame_block.
LIST selects from dimensions=[...]. ALL selects enabled/READY imported WDL dimensions only; Overworld is never auto-added.
Overworld Gate: LIST + dimensions=["minecraft:overworld"].
open_time_seconds=-1 is permanent; otherwise 1 or greater.
Omit allowed_igniters, or use [], for no normal WDL Dimension Igniter restriction. A non-empty list restricts normal activation to listed IDs. Creative is the separate master/admin Igniter.
Same-frame examples: unrestricted + unrestricted = conflict; unrestricted + Advanced-only = conflict on Advanced; Basic-only + Advanced-only = separable for normal Igniters; unrestricted + Creative-only has no normal-Igniter conflict and explicit Creative remains a disambiguation hint. Omitted/empty does not allow arbitrary Minecraft items; it applies only to WDL Dimension Igniters entering the Gate activation path.
Shared physical frames are valid only when frame/size/Igniter conditions resolve unambiguously. Ambiguous matches fail closed with GATE_CONFIG_AMBIGUOUS; Config order does not win.

D. Gate Cost
Types: ITEM / XP_LEVEL / XP_POINTS / HEALTH / HUNGER.
ITEM modes: FIXED / RANGE. RANGE requires holding at least max before activation starts, then consumes one min..max roll.
Creative Igniter bypasses configured Gate costs.

E. Policy timing
Travel Policy controls the route and applies at activation/traversal.
Inventory Policy applies at actual player traversal and does not block Gate activation.
A Creative-opened Gate Session bypasses Cost and Inventory/Travel Policy, but not physical validity, destination validity or ambiguity safety.

F. Gate Travel History
Configured in common.toml. History never changes destination; it assists landing for only the latest exact reverse route and POPs after successful reverse travel.

G. Reload
Run /wdl scan or restart. On dedicated servers edit server-side Config.

H. Templates
config_samples/*.template.toml contains blank placeholders and is intentionally invalid until filled. Use generated Config/example files as the safer starting point.
