NetherRatio-NG

NetherRatio

Paper

Java

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

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

📋 Requirements

- Dependencies: Paper 1.21.4+ (or compatible Spigot fork) - Dependencies: 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

```yaml

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 |

destination - 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: ```yaml 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`): ```yaml world-pairs: world: world_nether creative: creative_nether ```

Advanced Format (per-world custom ratios and offsets): ```yaml 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

subtracted - When traveling subtracted: Coordinates are divided by ratio, then offsets are subtracted - When traveling subtracted: Offsets are subtracted first, then coordinates are multiplied by ratio

Example: ```yaml 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): ```yaml value: 8 world-pairs: world: world_nether survival: survival_nether ```

1:1 Ratio (same coordinates in both dimensions): ```yaml value: 1 world-pairs: world: world_nether ```

Different Ratios Per World: ```yaml 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).

Example Output: `netherratio.netherratio` Example Output: `/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.

Example: `netherratio.netherratio` Example: `/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.

Example: `netherratio.netherratio` Example: `/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.

Usage: `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.

Usage: `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:

- 🇬🇧 Korean (`en`) - 🇩🇪 Korean (`de`) - 🇫🇷 Korean (`fr`) - 🇮🇹 Korean (`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. divided: Coordinates are divided by the ratio - Example with 8:1 ratio: `X=800, Z=600` → `X=100, Z=75`

2. multiplied: 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

```bash

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

- Performance: HIGH (runs after most plugins, before monitoring) - Performance: Players, minecarts, items, and all other entities - Performance: Nether portals only (End portals are not affected) - Performance: 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.

Current Maintainer: Current Maintainer: Current Maintainer: %%MD1%%

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

---

Made with ❤️ for the Minecraft community