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.