Portal Preloader

A Folia-compatible Minecraft plugin that reduces loading screens and improves the portal travel experience by preloading chunks at portal destinations before players teleport.

Features

• Portal Preloading: Automatically spawns a snowball through newly created portals to pre-generate destination chunks
• Portal Cooldown System: Gives the destination time to fully load before allowing players to teleport
• Dimension-Specific Cooldowns: Set different cooldown times for Overworld and Nether portals
• Live Countdown: Players waiting in a portal see a countdown message every second
• Automatic Timer Reset: When cooldown expires, players don't need to leave and re-enter the portal
• Folia Compatible: Fully compatible with Folia's region-based threading
• Customizable Messages: All chat messages are configurable with color code support
• Reload Command: Update configuration without restarting the server

Why Use This Plugin?

When players travel through nether portals to unexplored areas, the destination chunks need to be generated. This can cause:

• Long loading screens
• Client freezing
• Players getting stuck in the portal animation
• Poor user experience, especially on servers with complex terrain generation

Portal Preloader solves this by:

1. Spawning a snowball through the portal immediately when it's lit
2. The snowball travels to the destination and triggers chunk generation
3. Chunks are pre-loaded and ready before any player teleports
4. The configurable cooldown ensures chunks have time to fully generate
5. Players experience smooth, instant teleportation with no loading screen

This is especially useful for:

• Servers with custom terrain generation
• High-performance servers running Folia
• Anarchy servers where players frequently explore new areas
• Any server wanting to improve the portal travel experience

Installation

1. Download the latest release JAR file
2. Place it in your server's plugins folder
3. Restart your server or use a plugin manager to load it
4. Configure the plugin in plugins/PortalPreloader/config.yml

Requirements

• Minecraft 1.21.x
• Folia or Paper server
• Java 21

Configuration

Default Config (config.yml)

# Portal Preloader Configuration

# Enable portal cooldown system
# When enabled, players cannot use newly lit portals for a set time
enable-portal-cooldown: true

# Default cooldown for all portals (in seconds)
# This is used when dimension-specific cooldowns are not set or set to -1
portal-cooldown-seconds: 10

# Dimension-specific cooldowns (set to -1 to use default cooldown)
# Overworld portals cooldown (portals lit in the overworld)
overworld-cooldown-seconds: -1

Nether portals cooldown (portals lit in the nether)

nether-cooldown-seconds: -1

Messages sent to players

Use {time} as a placeholder for remaining seconds in cooldown message

Color codes supported with & (e.g., &c for red, &a for green, &e for yellow)

messages:

Message sent every second while player waits in a portal on cooldown

cooldown: "&cThis portal is still loading! Please wait {time} seconds."

Message sent when the portal becomes ready while player is waiting inside

ready: "&aPortal is ready! You can now travel."

Enable verbose logging for debugging

Shows detailed information about portal creation, cooldowns, and player interactions

verbose: false

### Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `enable-portal-cooldown` | Enable/disable the cooldown system | `true` |
| `portal-cooldown-seconds` | Default cooldown time in seconds | `10` |
| `overworld-cooldown-seconds` | Cooldown for portals lit in the Overworld (-1 = use default) | `-1` |
| `nether-cooldown-seconds` | Cooldown for portals lit in the Nether (-1 = use default) | `-1` |
| `messages.cooldown` | Message shown during countdown (use `{time}` for seconds remaining) | See config |
| `messages.ready` | Message shown when portal becomes ready | See config |
| `verbose` | Enable detailed logging for debugging | `false` |

### Color Codes

Messages support Minecraft color codes using `&`:
- `&0` - Black
- `&1` - Dark Blue
- `&2` - Dark Green
- `&3` - Dark Aqua
- `&4` - Dark Red
- `&5` - Dark Purple
- `&6` - Gold
- `&7` - Gray
- `&8` - Dark Gray
- `&9` - Blue
- `&a` - Green
- `&b` - Aqua
- `&c` - Red
- `&d` - Light Purple
- `&e` - Yellow
- `&f` - White

## Commands

| Command | Permission | Description |
|---------|------------|-------------|
| `/portalpreloader` | - | Shows plugin version and help |
| `/portalpreloader reload` | `portalpreloader.reload` | Reloads the configuration |

**Aliases:** `/pp`, `/preloader`

## Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `portalpreloader.reload` | Allows reloading the plugin configuration | `op` |

## How It Works

### Portal Preloading
1. When a nether portal is lit with fire
2. A snowball is spawned in the center of the portal
3. The snowball immediately goes through the portal
4. This generates the destination portal before any player can teleport

### Cooldown System
1. When a portal is created, it's placed on cooldown
2. Players attempting to enter get a message showing remaining time
3. If a player waits inside the portal, they see countdown updates every second
4. When the cooldown expires, their portal timer automatically resets
5. Players can then teleport without leaving and re-entering

### Standing in Portal Area
- If a player is already standing where portal blocks will appear when it's lit
- They automatically get the cooldown and countdown starts
- This prevents bypassing the system by pre-positioning

## License

This project is provided as-is for use on Minecraft servers.