WDN File Format - MarkusBordihn/BOs-World-Dimension-Nexus GitHub Wiki

📦 WDN File Format

The .wdn (World Dimension Nexus) file format is a standardized container for dimension data that enables easy sharing and migration of Minecraft dimensions between servers.

⚠️ Important: Always create a complete server backup before working with WDN files.

📋 Table of Contents

  1. What is a WDN File?
  2. File Structure
  3. Creating WDN Files
  4. Editing WDN Files
  5. Dimension Configuration
  6. File Size Optimization
  7. Best Practices
  8. Troubleshooting

🎯 What is a WDN File?

Understanding the WDN file format is essential for effectively managing dimension data transfers and customizations.

A .wdn file is essentially a ZIP archive containing all the data needed to recreate a Minecraft dimension. Despite having a .wdn extension, you can:

  • Rename the file to .zip to open it with any ZIP program
  • Extract the contents to examine or modify them
  • Repack the modified contents back into a .wdn file

This format ensures compatibility across different systems while keeping dimension data organized and compressed.

🗂️ File Structure

The internal structure of WDN files follows a standardized layout that ensures compatibility and proper data organization.

Basic Structure

dimension_name.wdn (ZIP archive)
├── dimension/           # Main dimension folder
│   ├── data/           # World data files
│   ├── entities/       # Entity data
│   ├── playerdata/     # Player-specific data
│   ├── poi/            # Points of Interest
│   ├── region/         # Chunk data files (.mca)
│   └── ...             # Other world data
└── dimension.json      # Dimension configuration (recommended)

Detailed Contents

📁 dimension/ Folder

Contains the complete Minecraft world data:

  • region/: Chunk files in Anvil format (.mca files)
  • data/: Game data like structures, advancements
  • entities/: Saved entity data
  • playerdata/: Player inventories and positions
  • poi/: Village and pillager outpost data
  • DIM folders: For Nether/End dimensions

📄 dimension.json File

Recommended configuration file containing dimension settings as JSON representation of DimensionInfoData. While optional, including this file ensures proper dimension configuration during import.

🛠️ Creating WDN Files

There are multiple ways to create WDN files depending on your needs and technical expertise.

Automatic Creation (Recommended)

The easiest way to create WDN files is using the export command:

# Export any dimension to create a .wdn file
/wdn dimension export mydimension

# The system automatically creates: mydimension.wdn (in server root directory)

Manual Creation

You can also create WDN files manually:

  1. Create a dimension folder with your world data
  2. Add dimension.json (recommended for proper configuration)
  3. Compress to ZIP using any archive program
  4. Rename from .zip to .wdn

Example dimension.json:

{
  "dimensionKey": "worlddimensionnexus:my_dimension",
  "type": "minecraft:overworld",
  "displayName": "My Custom Dimension",
  "description": "A custom dimension for special builds",
  "isCustom": true,
  "chunkGeneratorType": "FLAT",
  "requiresHotInjectionSync": true,
  "spawnPoint": [0, 100, 0],
  "gameType": "CREATIVE",
  "spawnRules": {
    "disableNaturalMobSpawning": false,
    "disableSpawnerBlocks": false,
    "allowedEntityTypes": []
  }
}

✏️ Editing WDN Files

Modifying WDN files allows you to customize dimension settings and world data before importing to your server.

Method 1: Direct ZIP Access

  1. Rename dimension.wdn to dimension.zip
  2. Open with your preferred ZIP program (WinRAR, 7-Zip, etc.)
  3. Extract or modify files directly
  4. Save the archive
  5. Rename back to .wdn

Method 2: Extract and Repack

  1. Extract the entire .wdn file to a folder
  2. Make changes to dimension data or configuration
  3. Select all contents of the extracted folder
  4. Create new ZIP archive with the modified contents
  5. Rename the new ZIP file to .wdn

💡 Important for Manual Packing: When creating the ZIP archive manually, always use maximum compression settings. Since imports typically happen only once, prioritize smallest file size over compression speed.

Recommended Compression Settings:

  • 7-Zip: Use "Ultra" compression level with LZMA2 method
  • WinRAR: Select "Best" compression method
  • Built-in Windows: Use "Send to > Compressed folder" then recompress with better tool
  • Command Line: 7z a -mx=9 dimension.wdn * (maximum compression)

Common Edits

Modifying Spawn Points

Edit dimension.json:

{
  "spawnPoint": [100, 80, -50]
}

Changing Game Type

{
  "gameType": "SURVIVAL"
}

Configuring Spawn Rules

{
  "spawnRules": {
    "disableNaturalMobSpawning": true,
    "disableSpawnerBlocks": false,
    "allowedEntityTypes": ["minecraft:cow", "minecraft:pig"]
  }
}

⚙️ Dimension Configuration

Proper configuration ensures your dimensions behave correctly when imported to different servers.

Default Behavior

If no dimension.json file is present:

  • A standard dimension configuration is used
  • Default spawn point at (0, 100, 0)
  • Survival game mode
  • Standard spawn rules

💡 Recommendation: Always include a dimension.json file for consistent behavior across different servers.

Available Configuration Options

Based on the actual DimensionInfoData implementation, the following options are supported:

Basic Settings

{
  "dimensionKey": "worlddimensionnexus:dimension_name",
  "type": "minecraft:overworld",
  "displayName": "Display Name",
  "description": "Dimension description",
  "isCustom": true
}

Chunk Generator Configuration

{
  "chunkGeneratorType": "FLAT",
  "requiresHotInjectionSync": true
}

Supported Chunk Generator Types:

  • FLAT - Flat world generation
  • VOID - Empty void world
  • OVERWORLD - Standard overworld generation
  • NETHER - Nether-like generation
  • END - End-like generation

Spawn Configuration

{
  "spawnPoint": [0, 100, 0]
}

Game Type

{
  "gameType": "SURVIVAL"
}

Supported Game Types:

  • SURVIVAL
  • CREATIVE
  • ADVENTURE
  • SPECTATOR

Spawn Rules

{
  "spawnRules": {
    "disableNaturalMobSpawning": false,
    "disableSpawnerBlocks": false,
    "allowedEntityTypes": []
  }
}

📊 File Size Optimization

Optimizing WDN file sizes is crucial for server performance and efficient data transfer between servers. WDN files should be kept as small as possible by including only essential content.

🎯 Optimization Philosophy

Export only what matters: Never export entire worlds. Instead, focus on specific areas and purposes:

  • Lobby dimensions: Export only the lobby island/area, remove all surrounding chunks
  • Build showcases: Include only the build area plus a small buffer zone
  • Minigame arenas: Export just the game area and necessary spawn points
  • Templates: Create minimal, clean versions without extra terrain

🗑️ Remove Unnecessary Chunks

Before exporting, aggressively clean up your dimension to achieve optimal file sizes:

Recommended Chunk Management Tools:

  1. MCA Selector (Most Popular)

    • Visual chunk selection and deletion
    • Filter by modification date, inhabited time
    • Batch operations for large areas

  2. WorldEdit (In-Game)

    //chunk delete [radius]
//regen [area]

  3. MCEdit (External Editor)

    • Advanced chunk editing capabilities
    • Precise selection tools

🎯 Aggressive Optimization Strategies

Essential Cleanup Checklist:

  • Remove ALL unused chunks - even empty air chunks take space
  • Delete surrounding terrain - keep only core functional areas
  • Remove experimental builds and temporary structures
  • Clear unnecessary entity data (items, mobs, etc.)
  • Delete exploration paths and access tunnels if not needed
  • Remove buffer zones - trim to absolute minimum required area

Target Areas for Complete Removal:

  • Any unused chunks - if it's not part of the core design, delete it
  • Empty air chunks - these still consume file space
  • Natural terrain around builds - remove unless specifically needed
  • Underground areas - delete unless they serve a purpose
  • Spawn platform surroundings - keep only the platform itself

📏 File Size Guidelines

Based on actual mod usage, WDN files should be kept extremely small:

Dimension Type Target Size Maximum Size Example
Small Build < 250 KB 500 KB Simple spawn platform
Medium Build 250 KB - 1 MB 2 MB Detailed lobby area
Large Build 1 MB - 5 MB 10 MB Complex minigame arena
Massive Project 5 MB - 25 MB 50 MB Large themed area

⚠️ Critical: Files larger than 50 MB should never be used for mod packs or distribution. Always optimize aggressively before export.

💡 Size Optimization Examples

Lobby Dimension:

  • Before optimization: 15 MB (entire world with exploration areas)
  • After optimization: 273 KB (lobby island only)
  • Removed: All chunks except the main lobby island and immediate spawn area

Simple Build:

  • Before optimization: 5 MB (build plus surrounding landscape)
  • After optimization: 63 KB (build area only)
  • Removed: All natural terrain, underground areas, and buffer zones

🔍 File Size Verification

After optimization, verify your file size:

  1. Check the final .wdn file size in your file manager
  2. Aim for the smallest possible size while maintaining functionality
  3. Test import to ensure nothing essential was removed
  4. Document what areas are included for future reference

📊 Best Practices

Following these best practices ensures reliable WDN file creation, distribution, and usage across different server environments.

🏗️ Creating Quality WDN Files

Pre-Export Preparation:

  1. Update all mods to latest versions
  2. Remove unnecessary mods that might cause conflicts
  3. Test thoroughly - Ensure everything works as expected
  4. Clean up - Remove unnecessary chunks and items
  5. Create backup - Keep original before modifications

Configuration Guidelines:

{
  "dimensionKey": "worlddimensionnexus:descriptive_name",
  "displayName": "Human Readable Name",
  "description": "Clear description of purpose and features",
  "gameType": "CREATIVE",
  "chunkGeneratorType": "FLAT",
  "spawnPoint": [0, 100, 0],
  "spawnRules": {
    "disableNaturalMobSpawning": false,
    "disableSpawnerBlocks": false
  }
}

🔄 Version Control

File Naming Convention:

project_name_v1.0.0.wdn
lobby_template_v2.1.0.wdn
minigame_arena_final.wdn

Documentation:

  • Maintain a changelog for major versions
  • Include version info in displayName or description
  • Document required mods and dependencies

🚀 Distribution

For Public Sharing:

  • Include detailed README with installation instructions
  • List all required mods and versions
  • Provide screenshots and feature descriptions
  • Test on fresh server installations with minimal mods

For Internal Use:

  • Standardize naming conventions across your server network
  • Create templates for common dimension types
  • Maintain organized file structure

🛠️ Troubleshooting

Common issues and their solutions when working with WDN files, helping you resolve problems quickly and efficiently.

Common Issues

Problem: WDN file won't open as ZIP

Solution:

  • Ensure the file wasn't corrupted during transfer
  • Try renaming to .zip explicitly
  • Use different archive software (7-Zip, WinRAR)
  • Check file permissions

Problem: Import fails with "Invalid format"

Solution:

  • Verify the dimension/ folder exists in the archive
  • Check that dimension.json syntax is valid JSON
  • Ensure all required files are present
  • Test with a fresh export first

Problem: Dimension appears empty after import

Solution:

  • Restart the server to load all data
  • Check server logs for import errors
  • Verify chunk files (.mca) are present in region/ folder
  • Ensure file wasn't corrupted during transfer

Problem: Configuration not applied

Solution:

  • Verify dimension.json is in the root of the archive
  • Check JSON syntax for errors
  • Ensure supported configuration options are used
  • Restart server after import for full effect

Problem: Very large file sizes

Solution:

  • Use chunk management tools to remove unused areas
  • Clean up entity data and unnecessary structures
  • Consider splitting large worlds into multiple dimensions
  • Optimize before export rather than after

🔍 Debugging Tips

Verify File Contents:

  1. Rename .wdn to .zip
  2. Extract to temporary folder
  3. Check folder structure matches expected format
  4. Validate dimension.json syntax if present

Test Import Process:

  1. Always test on development server first
  2. Monitor server console for error messages
  3. Check server logs after import
  4. Verify dimension accessibility in-game