World Dimension Loader 1.2.2

⚠️ Important: Config Update Recommendation

Existing Config files remain compatible and are not automatically overwritten or destructively migrated.

However, if you are updating from WDL 1.1.3 or another older version, regenerating the Config is strongly recommended.

Since 1.1.3, WDL has received major changes to:

• Gate routing
• Return travel behavior
• Gate Travel History
• Inventory / Travel Policies
• Dimension loading and teleport handling
• Config structure
• Igniter behavior
• Compatibility handling for other MODs

WDL 1.2.2 also introduces a significantly cleaner Config layout.

Recommended upgrade procedure

1. Stop Minecraft / the server.
2. Back up: config/worlddimensionloader/
3. Move or rename the old WDL Config files.
4. Start Minecraft with WDL 1.2.2 to generate the latest Config.
5. Copy only the settings you intentionally customized from the old Config.
6. Run: /wdl scan /wdl list /wdl status
7. Test your Gates and imported dimensions.

You do not need to copy every old setting.

In WDL 1.2.2, default behavior is intentionally represented by omitting the setting.

If you prefer to keep your existing Config, it should continue to work through WDL's legacy compatibility handling.

1.2.2

Config Layout / Usability

• Reworked generated Config around one simple rule:

  default behavior is expressed by omission.

• Added a fully commented ALL OPTIONS TEMPLATE to generated Config files.

• Added cleaner practical examples containing only settings that actually need to be changed.

• common.toml may contain no active assignments at all; WDL's built-in defaults remain authoritative.

• Simplified dimensions.toml examples by removing redundant default settings such as:

  • enabled = true
  • default folder values
  • default rarity weights
  • default Respawn settings
  • keep_loaded = false
  • Bed Respawn disabled
  • Anchor enabled
  • unrestricted Inventory / Travel Policies

• Simplified the generated default Overworld Gate while preserving its existing behavior.

• Simplified imported-world Gate examples by removing default-only Gate options.

• Java-generated Config and bundled *.example.toml files are synchronized.

• *.template.toml files are now valid, fully commented TOML instead of incomplete blank-value templates.

• Updated Japanese and English:

  • README
  • Tutorial
  • Config Guide
  • Troubleshooting
  • Upgrade Guide
  • Release Notes

Compatibility

• No intentional Runtime or parser default changes.
• Existing WDL 1.2.1 Config remains valid.
• Existing Config is never automatically rewritten.
• Config regeneration is optional, but strongly recommended when upgrading from older releases if you want the latest structure and examples.
• Gate Travel History, Policies, Return Scroll, Distant Horizons / Forge lifecycle handling, and Advanced Igniter durability behavior are unchanged.

1.2.1

Config / Igniter Usability

• Automatically generated:

  • common.toml
  • dimensions.toml
  • gates.toml

  now use English-only comments for improved readability.

• Bundled Config examples/templates also use English-only comments.

• Changed allowed_igniters behavior:

  • omitted = unrestricted for normal WDL Dimension Igniters
  • allowed_igniters = [] = unrestricted
  • non-empty list = restrict the Gate to the listed normal Igniters

• Unrestricted Gate examples no longer include unnecessary allowed_igniters entries.

• Same-frame Gate ambiguity validation now understands unrestricted Igniter definitions and remains fail-closed.

• Creative Dimension Igniter remains the separate admin/master Igniter.

• Creative cost bypass, Policy bypass, and same-frame disambiguation behavior are unchanged.

Compatibility

• Existing explicit Basic + Advanced Igniter lists retain the same restriction.
• Existing omitted/empty Igniter lists become unrestricted normal-Igniter Gate definitions.
• Existing Config is never destructively rewritten.
• Gate Costs, Inventory / Travel Policy, Gate Travel History, Return Scroll, destination architecture, DH/Forge compatibility, and Advanced Igniter durability behavior remain unchanged.

1.2.0

WDL 1.2.0 was a larger internal and gameplay architecture update.

In addition to new configuration features, several older systems were reorganized to remove overlapping responsibilities and improve compatibility with dynamic Dimension loading.

Gate / Travel Architecture

• Added per-dimension Inventory Import / Export Policy.

• Added per-dimension Travel Import / Export Policy.

• Inventory Policy is checked when the player actually traverses the Gate rather than preventing Gate activation.

• Removed gate_type from the new Gate Config format.

• Overworld is now treated as a normal explicit Gate destination:

  minecraft:overworld

• Legacy:

  • gate_type = "DIMENSION"
  • gate_type = "RETURN"

  remain readable for compatibility.

🔄 Return Gate System Rework

The old special RETURN Gate system was reworked.

As WDL gained:

• normal Overworld destination Gates
• Gate Travel History
• Return Scroll
• Inventory Policy
• Travel Policy
• multiple Gate routing rules

the old dedicated RETURN Gate began to overlap with several newer systems.

Keeping a separate special-purpose Return Gate path would have created duplicated routing rules and increased the risk of conflicts between:

• destination selection
• Return History
• Travel Policy
• Inventory Policy
• Gate Session state
• normal Gate traversal

To avoid these feature conflicts, the return system was simplified.

New design

Legacy RETURN Gates are now treated as normal Gates targeting:

minecraft:overworld

The previous route-return functionality is handled separately by Gate Travel History.

This separates two responsibilities:

```text id="1k50cn" Gate definition → decides WHERE the Gate travels

Gate Travel History → helps decide WHERE the player lands on a valid reverse route ```

This makes Gate routing more predictable and avoids having two separate systems trying to control the same travel event.

Old RETURN Config remains readable for compatibility.

Gate Travel History

• Replaced the old special Return Gate route logic with Gate Travel History.
• Successful normal Gate travel records the source Gate.
• When the player later travels through the exact reverse route, WDL can return them near the original Gate.
• Default history size: 3
• Configurable range: 1–10
• History changes the landing position only.
• The configured Gate / ActiveGate always determines the destination.
• Return Scroll remains a separate direct-Overworld emergency return method.
• Successful Return Scroll clears Gate Travel History.
• History is stored separately for each player.
• History survives logout/login and server restarts.
• Invalid or unrelated Dimension changes do not create false Gate History entries.

Gate Costs

• Hardened ITEM + RANGE Gate costs.
• Players must now hold at least the configured max amount before the Gate activation challenge may begin.
• Actual consumption is rolled once between min and max.
• Fixed behavior that could allow repeated activation attempts without satisfying the intended maximum stock requirement.
• Gate costs are committed only after the destination and Gate opening process are ready to proceed.

Creative Dimension Igniter

Creative Dimension Igniter remains the WDL admin/master Igniter.

It can:

• activate valid Gates without being listed normally
• bypass configured Gate costs
• open a Gate Session that bypasses Inventory / Travel Policy

Safety checks still apply:

• valid Gate structure
• valid destination
• current-dimension restrictions
• same-frame ambiguity checks
• runtime safety checks

Same-frame Gate selection was also hardened so multiple definitions cannot be silently selected simply because of Config order.

Ambiguous definitions fail closed.

Per-Dimension Controls

Added or reorganized per-dimension control for:

• Dimensional Anchor
• Return Scroll
• Bed Respawn
• keep_loaded
• Inventory Policy
• Travel Policy

Travel Policy also applies consistently to Return Scroll routes.

Advanced Dimension Igniter

Advanced Dimension Igniter maximum durability is now configurable.

Default:

100

Allowed range:

1–10000

Changing this value requires a full game/server restart.

Config Generation

• Missing WDL Config files are now generated during game startup, before a world needs to be opened.
• Existing Config is never automatically overwritten.
• Legacy Config remains supported as far as practical.
• Improved generated examples and upgrade guidance.

🛠️ Bug Fixes / Stability Improvements

Several travel and dynamic-Dimension edge cases were hardened during the 1.2.0 development cycle.

Improvements include:

• Fixed cases where player state could become inconsistent when returning from or reconnecting inside Lazy-Mounted WDL Dimensions.
• Hardened Session Resume behavior when a player logs out inside an imported Dimension.
• Improved Dimension mount / remount handling.
• Improved same-ID Dimension remount safety.
• Improved shutdown and unload handling.
• Hardened teleport completion handling so WDL does not incorrectly treat an already-completed Minecraft Dimension transfer as a failed transfer.
• Prevented Gate Travel History from being updated by unrelated or unmanaged Dimension changes.
• Improved fail-closed behavior for ambiguous same-frame Gates.
• Hardened Gate Cost transaction handling to avoid partial or inconsistent consumption.
• Improved handling around dynamic Level creation and removal for compatibility with other MODs.

🌄 Distant Horizons Compatibility / Conflict Avoidance

Compatibility work was added for environments using Distant Horizons with dynamically mounted WDL Dimensions.

Previously, WDL could create and use a dynamic ServerLevel without other MODs receiving the Forge Level lifecycle events they expected.

With Distant Horizons, this could result in a timing conflict during Dimension travel where PlayerChangedDimensionEvent was processed before DH had registered the dynamically mounted Level.

One observed result was a null-level error during Dimension transfer.

To avoid this conflict:

• Dynamic WDL ServerLevels now participate in the Forge Level Load / Unload lifecycle.
• Other MODs receive the expected Level lifecycle notifications when WDL mounts or unloads a Dimension.
• Added commit-aware managed teleport handling.
• If Minecraft has already completed the Dimension transfer but another MOD throws an exception afterward, WDL can recognize that the teleport itself was committed and correctly finalize its own state.

Managed teleport handling is used by:

• Gates
• Gate Travel History
• Return Scroll
• /wdl tp
• Session Resume
• Respawn handling

Testing with Distant Horizons 3.2.0-b no longer reproduced the previously observed null-level PlayerChangedDimensionEvent NPE.

This compatibility work is designed to reduce conflicts not only with Distant Horizons, but also with other MODs that depend on standard Forge Level lifecycle notifications.

Documentation / Packaging

Expanded the bundled Japanese and English documentation covering:

• first-time setup
• dedicated servers
• Gate construction
• Gate geometry
• rarity / weight
• LIST / ALL
• same-frame Gate ambiguity
• recipes
• imported WorldGen preservation
• Inventory / Travel Policy
• Gate Travel History
• migration
• troubleshooting

The release JAR includes the complete public documentation and Config reference files.

1.1.3

Documentation / Release Hardening

• Improved first-time-user setup documentation.

• keep_loaded and Bed Respawn are explicitly opt-in in beginner examples.

• Fixed release packaging so Japanese and English user guides are included in the final JAR.

• Bundled:

  • Config samples
  • Changelog
  • License
  • Credits
  • Root README

• Added a shorter beginner setup path.

• Added a dedicated existing-user Config upgrade guide.

• Expanded documentation for:

  • keep_loaded
  • max_loaded_dimensions
  • Creative Dimension Igniter
  • same-frame ambiguity
  • Session Resume
  • shutdown hardening

Compatibility

• Existing 1.0.0 / 1.1.x Config remains supported.
• Missing: dimensions.runtime.keep_loaded defaults to false.
• Missing: dimensions.bed.allow_bed_respawn defaults to false.
• Existing Gate selection, rarity/weight, Anchor, Auto-Unload, source WorldGen inheritance, Session Resume, and Valkyrien Skies compatibility behavior are preserved.

Current Version

World Dimension Loader 1.2.2

Minecraft 1.20.1 Forge 47.4.22+ Java 17