NetherRatio

A Paper/Spigot plugin that allows you to customize the Nether-to-Overworld coordinate ratio for portal travel. Perfect for servers that want to change the vanilla 8:1 ratio to suit their world design!

✨ Features

• 🎯 Per-World Ratios: Set different ratios for each world pair
• 🧮 Coordinate Calculator: Calculate portal coordinates without building portals
• 🛡️ Coordinate Bounds: Prevent teleportation into ungenerated chunks or beyond world borders
• 🌍 Multi-World Support: Configure different world pairs for complex server setups
• 🌐 Internationalization: Built-in support for English, German, French, Italian, and Korean
• ⚡ Performance Optimized: Lightweight with minimal server impact
• 🔒 Permission-Based: Full integration with permission management plugins
• 🔄 Hot Reload: Change settings without restarting the server
• 📝 Well Documented: Comprehensive JavaDoc and code comments
• ⚙️ Easy Configuration: Simple YAML configuration files

📋 Requirements

• Server: Paper 1.21.4+ (or compatible Spigot fork)
• Java: Java 21 or higher
• Dependencies: None required

📥 Installation

1. Download the latest version from GitHub Releases
2. Place the JAR file in your server's plugins folder
3. Restart your server
4. Configure the plugin in plugins/NetherRatio/config.yml
5. Use /netherratio reload to apply changes

⚙️ Configuration

config.yml

# Language for messages (available: en, de, fr, it, ko)
language: en

# Default ratio for world pairs that don't have a specific ratio configured
# Overworld value : Nether 1
# For vanilla Minecraft behavior, set to 8
value: 8

# Coordinate bounds - Prevent players from being teleported outside safe areas
# This helps avoid teleportation into ungenerated chunks or beyond world borders
coordinate-bounds:
  enabled: false
  # Minecraft's world border default is ±29,999,984 blocks
  # These values apply to the destination coordinates (after ratio calculation)
  min-x: -29999968
  max-x: 29999968
  min-z: -29999968
  max-z: 29999968

# World pairs for portal travel
# Define which overworld connects to which nether world
#
# Simple format (uses default ratio):
#   overworld_name: nether_name
#
# Advanced format (per-world ratio):
#   overworld_name:
#     nether: nether_name
#     ratio: 16
#
# Examples:
world-pairs:
  world: world_nether
  # Example with custom ratio:
  # survival:
  #   nether: survival_nether
  #   ratio: 16
  # Example with coordinate offsets:
  # adventure:
  #   nether: adventure_nether
  #   ratio: 8
  #   offset-x: 1000
  #   offset-z: -500
  # Example with simple format:
  # creative: creative_nether

Configuration Options

Option	Type	Default	Description
language	String	en	Language for in-game messages (en, de, fr, it, ko)
value	Double	8	Default coordinate conversion ratio (Overworld blocks : 1 Nether block)
coordinate-bounds	Section	See below	Safe coordinate limits to prevent teleportation into ungenerated areas
world-pairs	Map	See below	Mapping of Overworld worlds to their corresponding Nether worlds

Coordinate Bounds Configuration

Coordinate bounds help prevent players from being teleported into ungenerated chunks or beyond world borders when using portals. This is especially useful for servers with custom world sizes or pre-generated regions.

Configuration Options:

Option	Type	Default	Description
enabled	Boolean	false	Enable or disable coordinate bounds checking
min-x	Integer	-29999968	Minimum X coordinate for portal destinations
max-x	Integer	29999968	Maximum X coordinate for portal destinations
min-z	Integer	-29999968	Minimum Z coordinate for portal destinations
max-z	Integer	29999968	Maximum Z coordinate for portal destinations

How it works:

• When enabled, portal destinations are checked against these bounds
• If a destination exceeds the bounds, coordinates are automatically clamped to the nearest safe position
• Bounds apply to the destination coordinates (after ratio calculation)
• Useful for servers with smaller world borders or pre-generated areas

Example:

coordinate-bounds:
  enabled: true
  min-x: -10000
  max-x: 10000
  min-z: -10000
  max-z: 10000

With this configuration, no portal will teleport a player beyond ±10,000 blocks in the destination world.

World Pairs Configuration

You can configure world pairs using two formats:

Simple Format (uses the default ratio from value):

world-pairs:
  world: world_nether
  creative: creative_nether

Advanced Format (per-world custom ratios and offsets):

world-pairs:
  world: world_nether  # Uses default ratio (8)
  survival:
    nether: survival_nether
    ratio: 16  # Custom 16:1 ratio for this world pair
  skyblock:
    nether: skyblock_nether
    ratio: 4  # Custom 4:1 ratio for this world pair
  adventure:
    nether: adventure_nether
    ratio: 8
    offset-x: 1000   # Add 1000 blocks to X when going to nether
    offset-z: -500   # Subtract 500 blocks from Z when going to nether

Coordinate Offsets:
The offset-x and offset-z options allow you to shift the entire nether coordinate space relative to the overworld. This is useful for:

• Aligning spawn points between dimensions
• Creating separated nether regions for different overworld areas
• Custom world designs where nether and overworld don't share the same origin

How offsets work:

• When traveling Overworld → Nether: Coordinates are divided by ratio, then offsets are added
• When traveling Nether → Overworld: Offsets are subtracted first, then coordinates are multiplied by ratio

Example:

world-pairs:
  world:
    nether: world_nether
    ratio: 8
    offset-x: 1000
    offset-z: 0

With this configuration:

• Overworld (0, 0) → Nether (1000, 0)
• Overworld (800, 0) → Nether (1100, 0)
• Nether (1000, 0) → Overworld (0, 0)

Configuration Examples

Default Ratio for All Worlds (8:1):

value: 8
world-pairs:
  world: world_nether
  survival: survival_nether

1:1 Ratio (same coordinates in both dimensions):

value: 1
world-pairs:
  world: world_nether

Different Ratios Per World:

value: 8  # Default ratio
world-pairs:
  world: world_nether  # Uses default 8:1
  survival:
    nether: survival_nether
    ratio: 16  # 16:1 for survival world
  skyblock:
    nether: skyblock_nether
    ratio: 1  # 1:1 for skyblock

🎮 Commands

All commands use a consistent subcommand structure:

/netherratio or /netherratio list

Display all configured ratios (default and per-world).

Permission: netherratio.netherratio
Usage: /netherratio or /netherratio list
Example Output:

Default ratio: 8.0
World-specific ratios:
  world: 8.0
  survival: 16.0

/netherratio set <ratio>

Set the default ratio for all world pairs that don't have a specific ratio.

Permission: netherratio.netherratio
Usage: /netherratio set <ratio>
Example: /netherratio set 8 - Sets default ratio to 8:1

/netherratio set <ratio> <world>

Set a custom ratio for a specific world pair.

Permission: netherratio.netherratio
Usage: /netherratio set <ratio> <world>
Example: /netherratio set 16 survival - Sets 16:1 ratio for the survival world

/netherratio calc [x z]

Calculate what coordinates in one dimension correspond to in the other dimension.

Permission: netherratio.calc (default: all players)
Usage:

• /netherratio calc - Calculate using your current position
• /netherratio calc 800 600 - Calculate specific coordinates

Example Output:

Coordinates 800.0, 600.0 in world correspond to 100.0, 75.0 in world_nether

/netherratio reload

Reload the plugin configuration from disk.

Permission: netherratio.netherratio
Usage: /netherratio reload

🔐 Permissions

Permission	Description	Default
netherratio.netherratio	Allows managing ratios and reloading config	OP only
netherratio.calc	Allows using the coordinate calculator	Everyone

Permission Examples

LuckPerms:

/lp group admin permission set netherratio.netherratio true

PermissionsEx:

/pex group admin add netherratio.netherratio

🌐 Supported Languages

NetherRatio comes with built-in translations for:

• 🇬🇧 English (en)
• 🇩🇪 German (de)
• 🇫🇷 French (fr)
• 🇮🇹 Italian (it)
• 🇰🇷 Korean (ko)

To change the language, edit language: en in config.yml to your preferred language code.

Custom Languages

You can create custom translations by:

1. Creating a new file in plugins/NetherRatio/messages/
2. Naming it <language_code>.yml
3. Copying the structure from any existing message file
4. Setting language: <language_code> in config.yml

🔧 How It Works

Coordinate Conversion

When a player or entity travels through a Nether portal:

1. Overworld → Nether: Coordinates are divided by the ratio

   • Example with 8:1 ratio: X=800, Z=600 → X=100, Z=75

2. Nether → Overworld: Coordinates are multiplied by the ratio

   • Example with 8:1 ratio: X=100, Z=75 → X=800, Z=600

3. Coordinate Bounds (if enabled): Destination coordinates are checked and clamped

   • Prevents teleportation into ungenerated chunks
   • Keeps players within safe, pre-generated areas
   • Example: If max-x is 10000 and calculated X is 12000, player spawns at X=10000

World Mapping

The plugin uses the world-pairs configuration to determine which Nether world corresponds to each Overworld. This allows:

• Multiple separate world pairs on the same server
• Custom world names (not restricted to world_nether naming)
• Flexible multi-world setups

🏗️ Building from Source

Prerequisites

• Git
• Maven 3.6+
• Java 21 JDK

Build Steps

# Clone the repository
git clone https://github.com/ZyanKLee/NetherRatio.git
cd NetherRatio

# Build with Maven
mvn clean package

# The compiled JAR will be in target/

The built plugin will be available at target/NetherRatio-2.3.1.jar

🐛 Troubleshooting

Portal doesn't work after changing ratio

1. Make sure you've saved the config and run /netherratio reload
2. Verify the world names in world-pairs match your actual world names
3. Check server logs for any error messages

"World not found" errors

• Ensure your world-pairs configuration correctly maps your worlds
• Use /worlds (if you have a world management plugin) to verify world names
• World names are case-sensitive

Permission errors

• Verify the permission is correctly set: netherratio.netherratio
• Check your permission plugin's configuration
• Ensure OPs have permissions if using the default setup

📊 Technical Details

• Event Priority: HIGH (runs after most plugins, before monitoring)
• Supported Entities: Players, minecarts, items, and all other entities
• Portal Types: Nether portals only (End portals are not affected)
• Thread Safety: All operations are thread-safe
• Performance: < 1ms processing time per portal event

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Code Style

• Follow existing code conventions
• Add JavaDoc comments for public methods
• Include appropriate error handling
• Write clear commit messages

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Download on Modrinth
• Report Issues
• Paper Documentation

💖 Support

If you find this plugin useful, please consider:

• ⭐ Starring this repository
• 📢 Sharing it with others
• 🐛 Reporting bugs and suggesting features

🙏 Credits

This project is a fork and continuation of the original work by xDxRAx.

Original Author: xDxRAx
Current Maintainer: ZyanKLee

Special thanks to the original author for creating the foundation of this plugin!

---

Made with ❤️ for the Minecraft community